Design System Starter Skill

A Claude Code skill for bootstrapping complete design systems from scratch — including tokens, component primitives, documentation, theming, and accessibility standards for scalable UI development.

When to Use This Skill

Choose this skill when:

• Starting a new project that needs consistent UI patterns
• Building a shared component library for multiple applications
• Migrating from ad-hoc styling to a systematic design approach
• Creating a white-label product with configurable theming
• Establishing design standards for a growing engineering team

Consider alternatives when:

• Adopting an existing design system (Material UI, Chakra, Shadcn/UI)
• Building a single-page prototype where consistency doesn't matter
• Working on backend code with no user interface

Quick Start

Copy
# Add to your Claude Code project
claude mcp add design-system-starter

# Bootstrap a complete design system
claude "create a design system for a SaaS dashboard application"

# Generate specific components
claude "add a form component set (Input, Select, Checkbox, Radio) to the design system"

Copy
// Generated: Design Token Foundation
// src/design-system/tokens.ts
export const tokens = {
  colors: {
    brand: { primary: '#2563eb', secondary: '#7c3aed', accent: '#06b6d4' },
    semantic: { success: '#16a34a', warning: '#d97706', error: '#dc2626', info: '#2563eb' },
    neutral: { 50: '#fafafa', 100: '#f5f5f5', 200: '#e5e5e5', 500: '#737373', 800: '#262626', 900: '#171717' },
  },
  spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2rem', '2xl': '3rem' },
  radius: { sm: '0.25rem', md: '0.5rem', lg: '0.75rem', xl: '1rem', full: '9999px' },
  typography: {
    fontFamily: { sans: 'Inter, system-ui, sans-serif', mono: 'JetBrains Mono, monospace' },
    fontSize: { xs: '0.75rem', sm: '0.875rem', base: '1rem', lg: '1.125rem', xl: '1.25rem', '2xl': '1.5rem' },
  },
  shadows: {
    sm: '0 1px 2px rgba(0,0,0,0.05)',
    md: '0 4px 6px rgba(0,0,0,0.07)',
    lg: '0 10px 15px rgba(0,0,0,0.1)',
  },
} as const;

Core Concepts

Design System Layers

Layer	Contents	Purpose
Tokens	Colors, spacing, typography, shadows	Shared design constants
Primitives	Button, Input, Text, Box, Stack	Base building blocks
Patterns	Form, Card, Modal, Table, Navigation	Composed UI patterns
Templates	Page layouts, dashboard shells	Full-page compositions
Documentation	Usage guides, do/don't examples	Developer onboarding

Component Architecture

Copy
// Primitive: Button component with variants
import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2',
  {
    variants: {
      variant: {
        primary: 'bg-brand-primary text-white hover:bg-brand-primary/90',
        secondary: 'bg-neutral-100 text-neutral-800 hover:bg-neutral-200',
        ghost: 'hover:bg-neutral-100 text-neutral-600',
        danger: 'bg-error text-white hover:bg-error/90',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
      },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  }
);

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>,
  VariantProps<typeof buttonVariants> {
  loading?: boolean;
}

export function Button({ variant, size, loading, children, ...props }: ButtonProps) {
  return (
    <button className={buttonVariants({ variant, size })} disabled={loading} {...props}>
      {loading ? <Spinner className="mr-2" /> : null}
      {children}
    </button>
  );
}

Configuration

Parameter	Type	Default	Description
framework	string	"react"	Target framework: react, vue, svelte, web-components
styling	string	"tailwind"	Styling approach: tailwind, css-modules, styled-components, vanilla-css
variant_system	string	"cva"	Variant management: cva, manual, stitches
dark_mode	boolean	true	Include dark mode token variants
accessibility_level	string	"AA"	WCAG compliance: A, AA, AAA
animation	boolean	true	Include animation tokens and transitions
documentation	string	"storybook"	Doc tool: storybook, docusaurus, none

Best Practices

1. Start with tokens, not components — define your color palette, spacing scale, and typography before building any components; tokens change less frequently and form the foundation everything else references.

2. Use semantic color names, not literal ones — name tokens error, success, primary instead of red, green, blue; semantic names allow theming and ensure consistent usage.

3. Build the smallest set of components first — start with Button, Input, Text, Card, and Stack; these five primitives cover 80% of UI needs. Add more components only when real usage demands them.

4. Make every component accessible from day one — add proper ARIA attributes, keyboard navigation, and focus management from the start; retrofitting accessibility is much harder than building it in.

5. Document components with live examples — use Storybook or a similar tool to show every variant, state, and size of each component; documentation without examples gets ignored.

Common Issues

Design tokens drift from design tool — Figma/Sketch changes don't automatically sync to code tokens. Use a design token pipeline (Style Dictionary, Tokens Studio) that exports tokens from design files to code.

Too many component variants make the API confusing — When a Button has 12 variants, developers don't know which to use. Limit variants to 3-4 per prop and document when to use each one.

Components are too rigid for edge cases — Components that don't accept className or style overrides force developers to work around the design system. Allow escape hatches while documenting when to use them.