Direct answer
Make the design system available to Claude Code through rules, component source, and MCP tools. Ask Claude to load those rules before editing. Scope each task to one user outcome, reuse components, then review the states.
What should Claude Code receive from the design system?
Do not paste the entire design manual into every task. Keep durable rules in the repository, keep component source in code, and let Claude retrieve focused guidance when it needs it.
- Semantic tokens for surfaces, text, actions, borders, focus, and status.
- Editable components with real behavior and accessibility.
- Repository instructions that say where the system lives and when to reuse it.
- UI and UX guidance for decisions the components do not settle.
- Review rules and project commands that define evidence of completion.
What workflow should Claude Code follow?
The design-system agent loop
Claude Code should load the system before editing and return review evidence after the build.
- Load system: Retrieve the tokens, components, and rules relevant to the screen.
- Scope task: Name one user outcome and what must remain unchanged.
- Build: Reuse approved primitives before adding a new pattern.
- Review: Inspect the diff, browser states, and project checks.
How do you connect Better Design to Claude Code?
Claude Code supports remote HTTP MCP servers. Add Better Design once, then confirm the server is connected before asking Claude to use its design-system and review tools.
claude mcp add --scope user better-design --transport http https://better-design.com/api/mcp --header "Authorization: Bearer <YOUR_API_KEY>"What should the task prompt say?
This prompt names the user, task, system, action hierarchy, required states, viewport, and evidence. It leaves implementation choices open without leaving the design unconstrained.
Improve the billing settings flow for a small-team admin. Keep the current data flow. Load the existing design system plus hierarchy and form guidance before editing. Reuse the current form primitives and semantic tokens. Make changing plans the primary task. Test errors, keyboard flow, and the 390px layout, then summarize the diff and review evidence.How should Claude Code use existing components?
- Search for the current primitive before creating a replacement.
- Compose at the feature layer when existing behavior already fits.
- Change a shared component only when the feature exposes a real system need.
- Keep semantic tokens in the shared theme instead of adding page-specific values.
- Document any new variant so the next agent can reuse it.
What does the final review need to prove?
Compilation proves that the code is valid. It does not prove that the screen is understandable or usable. Ask Claude to open the affected page, use the keyboard, test responsive widths, trigger changed states, and fix critical or serious review findings.
Review the diff separately. A visually convincing result can still duplicate components, escape tokens, or change unrelated behavior.
What does a design system not solve?
A design system cannot decide whether the product solves the right problem, whether the data model is secure, or whether the flow works for real users. It reduces avoidable visual and interaction inconsistency. Product research, engineering review, accessibility testing, and human judgment remain necessary.
Questions
Can Claude Code choose a design system automatically?
It can suggest suitable systems, but the user should choose the direction or explicitly request a custom one. That decision affects the whole product and should remain visible.
Should Claude Code rewrite existing components?
Usually no. It should compose the project's existing primitives first and change shared components only when the requested behavior cannot be expressed cleanly at the feature layer.
Should the design system live only in CLAUDE.md?
No. Repository instructions should point to the system and explain the workflow. The actual tokens and components should remain versioned source, while focused guidance can be retrieved through tools such as MCP.
Is a screenshot enough to verify Claude Code UI?
No. A screenshot covers one state and size. Interactive work also needs keyboard, focus, loading, error, long-content, responsive, and code-diff checks.