AIClaudeWorkflowDesign Systems

Using Claude to Build UI From Your Design System

DesignDNA Team4 min read

Claude is one of the best AI coding assistants available. It writes clean, well-reasoned code, follows complex instructions precisely, and handles multi-file context better than most models. But without your design system as context, it will invent visual decisions you didn't ask for.

Here's the workflow we use at DesignDNA — and recommend to every team that scans a site with us.

The Problem: AI Design Drift

Ask Claude to "build a settings page" and you'll get something functional. But it will likely:

  • Use hardcoded colors (#3B82F6) instead of your CSS variables (var(--color-primary))
  • Pick a border radius that doesn't match your component library
  • Choose a font weight that feels slightly off from your headings
  • Create spacing that's close to — but not exactly — your 4px grid

None of these are bugs. Claude doesn't know your design system, so it makes reasonable defaults. The problem compounds with every prompt: after ten interactions, your codebase has ten new implicit "decisions" that diverge from your actual system.

The Solution: design.md as System Prompt Context

The fix is simple: give Claude your design.md file as part of every conversation.

In Claude's Projects feature, you can upload files as project knowledge. Upload your design.md there, and every conversation in that project will have your full design system as context — without you having to paste it every time.

For Cursor or Windsurf, drop design.md in your project root and reference it in .cursorrules:

# .cursorrules
Always follow the design system documented in design.md.
Never use hardcoded color values — use the CSS variables defined there.
For spacing, use only values from the spacing scale in design.md.
For border-radius, use only values from the radius tokens.

A Real Workflow Example

Let's say you want a new "Danger Zone" section on a settings page — the kind with a red-tinted destructive action.

Without design.md, you might prompt:

"Add a danger zone section to the settings page with a delete account button."

Claude outputs something with bg-red-50 border-red-200 text-red-700 — Tailwind defaults, not your tokens.

With design.md, you prompt:

"Add a danger zone section to the settings page with a delete account button. Follow design.md."

Claude now knows:

  • Your destructive color is var(--color-destructive) → #EF4444
  • Your card component uses border border-border rounded-[var(--radius-lg)] bg-surface
  • Your body text is text-[15px] text-ink-soft
  • Your destructive button variant is bg-destructive text-white hover:bg-destructive/90

The output matches your system exactly — without a single revision.

Prompting Patterns That Work

Here are the prompting patterns we've found most effective:

Pattern 1: Component Generation

Using design.md as your reference, create a [component name] component.
It should support these variants: [list].
Use our existing token naming conventions for all styles.

Pattern 2: Page Assembly

Build the [page name] page layout.
Reference design.md for:
- The navigation pattern
- Card and surface styles
- Typography hierarchy (h1 → section heading → body)
- Spacing between sections

Pattern 3: Design Review

Review this component against design.md.
List any values that don't match our design tokens and suggest the correct token references.

Pattern 4: Migration

I have this legacy component that uses hardcoded values.
Migrate it to use our design system tokens from design.md.
Preserve all functionality — only update the styling references.

Keeping design.md in Sync

The biggest maintenance challenge: your design system evolves, but design.md can fall out of sync.

Two strategies:

  1. Regenerate on change — whenever you update your CSS variables or component library, re-scan your staging site with DesignDNA to get a fresh design.md. This takes 30 seconds.

  2. Track it in version control — treat design.md like any other code file. Review changes in PRs. When a designer updates the primary color, the token change and the design.md update go in the same commit.

We're building automated sync features — watch this space.

The Bigger Picture

The real value of this workflow isn't just cleaner AI output. It's that your design system becomes a first-class artifact in your engineering workflow.

When design.md lives in your repo, it's:

  • Readable by every developer (no Figma account needed)
  • Queryable by AI agents (no schema required)
  • Diff-able in PRs (you can see exactly what design decisions changed)
  • Portable (works with any AI tool that accepts file context)

This is what we built DesignDNA to enable. The scanner is the easy part — getting teams to actually work this way is the harder problem. But once you do, the results are clear.

Generate your design.md in 30 seconds — scan your site with DesignDNA →

Back to Blog