--- name: design-system-architecture description: Build scalable design systems with design tokens, component APIs, and documentation. Use when creating or evolving component libraries. keywords: - design system - design tokens - component library - ui components - theming triggers: - design system - component library - design tokens - theme architecture - ui kit --- # Design System Architecture Comprehensive guide to building scalable design systems with proper token architecture, component APIs, and documentation strategies. ## When to Use This Skill - Creating a new design system from scratch - Evolving an existing component library - Defining token architecture - Establishing component API patterns - Setting up design system documentation ## Token Architecture ### Three-Tier Token System ``` ┌─────────────────────────────────────┐ │ Component Tokens │ → button-primary-bg │ (Specific to components) │ ├─────────────────────────────────────┤ │ Semantic Tokens │ → color-action-primary │ (Purpose-based naming) │ ├─────────────────────────────────────┤ │ Primitive Tokens │ → blue-500 │ (Raw values) │ └─────────────────────────────────────┘ ``` ### Token Categories ```css /* Primitive Tokens */ --color-blue-500: #3b82f6; --spacing-4: 1rem; --font-size-base: 16px; --radius-md: 8px; /* Semantic Tokens */ --color-action-primary: var(--color-blue-500); --color-text-primary: var(--color-gray-900); --spacing-component-gap: var(--spacing-4); /* Component Tokens */ --button-bg: var(--color-action-primary); --button-padding-x: var(--spacing-4); --card-radius: var(--radius-md); ``` ### Theme Support ```typescript // tokens/themes.ts export const lightTheme = { 'color-bg-primary': 'var(--color-white)', 'color-text-primary': 'var(--color-gray-900)', 'color-border': 'var(--color-gray-200)', } export const darkTheme = { 'color-bg-primary': 'var(--color-gray-900)', 'color-text-primary': 'var(--color-gray-100)', 'color-border': 'var(--color-gray-700)', } ``` ## Component API Patterns ### Prop API Design ```typescript // ✅ Good: Clear, typed, with sensible defaults interface ButtonProps { variant?: 'primary' | 'secondary' | 'ghost'; size?: 'sm' | 'md' | 'lg'; isLoading?: boolean; isDisabled?: boolean; leftIcon?: React.ReactNode; children: React.ReactNode; onClick?: () => void; } // ✅ With defaults const Button = ({ variant = 'primary', size = 'md', isLoading = false, isDisabled = false, ...props }: ButtonProps) => { ... } ``` ### Compound Component Pattern ```typescript // Compound components for complex UIs const Tabs = ({ children, defaultValue }) => { ... } Tabs.List = ({ children }) => { ... } Tabs.Tab = ({ value, children }) => { ... } Tabs.Panel = ({ value, children }) => { ... } // Usage First Second Content 1 Content 2 ``` ### Polymorphic Components ```typescript // Component that can render as different elements interface BoxProps { as?: C; children?: React.ReactNode; } type PolymorphicProps = BoxProps & Omit, keyof BoxProps>; const Box = ({ as, ...props }: PolymorphicProps) => { const Component = as || 'div'; return ; }; // Usage Content Click me ``` ## Component Categories (Atomic Design) ### Atoms (Primitives) - Button, Input, Label, Icon - Typography (Text, Heading) - Box, Flex, Grid (layout primitives) ### Molecules (Compositions) - FormField (Label + Input + Error) - SearchInput (Input + Icon + Button) - Card (Box + padding + border) ### Organisms (Features) - Header (Logo + Nav + UserMenu) - DataTable (Table + Pagination + Filters) - Modal (Overlay + Card + Actions) ## Documentation Strategy ### Component Documentation ```markdown # Button Buttons trigger actions or navigate users. ## Usage \`\`\`jsx import { Button } from '@/components/ui' \`\`\` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style | | size | 'sm' \| 'md' \| 'lg' | 'md' | Size preset | ## Examples ### Variants [Interactive examples] ### With Icons [Interactive examples] ## Accessibility - Uses `

design-system-architecture

Install this skill

Comments