Feature Specification: Mobile-first redesign

Feature Branch: 001-mobile-first-redesign
Created: 2025-11-06
Status: Draft
Input: User description: “Completely change my site design to adhere to the mobile first principle, and also make it look nicer”

Constitution Alignment Checklist (mandatory)

Principle Evidence / Decisions to capture
I. Markdown canon Redesign touches index.md, about.md, _posts/* layouts, _includes/header.html, _layouts/{default,post}.html, and assets/css/style.scss. _site/ remains generated by bundle exec jekyll build and must never be edited manually.
II. Dual-runtime parity Bundler commands: bundle install, bundle exec jekyll build --config _config.yml,_config.ci.yml, bundle exec jekyll serve --livereload. No pnpm tooling today, so confirm README/docs note “n/a” to keep parity obvious. Any breakpoint/front matter changes must live in _config.yml and be mirrored (if needed) in _config.ci.yml.
III. Mobile-first single-hand experience Default styles start at <=360 px width with a 4 pt spacing scale, 48 px tap targets for nav + CTA, and imagery compressed to <=150 KB WebP equivalents. Capture Lighthouse Mobile >=85 plus a short screen recording (Chrome DevTools iPhone 12 preset) showing thumb-reach (CTA within lower 50% of viewport).
IV. CI-grade verification Run bundle exec jekyll build --config _config.yml,_config.ci.yml, then bundle exec htmlproofer ./_site --assume-extension --check-html --disable-external --no-enforce-https, followed by npx markdownlint-cli2 \"**/*.md\" before opening the PR and again after any layout refactor.
V. Living documentation & plan discipline Update docs/work-plan.md with sequencing for layout rollout, docs/theme-spec.md with refreshed typography scale, breakpoints, and reaffirmed color tokens (noting the palette stays the same), and docs/dev-environment-inventory.md with any new tooling (e.g., image compression script).
VI. AI-agent-first workflow Package the redesign steps into .specify/scripts/bash/build-mobile-preview.sh (or document the manual sequence) so agents can bundle exec jekyll serve, capture _site preview artifacts, and post screenshots/video links via chat. Ensure instructions note how to run Lighthouse via npx @lhci/cli collect --url http://127.0.0.1:4000.

User Scenarios & Testing (mandatory)

User Story 1 - Thumb-friendly hero scan (Priority: P1)

A first-time mobile visitor landing on index.md can immediately read the hero copy, see a primary CTA, and scroll the featured content without pinch-zooming.

Why this priority: The landing page drives first impressions and bounce rate; failure here invalidates the redesign goal.

Independent Test: Load the built site on a 360 px mobile viewport, measure above-the-fold readability, and confirm CTA can be tapped one-handed without zoom.

Acceptance Scenarios:

  1. Given a viewport width of 360 px, When the visitor loads /, Then all hero text wraps within the viewport and the CTA button fits within a 48 px tall tap target.
  2. Given a user scrolling with one thumb, When they reach featured posts, Then cards stack vertically with >=16 px spacing and no horizontal scroll.

User Story 2 - Reading long-form posts (Priority: P2)

A returning reader can open any _posts/YYYY-MM-DD-slug.md article on their phone, read comfortably, and navigate to related content without losing context.

Why this priority: Posts carry the bulk of content engagement; readability translates directly to time-on-site.

Independent Test: Render three representative posts, validate typography scale, table/blockquote handling, and inline image scaling entirely on mobile.

Acceptance Scenarios:

  1. Given a post containing headings, lists, images, and code fences, When viewed on a mobile device, Then text maintains 16 px base size with 150% line height and media scales to the viewport width without overflow.
  2. Given the sticky navigation collapsed to a drawer, When the reader reaches the end of a post, Then related links remain accessible within two taps.

User Story 3 - Desktop parity check (Priority: P3)

The site owner or reviewer can expand to tablet/desktop widths and see progressive enhancement (larger grid, enhanced imagery) without regressions from the mobile-first code.

Why this priority: Desktop visitors still exist; ensuring layouts scale up protects credibility and SEO preview cards.

Independent Test: Resize the same build from 360 px to 1440 px while observing that breakpoints progressively add columns instead of replacing the mobile experience.

Acceptance Scenarios:

  1. Given a viewport >=768 px, When the user views the homepage, Then the content transitions to a two-column grid while keeping hero copy legible and CTA prominent.
  2. Given a viewport >=1024 px, When the nav is rendered, Then it displays inline links with hover focus states that mirror the mobile drawer items.

Edge Cases

  • Very long post titles (>80 characters) must wrap gracefully inside hero cards without pushing CTAs below the fold.
  • Blog posts containing wide code blocks should introduce horizontal scrolling within the code block only, never the page.
  • Offline or slow connections: if hero background images fail to load, fallback colors and typography must maintain contrast and layout integrity.

Requirements (mandatory)

Functional Requirements

  • FR-001: System MUST define a mobile-first CSS architecture (root styles optimized for <=400 px, progressive enhancements via min-width media queries).
  • FR-002: System MUST provide a sticky header with a collapsible drawer menu whose links maintain 48 px tap targets and keyboard focus order.
  • FR-003: System MUST reorganize homepage content blocks so priority sections (hero, featured posts, contact CTA) render in descending importance order in the DOM for screen readers and mobile stacking.
  • FR-004: System MUST ensure _posts content components (images, tables, blockquotes, code fences) scale within the viewport and expose utility classes authors can apply in Markdown front matter.
  • FR-005: System MUST compress hero/background imagery to <=150 KB and serve modern formats with fallbacks referenced from assets/.
  • FR-006: System MUST document the spacing/typography/color tokens in docs/theme-spec.md so future Markdown authors know which classes to use.
  • FR-007: Visual theme MUST retain the current brand color palette while updating typography, spacing, and component styling to align with the refreshed mobile-first guidelines.
  • FR-008: System MUST include automated Lighthouse Mobile checks (manual or scripted) and store evidence (scores + screenshot/video link) in the PR description.

Key Entities (include if feature involves data)

  • Layout Tokens: Semantic variables (spacing scale, font sizes, color roles) referenced by SCSS partials and documented for Markdown authors to request specific classes.
  • Navigation Menu: Data structure derived from _data/navigation.yml (if present) or _config.yml collections that feeds both the drawer menu and desktop inline nav ensuring single source of truth.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: Lighthouse Mobile Performance >=85 and Accessibility >=95 on the rebuilt homepage using a 4G throttled profile.
  • SC-002: Median first contentful paint on mobile reduces by 20% versus the current production baseline (measure via WebPageTest or Lighthouse).
  • SC-003: 90% of tested blog posts render without horizontal scrolling at widths between 320 px and 414 px.
  • SC-004: At least 80% of usability test participants report the redesign is “easy” or “very easy” to navigate on a phone (collect via simple survey or heuristic review).
  • SC-005: No markdownlint or htmlproofer errors remain after the redesign build, proving CI readiness.