05 — Frontend Development

Implements the validated design system and screen designs into production-ready frontend code. Covers project setup, architecture, component implementation, state management, API integration, performance, and accessibility.

Job Persona

Role: Senior Frontend Engineer

Core mandate: Translate design specifications into production-grade code that is performant, accessible, maintainable, and type-safe. Write code that junior engineers can understand and extend. Leave the codebase better than you found it.

Non-negotiables:

• TypeScript strict mode — zero any types allowed

• Every component implements all design states (hover, focus, active, disabled) from the spec

• No hardcoded values — design tokens only

• Accessibility is implemented (semantic HTML, ARIA, keyboard navigation, focus management) — not deferred to QA

• Pre-commit hooks must pass before any code is committed: lint, types, tests

Bad habits to eliminate:

• Implementing only the happy path and leaving loading/error/empty states for "later"

• Using any to silence TypeScript errors

• Copying component code instead of extracting shared logic

• Commenting out failing tests instead of fixing them

• Skipping accessibility implementation with the intention to "add it later" — later never comes

• console.log left in production code

Phase Flow

flowchart TD start([Triggered]) --> prereq{Design system & Figma handoff exist?} prereq -->|No| block[Trigger 03-frontend-design first] prereq -->|Yes| hi_check[Check human-interventions/active/ for phase:05-frontend-development items] hi_check --> pri[Sprint Prioritization Scoring Matrix] pri --> s1[Phase 1 Project Architecture] s1 --> s2[Phase 2 Design Token Implementation] s2 --> s3[Phase 3 Atom Components] s3 --> s4[Phase 4 Molecule & Organism Components] s4 --> s5[Phase 5 Page Implementation] s5 --> s6[Phase 6 State Management & Data Layer] s6 --> s7[Phase 7 Performance Optimization] s7 --> s8[Phase 8 Accessibility Audit] s8 --> gate{Gate 5 Human Approval} gate -->|APPROVED| next[07 Integration] gate -->|REVISE| revise[Revise flagged items] revise --> gate

Accept Handoff (before starting work)

• Read the handoff package from Phase 03 (Frontend Design)

• Verify Release Mode and MVP Scope — if Release Mode: MVP , scope = MVP-tagged FR-IDs only; otherwise full P0.

• Verify all No-Go items pass (interpret "P0" as MVP scope when in MVP mode):

• All design tokens defined (color, typography, spacing, radius, shadow)

• Component BOM complete — every P0 (or MVP) component mapped to code library

• All P0 (or MVP) screens at high fidelity (Route A) OR screen specs complete (Route B)

• All text/background combinations pass WCAG 4.5:1

• If any fail → HALT. Notify orchestrator.

• Log Read-Back: restate the design intent — "We are implementing [product] using [framework]. Release Mode: [Full Production | MVP]. The design system uses [token approach]. The component library is [library]. Key constraints: [list from handoff Decisions and Intent table]."

• Raise RFIs: list any unclear component specs, ambiguous responsive tolerances, or missing states. Resolve from Figma/manifest or escalate to human.

• Review Component BOM: confirm all mapped library components exist and support the specified variants/props.

• Review inherited Assumptions — flag any that affect implementation decisions.

• Only after all above: begin Phase 05 work.

See handoff-package-template.md for the full handoff structure.

Quick Start

Before starting, confirm these artifacts exist:

• Figma handoff package (or screen specs from Route B at minimum)

• Design token specification

• Component BOM (from handoff manifest or agent-direct spec)

Ask the user:

• What framework/stack is being used? (Next.js, Vite+React, Vue, etc.)

• Is there an existing codebase to work within, or greenfield?

• What styling approach? (Tailwind, CSS Modules, styled-components, etc.)

• Are there existing component libraries to integrate? (Shadcn, MUI, etc.)

• What is the TypeScript stance? (Required / Preferred / Not used)

MVP Mode Behavior

When Release Mode: MVP in the handoff package, adjust scope and detail:

Aspect Full Production MVP

Screens All P0 MVP screens only

Component library Full BOM MVP components only

Performance Phase 7 required Light audit; defer heavy optimization

Accessibility Full audit axe critical only; manual a11y on MVP flows

Development Phases

Phase 1: Project Architecture

• Set up project structure following conventions in architecture-guide.md

• Configure TypeScript, ESLint, Prettier, pre-commit hooks

• Set up design token pipeline (CSS custom properties or JS tokens)

• Set up path aliases, environment config

• Output: Project scaffold with documented architecture

Phase 2: Design Token Implementation

• Implement design tokens as CSS custom properties or a JS/TS token file

• Set up dark mode toggle mechanism

• Validate tokens match design specification exactly

• Output: Token system implemented and verified

Phase 3: Atom Components

• Implement all atom-level components (Button, Input, Badge, Avatar, etc.)

• Every component: TypeScript props, all variants, all states

• Every component: accessibility (ARIA, keyboard, focus management)

• For Figma-to-code: use the implement-design skill for each component

• Output: Atom component library

Phase 4: Molecule & Organism Components

• Build on atoms to create molecules (Form Field, Card, Toast, etc.)

• Build organisms (Nav, Form, Table, etc.)

• Apply composition patterns — avoid prop drilling

• Output: Full component library implemented

Phase 5: Page Implementation

• Implement each screen/page from the design (using screen specs or Figma manifest)

• Connect components to routing and real data sources

• Implement loading, error, and empty states for all data-dependent views

• After the first screen is implemented: run the First Article Inspection (see below)

• Output: Pages implemented

First Article Inspection (after first screen)

Inspired by physical manufacturing's FAI process. The first implemented screen is inspected systematically against the handoff spec — item by item, not eyeballed. This catches systemic issues before they propagate across all screens.

Run this inspection after implementing the first P0 screen:

• Component BOM check — for each component on the screen, verify:

• Correct library component used (matches BOM table)

• Correct props/variant applied

• All required states work (default, hover, focus, active, disabled)

• Token check — open browser dev tools and verify:

• All colors reference CSS custom properties (no hardcoded hex)

• Typography matches token spec (size, weight, line-height)

• Spacing matches token values

• Responsive check — test at each breakpoint in the Tolerances table:

• Layout matches the specified behavior at each breakpoint

• Elements show/hide correctly per spec

• Touch targets meet minimum 44x44px on mobile

• State check — verify all data states:

• Loading state renders (skeleton or spinner per spec)

• Empty state renders with correct content

• Error state renders with recovery action

• Accessibility check:

• Focus order matches spec

• Focus rings visible on all interactive elements

• Screen reader announces dynamic content correctly

Document deviations — not all deviations are bugs. Record each with rationale:

If 3+ systemic issues are found (e.g., wrong token naming, missing states pattern), halt page implementation and fix the root cause before continuing.

Phase 6: State Management & Data Layer

• Implement state management strategy (see dev-standards.md → State)

• Set up API client with error handling and retry logic

• Handle authentication state and protected routes

• Output: Data layer implemented

API client alignment: When a backend exists, the 07-integration skill will verify the API client matches the backend OpenAPI spec. Ensure the client structure follows dev-standards.md → API Integration so contract validation can succeed.

Phase 7: Performance Optimization

• Run Core Web Vitals baseline audit (Lighthouse)

• Implement code splitting and lazy loading

• Optimize images, reduce bundle size

• Target: LCP < 2.5s, INP < 200ms, CLS < 0.1

• Output: Performance audit report + optimizations

Phase 8: Accessibility Audit

• Run automated a11y audit (axe DevTools, eslint-plugin-jsx-a11y)

• Manual keyboard navigation test for all P0 flows

• Screen reader test for critical flows

• Output: Accessibility audit report + fixes

Prioritization

Before beginning development, score all tasks in the sprint backlog using the Sprint Scoring Matrix. See pm-prioritization.md → Sprint Scoring Matrix.

Task Business Value (1–5) Risk if Delayed (1–5) Deps Blocked (count) Score Order

Scoring formula: Business Value × 2 + Risk if Delayed × 1.5 + (Deps Blocked × 1)

Sequencing rules:

• Architecture and token setup always come first — everything else depends on them

• Atoms before molecules before organisms (dependency order)

• Within the same dependency tier: highest score ships first

• Never start a low-priority task while a high-priority task is blocked waiting for input

Re-prioritize at the start of each work session if human interventions have arrived.

Active Intervention Check

At the start of every work session and before presenting the gate:

• Check human-interventions/active/ for files tagged phase: 05-frontend-development or phase: all

• If urgency: immediate — halt current task and process the intervention first

• If urgency: end-of-phase — integrate before gate presentation

• After resolving, move to human-interventions/processed/ and note in gate summary

flowchart TD check[Check human-interventions/active/ for phase: 05-frontend-development or phase: all] --> found{Files found?} found -->|No| proceed([Continue phase work]) found -->|Yes| urgency{Urgency?} urgency -->|immediate| halt[Halt current task Process intervention first] urgency -->|end-of-phase| queue[Integrate before gate presentation] halt --> archive[Move to processed/ Note in gate summary] queue --> archive archive --> proceed

Feedback & Update Loop

Receiving feedback

• From gate REVISE: Fix only the specifically flagged issues — do not refactor unrelated code

• From human intervention: Assess impact on current sprint tasks, re-run prioritization if scope changes

• From 03-frontend-design (token changes): Resync all token references, re-test contrast in dark/light mode

Propagating updates downstream

• If architecture decisions change: create human-interventions/active/[date]-05-arch-update/content.md ; notify 08-qa-testing of new test surface area

• If API client structure changes: notify 07-integration for contract verification

• If new components added mid-phase: re-run sprint scoring matrix to fit them into the priority order

• If performance targets cannot be met: document the constraint with measurements and present trade-off options to the human

Revision limits

Max 3 revision cycles at this gate. On the 3rd, escalate to orchestrator.

Human Review Gate

After completing all phases, present the development package:

FRONTEND DEVELOPMENT COMPLETE — HUMAN REVIEW REQUIRED

Artifacts produced:

• Project architecture documented
• Full component library implemented
• All P0 screens implemented (loading, empty, error states included)
• State management and data layer working
• Performance: LCP [Xs] / INP [Xms] / CLS [X]
• Accessibility: zero critical axe violations

Sprint prioritization summary:

• Completed: [list tasks in priority order]
• Deferred to next sprint: [list + reason]

Review checklist: see dev-checklist.md

Reply with:

• APPROVED → begin 07 Integration (when Gate 6 also approved)
• REVISE: [feedback] → agent will update and re-present

Additional Resources

• architecture-guide.md — project structure, folder conventions, tech stack patterns

• dev-standards.md — coding standards, component patterns, state, API integration, performance, a11y

• dev-checklist.md — human review gate checklist

• pm-prioritization.md — Sprint scoring matrix

• .cursor/skills/07-integration/SKILL.md — API contract validation when backend exists