style-guide-generator/design_system_examples.md

Design System Examples & Best Practices

This reference document provides examples of well-structured design systems and style guides from leading companies, along with best practices for organizing and presenting design system documentation.

Industry-Leading Design Systems

1. Material Design (Google)

Structure Highlights:

• Clear hierarchy: Foundation → Styles → Components → Patterns
• Comprehensive component documentation with interactive examples
• Accessibility guidelines integrated throughout
• Design tokens for colors, spacing, and typography
• Multiple platform implementations (Web, Android, iOS)

Key Sections:

• Design principles
• Color system with semantic naming
• Typography scale
• Motion guidelines
• Component library with states and variants
• Layout grid system
• Accessibility standards

2. Human Interface Guidelines (Apple)

Structure Highlights:

• Platform-specific guidelines (iOS, macOS, watchOS, tvOS)
• Strong focus on user experience principles
• Detailed interaction patterns
• System components with usage guidelines
• Accessibility as first-class concern

Key Sections:

• Foundations (Color, Typography, Layout)
• Technologies integration
• Inputs (Gestures, Buttons, Controls)
• Visual design elements
• Platform-specific conventions

3. Atlassian Design System

Structure Highlights:

• Component-first organization
• Living documentation with code examples
• Design tokens for theming
• Contribution guidelines for teams
• Comprehensive accessibility documentation

Key Sections:

• Foundations (Brand, Color, Typography, Layout)
• Components (organized by function)
• Patterns (common solutions)
• Content guidelines
• Resources and tools

4. IBM Carbon Design System

Structure Highlights:

• Clear separation of design and code documentation
• Comprehensive theming system
• Data visualization guidelines
• Motion and animation principles
• Multiple framework support

Key Sections:

• Design principles
• Visual foundations
• Components
• Patterns
• Data visualization
• Content guidelines

Essential Style Guide Components

Must-Have Sections

1. Brand Foundations

• Mission and vision statements
• Brand values and personality
• Design principles (4-6 core principles)
• Target audience definition

2. Visual Identity

• Logo specifications and usage rules
• Color palette with accessibility ratings
• Typography system (headings, body, special uses)
• Iconography guidelines
• Imagery and photography style

3. UI Components

• Buttons (all states and variants)
• Form elements (inputs, selects, checkboxes, radio buttons)
• Navigation components
• Cards and containers
• Modals and dialogs
• Alerts and notifications
• Tables and data display
• Loading states and progress indicators

4. Layout & Spacing

• Grid system specifications
• Responsive breakpoints
• Spacing scale (base unit methodology)
• Container and content widths
• Safe zones and padding

5. Content Guidelines

• Voice and tone
• Writing style
• Grammar and mechanics
• Terminology and vocabulary
• Localization considerations

6. Accessibility

• WCAG compliance level
• Color contrast requirements
• Keyboard navigation standards
• Screen reader support
• Focus management
• Alternative text guidelines

Recommended Sections

7. Motion & Animation

• Animation principles
• Duration and easing standards
• Transition patterns
• Loading animations
• Micro-interactions

8. Data Visualization

• Chart types and usage
• Color application in charts
• Label and legend standards
• Responsive data display

9. Implementation

• Code standards
• Framework-specific guidelines
• Performance considerations
• Browser support matrix

10. Governance

• Contribution guidelines
• Review and approval process
• Version control strategy
• Deprecation policy

Component Documentation Best Practices

Anatomy of Good Component Documentation

Each UI component should include:

1. Overview

   • Brief description of the component
   • When to use (and when not to use)
   • Related components

2. Visual Examples

   • Default state
   • All interactive states (hover, focus, active, disabled)
   • Size variants (small, medium, large)
   • Style variants (primary, secondary, tertiary)

3. Specifications

   • Dimensions and spacing
   • Typography details
   • Color usage
   • Border and shadow values
   • Icon sizing and positioning

4. Usage Guidelines

   • Best practices
   • Common mistakes to avoid
   • Content guidelines (character limits, etc.)
   • Accessibility requirements

5. Code Examples

   • HTML structure
   • CSS classes
   • JavaScript behavior (if applicable)
   • Framework-specific implementations

Example: Button Component Documentation

Overview: Buttons trigger actions or navigate users to different pages. Use buttons for important actions that require user interaction.

Variants:

• Primary: Main call-to-action
• Secondary: Supporting actions
• Tertiary: Subtle actions
• Destructive: Delete or remove actions

States:

• Default
• Hover
• Focus
• Active
• Disabled
• Loading

Specifications:

Property	Value
Height	40px
Padding	12px 24px
Border Radius	4px
Font Size	16px
Font Weight	600
Line Height	1.5

Accessibility:

• Minimum touch target: 44x44px
• Keyboard accessible via Tab
• Focus indicator visible
• Descriptive text (avoid "Click here")
• ARIA labels for icon-only buttons

Color System Best Practices

Semantic Color Naming

Instead of literal names, use semantic naming:

Good:

• color-primary
• color-text-body
• color-background-elevated
• color-border-interactive
• color-status-success

Avoid:

• blue-500
• dark-gray
• light-background

Color Palette Organization

Base Colors:

• Primary brand color (1-2 shades)
• Secondary brand color (optional)
• Neutral grays (5-7 shades)

Semantic Colors:

• Success (green)
• Warning (yellow/orange)
• Error (red)
• Info (blue)

Application Colors:

• Text colors (primary, secondary, disabled)
• Background colors (default, elevated, overlay)
• Border colors (default, hover, focus)
• Interactive colors (link, hover, active)

Accessibility Requirements

Document contrast ratios for all color combinations:

• Normal text: minimum 4.5:1
• Large text (18pt+): minimum 3:1
• UI components: minimum 3:1

Typography System Best Practices

Type Scale

Use a modular scale for consistency:

• Scale ratio: 1.250 (Major Third) or 1.333 (Perfect Fourth)
• Base size: 16px
• Scale: 12px, 14px, 16px, 20px, 24px, 30px, 36px, 48px

Font Loading Strategy

Document how fonts should be loaded:

• System fonts vs. web fonts
• Font loading approach (FOUT, FOIT, FOFT)
• Fallback font stack
• Variable font usage (if applicable)

Responsive Typography

Specify how typography scales:

• Fluid typography (CSS clamp)
• Breakpoint-based sizing
• Line length considerations (45-75 characters optimal)

Layout & Spacing Best Practices

8-Point Grid System

Use multiples of 8 for spacing:

• 4px: Minimal spacing (between closely related elements)
• 8px: Default spacing
• 16px: Section spacing
• 24px: Component spacing
• 32px: Large spacing
• 48px: Section breaks
• 64px: Major section breaks

Responsive Grid

Document grid behavior:

• Column count per breakpoint
• Gutter width
• Margin width
• Content max-width
• Grid nesting rules

Versioning & Changelog Best Practices

Semantic Versioning

Use semantic versioning for design systems:

• Major (1.0.0): Breaking changes
• Minor (1.1.0): New features, backward compatible
• Patch (1.1.1): Bug fixes

Changelog Format

Document all changes:

## Version 1.2.0 - 2024-01-15

### Added
- New toast notification component
- Dark mode support for all components

### Changed
- Updated button focus states for better accessibility
- Refined color palette with improved contrast ratios

### Deprecated
- Old modal component (use Dialog instead)

### Fixed
- Input field placeholder text color contrast
- Card shadow rendering on mobile devices

Documentation Format Best Practices

Writing Style

• Use active voice
• Be concise and specific
• Include examples
• Explain the "why" not just the "what"
• Provide do's and don'ts
• Consider international audiences

Visual Documentation

• Include screenshots or mockups
• Show before/after comparisons
• Illustrate spacing with visual markers
• Display color swatches with values
• Demonstrate responsive behavior

Code Examples

• Syntax highlight code blocks
• Show complete, working examples
• Include comments for clarity
• Provide copy button for easy use
• Support multiple frameworks when relevant

Tools & Resources

Design Tools

• Figma (collaborative design, components, design tokens)
• Sketch (Mac-based design tool)
• Adobe XD (design and prototyping)

Documentation Platforms

• Storybook (component documentation)
• Zeroheight (design system documentation)
• Notion (knowledge management)
• GitBook (technical documentation)

Design Token Management

• Style Dictionary (token transformation)
• Theo (design token tooling)
• Design Tokens Community Group format

Testing & Validation

• Chromatic (visual regression testing)
• Axe DevTools (accessibility testing)
• Contrast checker tools
• Typography tester tools

Common Pitfalls to Avoid

1. Over-specification: Don't document every pixel. Focus on principles and key measurements.

2. Under-maintenance: Keep documentation current. Outdated docs are worse than no docs.

3. Ignoring accessibility: Build accessibility in from the start, not as an afterthought.

4. Poor organization: Use clear hierarchy and navigation. Make content easy to find.

5. No governance: Establish who maintains the system and how changes are proposed.

6. Platform-specific only: Consider cross-platform needs if relevant.

7. Missing context: Always explain why, not just what and how.

8. No examples: Show, don't just tell. Include visual and code examples.

9. Inconsistent naming: Use consistent terminology throughout the system.

10. Forgetting users: Design documentation for your actual users (designers and developers).

Further Reading

• "Design Systems" by Alla Kholmatova - Comprehensive guide to creating design systems
• "Atomic Design" by Brad Frost - Methodology for creating design systems
• Material Design Documentation - Google's comprehensive design system
• Inclusive Components by Heydon Pickering - Accessible component patterns
• Design Systems Repo - Collection of design system examples and resources