Design system / React component library / self-documenting reference site

Design System Lab

Design System Lab is a design system and the reference website that documents it, built as one project. The site is built from the same components it documents: navigation, the Components index, the playground, and the pattern demos all read one shared catalog rather than a separately maintained set of docs.

It ships a working, token-driven component library for React, and it shows how a production design system is actually put together: tokens, theming, component APIs, responsive rules, accessibility, and architecture enforcement. The docs avoid drifting from the code because they render from the code itself — the generated token manifest, the real source files, and the same prop option arrays the components use.

View repo View demo

361 design tokens, resolved into 919 lines of generated CSS across every modifier combination

3 × 2 × 2 products, themes, and densities resolved from one token source

534 foreground/background contrast checks, unit-tested across every product and theme

7 architecture decision records, from the stack and token tiers to multi-product theming and product typefaces

What the site does

Overview — who built it and why, a suggested review path, one design decision followed live into a working Button, and the layered architecture shown with live data.
Foundations — token tiers, color, typography, spacing, radii, elevation, motion, themes, and responsive rules, including a Theme studio that builds a full product theme from one brand color.
Components — for each one: props, defaults, precedence rules, how each prop maps to tokens, examples, accessibility notes, and the real source.
Playground — Storybook-style controls for the real public props, with presets, per-component drafts, shareable example links, a scoped product, theme and density, a resizable preview that stays in view on desktop while you edit, a container-query overlay, and a usage snippet that always matches the controls.
Patterns — realistic demos: a resource directory, a resource detail page, an activity dashboard, and a validated form. The three request-driven demos each have a scenario selector listing only the states that apply to them — loading, success, error, an empty state (an empty history for the detail page), and no results where there is a search. The form has no request, so it demonstrates validation and error recovery instead.
Design decisions — how a system is planned, shared across products, implemented, and operated, with interactive comparisons and hypothetical examples labelled as such.

The header switches the whole site between three products (Design System Lab, Harbor, and Meadow), light and dark themes, and comfortable or compact density. Each product sets its own brand color, typefaces, and shape: Design System Lab uses Jost, Harbor uses IBM Plex Sans with tighter corners, and Meadow sets Fraunces headings over Nunito text with pill-shaped controls. No component knows which one is active; everything is handled through CSS custom properties.

Theme studio

Pick one brand color and the Theme studio builds a full product theme from it: an OKLCH color ramp, every role chosen by contrast, and checks against WCAG 2, APCA, and color-vision deficiency. It exports the resulting files plus a link you can share.

This is the same decision the token pipeline makes for Design System Lab, Harbor, and Meadow, exposed as a tool instead of a one-time setup script — one brand color in, a contrast-checked product theme out.

How it's built

Tokens, components, layered imports, and container-first layout.

Design tokens

Three DTCG tiers — reference (raw palettes and scales), semantic (surface.panel, tone.danger.text), and component (button.primary.background-hover). A resolver config defines theme, product, and density modifiers; a custom pipeline in scripts/tokens resolves all 12 combinations, works out which modifiers each token actually depends on, and writes each one only as often as needed.

Component library

Layout primitives (Box, Stack, Inline, Grid, Container, ThemeScope, ScrollRegion), primitives (Text, Heading, Button, Badge, Icon, Link, Input, Select, Checkbox, Switch, Progress, Skeleton, VisuallyHidden), and composites (Card, Dialog, Alert, Tabs, Disclosure, Field, PageHeader, EmptyState, RadioGroup). Props only accept named values such as gap="medium" or tone="danger", each mapped to a token; an explicit prop always wins over the component token.

Layered architecture

Imports only point down the stack: app → content → features → domain → design-system, and within design-system: composites → primitives → layout → tokens. Custom lint scripts in scripts/architecture block layer violations, sibling-module imports, reaching past a module's public entry, import cycles, and raw colors in CSS, and require every CSS Module to declare a cascade layer.

Responsive strategy

Layout is intrinsic first — Inline wraps, Grid auto-fits. Components respond to their own container's size with container queries; viewport media queries appear only in the app shell. The site documents every @container and @media rule it actually uses.

Tech stack

React 19, strict TypeScript, Vite 7, React Router 7, and CSS Modules with native custom properties. Runtime dependencies are deliberately minimal — React, React DOM, React Router, and the products' self-hosted variable fonts from Fontsource (Jost, IBM Plex Sans, Fraunces, Nunito), with no third-party UI library. Vitest and Testing Library cover unit and component tests; Playwright with axe-core covers end-to-end, accessibility, responsive, and theming tests.

Quality gate

npm run verify runs, in order: lint (ESLint, token freshness, import boundaries, and stylesheet rules), typecheck, unit tests, the production build, and Playwright end-to-end tests with axe accessibility checks. Documentation lives alongside the code: docs/architecture.md for layers, token tiers, state ownership, and routing; the decision records in docs/decisions/; and separate accessibility, contributing, and maintenance guides.

All projects