System DesignMonth 3 · Week 9

Day 41: Scalable Component Library Design (Design Tokens, Storybook)

Design a component library around design tokens as the single source of visual truth, so design and code never drift apart across a growing product.

Mark this day complete

Study

Concepts

Design tokens: naming the WHY, not the value

A design token is a named, semantic value (`color.text.primary`, `space.md`, `radius.card`) that abstracts away the raw value (`#15212b`, `16px`, `12px`) so the raw value can change in exactly ONE place and propagate everywhere. Tokens are typically layered: primitive tokens (raw palette: `blue-500 = #3b82f6`) feed into semantic tokens (`color.action.primary = blue-500`) that components actually consume — this indirection is what lets a full rebrand or a dark-mode variant swap values without touching component code at all.

This is the same principle as the CSS custom properties already used in this portfolio (`--ink-900`, `--accent`, `--sea`) — a token system is that idea formalized and scaled across a whole design system, often exported to multiple platforms (CSS variables for web, a Swift/Kotlin constants file for native) from one source (a tool like Style Dictionary or Tokens Studio).

Storybook as the contract between design and engineering

Storybook renders each component in isolation, across its meaningful prop/state permutations (a Button in default/hover/disabled/loading states; each token-driven color variant), independent of any specific page or app — this makes visual regressions and accidental prop-API changes obvious in review, and gives designers and other engineers a browsable, always-up-to-date reference instead of a stale wiki page or a "read the source" answer.

A mature library pairs Storybook with automated visual regression testing (Chromatic or similar) so a token or component change that visually affects components elsewhere in the library is CAUGHT in CI as a diff to review, rather than discovered by a user in production weeks later.

See It

Visualizations

Visualization

Token layering: one change propagates everywhere

Primitive Tokensblue-500: #3b82f6

Semantic Tokenscolor.action.primary → blue-500

Component<Button variant="primary">

Build It

Code Examples

Token layers as CSS custom properties

css

:root {
  /* Primitive layer — raw palette, rarely referenced directly by components */
  --blue-500: #3b82f6;
  --gray-900: #15212b;
  --space-4: 16px;

  /* Semantic layer — what components actually consume */
  --color-action-primary: var(--blue-500);
  --color-text-primary: var(--gray-900);
  --space-md: var(--space-4);
}

/* Dark mode: only the semantic layer needs to change */
[data-theme='dark'] {
  --color-action-primary: #60a5fa;
  --color-text-primary: #f1f5f9;
}

.button-primary {
  background: var(--color-action-primary); /* never a raw hex in component code */
  padding: var(--space-md);
}

A Storybook story exercising every meaningful Button state

tsx

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  argTypes: { variant: { control: 'select', options: ['primary', 'secondary', 'danger'] } },
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { variant: 'primary', children: 'Continue' } };
export const Disabled: Story = { args: { variant: 'primary', disabled: true, children: 'Continue' } };
export const Loading: Story = { args: { variant: 'primary', loading: true, children: 'Continue' } };
export const Danger: Story = { args: { variant: 'danger', children: 'Delete account' } };

Remember

Key Takeaways

Tokens name the WHY (semantic role) so the WHAT (raw value) can change globally from one source of truth.
Layer tokens: primitives (raw palette) → semantic (role-based) → components consume only the semantic layer.
This is the same idea as this portfolio's CSS variables, scaled into a formal, often multi-platform system.
Storybook isolates components across states, turning them into a browsable, reviewable contract, not tribal knowledge.
Visual regression testing (Chromatic or similar) catches unintended visual changes in CI before they reach production.

Do It

Practice

1Convert 5 raw hex/px values in a real component to a two-layer token system (primitive + semantic).
2Set up Storybook for one existing component (from this portfolio or another project) with stories for every meaningful state.
3Design a dark-mode variant for your token set by changing ONLY semantic-layer values, and verify no component code needed edits.