Design Systems

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

:root {  /* Colors */  --color-primary-500: #0066cc;  --color-neutral-100: #f5f5f5;
  /* Spacing */  --space-1: 4px;  --space-2: 8px;  --space-4: 16px;
  /* Typography */  --font-size-sm: 0.875rem;  --font-size-base: 1rem;  --font-size-lg: 1.125rem;
  /* Shadows */  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);}

Example: React Button Component Using Design Tokens

import React from "react";
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {  variant?: "primary" | "secondary" | "danger";  size?: "sm" | "md" | "lg";  loading?: boolean;}
const sizeStyles: Record<string, React.CSSProperties> = {  sm: { padding: "var(--space-1) var(--space-2)", fontSize: "var(--font-size-sm)" },  md: { padding: "var(--space-2) var(--space-4)", fontSize: "var(--font-size-base)" },  lg: { padding: "var(--space-3) var(--space-6)", fontSize: "var(--font-size-lg)" },};
export const Button: React.FC<ButtonProps> = ({  variant = "primary",  size = "md",  loading = false,  disabled,  children,  ...props}) => (  <button    style={{      ...sizeStyles[size],      backgroundColor: `var(--color-${variant}-500)`,      color: "var(--color-neutral-100)",      borderRadius: "var(--radius-md)",      boxShadow: "var(--shadow-sm)",      cursor: disabled || loading ? "not-allowed" : "pointer",      opacity: disabled ? 0.5 : 1,    }}    disabled={disabled || loading}    aria-busy={loading}    {...props}  >    {loading ? "Loading…" : children}  </button>);

Example: Storybook Configuration

// .storybook/preview.tsimport type { Preview } from "@storybook/react";import "../src/tokens.css"; // import design tokens globally
const preview: Preview = {  parameters: {    a11y: { element: "#storybook-root" },    backgrounds: {      default: "light",      values: [        { name: "light", value: "#ffffff" },        { name: "dark", value: "#1a1a1a" },      ],    },  },};
export default preview;

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.