Component Development on Your Design System

Arjun's month is the defining component-development problem of the AI era: the tools generate a design system fluently — just not yours. Left unconditioned, every assistant on the team converges on the same generic output, and your design system dies by a thousand plausible duplicates. The fix is not better reviewing. It is conditioning the generator before it types: telling it what exists, showing it what good looks like, and — at the advanced tier — wiring it to query the truth instead of trusting it to remember. This module covers that discipline end to end, then applies the same grounding mindset to the rest of the component workload: forms, Storybook, state refactors, data layers, and typed API clients.

What You'll Learn

• Instruction files and few-shot exemplarsthe conditioning that makes any generator emit on-system code
• Registry and Storybook MCP groundingagents fetch real props instead of hallucinating them
• Schema-first form generationevery state enumerated before the first render
• Storybook as the agent's verification loopstories as the visual contract
• State and data-layer refactorsrun under characterization-test protection
• Typed API clients and MSW mocksgenerated from the schema, drift-checked in CI

Conditioning the Generator: Instruction Files and Exemplars

Every serious assistant now reads a persistent instruction file from the repo — Copilot's .github/copilot-instructions.md, Cursor rules, Claude Code's CLAUDE.md. For frontend teams this file is the single highest-leverage artifact you can write, because it runs on every generation by every teammate. The generic version ("use TypeScript, follow our conventions") does nothing. The version that works is concrete and mechanical:

• Name the system explicitly"All UI comes from @acme/ui. Never create a component that duplicates an existing primitive. Before writing any button, input, card, dialog, or badge, use the existing one."
• Enumerate the tokens"Colors only via var(--color-*) / Tailwind theme tokens. No raw hex, no arbitrary values like p-[13px]. Spacing uses the 4px scale tokens."
• State the states"Every component with async data renders loading, empty, error, and populated states. Every form field renders error and disabled states."
• Encode the a11y floor"Interactive elements are semantic (button, a, label). Every input has an associated label. Focus states are never removed." (M5 deepens this.)
• Point to exemplars"When generating a new component, follow the structure of src/components/DataCard/ — it is the reference implementation."

The exemplar line is the underrated half. Models are few-shot learners: one actual component from your codebase in context — with its prop patterns, token usage, test file, and story — moves output quality more than a page of prose rules. Keep two or three "gold" components deliberately polished and small, and reference them by path so agentic tools open and imitate them.

Registry-Grounded Generation: From Memory to Query

Instruction files reduce hallucination; they cannot eliminate it, because the model is still generating your component APIs from memory it doesn't have. The structural fix is MCP grounding: give the agent a tool that returns the truth.

A shadcn-style registry MCP server (or an internal registry server, or the Storybook MCP addon) lets the agent do what you would do — look up the component, read its actual props and variants, and install or import the real thing. The workflow difference is stark, and Lab 03 has you measure it directly by requesting the same data-table screen with and without the registry wired:

The same grounding logic extends to Storybook: the Storybook MCP addon exposes your stories — component inventory, states, controls — as queryable context, which both grounds generation and gives agents a render target for verification (below).

Schema-First Forms: Enumerate Every State Up Front

Forms are the highest-frequency frontend task and the place where generated happy paths hurt most, because the unhappy paths carry the business logic: validation, server rejection, double-submit, dirty-state warnings. The pattern that works is schema-first with state enumeration: define the Zod schema yourself (it is the contract — human work), then have AI generate the react-hook-form wiring with the full state matrix demanded explicitly:

Given this Zod schema [paste], generate the form component using
react-hook-form + our FormField primitives (see src/components/Form/).
Enumerate and render ALL of: per-field validation errors, form-level
server error, dirty-unsaved warning, disabled-while-submitting,
submit success, and empty/initial. No state may be represented
only in comments.

Then hand-verify the unhappy paths in the browser — submit with the network failing, double-click submit, navigate away dirty. The model enumerates flawlessly when told to; it is the telling that is the skill, and the manual unhappy-path pass that is the review.

Storybook as the Agent's Verification Loop

Text-only generation is open-loop: the model emits JSX and never sees a pixel. Storybook closes the loop cheaply. The workflow: have the agent generate (or update) stories for every variant and state alongside the component; run Storybook; the agent (via the MCP addon or a screenshot tool) — and you, in two seconds of scanning — verify each state actually renders as intended. Stories become three things at once: the generation contract ("these states must exist"), the visual review surface, and the input to visual-regression gates later (M5). A component PR without stories for its states is, under this discipline, incomplete by definition — for humans and agents alike.

Refactoring State and Data Layers Under Protection

The second half of component work is not greenfield — it is evolving the client architecture you already have: prop-drilling that needs scoped stores, useEffect-fetch spaghetti that needs TanStack Query. AI is genuinely strong at the mechanical conversion and genuinely dangerous at the semantics, so the discipline is sequence:

1. 1Map first. Have the agent inventory the data flow: who reads this state, who writes it, what re-renders when it changes. This read-only analysis is high-trust output — errors surface immediately when you spot-check.
2. 2Pin behavior. Generate characterization tests that capture current user-visible behavior (RTL, accessible queries) before touching anything. These tests are the safety net, so review them hardest — decorative assertions here mean an unprotected refactor.
3. 3Stage the refactor. Convert one slice at a time — one context to one store, one fetch to one query hook — with the pinned tests green after each step. Reject any agent plan whose first move is "rewrite the state layer."
4. 4Review the semantics yourself. Cache keys, invalidation, optimistic updates, stale-time: these encode product decisions (what may be stale? what must refetch on focus?) the model cannot know. The mechanical conversion is delegated; the cache-semantics review is not.

The last row is its own quick win: openapi-typescript or GraphQL codegen plus AI glue turns a schema into typed fetch hooks and MSW handlers in one pass. Put a drift check in CI (regenerate and diff against the committed client) so the contract cannot silently rot — the AI-era version of "the mock lied."

Try It Now

1. 1Write the instruction file. Draft your repo's generation rules today: system import path, token rules, state requirements, a11y floor, and two exemplar component paths. Commit it as CLAUDE.md / Copilot instructions and generate one small component to compare before/after.
2. 2Run the grounding A/B. Ask your agent for a screen using your design system twice — once cold, once with your registry or Storybook MCP (or, minimally, with your component index pasted into context). Count hallucinated props and duplicated primitives in each. Keep the diff; it is your business case.
3. 3Enumerate a real form. Take one production form you own, list its actual states, then run the schema-first prompt and diff the generated state matrix against reality. Any state the generator produced that production lacks is a bug you just found for free.

Your playbooks & labs

This module's playbooks: pb-02 (Instruction Files That Keep Generated UI on Your Design System), pb-03 (Registry-Grounded Generation), pb-04 (Schema-First Forms), pb-05 (Complex Interactions: AI Scaffolds, You Own the Last 30%), pb-06 (Storybook as the Agent's Visual Verification Loop), pb-07 (Typed API Clients and MSW Mocks from the Schema), and pb-08 (State and Data-Layer Refactors with Characterization Protection). Lab 01 grades your instruction files with an automated on-system lint; Lab 03 is the registry A/B with a comparison memo.

Further Reading

• •
  GitHub Copilot — Repository custom instructions — the mechanics of instruction files.
• •
  shadcn registry MCP ecosystem — registry servers for grounded generation.
• •
  jaan.to — The MCP foundation: four servers, one coherent context layer — the Storybook + registry + agent workflow in production.
• •
  TanStack Query docs — the cache-semantics vocabulary you'll be reviewing.
• •
  MemU — Why v0-style output repeats itself — the off-system generation critique in depth.