Design Systems Best Practices

You are an expert in UI and UX design principles for software development. Apply these guidelines when creating or maintaining design systems.

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 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);
}

Quality Assurance

Visual regression testing
Accessibility automated testing
Cross-browser testing
Performance benchmarking
Component unit testing
Integration testing

Stay current with design system practices and industry standards.

design-systems