Building Style Guides: Consistency at Scale

Easy•

Style guides are living documentation that ensures design consistency and speeds up development.

Quick Navigation: Design Tokens • Component Documentation • Interactive Documentation • Implementation Example

Quick Decision Guide

Style Guide Essentials:

Design Tokens: Define colors, spacing, typography as variables/constants

Components: Document each component with props, variants, examples

Patterns: Show common layouts and interaction patterns

Tools: Use Storybook or similar for interactive documentation

Result: Faster development, consistent UI, easier onboarding

Design Tokens

What are Design Tokens?

Named values for design decisions: colors, spacing, typography.

// tokens.js
export const tokens = {
  colors: {
    brand: {
      primary: '#007bff',
      secondary: '#6c757d'
    },
    semantic: {
      success: '#28a745',
      error: '#dc3545',
      warning: '#ffc107'
    },
    neutral: {
      black: '#000',
      white: '#fff',
      gray: {
        100: '#f8f9fa',
        500: '#adb5bd',
        900: '#212529'
      }
    }
  },
  
  spacing: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 32,
    xxl: 48
  },
  
  typography: {
    fontFamily: {
      sans: "'Inter', -apple-system, sans-serif",
      mono: "'Fira Code', monospace"
    },
    fontSize: {
      xs: 12,
      sm: 14,
      base: 16,
      lg: 18,
      xl: 20,
      '2xl': 24
    },
    fontWeight: {
      normal: 400,
      medium: 500,
      semibold: 600,
      bold: 700
    }
  }
};

CSS Variables

:root {
  /* Colors */
  --color-primary: #007bff;
  --color-secondary: #6c757d;
  
  /* Spacing */
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  
  /* Typography */
  --font-sans: 'Inter', sans-serif;
  --font-size-base: 1rem;
  --font-weight-bold: 700;
}

.button {
  background: var(--color-primary);
  padding: var(--spacing-md);
  font-family: var(--font-sans);
}

Component Documentation

Button Component

/**
 * Button Component
 * 
 * Primary UI element for user actions
 * 
 * @param {string} variant - primary | secondary | outline
 * @param {string} size - sm | md | lg
 * @param {boolean} disabled - Disable button
 */
function Button({ 
  variant = 'primary', 
  size = 'md',
  disabled = false,
  children,
  onClick 
}) {
  return (
    <button 
      className={`btn btn-${variant} btn-${size}`}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// Usage Examples
<Button variant="primary">Primary Action</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline" disabled>Disabled</Button>

Documentation Template

# Button

Primary UI element for user actions.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | string | 'primary' | Button style variant |
| size | string | 'md' | Button size |
| disabled | boolean | false | Disable button |
| onClick | function | - | Click handler |

## Variants

- **primary**: Main action button
- **secondary**: Less prominent action
- **outline**: Tertiary action

## Examples

\`\`\`jsx
<Button variant="primary">Save Changes</Button>
<Button variant="secondary">Cancel</Button>
\`\`\`

## Accessibility

- Uses semantic <button> element
- Includes proper ARIA attributes
- Keyboard accessible (Enter/Space)

Interactive Documentation

Storybook

// Button.stories.js
import Button from './Button';

export default {
  title: 'Components/Button',
  component: Button,
};

export const Primary = () => <Button variant="primary">Primary</Button>;
export const Secondary = () => <Button variant="secondary">Secondary</Button>;
export const Disabled = () => <Button disabled>Disabled</Button>;

export const AllSizes = () => (
  <>
    <Button size="sm">Small</Button>
    <Button size="md">Medium</Button>
    <Button size="lg">Large</Button>
  </>
);

Benefits

•✅ Visual component browser

•✅ Interactive playground

•✅ Auto-generated docs

•✅ Isolated development

•✅ Accessibility testing

Implementation Example

Complete Style Guide Structure

/style-guide
  /tokens
    colors.js
    spacing.js
    typography.js
  /components
    /Button
      Button.jsx
      Button.stories.js
      Button.test.js
      README.md
    /Input
    /Card
  /patterns
    layouts.md
    navigation.md
    forms.md
  /guidelines
    accessibility.md
    code-standards.md

Usage in App

import { tokens } from '@/style-guide/tokens';
import { Button, Input, Card } from '@/style-guide/components';

function App() {
  return (
    <div style={{ padding: tokens.spacing.lg }}>
      <Card>
        <Input placeholder="Email" />
        <Button variant="primary">Submit</Button>
      </Card>
    </div>
  );
}