CLAUDE.md Design Instructions: A Template for Consistent UI

A useful CLAUDE.md design template names the existing design tokens, reusable components, responsive requirements, and checks that define an acceptable interface change. Replace vague requests for “polish” with constraints someone can inspect. Tools like fenbs keep the approved design decisions and implementation tasks together, so a future assistant can understand why those constraints exist.

Start with the product you already have. A template should help Claude preserve its visual language and improve a specific screen. It should not quietly authorize a new brand, component library, or navigation structure. The person reviewing the change needs to recognize both the requested improvement and the existing product.

What should the design instructions describe?

Include the information a contributor would otherwise have to ask a designer: which source is approved, where colors and spacing are defined, which components to reuse, and what states the change must cover. Name real files and examples after inspecting the repository. A path guessed from another project can be worse than no path.

• Visual foundations: token names, typography, spacing, surfaces, and supported themes.
• Component conventions: existing buttons, inputs, dialogs, menus, and patterns to reuse.
• Interaction behavior: keyboard operation, focus, validation, loading, empty states, and errors.
• Responsive expectations: content priorities and behavior on narrow and wide screens.
• Review evidence: which screens and states to inspect, and which checks to report.

Anthropic’s CLAUDE.md documentation↗ (opens in a new tab) recommends concrete instructions that can be verified. “Reuse the shared dialog component” is actionable when you name its location. “Make it modern” leaves the assistant to invent a design direction and gives the reviewer no shared standard.

What can you copy as a starting template?

This example describes an imaginary customer portal. Replace its paths and choices with your project’s approved ones before using it. If a requirement is still undecided, mark the question for a person rather than presenting the example as an established policy.

# Interface design
## Sources
Read docs/design/approved-patterns.md before UI changes.
Use src/styles/tokens.css for colors, spacing, and typography.
Use the current account screen as the reference for form layout.

## Components
Reuse components in src/components/ui.
Check existing variants before adding a new variant or component.
Do not add a UI dependency without a person approving it.

## Behavior
Preserve keyboard access and visible focus.
Give inputs associated labels and actionable error text.
Include loading, empty, error, and success states where relevant.
Check narrow and wide layouts and each supported theme.
Keep long content from causing page-wide horizontal scrolling.

## Review
Keep the change within the requested screen and behavior.
Describe the visual change and why it helps the user.
Report the screens, states, and checks actually inspected.
Do not claim accessibility or browser checks that were not run.
Ask before changing approved navigation or brand decisions.

Keep the template short enough to read with the task. Detailed component specifications can remain in their own documents. The instruction file should identify the authoritative source and the relevant review boundaries. It does not need to contain every style value or a complete design history.

For the general file structure, see the CLAUDE.md guide; for more instruction patterns, see CLAUDE.md examples. Use this design section to express your own system rather than copying another product’s visual choices.

How do you make visual rules measurable?

Translate an adjective into a choice and a check. “Consistent” might mean using the existing field component and its spacing. “Readable” might mean checking the approved text size with a realistic paragraph and long labels. A measurable instruction tells the assistant what to do and tells a person what evidence to inspect.

Choose requirements that reflect actual user needs. A dense desktop table may need a different reading order on a phone; shrinking every column does not resolve the task. State what the person must still be able to read or do. Leave implementation choices open when the existing system already supports several valid solutions.

Keep the person’s approved tradeoffs in fenbs Decisions and rules. The file can state the current constraint while the shared record explains why the team chose it.

Which accessibility checks belong in the template?

Include the checks the team can actually perform, and distinguish guidance from completed verification. W3C’s form labeling tutorial↗ (opens in a new tab) explains how labels identify controls and connect them to assistive technology. Its heading guidance↗ (opens in a new tab) describes headings as a way to organize page sections. These are useful sources for specific review requirements.

For example, ask the assistant to preserve associated input labels, use meaningful heading structure, and report keyboard testing. Also ask it to identify any state it could not inspect. An instruction to “meet accessibility standards” alone neither defines the work nor proves that the finished screen is accessible.

Test with realistic content, including long names, validation errors, and empty results. A layout that looks balanced with two short labels can fail with ordinary customer data. Use invented sample content for review rather than copying sensitive information into screenshots or prompts.

How do you stop small changes from becoming redesigns?

Give the task a visible boundary. A request to fix a clipped dialog title should name the dialog and the behavior to preserve. Ask the assistant to identify any broader change it thinks is needed before implementing it. That allows a person to separate a necessary fix from an optional improvement.

Keep approved decisions distinct from suggestions. If a person selected a compact navigation pattern, an assistant can point out a usability concern and propose an alternative. It should not treat that proposal as approval to rebuild navigation. Record the open question, show the tradeoff, and continue work that does not depend on its answer.

A review should inspect the diff as well as the screen. Unrelated component replacements and new dependencies can hide behind a visually small result. The broader Claude design guide covers design work; this template keeps the repository instructions focused on implementing the approved direction.

How should you verify the template before sharing it?

Try it on one modest change, such as an account form error state. Ask Claude to identify the source components and relevant constraints before editing. Then inspect whether it reused the expected components, handled the required states, and reported the checks honestly.

If the result is wrong, first check the instructions and references. A renamed component or contradictory example needs correction, not more emphatic wording. Our CLAUDE.md troubleshooting guide helps separate missing context from ambiguous instructions. Revise one cause at a time so the next trial tells you something useful.

How to do this with fenbs

1. Create a free account and add the product or website project.
2. Record the design decisions a person has approved, including their scope and reason. Keep undecided alternatives as open decisions.
3. Add the UI task and a plan naming the affected screen, reference components, and review checks.
4. Connect a supported assistant through Integrations, ask it to read the project context, and have it apply the repository’s current design instructions.
5. Save the actual review results and Where we left off. Record an uninspected state as unfinished verification rather than calling it complete.

fenbs does not render your interface, inspect screenshots, or replace a component library. If you only need to document a few stable styles, a short repository file may be enough. A shared record helps when several people and assistants need the approved choices and the tasks implementing them. Find more instruction patterns in the AI prompts hub.