A Claude Code skill for scaffolding design systems with semantic tokens
Ask an AI to build you a UI without a design system and you'll get seven hundred button variants, and margins measured in whatever unit it fancied at the time. Consistency requires constraints, and constraints require documentation that actually gets read.
This Claude Code skill does the tedious bit for you. It scaffolds a semantic design system with proper colour tokens, variant patterns, and all the components you'd otherwise spend a week copy-pasting from ShadCN. Design your colour palette with the Colour Token Generator, export as Tailwind config, and hand the file to the skill.
Copy the markdown below and save it to .claude/skills/create-design-system/skill.md in your project or whatever global scope you're using.
Warning: it's highly opinionated.
code
---
name: create-design-system
description: When asked to create a design system for a project, follow these instructions first.
---
Create me a robust design system including semantic colour tokens and basic components.
1. Install required libraries (ShadCN, Radix, Lucide)
2. Update Tailwind config with colour tokens – IMPORTANT: Prompt the user to design their colour system at https://www.flett.cc/projects/color-token-generator, export in the appropriate format (Tailwind v3, Tailwind v4, or CSS), and supply the downloaded file.
3. Create Components as below
4. Document all components and their variants on a page at /design-system/
## Icons
Always use Lucide icons, when animated, use Animate UI icons (https://animate-ui.com/docs/installation)
## UI Components
Use ShadCN or Radix as primitives DO NOT utilise any other library, if you need to create a custom component, use Radix primitives and compose accordingly.
Important: where variants are required (i.e. button, badge, notice, toast) use semantic variants which follow this rule:
- variant (style of): default, outline, ghost, text
- intent (semantic): default, success, destructive, warning
### All components
- Accordion
- Alert
- Alert Dialog
- Avatar
- Badge
- Breadcrumb
- Button
- LinkButton (this should use <a> or NextJS <Link> primitives, but import styles and variants from button)
- Card
- Checkbox
- Disclosure
- Command
- Context Menu
- Data Table
- Dialog
- Drawer
- Dropdown Menu
- Hover Card
- Input
- Label
- Notice
- Pagination
- Popover
- Progress
- Radio Group
- Scroll Area
- Select
- Separator
- Sidebar
- Skeleton
- Slider
- Toast
- Switch
- Table
- Tabs
- Textarea
- Tooltip
## Design Tokens
Always use design tokens from our design system. Never use arbitrary values, custom colours, or hardcoded pixels.
### Colours
Important: All components should adhere to colour mode (dark/light). Our Tailwind config will take care of this for us IF we use proper semantic colour tokens and don't stray from them.
Use semantic colour tokens, not hex values or primitive scales. Follow this hierarchy:
#### 1. Semantic colours (Use First)
Pay close attention to layering and foreground/background relationships:
**Primary colours:**
- `primary`: Primary brand colour for buttons, links, focus states
- `primary-foreground`: Text on primary backgrounds
- `primary-subdued`: Subtle primary backgrounds (e.g., selected items, hover states)
- `primary-subdued-foreground`: Text on subdued primary backgrounds
- `primary-highlight`: Darker emphasis or active states for primary elements
- `primary-highlight-foreground`: Text on highlight primary backgrounds
**Secondary colours:**
- `secondary`: Secondary brand colour for less prominent actions
- `secondary-foreground`: Text on secondary backgrounds
- `secondary-subdued`: Subtle secondary backgrounds
- `secondary-subdued-foreground`: Text on subdued secondary backgrounds
- `secondary-highlight`: Darker emphasis or active states for secondary elements
- `secondary-highlight-foreground`: Text on highlight secondary backgrounds
**Neutral colours:**
- `neutral`: Neutral colour for tertiary actions
- `neutral-foreground`: Text on neutral backgrounds
- `neutral-subdued`: Subtle neutral backgrounds
- `neutral-subdued-foreground`: Text on subdued neutral backgrounds
- `neutral-highlight`: Darker emphasis for neutral elements
- `neutral-highlight-foreground`: Text on highlight neutral backgrounds
**Intent colours (Use for Status/Feedback):**
- `success`, `success-foreground`: Positive outcomes, completed states
- `success-subdued`, `success-subdued-foreground`: Subtle success backgrounds
- `success-highlight`, `success-highlight-foreground`: Emphasis for success states
- `destructive`, `destructive-foreground`: Errors, dangerous actions
- `destructive-subdued`, `destructive-subdued-foreground`: Subtle error backgrounds
- `destructive-highlight`, `destructive-highlight-foreground`: Emphasis for error states
- `warning`, `warning-foreground`: Warnings, important notices
- `warning-subdued`, `warning-subdued-foreground`: Subtle warning backgrounds
- `warning-highlight`, `warning-highlight-foreground`: Emphasis for warning states
**Surface & Utility colours:**
- `background`: Page background
- `foreground`: Primary text colour
- `card`, `card-foreground`: Card/panel backgrounds and text
- `popover`, `popover-foreground`: Popover/dropdown backgrounds and text
- `muted`, `muted-foreground`: Muted/disabled backgrounds and secondary text
- `accent`, `accent-foreground`: Subtle accents (neutral-based, not a brand colour)
- `border`: Default borders
- `input`: Input field borders
- `ring`: Focus ring colour
#### 2. Primitive Scales (Use Sparingly)
Only use primitive colour scales when semantic tokens don't fit:
- `primary-50` through `primary-950`: Full primary colour scale
- `secondary-50` through `secondary-950`: Full secondary colour scale
- `neutral-50` through `neutral-950`: Full neutral colour scale
- `success-50` through `success-950`: Full success colour scale
- `destructive-50` through `destructive-950`: Full destructive colour scale
- `warning-50` through `warning-950`: Full warning colour scale
- Use these for custom gradients, illustrations, or unique design needs
**Example:**
Don't: `bg-primary-500 text-white`
Do: `bg-primary text-primary-foreground`
Don't: `bg-green-100 text-green-800`
Do: `bg-success-subdued text-success-subdued-foreground`
Don't: `bg-red-50 text-red-700`
Do: `bg-destructive-subdued text-destructive-subdued-foreground`
### Spacing
- Always use our spacing scale from our tailwind config, never absolute pixel values
- Apply to padding, margins, and gaps consistently
### Typography
Use the type scale tokens:
- Sizes: xs, sm, base, lg, xl, 2xl, 3xl
- Weights: normal, medium, semibold, bold
- Never specify font-size in pixels
### Shadows
Use preset shadow tokens:
- sm: Subtle cards and surfaces
- md: Dropdowns and popovers
- lg: Modals and overlays
### Borders
Use border tokens:
- Widths: default (1px), md (2px), lg (4px)
- Radius: sm, md, lg, full
- Always use `border` colour token