Skip to content
xds

How it fits together

A single set of token files serves as the source of truth, and each platform renders the same set of components using code generated from those files.

  • Platforms share design decisions rather than component code. Token names and values are shared across targets, along with each component’s variants, sizes, and tones, while each platform implements the rendering natively in its own stack.
  • Color tokens are organized into three tiers: a raw palette, semantic colors tied to UI roles, and component-specific colors. Application screens never reference the raw palette directly.
  • Accessibility contrast is verified at build time. Every token build checks 110 color pairings across both light and dark modes.
  • Control heights scale with the input device (mouse pointer vs. touch) rather than screen width.
  • Applications import only the design system package, never the underlying UI libraries directly (HeroUI v3 on web, GPUI Component on desktop, React Native primitives on mobile, and Compose foundation in the Kotlin client).
  • Accent and neutral colors are defined as themes. Five themes ship with the template, and switching between them swaps two color ramps in the palette without changing anything else.
flowchart TD
  SRC["design/tokens<br/>DTCG JSON"]
  BUILD["tools/design-build<br/>validate, check contrast, generate"]
  SRC --> BUILD


  BUILD --> CSS["theme.css<br/>CSS custom properties"]
  BUILD --> TW["tailwind.css<br/>Tailwind theme"]
  BUILD --> TS["tokens.ts<br/>TypeScript constants"]
  BUILD --> RS["generated.rs<br/>Rust constants"]
  BUILD --> KT["Tokens.kt<br/>Compose values"]


  CSS --> WEB["@acme/ui<br/>web components (HeroUI)"]
  TW --> WEB
  TS --> RN["@acme/ui-native<br/>React Native components"]
  RS --> UI["acme-ui<br/>GPUI components"]
  KT --> CMP["kotlin/ui<br/>Compose components"]

design/build.json configures which output files the generator writes and where they are placed. A project scaffolded with a subset of clients lists only the outputs it needs.

The generator has no dependencies beyond Node itself: node tools/design-build/src/build.ts runs it directly, which is what mise run tokens invokes.

Generated files are committed to the repository. CI runs mise run check:generated to rebuild them and fails if the output differs from the committed files.