Design systems as versioned behavioral contracts

Outcome and why a component gallery is insufficient

A design system distributes interaction, visual and release contracts. A button screenshot cannot prove form semantics, focus behavior, package consumption or upgrade compatibility. Begin with two consumers and one capability they genuinely share.

Token pipeline and constraints

The workbench compiles a documented subset of DTCG-style token data into CSS variables and TypeScript names. It supports sRGB colors, dimensions and aliases with inherited types; it rejects cycles, unresolved references and flattened-name collisions. It does not claim complete DTCG conformance. The 2025.10 format is a community specification, not a W3C Recommendation.

Separate primitive values from semantic roles such as text, surface and action. Consumers should use semantic names so brand changes do not require replacing every component class. A token rename is an API migration: retain an alias during a deprecation window, update consumers, then remove the old name in an appropriate release. Validate alias graphs before emitting partial output.

Behavioral kernel

The fixture provides Button, Field, Dialog and Notice. Button defaults to type=button to avoid accidental form submission. Field associates labels and errors with a stable generated ID. Dialog uses a named native modal and a close form. Notice exposes meaningful progress through a status region. These choices are behavior, not merely style.

Do not promise that a prop-compatible update is nonbreaking. Changing focus order, accessible names, CSS precedence or default form behavior can break consumers. Publish a compatibility table covering TypeScript API, DOM semantics, tokens, stylesheet delivery and runtime peers.

Package and adoption decisions

Use explicit exports and peer dependencies for React. Decide whether consumers compile source styles or import distributed CSS. The latter reduces build coupling; the former can enable integration-specific optimization but expands your compatibility matrix. The test:package script packs the kernel and builds both Vite and Next consumers from its tarball. This catches missing files and undeclared dependencies that workspace symlinks can hide. Storybook includes default, disabled, pending, invalid-field and modal states.

Headless behavior is useful when several brands require different markup or styling, but headless does not mean accessible by default regardless of composition. Slot contracts must specify where names, descriptions, refs and event handlers land. Avoid unrestricted polymorphism when it makes those contracts impossible to state.

Failure exercise and evaluation

Rename a semantic token, create an alias cycle, and consume the kernel in a second build. Run keyboard tests, dark mode, RTL, zoom and forced-colors checks. The automated axe scan detects some failures; manual assistive-technology testing remains a distinct review activity. Use realistic invalid, pending, empty and destructive states in the component catalog.

A strong migration includes a compatibility alias, a consumer diff, both production builds and a rollback version. Do not report faster authoring or smaller CSS without a controlled comparison. The token tests establish compiler behavior; they do not establish usability or full specification compliance.

Executable reference and sources

Implementation · Behavioral evidence · Primary source.

Run the projects and assessment. Human review is pending.