Comprehensive design system guidelines for building consistent, accessible, and scalable component libraries. Use when creating design tokens, building component libraries, implementing design systems, setting up theming architecture, or establishing UI governance processes.

Design Systems Best Practices Guidelines for creating and maintaining design systems that ensure visual consistency, accessibility compliance, and scalable component architecture across digital products. Workflow: Setting Up a Design System 1. Audit existing UI — Inventory current components, colors, typography, and spacing across the product to identify inconsistencies and reusable patterns. 2. Define design tokens — Establish primitive tokens (colors, spacing, typography, shadows) as CSS custom properties or a token format (e.g., Style Dictionary) that serves as the single source of truth. 3. Build foundational components — Create atomic components (Button, Input, Text, Icon) that consume design tokens and expose a clear props API with TypeScript types. 4. Compose patterns and layouts — Assemble atomic components into higher order patterns (forms, cards, navigation) with documented usage guidelines. 5. Set up documentation and Storybook — Configure Storybook with stories for every component variant, state, and accessibility annotation. Publish as a living style guide. 6. Integrate testing and governance — Add visual regression tests (e.g., Chromatic), accessibility linting (e.g., axe core), and a contribution/review process for new components. 7. Ship and iterate — Publish the library as a versioned package, gather consumer feedback, and run regular accessibility and performance audits. Foundation Elements Color System Define primary, secondary, and accent colors Include semantic colors for success, warning, error, info states Ensure all color combinations meet WCAG contrast requirements Document color usage guidelines and contexts Provide light and dark mode variants Typography Establish a type scale with consistent ratios Define font families for headings and body text Set line heights and letter spacing standards Document font weights and their usage Ensure readability across screen sizes Spacing System Define consistent spacing scale (4px, 8px, 16px, 24px, etc.) Create layout primitives for common patterns Document margin and padding conventions Ensure responsive spacing behavior Use CSS custom properties for maintainability Icons and Imagery Maintain consistent icon style and sizing Define icon grid and stroke weights Document icon naming conventions Optimize assets for web performance Provide multiple formats when needed (SVG, PNG) Component Architecture Component Structure Create atomic, reusable components Define clear component APIs (props/attributes) Document variants and states Ensure components are accessible by default Provide clear naming conventions Component States Default state Hover state Focus state (keyboard navigation) Active/pressed state Disabled state Loading state Error state Component Variants Size variants (small, medium, large) Color/theme variants Layout variants Contextual variants Accessibility Requirements Follow WCAG 2.1 AA guidelines minimum Use semantic HTML elements Provide ARIA labels where needed Ensure keyboard navigation Test with screen readers Maintain color contrast ratios Support reduced motion preferences Documentation Standards Component Documentation Purpose and use cases Props/API reference Code examples Do's and don'ts Accessibility notes Related components Pattern Documentation When to use Anatomy breakdown Behavior specifications Responsive considerations Edge cases Implementation Guidelines CSS Architecture Use CSS custom properties for tokens Implement utility classes for common patterns Follow BEM or similar naming convention Ensure specificity is manageable Support theming and customization Component Libraries Framework agnostic when possible Tree shakeable exports TypeScript support Comprehensive test coverage Storybook integration Governance Contribution Guidelines How to propose new components Review and approval process Versioning strategy Breaking change policy Deprecation process Maintenance Regular accessibility audits Performance monitoring Browser compatibility testing Documentation updates Community feedback incorporation Design Tokens Token Categories Colors Typography (font sizes, weights, line heights) Spacing Border radius Shadows Breakpoints Animation durations Z index values Token Implementation Example: React Button Component Using Design Tokens Example: Storybook Configuration Quality Assurance Visual regression testing Accessibility automated testing Cross browser testing Performance benchmarking Component unit testing Integration testing When evolving the design system, validate changes against WCAG 2.1 AA, run visual regression tests, and ensure token updates propagate correctly across all consuming applications.

design-systems