| name | design-system-setup |
| description | Use this skill when a user wants to set up or configure a design system for use with Claude Design, extract brand tokens from a codebase or Figma file, or onboard their team's visual identity into Claude's design tools. Triggers include: "set up my design system", "connect my codebase to Claude Design", "extract brand tokens from my repo", "onboard my brand to Claude Design", "Claude Design doesn't know my colors/fonts", "add my design system to Claude", or any task involving reading a codebase/Figma/assets folder to define colors, typography, spacing, and components for AI-assisted design. Also trigger when a user wants consistent branding across Claude Design projects. Do not attempt design system setup for Claude Design without reading this skill first.
|
Design System Setup Skill
Claude Design builds a design system for your team during onboarding by reading your codebase
and design files. This skill guides you through that setup process — whether you're onboarding
fresh or fixing inconsistencies.
What Claude Design Needs
A complete design system provides:
- Color palette — primary, secondary, accent, neutral, semantic (success/warning/error)
- Typography — font families, weights, size scale, line heights
- Spacing scale — padding/margin rhythm (e.g. 4px base unit, or 8px, T-shirt sizes)
- Border radius — for buttons, cards, inputs
- Shadow/elevation — card shadows, dropdown shadows
- Component patterns — button variants, input styles, card layouts, nav patterns
- Logo and brand assets — SVG or PNG files for headers/footers
Input Sources Claude Design Accepts
| Source | What to provide |
|---|
| GitHub repo link | URL to the repo (public or with token) |
| Local code files | Upload key files: tailwind.config.js, tokens.json, variables.css, theme.ts |
| Figma file | Upload exported Figma JSON or connect via Figma MCP |
| Assets folder | Upload zip of /assets or /public (fonts, logos, icons) |
| Text notes | Plain description of brand guidelines |
Claude Design supports combining multiple sources. Use all that are available.
Step-by-Step: Extracting Tokens from a Codebase
1. Locate Token Files
Look for these files first — they contain the richest token data:
tailwind.config.js / tailwind.config.ts ← colors, fonts, spacing, radius
src/styles/tokens.css / variables.css ← CSS custom properties
src/theme.ts / theme.js ← JS/TS theme objects (MUI, Chakra, etc.)
src/styles/globals.css ← root CSS variables
design-tokens.json / tokens.json ← Style Dictionary or Theo tokens
.storybook/ ← component showcase (great for pattern reference)
2. Extract Color Tokens
Read the token files and extract named colors:
colors: {
primary: { DEFAULT: '#1a1a2e', light: '#2d2d5e', dark: '#0d0d17' },
accent: '#e94560',
neutral: { 50: '#fafafa', 100: '#f5f5f5', ..., 900: '#171717' },
success: '#22c55e',
warning: '#f59e0b',
error: '#ef4444',
}
Map these to a canonical token set and document the purpose of each:
primary → main brand color, used for primary buttons, links, active statesaccent → highlights, CTAs, badgesneutral-* → text, borders, backgrounds (document the gray scale)
3. Extract Typography
:root {
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', monospace;
--font-display: 'Playfair Display', serif;
}
Also extract the type scale:
xs: 0.75rem / 1rem
sm: 0.875rem / 1.25rem
base: 1rem / 1.5rem
lg: 1.125rem / 1.75rem
xl: 1.25rem / 1.75rem
2xl: 1.5rem / 2rem
3xl: 1.875rem / 2.25rem
4xl: 2.25rem / 2.5rem
4. Extract Spacing and Layout
spacing: {
'section': '5rem',
'container': '1.5rem',
'card': '1.5rem',
}
If no custom spacing, note that the project uses default Tailwind spacing.
5. Extract Component Patterns
Scan src/components/ or components/ui/ for:
- Button variants (primary, secondary, ghost, danger)
- Input/form field styles
- Card layouts
- Navigation patterns (sidebar, topbar, tabs)
- Modal/dialog structure
For each, note: the class names used, the HTML structure, and any state variants.
6. Collect Brand Assets
Gather from public/, assets/, or static/:
- Logo files (SVG preferred; note light and dark variants)
- Favicon
- Any icon set being used (Lucide, Heroicons, custom SVG sprite)
- Custom fonts (
.woff2 files)
Formatting the Design System for Claude Design
Once extracted, format the system as a design system brief — a markdown document that Claude Design reads during onboarding:
# [Company] Design System
## Brand Identity
[Brief: what the brand feels like — modern/warm/technical/minimal]
## Colors
- Primary: #1a1a2e (dark navy) — main buttons, active nav, headings
- Accent: #e94560 (red-pink) — CTAs, badges, highlights
- Neutral: 50–900 scale (gray) — text body: 800, borders: 200, bg: 50
- Success: #22c55e | Warning: #f59e0b | Error: #ef4444
## Typography
- Sans: Inter (weights: 400, 500, 600, 700)
- Mono: JetBrains Mono (code blocks only)
- Scale: follows Tailwind defaults
## Spacing
- Base unit: 4px (Tailwind default)
- Section padding: 80px vertical
- Card padding: 24px
## Border Radius
- Buttons: 8px | Cards: 12px | Inputs: 6px | Badges: 9999px
## Shadows
- Card: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)
- Dropdown: 0 10px 15px -3px rgba(0,0,0,0.1)
## Components in Codebase
- Button: `src/components/ui/button.tsx` — variants: default, outline, ghost, destructive
- Input: `src/components/ui/input.tsx`
- Card: `src/components/ui/card.tsx` — with CardHeader, CardContent, CardFooter
- Nav: `src/components/layout/navbar.tsx` — fixed top, logo left, links right
## Assets
- Logo SVG: `public/logo.svg` (dark bg) | `public/logo-dark.svg` (light bg)
- Icon set: Lucide React
Maintaining Multiple Design Systems
Claude Design supports multiple design systems (e.g. one per brand or product line).
Naming convention:
[brand]-design-system.md — e.g. acme-corp-design-system.md- Store in a dedicated
/design-systems/ folder in the repo
- Reference which system to use at the start of each Claude Design project
When to update:
- After any rebrand or color change
- After adding new component patterns
- After changing the font stack
- Quarterly audit recommended
Troubleshooting
| Problem | Cause | Fix |
|---|
| Claude Design uses wrong colors | Tokens not found in provided files | Explicitly list hex values in the brief |
| Wrong font renders | Font file not provided | Upload .woff2 or add Google Fonts link |
| Components look generic | No component patterns extracted | Add component screenshots or Storybook export |
| Brand extraction takes >20 min | Large repo with many files | Provide only the token/theme files, not the full repo |
| Dark/light mode inconsistency | Only one mode's tokens provided | Extract both and note which is default |
