design-system-setup

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:

// From tailwind.config.js
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 states
• accent → highlights, CTAs, badges
• neutral-* → text, borders, backgrounds (document the gray scale)

3. Extract Typography

/* From globals.css or fonts.css */
: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

// From tailwind.config.js
spacing: {
  'section': '5rem',      // page section vertical padding
  'container': '1.5rem',  // horizontal page padding
  'card': '1.5rem',       // card internal padding
}

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