frontend-scaffold

frontend-scaffold

Convert designs and specs into production-ready React/Next.js component scaffolds with typed API hooks.

Context Files

• $JAAN_CONTEXT_DIR/tech.md - Tech stack context (CRITICAL — determines framework, styling, versions)
  • Uses sections: #current-stack, #frameworks, #constraints
• $JAAN_CONTEXT_DIR/design.md - Design system guidelines (optional)
• $JAAN_CONTEXT_DIR/brand.md - Brand guidelines (optional)
• $JAAN_TEMPLATES_DIR/jaan-to-frontend-scaffold.template.md - Output template
• $JAAN_LEARN_DIR/jaan-to-frontend-scaffold.learn.md - Past lessons (loaded in Pre-Execution)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/frontend-ui-workflow-reference.md - Shared UI workflow reference (CSF3 format)

Input

Upstream Artifacts: $ARGUMENTS

Accepts 1-3 file paths or descriptions:

• frontend-design — Path to HTML preview or component description (from /jaan-to:frontend-design output)
• frontend-task-breakdown — Path to FE task breakdown (from /jaan-to:frontend-task-breakdown output)
• backend-api-contract — Path to OpenAPI YAML (from /jaan-to:backend-api-contract output)
• Empty — Interactive wizard
• Cross-role: optionally consumes /jaan-to:ux-microcopy-write output

---

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: frontend-scaffold Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

• $JAAN_CONTEXT_DIR/tech.md — Know the tech stack for framework-specific code generation
• $JAAN_CONTEXT_DIR/design.md — Know the design system patterns
• $JAAN_CONTEXT_DIR/brand.md — Know brand colors, fonts, tone

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_frontend-scaffold

Language exception: Generated code output (variable names, code blocks, schemas, SQL, API specs) is NOT affected by this setting and remains in the project's programming language.

---

PHASE 1: Analysis (Read-Only)

Thinking Mode

ultrathink

Use extended reasoning for:

• Analyzing design artifacts to derive component architecture
• Mapping API contract schemas to TypeScript interfaces and hooks
• Planning Server Component vs Client Component boundaries
• Identifying accessibility requirements per component

Step 1: Validate & Parse Inputs

For each provided path:

• frontend-design: Read HTML preview or component description, extract component list, layout, interactions
• frontend-task-breakdown: Read markdown, extract component inventory, state matrices, estimates, dependencies
• backend-api-contract: Read OpenAPI YAML, extract schemas for TypeScript interfaces, endpoints for API hooks
• Report which inputs found vs missing; suggest fallback for missing

Present input summary:

INPUT SUMMARY
─────────────
Sources Found:    {list}
Sources Missing:  {list with fallback suggestions}
Components:       {extracted component names with atomic level}
API Endpoints:    {count from API contract}
TypeScript Types: {count derivable from schemas}

Step 2: Detect Tech Stack

Read $JAAN_CONTEXT_DIR/tech.md:

• Extract frontend framework from #current-stack (default: React v19 + Next.js v15)
• Extract styling approach (default: TailwindCSS v4)
• Extract state management, testing tools
• If tech.md missing: ask framework/styling via AskUserQuestion

Storybook detection (check alongside tech stack):

• Glob: .storybook/main.* — Storybook installed?
• Grep: "storybook" package.json — Storybook in devDependencies?
• Glob: src/**/*.stories.tsx — Existing stories pattern?
• If detected: set storybook_available = true (used in Steps 5, Phase 2 Output, Step 8)

Step 3: Design System Check

Read $JAAN_CONTEXT_DIR/design.md and $JAAN_CONTEXT_DIR/brand.md if available:

• Extract color tokens, typography, spacing scale
• Identify existing component patterns to extend
• Note brand guidelines affecting component appearance

Step 4: Clarify Architecture

AskUserQuestion for items not in tech.md or design.md:

• State management (TanStack Query only / + Zustand / + URL state via nuqs)
• Routing (App Router / Pages Router / custom)
• Testing (Vitest + Testing Library / Playwright / both)
• Responsive strategy (mobile-first / desktop-first / adaptive)

Step 5: Plan Component Tree

Present component tree with atomic design levels:

COMPONENT TREE
══════════════

STACK: {framework} + {styling} + {state_management}

COMPONENTS ({count} total)
──────────────────────────
Atoms:     {list with estimates}
Molecules: {list with estimates}
Organisms: {list with estimates}
Templates: {list}
Pages:     {list}

API HOOKS ({count})
───────────────────
{list of TanStack Query hooks with endpoints}

TYPES ({count})
───────────────
{list of TypeScript interfaces from API schemas}

STORIES ({count} — if Storybook detected)
──────────────────────────────────────────
{list of CSF3 story files to generate, one per component}

---

HARD STOP — Review Scaffold Plan

Use AskUserQuestion:

• Question: "Proceed with generating the frontend scaffold?"
• Header: "Generate"
• Options:
  • "Yes" — Generate the scaffold code
  • "No" — Cancel
  • "Edit" — Let me revise the component tree or architecture first

Do NOT proceed to Phase 2 without explicit approval.

---

PHASE 2: Generation (Write Phase)

Phase 2 Output — Flat folder

All files in $JAAN_OUTPUTS_DIR/frontend/scaffold/{id}-{slug}/:

{id}-{slug}/
├── {id}-{slug}.md                     # Main doc (architecture + component map)
├── {id}-{slug}-components.tsx          # React components
├── {id}-{slug}-hooks.ts               # Typed API client hooks
├── {id}-{slug}-types.ts               # TypeScript interfaces from API schemas
├── {id}-{slug}-pages.tsx               # Page layouts / routes
├── {id}-{slug}-config.ts              # Package.json + tsconfig + tailwind config
├── {id}-{slug}-stories.tsx            # CSF3 Storybook stories (if Storybook detected)
├── {id}-{slug}-orval-config.ts         # → project root: orval.config.ts
├── {id}-{slug}-msw-handlers.ts         # → src/mocks/handlers.ts
├── {id}-{slug}-msw-browser.ts          # → src/mocks/browser.ts
├── {id}-{slug}-msw-server.ts           # → src/mocks/server.ts
└── {id}-{slug}-readme.md              # Setup + run instructions

Include Source → Destination mapping table in {id}-{slug}-readme.md for dev-output-integrate to consume.

Step 6.5: Generate API Integration Layer (if backend-api-contract provided)

When an API contract (OpenAPI spec) is available from inputs:

1. Generate {id}-{slug}-orval-config.ts — Orval configuration:

   • input.target: relative path to the spec file
   • output.client: 'react-query' (TanStack Query v5)
   • output.target: './src/lib/api/generated'
   • output.schemas: './src/lib/api/schemas'
   • output.mock: true (generates MSW handlers)
   • output.mode: 'tags-split'

2. Generate {id}-{slug}-msw-handlers.ts — MSW request handlers from spec:

   • For each endpoint: success handler (200/201), error handler (4xx/5xx with RFC 9457 shape)
   • Import pattern: import { http, HttpResponse } from 'msw'

3. Generate {id}-{slug}-msw-browser.ts — MSW browser setup:

   import { setupWorker } from 'msw/browser';
   import { handlers } from './handlers';
   export const worker = setupWorker(...handlers);
   

4. Generate {id}-{slug}-msw-server.ts — MSW Node.js server setup:

   import { setupServer } from 'msw/node';
   import { handlers } from './handlers';
   export const server = setupServer(...handlers);
   

5. Update {id}-{slug}-config.ts: add to devDependencies: orval, msw, msw-storybook-addon. Add script: "generate:api": "orval --config ./orval.config.ts".

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/openapi-integration-reference.md for Orval config patterns, MSW handler patterns, and flat output conventions.

Step 7: Generate Content

Read $JAAN_TEMPLATES_DIR/jaan-to-frontend-scaffold.template.md and populate all sections based on Phase 1 analysis.

If tech stack needed, extract sections from tech.md:

• Current Stack: #current-stack
• Frameworks: #frameworks
• Constraints: #constraints

Step 8: Quality Check

Validate generated output against checklist:

• All components from task breakdown inventory generated
• Server Components default; 'use client' only where needed
• TypeScript interfaces match API contract schemas
• TanStack Query hooks for client-side data fetching
• Loading/error/empty/success states on all data components
• Accessibility: ARIA, semantic HTML, keyboard nav
• No anti-patterns present in generated code
• Framework-implied build dependencies included (e.g., babel-plugin-react-compiler when reactCompiler: true)
• CSF3 stories generated for each component (if storybook_available) — see ${CLAUDE_PLUGIN_ROOT}/docs/extending/frontend-ui-workflow-reference.md section "CSF3 Story Format Spec"

If any check fails, fix before preview.

Step 9: Preview & Approval

Present generated output summary. Use AskUserQuestion:

• Question: "Write scaffold files to output?"
• Header: "Write Files"
• Options:
  • "Yes" — Write the files
  • "No" — Cancel
  • "Refine" — Make adjustments first

Step 10: Generate ID and Folder Structure

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/frontend/scaffold"
mkdir -p "$SUBDOMAIN_DIR"
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")
slug="{project-name-slug}"
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"

Preview output configuration:

Output Configuration

• ID: {NEXT_ID}
• Folder: $JAAN_OUTPUTS_DIR/frontend/scaffold/{NEXT_ID}-{slug}/
• Main file: {NEXT_ID}-{slug}.md

Step 11: Write Output

1. Create output folder: mkdir -p "$OUTPUT_FOLDER"
2. Write all scaffold files to $OUTPUT_FOLDER
3. Update subdomain index:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
  "$SUBDOMAIN_DIR/README.md" \
  "$NEXT_ID" \
  "${NEXT_ID}-${slug}" \
  "{Project Title}" \
  "{Executive summary — 1-2 sentences}"

4. Confirm completion:

Scaffold written to: $JAAN_OUTPUTS_DIR/frontend/scaffold/{NEXT_ID}-{slug}/ Index updated: $JAAN_OUTPUTS_DIR/frontend/scaffold/README.md

Step 12: Suggest Next Actions

Scaffold generated successfully!

Next Steps:

• Copy scaffold files to your project directory
• Run npm install to install dependencies
• Run /jaan-to:frontend-story-generate to generate additional Storybook stories
• Run /jaan-to:frontend-visual-verify to visually verify components (requires Playwright MCP)
• Run /jaan-to:dev-output-integrate to integrate scaffold into project
• Run /jaan-to:qa-test-cases to generate test cases

Step 13: Capture Feedback

Use AskUserQuestion:

• Question: "How did the scaffold turn out?"
• Header: "Feedback"
• Options:
  • "Perfect!" — Done
  • "Needs fixes" — What should I improve?
  • "Learn from this" — Capture a lesson for future runs

If "Learn from this": Run /jaan-to:learn-add frontend-scaffold "{feedback}"

---

Key Generation Rules (Research-Informed)

React 19 Patterns (CRITICAL — differs from React 18):

• Server Components are default — only add 'use client' when needed
• async/await in Server Components, NOT useEffect + useState
• use(promise) with Suspense, NOT useEffect; never create promises during render (infinite loops)
• ref is a regular prop, NOT forwardRef
• React Compiler (stable v1.0, October 2025) handles memoization — no useMemo/useCallback/React.memo; enable in next.config.ts with { reactCompiler: true }; requires babel-plugin-react-compiler in devDependencies; up to 12% faster initial loads
• useActionState + useFormStatus (must be in child component of <form>) for forms
• Server Actions for mutations, ES6 default parameters (NOT defaultProps)
• <Context.Provider> deprecated — use <Context> directly
• ref callbacks support cleanup functions

TailwindCSS v4 Patterns:

• CSS-first config: @import "tailwindcss" + @theme { } — NO tailwind.config.js
• Dark mode: @custom-variant dark (&:where(.dark, .dark *)) + next-themes
• cn() helper (clsx + tailwind-merge), OKLCH colors
• v3→v4 breaking syntax: !bg-red-500 → bg-red-500! (suffix), @layer utilities → @utility, bg-[--my-var] → bg-(--my-var); requires Safari 16.4+, Chrome 111+, Firefox 128+
• PostCSS uses @tailwindcss/postcss as single plugin — autoprefixer is built-in
• Content detection is automatic (no content array)

Component Generation:

• 4 states per data component: loading, error, empty, success
• Atomic Design: Atoms -> Molecules -> Organisms -> Templates
• Feature-based organization, aria-* on all interactive elements
• Minimum 24x24px touch targets (WCAG 2.2 AA); 44x44px recommended (AAA / mobile guideline)
• Use semantic HTML (<button>, <nav>, <main>) before ARIA; enforce with eslint-plugin-jsx-a11y

API Integration:

• Orval v7 for TypeScript types + TanStack Query hooks from OpenAPI (ready-to-use useQuery/useMutation with auto-generated keys)
• Alternative: openapi-typescript (~1.68M weekly downloads) generates only TypeScript types with zero runtime; companion openapi-fetch provides type-safe createClient<paths>() wrapper; requires manually writing TanStack Query hooks but offers more control
• TanStack Query v5 for client-side fetching; HydrationBoundary for RSC → client data handoff (prefetch with queryClient.prefetchQuery(), dehydrate cache, wrap in <HydrationBoundary state={dehydrate(queryClient)}>)
• Use queryOptions() factories for type-safe, reusable query definitions with hierarchical key factories
• Separate generated API code into src/lib/api/generated/ — treated as dependency, never hand-edited
• Add "generate:api": "orval --config ./orval.config.ts" to package.json

State Management:

• Server/API data → TanStack Query v5
• Local state → useState/useReducer
• Global client state → Zustand v5 (no Provider needed, ~1KB gzip); use targeted selectors to minimize re-renders
• URL state → nuqs v2.5+ (used by Sentry, Supabase, Vercel); type-safe parsers, server-side via createLoader()
• Form state → useActionState + useFormStatus
• Optimistic UI → useOptimistic (React 19); instant UI feedback, auto-reconcile or rollback

Next.js 15 Caching:

• fetch() defaults to no-store (was force-cache in v14); opt into caching with cache: 'force-cache' or next: { revalidate: 3600 }
• unstable_cache deprecated — use 'use cache' directive with cacheTag() and cacheLife()
• Server Actions for internal mutations; Route Handlers (route.ts) for external consumers
• ESLint 9 flat config (eslint.config.mjs) replaces .eslintrc.json

CSF3 Story Patterns (when storybook_available):

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/frontend-ui-workflow-reference.md for CSF3 format spec, CVA variant detection, argTypes controls, and state coverage matrix.

• Generate one {ComponentName}.stories.tsx per component
• Use Meta<typeof Component> + StoryObj<typeof meta> pattern
• Cover: Default, Loading, Error, Empty, each CVA variant
• Declarative args objects only (no render functions)
• Match existing story conventions from project's *.stories.tsx files

Anti-Patterns to NEVER Generate

React 19: useEffect for data fetching, forwardRef, manual memoization (useMemo/useCallback/React.memo), defaultProps, PropTypes, <Context.Provider>

Next.js 15: 'use client' everywhere, API routes for internal mutations, unstable_cache (deprecated — use 'use cache' directive with cacheTag()/cacheLife()), next lint (removed in Next.js 16 — use ESLint CLI with eslint.config.mjs flat config)

TailwindCSS v4: tailwind.config.js, dynamic class construction, @tailwind directives, v3 bang syntax (!bg-red-500), @layer utilities

Accessibility: <div onClick>, missing alt, color-only indicators, missing form labels

Package Dependencies (Research-Validated)

Production: react ^19, react-dom ^19, next ^15, @tanstack/react-query ^5.60, zustand ^5, nuqs ^2.5, next-themes ^0.4, clsx ^2.1, tailwind-merge ^2.6, zod ^3.23, axios ^1.7

Dev: typescript ^5.7, @types/react ^19, @types/node ^22, @tailwindcss/postcss ^4, tailwindcss ^4, eslint ^9, prettier ^3.4, orval ^7, vitest ^2, @testing-library/react ^16, eslint-plugin-jsx-a11y, babel-plugin-react-compiler (when reactCompiler: true)

---

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Framework-agnostic with tech.md detection
• Template-driven output structure
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

• All components from frontend-task-breakdown inventory generated
• Server Components default; 'use client' only where needed
• TypeScript interfaces from API contract schemas
• TanStack Query hooks for client-side data fetching
• Loading/error/empty/success states on all data components
• Accessibility: ARIA, semantic HTML, keyboard nav
• TailwindCSS v4 CSS-first config
• Responsive mobile-first breakpoints
• CSF3 stories generated per component (if Storybook detected)
• Setup README complete
• Output follows v3.0.0 structure
• Index updated with executive summary
• User approved final result