How would you architect a design system used by several product teams? Cover tokens, components, distribution and documentation.

Build it in layers: tokens, then components, then distribution, documentation and governance.

Tokens are the foundation. A design token is a named design value, like a colour or a spacing size. Tokens cover colour, spacing, typography, radius, shadow and motion. They are defined once in a platform-neutral format (JSON). Then they are compiled to CSS variables, TypeScript constants and native formats. I use tiers:

• Primitive tokens, like blue-600.
• Semantic tokens, like color-bg-danger. They describe a purpose.
• Component tokens, occasionally.

Components only use semantic tokens.

Components are built in layers. First come unstyled accessible primitives, or a headless library (logic with no styling). Then come styled components with a small, consistent prop API. Accessibility is built in and tested, so teams get it for free.

Distribution: publish a versioned package that follows semantic versioning (semver: the major number goes up on breaking changes). The package is tree-shakeable ESM, so apps only bundle what they import. It has changelogs. Breaking changes ship with codemods and deprecation warnings before removal. A codemod is a script that rewrites code automatically.

Documentation: a Storybook-style site with:

• live examples
• usage guidance
• do and don't examples
• accessibility notes
• props tables generated from the types

Visual regression tests and a11y (accessibility) tests run on every story. Visual regression tests compare screenshots to catch unwanted visual changes.

Governance: a core team owns the system. A contribution process lets product teams propose components.