Design systems

Design Systems

Purpose

Build a component library that teams actually adopt: tokens instead of hardcoded values, components with a small honest API, and documentation that answers "which one do I use" without a meeting.

When to Use

• Starting a design system or component library.
• Auditing a codebase for inconsistency (fourteen shades of grey, six button implementations).
• Designing the API of a shared component.
• Deciding whether a new pattern belongs in the system.

Capabilities

• Token architecture: primitive, semantic, and component layers.
• Component API design: variants, sizes, states, composition.
• Theming, including dark mode and per-brand overrides.
• Documentation with live examples and usage guidance.
• Adoption tracking and migration from ad-hoc components.

Inputs

• The existing visual language, however inconsistent.
• The consuming applications and their frameworks.
• The team's appetite for governance — a system nobody enforces will not hold.

Outputs

• A token set with three layers and no hardcoded values in components.
• Components with documented variants, states, and accessibility behavior.
• A contribution and deprecation process.

Workflow

1. Audit first — Extract every colour, spacing value, font size, and radius currently in use. The count is always shocking, and it is the argument for the system.
2. Build tokens in layers — Primitives (blue-600) hold raw values. Semantic tokens (color-action-primary) reference primitives and carry meaning. Component tokens (button-bg-primary) reference semantic tokens. Only the primitive layer contains literal values.
3. Design the component API around variants — variant, size, state. Not fifteen boolean props whose combinations are mostly invalid.
4. Cover the states — Default, hover, active, focus-visible, disabled, loading, error. A component missing focus-visible is inaccessible, not merely incomplete.
5. Document with live examples — Show the correct usage and the incorrect one. "Do / Don't" prevents more misuse than prose.
6. Govern adoption — A lint rule that forbids hardcoded colours is worth more than a style guide nobody reads.

Best Practices

• Semantic tokens are what let you re-theme. A component referencing blue-600 directly cannot be themed; one referencing color-action-primary can.
• Boolean props multiply: isPrimary, isLarge, isDanger allows isPrimary + isDanger, which is meaningless. A variant union makes invalid combinations unrepresentable.
• Every interactive component needs a visible focus indicator. Removing the outline without replacing it is the most common accessibility failure in design systems.
• Provide an escape hatch (className, style) but do not design around it. If every consumer overrides the same thing, the component's API is wrong.
• Version and deprecate properly. Removing a prop without a deprecation cycle breaks consumers you do not know about.
• A component used by one team is not a design-system component. Promote on the second consumer, not on speculation.

Examples

Three-layer token architecture:

:root {
  /* 1. Primitives — raw values, never used directly by components. */
  --blue-600: #2563eb;
  --blue-700: #1d4ed8;
  --grey-100: #f3f4f6;
  --grey-900: #111827;

  /* 2. Semantic — meaning, referencing primitives. This layer is what themes swap. */
  --color-action-primary: var(--blue-600);
  --color-action-primary-hover: var(--blue-700);
  --color-surface: #ffffff;
  --color-text: var(--grey-900);

  /* 3. Component — scoped to one component, referencing semantic tokens. */
  --button-bg-primary: var(--color-action-primary);
  --button-bg-primary-hover: var(--color-action-primary-hover);
}

[data-theme="dark"] {
  /* Only the semantic layer is redefined. Components need no changes. */
  --color-action-primary: #60a5fa;
  --color-surface: var(--grey-900);
  --color-text: var(--grey-100);
}

Component API: variants, not boolean soup:

type ButtonProps = {
  variant?: "primary" | "secondary" | "ghost" | "danger";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
  disabled?: boolean;
} & ButtonHTMLAttributes<HTMLButtonElement>;

Four variants and three sizes yield twelve valid combinations. Four booleans would yield sixteen, of which most are nonsense.

Notes

• Enforce token usage with a lint rule (stylelint-declaration-strict-value or an ESLint rule for inline styles). Without enforcement, hardcoded values return within a month.
• A design system's real adoption metric is the number of hardcoded values remaining in consuming applications, trending toward zero. Track it.
• Do not build a component until it has two real consumers with the same requirements. Building for a hypothetical second consumer produces an API that fits neither.