Core Components Design System Skill

A Claude Code skill for building and maintaining a consistent component library with design tokens, spacing scales, typography, and reusable UI primitives that enforce visual consistency across your application.

When to Use This Skill

Choose this skill when:

• Establishing a design system for a new project
• Building a shared component library used across multiple pages
• Enforcing consistent styling with design tokens instead of hardcoded values
• Creating accessible, responsive UI primitives (buttons, inputs, cards, modals)
• Migrating from ad-hoc styling to a systematic design approach

Consider alternatives when:

• Using an existing component library like Shadcn, Radix, or MUI as-is
• Building a one-page prototype where consistency doesn't matter
• Working on backend-only code with no UI

Quick Start

Copy
# Set up your design system structure
mkdir -p src/components/core src/styles/tokens

# Create the skill configuration
claude mcp add core-components

Copy
// src/styles/tokens/spacing.ts
export const spacing = {
  0: '0',
  1: '0.25rem',   // 4px
  2: '0.5rem',    // 8px
  3: '0.75rem',   // 12px
  4: '1rem',      // 16px
  6: '1.5rem',    // 24px
  8: '2rem',      // 32px
  12: '3rem',     // 48px
  16: '4rem',     // 64px
} as const;

// src/styles/tokens/colors.ts
export const colors = {
  primary: { 50: '#eff6ff', 500: '#3b82f6', 700: '#1d4ed8', 900: '#1e3a5f' },
  neutral: { 50: '#fafafa', 200: '#e5e5e5', 500: '#737373', 800: '#262626' },
  success: { 500: '#22c55e' },
  error: { 500: '#ef4444' },
  warning: { 500: '#f59e0b' },
} as const;

Core Concepts

Design Token Categories

Category	Purpose	Example Values
Spacing	Consistent margins, padding, gaps	4px, 8px, 16px, 24px, 32px
Colors	Brand palette and semantic colors	primary-500, error-500, neutral-200
Typography	Font sizes, weights, line heights	text-sm (14px), text-base (16px), text-xl (20px)
Radii	Border radius values	sm (4px), md (8px), lg (12px), full (9999px)
Shadows	Elevation and depth effects	sm, md, lg, xl
Breakpoints	Responsive design boundaries	sm (640px), md (768px), lg (1024px)

Component Primitives

Copy
// src/components/core/Button.tsx
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'ghost' | 'danger';
  size: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
}

export function Button({ variant, size, children, loading, ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        'inline-flex items-center justify-center rounded-md font-medium transition-colors',
        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
        variants[variant],
        sizes[size],
        loading && 'opacity-50 cursor-wait'
      )}
      disabled={loading || props.disabled}
      {...props}
    >
      {loading && <Spinner className="mr-2 h-4 w-4" />}
      {children}
    </button>
  );
}

Configuration

Parameter	Type	Default	Description
token_format	string	"css-vars"	Token output: css-vars, tailwind, scss, json
component_library	string	"react"	Target framework: react, vue, svelte
styling_approach	string	"tailwind"	Styling method: tailwind, css-modules, styled-components
prefix	string	""	CSS variable prefix for namespacing
breakpoints	object	{ sm: 640, md: 768, lg: 1024, xl: 1280 }	Responsive breakpoint widths
dark_mode	boolean	true	Generate dark mode token variants
accessibility	string	"AA"	WCAG compliance level: A, AA, AAA

Best Practices

1. Never hardcode values — always use design tokens — every color, spacing value, and font size should reference a token; this ensures a single change propagates across the entire application.

2. Build components from smallest to largest — start with atoms (Button, Input, Badge), compose into molecules (FormField, SearchBar), then organisms (Header, Card); this layered approach prevents duplication.

3. Enforce token usage through linting — add ESLint rules or Stylelint rules that flag hardcoded pixel values, hex colors, and font sizes in component styles.

4. Document every component with props and examples — each core component should have a clear interface definition and visual examples showing all variants and states.

5. Test components in isolation with Storybook or similar — render each variant, size, and state in a visual testing tool to catch regressions before they reach production.

Common Issues

Tokens get out of sync with design files — Establish a single source of truth. Either generate tokens from Figma design tokens plugin or maintain a shared JSON file that both designers and developers reference.

Components grow too many props — When a component has more than 8-10 props, it's doing too much. Split into separate components (PrimaryButton, IconButton, LinkButton) rather than adding endless configuration to a single Button.

Dark mode colors look washed out — Don't simply invert colors for dark mode. Define separate dark palette tokens with adjusted contrast ratios that account for screen luminance differences.