Design System Best Practices

A well-crafted design system is the foundation of any successful product. In this post, we’ll explore the key principles that make Anti-Gravity’s design system effective and maintainable.

What is a Design System?

A design system is a collection of reusable components, guided by clear standards, that can be assembled to build any number of applications. It includes:

• Design tokens (colors, typography, spacing)
• Components (buttons, cards, forms)
• Patterns (navigation, layouts)
• Documentation

Core Principles

1. Consistency Over Creativity

While creativity is important, consistency is crucial for a good user experience. Users should be able to predict how elements behave across your application.

/* Use consistent spacing */
--space-1: 0.25rem;  /* 4px */
--space-2: 0.5rem;   /* 8px */
--space-3: 0.75rem;  /* 12px */
--space-4: 1rem;     /* 16px */
--space-6: 1.5rem;   /* 24px */
--space-8: 2rem;     /* 32px */

2. Token-Based Design

Design tokens are the visual design atoms of the design system. They’re named entities that store visual design attributes.

:root {
  /* Colors */
  --color-primary: #4f46e5;
  --color-text: #0a0a0a;
  --color-muted: #737373;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  
  /* Radii */
  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 14px;
}

3. Component Composition

Build complex components from simpler ones. This promotes reusability and makes maintenance easier.

// Card is composed of smaller parts
<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
  </CardHeader>
  <CardContent>
    Content goes here
  </CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>

4. Accessibility First

Accessibility should be built into components from the start, not added as an afterthought.

Key considerations:

• Keyboard navigation
• Screen reader support
• Color contrast ratios
• Focus indicators
• Reduced motion support

/* Respect user preferences */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

5. Dark Mode Support

Modern applications need to support both light and dark themes. Use CSS variables to make this seamless.

:root {
  --color-bg: #ffffff;
  --color-text: #0a0a0a;
}

.dark {
  --color-bg: #0a0a0a;
  --color-text: #fafafa;
}

Component States

Every interactive component should have clearly defined states:

1. Default - The normal state
2. Hover - When the cursor is over the element
3. Focus - When the element has keyboard focus
4. Active - When the element is being pressed
5. Disabled - When the element is not interactive
6. Loading - When an action is in progress

const buttonVariants = cva(
  'inline-flex items-center justify-center',
  {
    variants: {
      variant: {
        primary: 'bg-primary text-white hover:bg-primary-hover',
        secondary: 'bg-surface border hover:bg-surface-2',
        ghost: 'hover:bg-surface',
      },
    },
  }
);

Documentation

Good documentation is essential. For each component, document:

• Purpose - What the component is for
• Props - Available customization options
• Examples - Common use cases
• Accessibility - A11y considerations
• Do’s and Don’ts - Best practices

Conclusion

Building a design system is an investment that pays dividends over time. By following these principles, you’ll create a system that’s:

• Easy to maintain
• Consistent across your application
• Accessible to all users
• Scalable as your product grows

Start small, iterate often, and always keep your users in mind.