Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: define theme-token architecture (#5708)

Cindy Zhange4f767718ec4
diff --git a/docs/architecture/theme-tokens.md b/docs/architecture/theme-tokens.md
new file mode 100644
index 0000000000..5c46a978f2
--- /dev/null
+++ b/docs/architecture/theme-tokens.md
@@ -0,0 +1,130 @@
+---
+schema_version: 1
+template_version: 1
+kind: architecture
+id: architecture:theme-tokens
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang, imdreamrunner]
+applies_to:
+ [
+ packages/core/src/theme/tokens.stylex.ts,
+ packages/core/src/theme/tokens.ts,
+ packages/core/src/theme/domainTokens/,
+ packages/core/src/theme/syntax/,
+ packages/cli/assets/theme.template.ts,
+ ]
+verified_by:
+ [
+ packages/core/src/theme/tokens.test.ts,
+ scripts/check-theme-template.test.mjs,
+ scripts/generate-token-docs.mjs,
+ ]
+deciding_specs: []
+---
+
+# Theme token architecture
+
+This record defines the semantic token vocabulary that components, themes,
+documentation, and non-CSS consumers share.
+
+## Purpose
+
+A theme author and a component author should refer to the same stable semantic
+names. Changing a default theme, resolving a token in JavaScript, or generating
+consumer documentation must not create a second token vocabulary.
+
+## System model
+
+Core tokens are declared as paired exports in `tokens.stylex.ts`:
+
+- `*Defaults` objects hold default CSS values.
+- `*Vars` objects are created from those defaults with `stylex.defineVars` and
+ are what component styles consume.
+- `defineTheme` combines the core defaults into the complete theme token type.
+- `tokenVar`, `tokenVars`, `resolveThemeToken`, and `resolveThemeTokens` expose
+ the same vocabulary to canvas, SVG, charts, tests, build tools, and other
+ non-StyleX consumers.
+
+Syntax-highlighting and data-visualization tokens are domain layers. They remain
+separately importable so applications that do not use those domains do not need
+their implementation modules, while `domainTokenDefaults` makes their names
+available to theme validation and resolution.
+
+The CLI theme template and generated token documentation are projections of
+this vocabulary. They do not define additional tokens.
+
+## Boundaries and invariants
+
+- **INV1 — `defineVars` declarations are canonical.** A core token name and its
+ default originate in `tokens.stylex.ts`; projections do not introduce names.
+- **INV2 — Defaults and typed variables move together.** Each core token family
+ has one `*Defaults` object and matching `*Vars` export.
+- **INV3 — Token names describe semantic roles.** Components consume purpose-led
+ names such as text, surface, spacing, and motion roles rather than embedding a
+ theme's raw palette choices.
+- **INV4 — Mode-relative defaults remain one token.** A semantic role that varies
+ by color mode uses a supported `light-dark()` or tuple value instead of
+ creating unrelated light and dark token names.
+- **INV5 — Domain layers are explicit.** Syntax and data tokens are available to
+ theme authoring and resolution without being folded into the core component
+ token module.
+- **INV6 — Non-CSS consumers resolve the same graph.** JavaScript helpers follow
+ token references and supported color expressions instead of maintaining a
+ second set of resolved values.
+- **INV7 — Projections cannot drift silently.** Theme-template inventory and
+ generated token docs change with the canonical family or fail validation.
+
+This record does not own:
+
+- the `defineTheme` input shape, generated scales, or precedence;
+- mounting, nesting, color-mode selection, or runtime theme observation;
+- turning a normalized theme into scoped CSS and build files;
+- component-specific targets, visual states, or private derived variables.
+
+Those concerns belong to separate theming architecture records so a token change
+does not silently change authoring, runtime, compiler, or component contracts.
+
+## Change coupling
+
+- Adding, removing, or renaming a core `*Defaults` family updates its `*Vars`
+ export, the combined `TokenName`/defaults surface, the CLI template inventory,
+ generated token docs, and drift tests together.
+- Adding or changing a domain token updates that domain's defaults and exported
+ name type; the aggregate domain map remains the validation bridge.
+- Renaming or removing a released token is a compatibility decision, not a
+ mechanical cleanup. Consumers may use its CSS custom-property name directly.
+- Changing a default value is a visual behavior change and requires real-browser
+ evidence for representative light/dark, status, and high-contrast surfaces.
+- Changes to JavaScript resolution preserve CSS cascade semantics for supported
+ references and color expressions; unsupported expressions remain intact
+ rather than being guessed.
+
+## Owning code
+
+- `packages/core/src/theme/tokens.stylex.ts` owns core token names, defaults, and
+ StyleX variables.
+- `packages/core/src/theme/domainTokens/` and
+ `packages/core/src/theme/syntax/tokens.ts` own domain vocabularies.
+- `packages/core/src/theme/defineTheme.ts` aggregates token types/defaults for
+ validation and authoring; it does not become a second token source.
+- `packages/core/src/theme/tokens.ts` owns server-safe references and resolution.
+- `packages/cli/assets/theme.template.ts` and generated token docs are checked
+ projections for theme authors and consumers.
+
+## Deciding specs
+
+None. This record captures the approved shipped token architecture.
+
+## Verification
+
+| Invariant | Evidence | Failure signal |
+| ---------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| INV1, INV2, INV7 | `scripts/check-theme-template.test.mjs` and token-doc generation check | A token family exists without a matching author-facing inventory or generated documentation |
+| INV5 | Domain-token exports and theme-generation tests | Domain names disappear from validation or require importing unused domain implementation |
+| INV6 | `packages/core/src/theme/tokens.test.ts` | JavaScript resolution disagrees with defaults, mode selection, references, or supported color expressions |
+| Released token compatibility | Type checking plus representative package/source builds | A released CSS variable or typed token name disappears without an explicit migration decision |
+| Visual defaults | Real Chromium examples in light, dark, status, and high-contrast contexts | A changed default produces unreadable or semantically inconsistent output |