85 lines
4.0 KiB
Markdown
85 lines
4.0 KiB
Markdown
## Context
|
|
|
|
The current site works functionally but has usability gaps: dynamic homepage title behavior can confuse context, discovery/sharing of individual articles is weak, error pages are plain, and footer affordances are limited. Readability needs incremental tuning, especially for Tamil and Malayalam text rendering. These issues span frontend state management, metadata behavior, footer UX, and static asset/routing support.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Stabilize homepage title for clarity and SEO consistency.
|
|
- Add back-to-top affordance and per-article permalink deep-linking that opens the correct modal.
|
|
- Add minimal icon-based sharing (X/WhatsApp/LinkedIn) for modal/permalink flows.
|
|
- Improve legibility via typography/color refinements, with explicit Tamil/Malayalam attention.
|
|
- Introduce branded AI favicon.
|
|
- Add expressive 404/500 pages with prominent code display and safe playful AI-style copy.
|
|
- Add env-driven GitHub/email footer links with randomized safe feedback tooltip microcopy.
|
|
|
|
**Non-Goals:**
|
|
- Rewriting router architecture or adding server-side rendering.
|
|
- Adding complex social auth or third-party share SDKs.
|
|
- Replacing existing analytics instrumentation.
|
|
- Building full i18n content moderation pipeline for tooltip text.
|
|
|
|
## Decisions
|
|
|
|
### Decision 1: Hash/query driven deep-link modal state
|
|
**Choice:** Use permalink token (`?article=<id>` or hash equivalent) and resolve on load to open matching modal.
|
|
|
|
**Rationale:**
|
|
- Works with existing SPA flow and avoids backend route explosion.
|
|
- Easy to share/copy and easy to close by clearing URL state.
|
|
|
|
### Decision 2: Keep sharing implementation lightweight
|
|
**Choice:** Construct provider share URLs client-side and use icon buttons without extra SDK dependencies.
|
|
|
|
**Rationale:**
|
|
- Minimal bundle impact.
|
|
- Predictable behavior with native share endpoints.
|
|
|
|
### Decision 3: Readability tuning via CSS tokens and language-aware classes
|
|
**Choice:** Adjust text size/line-height/color contrast in existing theme token system; apply optional class hooks for Tamil/Malayalam content rendering.
|
|
|
|
**Rationale:**
|
|
- Incremental and low-risk.
|
|
- Preserves current theme architecture.
|
|
|
|
### Decision 4: Error pages with controlled safe message pool
|
|
**Choice:** Use curated safe message templates (50+) and deterministic randomization per request/session.
|
|
|
|
**Rationale:**
|
|
- “Oh no!” playful tone without unsafe generation risks.
|
|
- No runtime LLM dependency required for error path.
|
|
|
|
### Decision 5: Footer extensibility via env-backed config
|
|
**Choice:** Expose `GITHUB_REPO_URL` and `CONTACT_EMAIL` through existing frontend config bootstrap and render conditional links.
|
|
|
|
**Rationale:**
|
|
- Keeps deployment-specific metadata configurable.
|
|
- Avoids hardcoded personal links.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- **[Risk] Deep-link to missing article id** -> Mitigation: fail gracefully (no modal open) and keep list view stable.
|
|
- **[Risk] Tooltip microcopy quality drift** -> Mitigation: curate fixed safe message corpus and review before release.
|
|
- **[Risk] Share URL encoding mistakes** -> Mitigation: centralized URL builder + encode all user-facing strings.
|
|
- **[Trade-off] Stable homepage title reduces article-specific title SEO** -> Mitigation: keep OG/Twitter/article-level metadata contextual in card/modal/share surfaces.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add permalink generation, URL parsing, and modal open-on-load logic.
|
|
2. Add share icons/buttons and footer microinteraction links.
|
|
3. Apply readability and color token tweaks; verify Tamil/Malayalam rendering.
|
|
4. Add error page handlers/templates and safe message pool.
|
|
5. Add favicon asset and head reference.
|
|
6. Add env-config plumbing for GitHub/email footer links.
|
|
|
|
Rollback:
|
|
- Revert permalink and share UI additions.
|
|
- Revert title and readability token changes.
|
|
- Restore prior generic error page behavior.
|
|
|
|
## Open Questions
|
|
|
|
- Should permalink use numeric article id only, or slug+id hybrid for readability?
|
|
- Should contact tooltip randomization rotate per hover event or per page load?
|
|
- Should 404/500 messages be localized immediately or staged in English first?
|