Workflow
How to make Claude Code design better UI
A practical loop for using Claude Code with stronger visual output.
Start with a file, not a vibe
The most common mistake when trying to get better UI from Claude Code is including a longer or more detailed style description in the prompt. Detailed one-time descriptions — "make it modern, minimal, with good visual hierarchy and consistent spacing" — are forgotten when the session ends and cannot be referenced by future sessions. Even within a single session, long style descriptions compete with the task description for context weight and produce inconsistent results across components. DESIGN.md solves both problems. It is a stable file that Claude Code can read at the start of every session, separate from the task prompt so it does not crowd the instruction. It grows over time to cover more surfaces as the product matures. The shift from in-prompt style instructions to a maintained DESIGN.md file is the single most effective change you can make to improve the visual quality of Claude Code's output across an entire project.
What a strong design brief includes
A design brief for Claude Code is not a mood board or a list of adjectives. It is a set of implementable rules that the agent can check against generated code. The brief should cover product personality (one short paragraph), color tokens with semantic roles, type scale with exact sizes and weights for each heading level, spacing values with use contexts mapped to specific pixel values, component rules for the most common UI elements, page layout patterns for the main product surfaces, and anti-patterns that explicitly prohibit common AI-generated UI mistakes. Each rule should be specific enough to produce a unique implementation decision. "Cards should feel clean" is not a rule. "Cards use 16px padding, 8px radius, no shadow, and a 1px neutral-200 border" is a rule. The difference between these two instruction types is the difference between a result that Claude Code interprets loosely and a result that matches the spec consistently.
Reference real examples
Claude Code benefits from concrete references alongside abstract rules. After stating a rule in DESIGN.md, point to an existing component that implements it correctly: "See the DashboardCard component for an example of the standard card pattern." This gives the agent a code-level reference that is more reliable than a text description alone. If the product has a screenshot or a Figma link that illustrates a pattern, include it in the DESIGN.md under the relevant rule. Claude Code can use visual references to anchor its implementation choices alongside text rules. This is especially valuable for layout patterns and page structures where prose descriptions are harder to be precise about. Combining a text rule with an existing code example gives Claude Code two alignment points for each major design decision, making the output significantly more consistent across sessions and across different feature surfaces.
The iterative prompt loop
Working with Claude Code on UI is most effective when treated as an iterative process with a clear rhythm. The first step is to have Claude Code read DESIGN.md and list the relevant rules for the current task. This makes its interpretation of the spec explicit before any code is written. The second step is implementation: build the component or feature with the stated rules as constraints. The third step is self-review: ask Claude Code to compare its output against DESIGN.md and identify any rules that were violated or interpreted ambiguously. The fourth step is correction or spec update: if the output is wrong, correct it with a specific reference to the violated rule; if the rule was unclear, update DESIGN.md to be more explicit before the next session. This loop produces both better UI and a progressively better spec, because each session starts with more accurate context than the last.
Review and tighten
Reviewing Claude Code's UI output against DESIGN.md is faster than open-ended visual review. Instead of asking "does this look right?" — which requires holding the entire design system in your head — you check each relevant rule in the file against the generated component. Does the card use the correct padding? Is the button the right variant for this action? Does the empty state follow the defined pattern? Are any anti-patterns present? This structured review takes minutes and produces precise feedback that Claude Code can apply directly. When you find a violation, the feedback is not "this does not look right" but "the card radius should be 8px per DESIGN.md, not 12px." Precise feedback improves the next session because it resolves the specific ambiguity that caused the mistake. When no violations are found, note that the spec is working for this surface and move forward without additional comment.
When Claude Code gets the design right
There is a qualitative difference in working with Claude Code once a well-maintained DESIGN.md is in place. The back-and-forth about visual details decreases noticeably. The number of rounds required to get a component to production quality drops. Reviews shift focus from padding and color to behavior and logic. Claude Code starts proposing design solutions that are on-brand rather than asking for clarification on basic visual choices. These improvements do not happen immediately after writing the first version of the file; they develop as the file is refined through real usage over several weeks. After consistent use and maintenance, DESIGN.md becomes a tested specification that Claude Code reliably follows. At that point, the agent is generating consistent, on-brand UI that needs minimal adjustment — which is the goal of every product team using AI tools to build and maintain a real product.
Use DESIGN.md with a real product reference
Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.
Related guides
How to make Cursor generate better frontend design
Use stable design memory instead of rewriting visual instructions in every chat.
How to create a DESIGN.md from a website
Turn an existing product surface into a reusable AI-readable design brief.
DESIGN.md for Kiro
How to use DESIGN.md with Kiro, the AWS agentic IDE built around specs, steering, hooks, and production-minded implementation.