← Back to Blog Engineering

Component Design Systems Guide

Last Rev Team Feb 28, 2023 8 min read
Design system component library with tokens, variants, and documentation panels in a development environment

A design system without adoption is just a Figma file nobody opens. We have seen it happen dozens of times... a team spends months building a comprehensive component library, publishes beautiful documentation, and then watches as developers continue building one-off components because the system is too rigid, too complex, or too disconnected from how they actually work.

The design systems that succeed are not the prettiest or the most comprehensive. They are the ones that make the right thing the easy thing. That means components that are genuinely faster to use than building from scratch, documentation that answers real questions, and a governance model that lets the system evolve without a committee meeting.

What a Design System Actually Is (and Is Not)

Let's clear up a common confusion. A design system is not a component library. A component library is part of a design system. The full picture includes:

  • Design tokens: The primitive values... colors, typography, spacing, shadows, border radii... that define your visual language
  • Components: Reusable UI pieces built on those tokens, from buttons and inputs to complex patterns like data tables and modal dialogs
  • Patterns: Documented solutions to common design problems. How do you handle form validation? What does an empty state look like? How do error messages work?
  • Documentation: Usage guidelines, do's and don'ts, accessibility requirements, and code examples for every component and pattern
  • Governance: How new components get proposed, reviewed, built, and released. Who decides what goes in the system and what stays out.

Companies like Shopify (Polaris), IBM (Carbon), and Salesforce (Lightning) have invested heavily in design systems because the ROI scales with organizational size. The more teams building products, the more value a shared system creates.

Start with Tokens, Not Components

Most teams make the mistake of starting with components. They build a button, then a card, then a navigation bar. But without tokens underneath, every component makes its own decisions about spacing, colors, and typography. You end up with a library of components that do not feel like they belong together.

Design tokens are the foundation. Define them first:

Token CategoryExamplesWhy It Matters
Colorbrand-primary, surface-default, text-secondarySemantic naming means designers and developers use the same language
Spacingspace-xs (4px), space-sm (8px), space-md (16px)Consistent spacing is the single biggest factor in visual harmony
Typographyfont-heading-lg, font-body-md, font-captionLimits the proliferation of random font sizes across the site
Elevationshadow-sm, shadow-md, shadow-lgCreates a clear visual hierarchy for overlapping elements
Motionduration-fast (100ms), easing-standardConsistent animation feels polished; inconsistent animation feels broken

Once your tokens are defined, every component references them. A button does not have padding: 12px 24px... it has padding: var(--space-sm) var(--space-md). Change the token, and every component using it updates automatically.

Building Components That Get Adopted

The best component library in the world is useless if developers do not use it. Adoption comes down to three things: the components must be easy to find, easy to use, and flexible enough to handle real-world scenarios.

Easy to find: Storybook has become the standard for documenting and browsing component libraries. It gives teams a visual catalog where they can see every component, every variant, and every state. Interactive examples beat static documentation every time.

Easy to use: The API surface of each component should be minimal. If a developer needs to read a page of documentation to use a button, the API is too complex. Sensible defaults matter... a <Button>Click me</Button> should look and work correctly without any additional props.

Flexible enough: Components need to handle the 80% case beautifully and provide escape hatches for the 20%. Composition patterns (slots, render props, children) give consumers flexibility without bloating the component API.

The Variant Problem

Every design system faces the variant explosion. You start with a primary button and a secondary button. Then someone needs a ghost button. Then a destructive button. Then a small destructive ghost button with an icon on the left.

How you handle variants determines whether your system stays maintainable or collapses under its own weight:

  • Limit intentional variants. Not every visual variation needs to be a first-class variant. If something is used on one page, it might not belong in the design system.
  • Use composition instead of props. Instead of <Button icon="check" iconPosition="left">, consider <Button><Icon name="check" /> Save</Button>. Less API surface, more flexibility.
  • Document when to use each variant. Developers should not have to guess whether to use "secondary" or "tertiary." Clear usage guidelines prevent misuse.
  • Have a contribution process. When someone needs a new variant, there should be a lightweight process to evaluate whether it belongs in the system or is a one-off.

Accessibility: Build It In, Not Bolt It On

A design system is the best place to solve accessibility because you solve it once and every consumer benefits. Every component in your system should handle:

  • Keyboard navigation: Focus management, tab order, keyboard shortcuts where appropriate
  • Screen reader support: Proper ARIA attributes, meaningful labels, live regions for dynamic content
  • Color contrast: Token-level enforcement of WCAG AA contrast ratios
  • Motion sensitivity: Respecting prefers-reduced-motion for animations

When accessibility is baked into the component, individual product teams cannot accidentally ship inaccessible features. The system enforces the standard. This is significantly more reliable than relying on individual developers to remember accessibility requirements on every feature they build.

Governance: Who Owns the System?

Design systems die without clear ownership. Somebody needs to be responsible for maintaining quality, reviewing contributions, and making decisions about what goes in and what stays out.

The models we see working in practice:

  1. Dedicated team: A small team (2-4 people) owns the design system full-time. They build core components, review contributions, and maintain documentation. This works best for large organizations with multiple product teams.
  2. Federated model: Design system responsibilities are distributed across product teams. Each team contributes components back to the shared library. A small group maintains standards and reviews contributions. Better for mid-size organizations.
  3. Champion model: One or two senior developers champion the design system alongside their regular product work. Contributions come from anyone. This works for smaller teams but requires strong individuals who can drive adoption.

The worst option is no ownership at all. A design system without a maintainer becomes outdated within months, and an outdated system is worse than no system... it creates false confidence that things are consistent when they are not.

How We Build Design Systems at Last Rev

At Last Rev, we have built design systems for clients across multiple industries and scales. Our approach starts with tokens and a small set of foundational components, then grows based on actual product needs rather than theoretical completeness.

We use Storybook for documentation and visual testing, design tokens for theming flexibility, and a contribution model that lets client teams extend the system without breaking it. The systems we build are designed to outlast our engagement... they should be maintainable by internal teams long after we are done.

If your team is struggling with UI inconsistency, slow feature delivery, or the gap between design and development, a well-built design system might be the highest-leverage investment you can make.

Sources

  1. Storybook -- "4 Ways to Document Your Design System with Storybook" (2023)
  2. Shopify -- "Polaris Design System" (2023)
  3. Brad Frost -- "Atomic Web Design" (2013)
  4. UXPin -- "How Storybook Helps Developers with Design Systems" (2023)