How to Create a UI Design Skill Using design.md

Every team has a design system. Almost no team has one that an AI agent actually respects. You can paste your style guide into a Claude conversation and watch the next reply use the right colors. Open a new chat and the agent is back to inventing hex codes.

The fix is to stop treating your design system as documentation and start treating it as a Skill — a packaged capability your AI agent installs once and reaches for automatically every time it touches UI. The artifact at the heart of that Skill is a single Markdown file: design.md. Done well, design.md gives an agent everything it needs to produce work that looks like your team made it.

This tutorial walks through building one end to end. What goes in design.md, how to wrap it as a Skill, how the agent invokes it, and how to maintain it without it becoming a museum piece. By the end you will have a working UI Design Skill that ships with your project and travels with every conversation.

Recap — What a Skill Is

If you have read AI Skills vs Prompts you can skip this section. The 30-second version: a Skill is a folder on disk that registers a capability with your AI agent. It contains a SKILL.md file with frontmatter and instructions, plus optional supporting files. The agent reads the frontmatter, learns what the Skill does and when to use it, and invokes it automatically when the user's intent matches.

A UI Design Skill is one specific application of that pattern: a Skill whose job is to make every UI the agent produces conform to your team's actual design system. The work lives in the supporting file design.md, which the Skill loads on demand.

Why design.md Is the Right Shape

You could put everything inside SKILL.md and call it a day. That works for tiny systems. For real design work it breaks down for three reasons:

• Designers can edit design.md without learning Skill mechanics. SKILL.md is agent infrastructure; design.md is design content. Splitting them lets the designer own the canonical file without touching frontmatter.
• design.md becomes the single source of truth across tools. The same file feeds your AI Skill, your Storybook, your onboarding doc, your contractor briefs. One file, many readers.
• Versioning works cleanly. Design.md changes show up in Git diffs that are readable by humans and reviewable in PRs. You can see when the brand color shifted from coral to indigo because the diff says exactly that.

The pattern across the teams we have seen succeed: a thin SKILL.md that delegates almost everything to design.md, plus a few templates and examples in supporting folders.

The Skill Scaffold

Create the Skill folder. For a project-level Skill, this lives at .claude/skills/ui-design/ in your repo. For a personal Skill that follows you across projects, use ~/.claude/skills/ui-design/.

.claude/skills/ui-design/
  SKILL.md
  design.md
  templates/
    component.tsx.tmpl
    page.tsx.tmpl
  examples/
    good-button.tsx
    bad-button.tsx
  references/
    tokens.json

Five pieces. SKILL.md tells the agent when to invoke and how to start. design.md is the canonical design system. templates/ holds boilerplate files the Skill can copy and adapt. examples/ holds reference implementations — one good, one anti-pattern, paired. references/ holds structured data like a tokens JSON if you have one (for example exported from Figma Tokens or Style Dictionary).

Writing the SKILL.md Frontmatter

The frontmatter is where the agent learns what this Skill is and when to use it. Keep it tight — vague descriptions cause under-invocation, broad ones cause over-invocation.

---
name: ui-design
description: Use this skill whenever the user asks to create, edit, refactor, or review any user-facing UI in this project — React components, pages, layouts, forms, or styling. Load design.md before generating any markup or CSS. Always prefer existing tokens over inventing new values.
---

You are producing UI for this project. Before writing any JSX or CSS, read design.md in this skill folder for the canonical design system. Read references/tokens.json for the exact token values. Use templates/component.tsx.tmpl as the starting shape for new components. When in doubt about a pattern, check examples/ for a working reference.

Hard rules:
1. Never invent a color, font size, spacing value, or radius that is not in design.md. If you genuinely need a new value, add it to design.md first and explain why.
2. Every interactive element must follow the accessibility checklist in design.md.
3. Every component must include a usage comment showing one example invocation.
4. After generating UI, run a self-review against the "anti-patterns" section of design.md and report any violations you found and fixed.

Three things to notice. The description names the exact intents (create, edit, refactor, review) and the exact surface (user-facing UI). The body delegates the substance to design.md instead of inlining it. The hard rules are short and enforceable — each one is something the agent can self-check.

The Seven Sections of a Good design.md

design.md is the substance. The structure that works across web apps, marketing sites, and design systems alike:

Each section gets concrete. Vague advice ("use ample whitespace") is filler; specific rules ("section vertical padding is 96px on desktop, 64px on tablet, 48px on mobile") are usable.

What Each Section Looks Like in Practice

Here are concrete excerpts you can adapt to your own design.md. The whole file is normally 400-1,500 lines — long enough to cover the system, short enough that the agent can hold it in working memory.

Section 1 — Design Tokens

# 1. Design tokens

## Color
- Brand primary: #6366F1 (indigo-500). Use for primary CTAs, links, focus rings.
- Brand secondary: #F472B6 (pink-400). Use sparingly for highlights and accents.
- Neutral scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900. Use 50/100 for surfaces, 700/800/900 for text.
- Semantic: success #10B981, warning #F59E0B, danger #EF4444, info #3B82F6.
- Background: #FFFFFF light mode, #0A0A0A dark mode. No off-white, no off-black.

## Typography
- Font stack: Inter, system-ui, sans-serif.
- Scale: 12 / 14 / 16 / 18 / 20 / 24 / 30 / 36 / 48 / 60 / 72 px. Never use other sizes.
- Line heights: 1.0 (display), 1.2 (heading), 1.5 (body), 1.75 (long-form).
- Weights: 400, 500, 600, 700. Do not use 300 or 800.

## Spacing
- 4px base unit. Allowed multiples: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96, 128.
- Never use 5, 6, 10, 13, etc. — if you need an in-between value, the design needs adjustment, not the spacing scale.

## Radius
- sm: 4px, md: 8px, lg: 12px, xl: 16px, full: 9999px (pills only).
- Inputs and cards: md. Buttons: md. Modals: lg. Avatars: full.

## Shadow
- sm: subtle 0 1px 2px elevation. md: 0 4px 6px (cards). lg: 0 10px 15px (modals). xl: 0 20px 25px (popovers).
- No glow shadows, no colored shadows. Shadows are functional, not decorative.

Section 2 — Component Patterns

# 2. Component patterns

## Button
- Variants: primary, secondary, ghost, danger.
- Sizes: sm (32px), md (40px), lg (48px).
- Padding: horizontal 16px (md), 12px (sm), 20px (lg). Vertical is implicit from size.
- Primary button uses brand primary background, white text. Hover darkens 10%. Active darkens 15%.
- Secondary button uses neutral-100 background, neutral-900 text. Hover goes to neutral-200.
- Ghost button is transparent until hover, then neutral-100 background.
- Disabled state: 40% opacity, cursor not-allowed, no hover effect.
- Focus ring: 2px brand primary with 2px offset.
- Loading state: spinner in place of text, button stays width-stable.

## Input
- Height matches button md (40px).
- Border: 1px neutral-300, becomes brand primary on focus.
- Padding: 12px horizontal, 8px vertical.
- Label sits above the input, 14px medium weight.
- Error state: border becomes danger color, error message below in 13px danger color.
- Help text below input in 13px neutral-600.

## Card
- Background: white (light) or neutral-900 (dark).
- Border: 1px neutral-200 (light) or neutral-800 (dark).
- Radius: md.
- Padding: 24px default.
- Shadow: sm.
- Hover on interactive cards: shadow md, slight 1px Y translate.

Section 3 — Layout Patterns

# 3. Layout patterns

## Container widths
- Marketing pages: max-w-7xl (1280px).
- App pages: max-w-screen-xl (1440px).
- Reading content (blog, docs): max-w-3xl (768px).

## Breakpoints
- sm: 640px, md: 768px, lg: 1024px, xl: 1280px, 2xl: 1536px.
- Mobile-first. Every component must render correctly at 360px.

## Section padding
- Desktop: 96px vertical, 32px horizontal.
- Tablet: 64px vertical, 24px horizontal.
- Mobile: 48px vertical, 16px horizontal.

Section 4 — Accessibility

# 4. Accessibility checklist (non-negotiable)

- Every interactive element is keyboard reachable (Tab) and operable (Enter/Space).
- Visible focus ring on every interactive element.
- Color contrast: 4.5:1 for body text, 3:1 for large text, 3:1 for UI components.
- No information communicated by color alone — always pair color with text or icon.
- Form inputs always have associated labels (label element, not placeholder).
- Error messages reference the input by name and explain the fix.
- All images have alt text. Decorative images use alt="".
- Motion respects prefers-reduced-motion — animations under 200ms are exempt; longer ones must offer reduced variants.
- Modals trap focus and return focus to the trigger on close.
- Heading order is sequential — no skipping h2 to h4.

Section 5 — Interaction & Motion

# 5. Interaction & motion

## Timing
- Quick: 100ms (hover, focus).
- Standard: 200ms (most transitions).
- Slow: 400ms (page transitions, modal entries).
- Never use durations under 80ms (jittery) or over 600ms (sluggish).

## Easing
- Default: cubic-bezier(0.2, 0, 0, 1) — smooth ease-out.
- Entrance: ease-out.
- Exit: ease-in.
- Bounce: cubic-bezier(0.34, 1.56, 0.64, 1) — used sparingly, only on user-triggered success.

## States to cover for every interactive component
1. Default 2. Hover 3. Focus 4. Active 5. Disabled 6. Loading 7. Success (where relevant) 8. Error (where relevant).

Section 6 — Content Voice in UI

# 6. Content voice in UI

- Buttons are verbs. "Save changes" not "Submit". "Send invitation" not "Confirm".
- Empty states explain why the surface is empty and propose the next action.
- Error messages name the problem and the fix in one sentence. "Email is required" not "Invalid input."
- Loading states never say "Loading..." — they name what is loading: "Saving changes…" "Fetching results…".
- Confirmation modals show the consequence, not just "Are you sure?" — "Delete this project? You will lose 47 tasks." not "Are you sure?".
- Tone: direct, friendly, never apologetic. No "Oops!". No "Sorry, something went wrong." Be specific about the problem.

Section 7 — Anti-Patterns

# 7. Anti-patterns — never ship these

- Inventing new hex codes or spacing values not in section 1.
- Using !important in CSS. If you reach for it, the architecture is wrong.
- Buttons styled as links or links styled as buttons. Pick one, commit.
- Placeholder-as-label. Always use a real label element.
- Modals with more than three actions. Three is the limit; if you need four, redesign.
- "Click here" link text. Links must be self-describing.
- Tooltips on touch devices. Tooltips are for hover-capable surfaces only.
- Carousels with auto-rotation. If you must use a carousel, no auto-rotate.
- Form errors that disappear when the user starts typing again. Errors persist until the field is valid.
- Disabled buttons with no explanation. Either show why it is disabled or do not show the button at all.

Adding Templates and Examples

The Skill becomes meaningfully more reliable when you give the agent reference artifacts beyond design.md.

Templates are starting-point files the agent copies and adapts. A typical templates/component.tsx.tmpl:

// Component: {{name}}
// Usage: <{{name}} />

import { cn } from "@/lib/utils";

interface {{name}}Props {
  className?: string;
}

export function {{name}}({ className }: {{name}}Props) {
  return (
    <div className={cn("", className)}>
    </div>
  );
}

The agent uses this as the spine. It fills in the structure, the className, the props — but the file shape, the imports, the className helper, and the props convention are anchored.

Examples teach the agent what good and bad look like. Pair them. examples/good-button.tsx is a button implemented to design.md spec. examples/bad-button.tsx is the same button with the most common anti-patterns. The pairing is more powerful than either alone — the agent learns the contrast, not just the target.

How the Agent Actually Uses the Skill

Once installed, the Skill works like this:

1. User types a UI-related ask: "Build me a settings page with three sections — profile, notifications, billing."
2. The agent matches the intent against installed Skill descriptions. ui-design matches because the user asked to create user-facing UI.
3. The agent reads SKILL.md.
4. SKILL.md tells it to load design.md first.
5. The agent reads design.md and now has the tokens, patterns, layouts, accessibility rules, and anti-patterns in working memory.
6. It reads templates/page.tsx.tmpl as the starting shape.
7. It generates the page, respecting every rule. Brand primary on CTAs. 96px section padding. Real labels on every input. Heading order h1, h2, h2.
8. It runs a self-review against the anti-patterns section and reports anything it caught and fixed.

The user never had to mention any of the design system. The Skill did.

Testing That the Skill Works

Three tests we run on every UI Design Skill before declaring it shipped.

Test 1 — The cold ask. Open a new conversation. Without any setup, ask the agent to build a small component. "Build me a feedback widget." Check the output for: tokens from design.md (not invented), an accessibility-correct label, focus styles, anti-pattern avoidance. If any of these are missing, the Skill description is probably under-invoking.

Test 2 — The adversarial ask. Ask for something the Skill should refuse to do its own way. "Make the button neon green with a glowing shadow." A working Skill responds by either using the closest approved color and noting the deviation, or pushing back and citing the design system. If the agent silently complies, the Skill instructions are too soft.

Test 3 — The drift check. Ask for the same component twice in two different conversations. Diff the outputs. They should be 80%+ identical in structure and tokens. If they are not, design.md is too vague and the agent is filling in gaps with its own defaults.

Maintaining design.md Without Letting It Rot

design.md is alive. Brand colors shift, components evolve, anti-patterns get added when something embarrassing ships. The maintenance loop that keeps it useful:

• Treat design.md as code. It lives in the repo, changes go through PR review, the design lead is a CODEOWNER. Drive-by edits are not okay.
• Add to the anti-patterns section every time something embarrassing ships. Every bug that turned out to be a design system violation is a new line in section 7.
• Run a quarterly audit. Open design.md, read it cover to cover, ask: is anything wrong, anything missing, anything no longer true? Update.
• Version your Skill. Tag releases of the Skill folder. When the design system has a major version bump, bump the Skill version. Teams using older versions stay on them until they migrate.
• Watch for sub-system creep. If a section grows past 100 lines, it probably wants its own file. Split — for example marketing-specific overrides into marketing.md that the Skill loads when the user is working in the marketing surface.

Pro tip: Pair design.md with a CI check. A small script that grep's the codebase for hex codes not present in section 1 of design.md and fails the build. Once you have this check, drift stops being a discipline problem and starts being a build problem.

Pairing With Figma and Real Design Tools

design.md is the source of truth for the agent. It is not the source of truth for the designer — Figma is. The handshake between the two:

• Tokens flow from Figma to design.md, not the other way around. Use Figma Tokens or a plugin like Tokens Studio to export the token JSON. Commit the JSON to references/tokens.json. Reference the JSON values in design.md sections 1, 4, and 5.
• Component patterns are described in design.md but live as components in Figma. When a designer ships a new Figma component, the design lead writes the design.md entry — usage, variants, sizes, anti-patterns — as part of the rollout.
• Anti-patterns flow from production back to design.md. The designers do not need to maintain section 7 directly. The engineers do, because they are the ones who hit the patterns.

The pattern that breaks: trying to keep design.md and Figma in lockstep manually. Use export tooling for the tokens, write the prose sections by hand, and accept that the two will drift slightly between releases.

Common Pitfalls

The mistakes we have seen kill UI Design Skills, in priority order:

1. design.md is too long. Past 1,500 lines, the agent starts losing attention to the middle sections. Split by surface (marketing.md, app.md) before that point.
2. design.md is too vague. "Use ample spacing" and "buttons should look professional" mean nothing to an agent. Use specific values, specific component patterns, specific examples.
3. No anti-patterns section. The agent will fill in gaps with its own defaults. The anti-patterns section is what closes the gaps.
4. SKILL.md description too broad. "Use this for any frontend work" causes the Skill to fire on backend tasks. Name the exact intents and surfaces.
5. Inventing values is allowed but not surfaced. The Skill says "never invent a color" but does not require the agent to call out when it had to. Make the agent surface deviations — that is what catches drift.
6. No tests. The cold ask, adversarial ask, and drift check above. Without them, the Skill works once and then degrades silently.
7. Owned by nobody. If design.md does not have a maintainer, it stops being maintained. Pick one person.

A Worked Example — From Zero to Working Skill in 30 Minutes

To make the whole flow concrete, here is the actual 30-minute build:

1. Minute 0-2. Make the folder: mkdir -p .claude/skills/ui-design. Create empty SKILL.md and design.md.
2. Minute 2-4. Write the SKILL.md frontmatter from the template above. Keep it short. The body delegates to design.md.
3. Minute 4-12. Write design.md sections 1-3 (tokens, components, layouts). Pull the values from your existing CSS, Tailwind config, or Figma file. Do not invent; lift what exists.
4. Minute 12-18. Write sections 4-6 (accessibility, interaction, voice). These are mostly the same across teams, so adapt the examples above to your own conventions.
5. Minute 18-22. Write section 7 (anti-patterns). List every UI bug you have seen ship in the last six months as a "never ship" rule.
6. Minute 22-26. Save the three most recent components you actually shipped into examples/. Pick one good, one with a pattern violation you have since fixed. Add the bad-good pair.
7. Minute 26-30. Run the three tests from above. Adjust the SKILL.md description if the cold-ask test fails. Tighten the relevant design.md section if the adversarial or drift test fails.

30 minutes. One Skill installed. Every UI generation from that point forward respects your design system without you having to remind the agent.

The Verdict

A UI Design Skill is the highest-leverage piece of AI infrastructure most product teams could ship right now. It costs an afternoon to build and pays back every time an agent touches the UI. The artifact at the heart of it — design.md — is a single Markdown file that any designer can read and any engineer can edit. It travels with the codebase, lives in version control, and turns the design system from documentation that gets ignored into infrastructure the agent actually uses.

The 30-minute build above is the floor, not the ceiling. Real production design Skills evolve over months — sections get split, anti-patterns accumulate, tokens drift in step with the Figma library. The maintenance loop matters more than the initial write. But the initial write is what unlocks the loop in the first place.

If you are still copy-pasting your style guide into Claude conversations, this afternoon is the right time to fix it.

Keep Reading

• AI Skills vs Prompts: What's the Difference? — the conceptual primer this tutorial builds on.
• HeyGen Hyperframes Prompts for Editing Videos — a worked example of a different published Skill.
• Claude Fable 5 Prompts for Web Developers — the prompt library that pairs with the UI Design Skill for end-to-end frontend work.
• 100 Best Claude Opus 4.7 Prompts for Power Users — the wider prompt library across categories.
• Claude Fable 5 vs GPT-5.5 vs Gemini 3.5 Flash — the model layer one step below Skills in the stack.
• Prompt Library — the searchable prompt collection.
• All AI Models — model catalogue with pricing and capabilities.