First deployment
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-13
|
||||
@@ -0,0 +1,84 @@
|
||||
## 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?
|
||||
@@ -0,0 +1,36 @@
|
||||
## Why
|
||||
|
||||
Several small UX and content-discovery issues are adding friction across navigation, sharing, readability, and trust signals. Addressing them together delivers a noticeable quality jump with low implementation risk.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Set a stable homepage title (for example, `ClawFort AI News`) instead of changing it to the latest article headline.
|
||||
- Add a footer `Back to Top` action for quick navigation.
|
||||
- Add per-article permalinks and support deep-link behavior that opens the correct article modal on page load.
|
||||
- Add minimal icon-only share actions for permalink sharing (`X`, `WhatsApp`, `LinkedIn`) in modal/footer share area.
|
||||
- Improve readability with small typography/color updates, with extra attention to Tamil and Malayalam legibility.
|
||||
- Add custom 404/500 pages that prominently show the error code and include safe, playful AI-generated “Oh no!” style messages.
|
||||
- Add footer links driven by environment configuration for GitHub repo and contact email; include enhanced hover/near-cursor feedback messages from a randomized safe message pool.
|
||||
- Add an AI-themed favicon asset and wire it into the site.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `article-permalinks-and-deep-link-modal`: Defines canonical per-article permalink structure and modal auto-open behavior from URL state.
|
||||
- `share-and-contact-microinteractions`: Defines social share actions, configurable GitHub/email links, and randomized safe feedback microcopy for contact affordance.
|
||||
- `error-pages-with-playful-ai-messaging`: Defines 404/500 UX with prominent status codes and policy-safe AI-style messaging.
|
||||
- `site-branding-favicon`: Defines favicon asset requirements and integration.
|
||||
|
||||
### Modified Capabilities
|
||||
- `seo-meta-and-social-tags`: Update homepage title behavior to remain stable and brand-oriented while preserving metadata quality.
|
||||
- `summary-modal-experience`: Extend modal contract to support permalink-driven open state and share entry points.
|
||||
- `responsive-device-agnostic-layout`: Apply small typography/color refinements for readability across devices.
|
||||
- `language-aware-content-delivery`: Improve Tamil/Malayalam presentation quality in the existing delivery surfaces.
|
||||
- `footer-policy-links`: Extend footer navigation with back-to-top, GitHub, and contact affordances.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Frontend UI:** `frontend/index.html` (title policy, footer controls, permalink/deep-link modal behavior, share icons, readability tweaks, favicon link).
|
||||
- **Backend/Config:** environment variables for GitHub URL and contact email exposure; possible API/config exposure if frontend config bootstrapping is needed.
|
||||
- **Routing/Pages:** new error page templates/handlers for 404 and 500 responses.
|
||||
- **Content/UX:** curated safe message pool for contact tooltip/hover microcopy and error-page “Oh no!” messaging.
|
||||
@@ -0,0 +1,25 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Each news item exposes a permalink
|
||||
The system SHALL expose a stable, shareable permalink for each rendered news item.
|
||||
|
||||
#### Scenario: Per-item permalink rendering
|
||||
- **WHEN** a news item is rendered in hero or feed context
|
||||
- **THEN** the UI provides a permalink target tied to that article context
|
||||
|
||||
#### Scenario: Permalink copy/share usability
|
||||
- **WHEN** a user uses share/copy affordances for an item
|
||||
- **THEN** the resulting URL contains sufficient information to resolve that article on load
|
||||
|
||||
### Requirement: Deep-link loads article modal in open state
|
||||
The system SHALL open the matching article modal when the page is loaded with a valid article permalink.
|
||||
|
||||
#### Scenario: Valid permalink opens modal
|
||||
- **WHEN** a user lands on homepage with a permalink for an existing article
|
||||
- **THEN** the corresponding article modal is opened automatically
|
||||
- **AND** modal content matches the permalink target
|
||||
|
||||
#### Scenario: Invalid permalink fails safely
|
||||
- **WHEN** a permalink references a missing or invalid article identifier
|
||||
- **THEN** the page remains usable without hard failure
|
||||
- **AND** modal is not opened with incorrect content
|
||||
@@ -0,0 +1,20 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Error pages prominently display status code
|
||||
The system SHALL show prominent HTTP status code display on 404 and 500 pages.
|
||||
|
||||
#### Scenario: 404 rendering
|
||||
- **WHEN** user visits a non-existent route
|
||||
- **THEN** the page prominently displays `404`
|
||||
|
||||
#### Scenario: 500 rendering
|
||||
- **WHEN** an internal server error page is rendered
|
||||
- **THEN** the page prominently displays `500`
|
||||
|
||||
### Requirement: Error pages include safe playful AI-style messaging
|
||||
The system SHALL render an "Oh no!" style playful message that is safe and policy-compliant.
|
||||
|
||||
#### Scenario: Safe message selection
|
||||
- **WHEN** an error page is displayed
|
||||
- **THEN** a playful message is selected from a curated safe message set
|
||||
- **AND** message excludes profanity and discriminatory/abusive content
|
||||
@@ -0,0 +1,24 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Footer exposes policy navigation links
|
||||
The system SHALL display footer links for Terms of Use and Attribution on the landing page.
|
||||
|
||||
#### Scenario: Footer links visible on landing page
|
||||
- **WHEN** a user loads the main page
|
||||
- **THEN** the footer includes links labeled "Terms of Use" and "Attribution"
|
||||
- **AND** links are visually distinguishable and keyboard focusable
|
||||
|
||||
#### Scenario: Footer links navigate correctly
|
||||
- **WHEN** a user activates either policy link
|
||||
- **THEN** the browser navigates to the corresponding policy page
|
||||
- **AND** navigation succeeds without API dependency
|
||||
|
||||
#### Scenario: Footer includes back-to-top action
|
||||
- **WHEN** a user reaches lower sections of the page
|
||||
- **THEN** footer exposes a "Back to Top" control
|
||||
- **AND** activating it returns viewport to page top smoothly
|
||||
|
||||
#### Scenario: Footer includes optional GitHub and email links
|
||||
- **WHEN** GitHub repository URL and/or contact email are configured
|
||||
- **THEN** footer renders corresponding links without replacing policy links
|
||||
- **AND** absent values do not break footer layout
|
||||
@@ -0,0 +1,32 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: API supports language-aware content retrieval
|
||||
The system SHALL support language-aware content delivery for hero and feed reads using selected language input.
|
||||
|
||||
#### Scenario: Language-specific latest article response
|
||||
- **WHEN** a client requests latest article data with a supported language selection
|
||||
- **THEN** the system returns headline and summary in the selected language when available
|
||||
- **AND** includes the corresponding base article metadata and media attribution
|
||||
|
||||
#### Scenario: Language-specific paginated feed response
|
||||
- **WHEN** a client requests paginated feed data with a supported language selection
|
||||
- **THEN** the system returns each feed item's headline and summary in the selected language when available
|
||||
- **AND** preserves existing pagination behavior and ordering semantics
|
||||
|
||||
#### Scenario: Tamil and Malayalam rendering quality support
|
||||
- **WHEN** Tamil (`ta`) or Malayalam (`ml`) content is delivered to frontend surfaces
|
||||
- **THEN** payload text preserves script fidelity and Unicode correctness
|
||||
- **AND** frontend presentation hooks can apply readability-focused typography adjustments without changing response shape
|
||||
|
||||
### Requirement: Language fallback to English is deterministic
|
||||
The system SHALL return English source content when the requested translation is unavailable.
|
||||
|
||||
#### Scenario: Missing translation fallback
|
||||
- **WHEN** a client requests Tamil or Malayalam content for an article lacking that translation
|
||||
- **THEN** the system returns the English headline and summary for that article
|
||||
- **AND** response shape remains consistent with language-aware responses
|
||||
|
||||
#### Scenario: Unsupported language handling
|
||||
- **WHEN** a client requests a language outside supported values (`en`, `ta`, `ml`)
|
||||
- **THEN** the system applies the defined default language behavior for this phase
|
||||
- **AND** avoids breaking existing consumers of news endpoints
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Core layout is device-agnostic and responsive
|
||||
The system SHALL render key surfaces (header, hero, feed, modal, footer) responsively across mobile, tablet, and desktop viewports.
|
||||
|
||||
#### Scenario: Mobile layout behavior
|
||||
- **WHEN** a user opens the site on a mobile viewport
|
||||
- **THEN** content remains readable without horizontal overflow
|
||||
- **AND** interactive controls remain reachable and usable
|
||||
|
||||
#### Scenario: Desktop and tablet adaptation
|
||||
- **WHEN** a user opens the site on tablet or desktop viewports
|
||||
- **THEN** layout reflows according to breakpoint design rules
|
||||
- **AND** no key content or controls are clipped
|
||||
|
||||
#### Scenario: Readability-focused typography and contrast updates
|
||||
- **WHEN** content is rendered in core reading surfaces
|
||||
- **THEN** typography and color choices improve baseline readability
|
||||
- **AND** updates remain compatible with responsive behavior across breakpoints
|
||||
@@ -0,0 +1,19 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Core SEO metadata is present on public pages
|
||||
The system SHALL expose standards-compliant SEO metadata on the homepage and policy pages, including description, robots, canonical URL, and social preview metadata.
|
||||
|
||||
#### Scenario: Homepage metadata baseline exists
|
||||
- **WHEN** a crawler or browser loads the homepage
|
||||
- **THEN** the document includes `description`, `robots`, and canonical metadata
|
||||
- **AND** Open Graph and Twitter card metadata fields are present with non-empty values
|
||||
|
||||
#### Scenario: Policy pages include indexable metadata
|
||||
- **WHEN** a crawler loads `/terms` or `/attribution`
|
||||
- **THEN** the page includes page-specific `title` and `description` metadata
|
||||
- **AND** Open Graph and Twitter card metadata are present for link previews
|
||||
|
||||
#### Scenario: Homepage title remains stable and brand-oriented
|
||||
- **WHEN** homepage content updates to newer articles
|
||||
- **THEN** document title remains a stable brand title (for example `ClawFort AI News`)
|
||||
- **AND** title does not switch to latest-article headline text
|
||||
@@ -0,0 +1,28 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Modal/footer exposes minimal icon-based share actions
|
||||
The system SHALL provide icon-only social share actions for article permalinks on supported providers.
|
||||
|
||||
#### Scenario: Supported share providers
|
||||
- **WHEN** share controls are rendered
|
||||
- **THEN** icons for `X`, `WhatsApp`, and `LinkedIn` are displayed
|
||||
- **AND** activating an icon opens provider share flow with the article permalink
|
||||
|
||||
### Requirement: Footer supports env-driven GitHub and contact links
|
||||
The system SHALL conditionally render GitHub and contact-email links from environment-backed configuration.
|
||||
|
||||
#### Scenario: Config present
|
||||
- **WHEN** GitHub URL and contact email are configured
|
||||
- **THEN** footer renders both links as interactive controls
|
||||
|
||||
#### Scenario: Config absent
|
||||
- **WHEN** either value is missing
|
||||
- **THEN** corresponding footer control is hidden without breaking layout
|
||||
|
||||
### Requirement: Contact affordance provides randomized safe microcopy
|
||||
The contact link SHALL present randomized, policy-safe helper messages to encourage feedback.
|
||||
|
||||
#### Scenario: Randomized helper tooltip
|
||||
- **WHEN** user hovers or nears the contact affordance
|
||||
- **THEN** a tooltip-style helper message is shown from a predefined safe message pool
|
||||
- **AND** message language avoids profanity/offensive/racist/sexist/misogynistic content
|
||||
@@ -0,0 +1,13 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Site includes AI-themed favicon
|
||||
The system SHALL include an AI-themed favicon asset and reference it from public pages.
|
||||
|
||||
#### Scenario: Favicon linked in document head
|
||||
- **WHEN** a public page is loaded
|
||||
- **THEN** a favicon link element resolves to the configured AI-themed icon asset
|
||||
|
||||
#### Scenario: Favicon asset is cacheable and valid
|
||||
- **WHEN** browser requests favicon asset
|
||||
- **THEN** asset responds successfully with a valid icon format
|
||||
- **AND** can be cached using standard static-asset policy
|
||||
@@ -0,0 +1,30 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Summary is rendered in a modal dialog using standard template
|
||||
The system SHALL render article summary content in a modal dialog using the required structure.
|
||||
|
||||
#### Scenario: Open summary modal
|
||||
- **WHEN** a user triggers summary view for an article
|
||||
- **THEN** a modal dialog opens and displays content in this order: relevant image, TL;DR bullets, summary body, source and citation, and "Powered by Perplexity"
|
||||
- **AND** modal content corresponds to the selected article
|
||||
|
||||
#### Scenario: Close summary modal
|
||||
- **WHEN** a user closes the modal via close control or backdrop interaction
|
||||
- **THEN** the modal is dismissed cleanly
|
||||
- **AND** user returns to previous feed context without page navigation
|
||||
|
||||
#### Scenario: Permalink-driven modal open
|
||||
- **WHEN** page is loaded with a valid article permalink state
|
||||
- **THEN** the modal opens for the linked article without requiring manual click
|
||||
|
||||
### Requirement: Modal content preserves source link-out behavior
|
||||
The system SHALL provide source link-outs from the summary modal.
|
||||
|
||||
#### Scenario: Source link-out from modal
|
||||
- **WHEN** a user clicks source/citation link in the modal
|
||||
- **THEN** the original source opens in a new tab/window
|
||||
- **AND** modal behavior remains stable for continued browsing
|
||||
|
||||
#### Scenario: Modal exposes share entry points
|
||||
- **WHEN** a summary modal is open for an article
|
||||
- **THEN** share controls for the article permalink are available from modal/footer share area
|
||||
@@ -0,0 +1,41 @@
|
||||
## 1. Homepage Metadata and Navigation
|
||||
|
||||
- [x] 1.1 Set homepage title to stable brand title (e.g., `ClawFort AI News`) and prevent latest-article overrides.
|
||||
- [x] 1.2 Add footer `Back to Top` control with smooth scroll behavior.
|
||||
|
||||
## 2. Permalinks and Deep-Link Modal
|
||||
|
||||
- [x] 2.1 Add per-article permalink generation for hero and feed items.
|
||||
- [x] 2.2 Add URL parsing on load to detect permalink article target.
|
||||
- [x] 2.3 Open matching article modal automatically when permalink target is valid.
|
||||
- [x] 2.4 Handle invalid/missing permalink targets safely without UI breakage.
|
||||
|
||||
## 3. Sharing and Footer Contact UX
|
||||
|
||||
- [x] 3.1 Add icon-only share actions for `X`, `WhatsApp`, and `LinkedIn` using article permalinks.
|
||||
- [x] 3.2 Add env-driven footer GitHub link (`GITHUB_REPO_URL`) and contact email link (`CONTACT_EMAIL`).
|
||||
- [x] 3.3 Implement randomized safe tooltip microcopy pool (~50 messages) for contact affordance.
|
||||
|
||||
## 4. Readability Improvements
|
||||
|
||||
- [x] 4.1 Apply minor typography and color-contrast refinements across reading surfaces.
|
||||
- [x] 4.2 Add targeted Tamil/Malayalam readability tuning (font size/line-height/weight adjustments as needed).
|
||||
- [x] 4.3 Verify updates preserve responsive behavior across mobile/tablet/desktop.
|
||||
|
||||
## 5. Error Experience
|
||||
|
||||
- [x] 5.1 Implement custom 404 page with prominent status code and safe playful "Oh no!" message.
|
||||
- [x] 5.2 Implement custom 500 page with prominent status code and safe playful "Oh no!" message.
|
||||
- [x] 5.3 Add curated safe message set and deterministic/randomized selection strategy.
|
||||
|
||||
## 6. Branding Asset
|
||||
|
||||
- [x] 6.1 Add AI-themed favicon asset to static files with proper licensing/attribution notes if required.
|
||||
- [x] 6.2 Wire favicon reference in public page heads.
|
||||
|
||||
## 7. Validation
|
||||
|
||||
- [x] 7.1 Verify permalink deep-link opens correct modal and share links include correct URL.
|
||||
- [x] 7.2 Verify footer controls (policy links, back-to-top, GitHub, email) across breakpoints.
|
||||
- [x] 7.3 Verify Tamil/Malayalam readability changes in actual rendered content.
|
||||
- [x] 7.4 Verify 404/500 pages render status code + safe playful message.
|
||||
Reference in New Issue
Block a user