Skip to content

Handoff to Frontend

What design provides to frontend, and what to check before handoff.

What frontend needs from design

For every page, frontend needs all of these before they can start:

Item Where it lives Status required
Design system tokens docs/design/mvp/design_system.md review or higher
CSS token file docs/design/mvp/design_tokens.css Generated alongside design_system.md
Component catalog docs/design/mvp/component_catalog.md review or higher
Component screens (Stitch URLs) docs/design/mvp/stitch_library.md → component row All components used on page must show ✅
Page spec docs/design/mvp/pages/<page>_spec_v1.md review or higher
Page screen (Stitch URL) docs/design/mvp/stitch_library.md → page row + spec frontmatter mcp_export URL must be filled
User flows (for navigation logic) docs/design/mvp/user_flows_v1.md draft or higher

How frontend imports design tokens

Frontend imports design_tokens.css at the app root. Never hardcode hex values.

// app/layout.tsx or _app.tsx
import '@/styles/design_tokens.css';  // or wherever design_tokens.css is copied

Then use CSS variables in Tailwind or directly:

// Correct — uses design token via CSS variable
className="text-[var(--color-text-primary)] bg-[var(--color-surface)]"

// Also correct — Tailwind theme configured via design: tailwind-config
className="text-text-primary bg-surface"

// Wrong — hardcoded hex
style={{ color: '#0F172A', background: '#FFFFFF' }}

If design_tokens.css changes: design team runs design: sync-tokens → file regenerates → frontend rebuilds. Do not copy-paste hex values from design_system.md. Always import from the CSS file.

Frontend Brief sections in component catalog

Every component entry in component_catalog.md has a #### Frontend Brief section that provides:

  • Which CSS variables the component uses
  • TypeScript interface (prop names, types, defaults)
  • Copy-paste usage examples
  • Which shadcn/ui base component to install (or "custom")
  • Stitch reference URL from stitch_library.md

Frontend agents should read the Frontend Brief section for each component before implementing it. This is the authoritative implementation spec — not the visual-design prose above it.

What the page spec provides

The page spec (docs/design/mvp/pages/<page>_spec_v1.md) contains:

Section What frontend uses it for
2. User stories covered Which acceptance criteria to satisfy
3. Navigation context Entry points, exit paths, previous/next pages
4. Layout Breakpoint behaviour (mobile → tablet → desktop)
5. Components used Which components to import, which variants to use
6. Page states Empty, loading, error, success, offline — exactly what to render
7. User interactions Every tap/click/swipe → what happens, loading state, optimistic update
8. Data requirements Which API endpoints to call and when
9. Validation Input rules, error messages, when to validate (blur vs submit)
10. Accessibility Page-specific a11y requirements
12. Performance budget LCP target, bundle size target

Token usage rule

Frontend uses token names from design_system.md, not hex values:

// Correct — uses design token
className="text-color-primary bg-color-surface"

// Wrong — hardcoded hex
style={{ color: '#2563EB', background: '#FFFFFF' }}

The design system maps token names to CSS variables. Frontend implements CSS variables from design_system.md.

Component implementation order

Frontend implements in the same order design produces:

  1. Atoms first (smallest, most reused)
  2. Molecules (compose atoms)
  3. Organisms (compose molecules)
  4. Pages (compose organisms)

Never implement a page before its atoms and molecules are done. The Stitch component screens are the visual reference for each level.

Stitch screens as visual reference

  • Component screens (stitch_prompts/components/<name>.md → Stitch URL): shows exact visual for every variant × state
  • Page screens (stitch_prompts/pages/<name>.md → Stitch URL): shows exact page layout

Frontend compares their implementation against the Stitch screen. If something looks different, check:

  1. Is the correct token being used?
  2. Is the correct component variant being used?
  3. Are the pixel dimensions matching the component spec?

Before design publishes a page spec

Run design: publish <file>. Brand Guardian checks automatically:

What it checks Why frontend needs it
No raw hex in spec — tokens only Frontend uses tokens, not hex
Every component in spec exists in catalog Frontend knows where to find the component spec
All 5 page states described Frontend knows what to render in every state
Stitch URL filled (mcp_export) Frontend has a visual reference
Mobile layout described first NepWalk is mobile-first PWA

If Brand Guardian blocks the publish, the spec is not ready for frontend.

Handoff checklist (run before opening a PR)

[ ] design_system.md is status: review
[ ] design_tokens.css exists and all /* AI: */ placeholders are filled
[ ] component_catalog.md is status: review
[ ] Every component has a Frontend Brief section with CSS vars + TypeScript interface
[ ] All components used on this page show ✅ in stitch_library.md
[ ] Page spec is status: review (published via design: publish)
[ ] Page Stitch URL is filled in spec frontmatter (mcp_export)
[ ] Page row in stitch_library.md shows ✅
[ ] User flows doc exists (user_flows_v1.md)
[ ] Brand Guardian returned APPROVED or APPROVED WITH WARNINGS
[ ] PR to nepwalk-docs is open