An open source design system that's fully customizable and agent ready
TypeScript
docs: define theme-authoring architecture (#5710)
Cindy Zhang6a90cd972f48
diff --git a/docs/architecture/theme-authoring-contract.md b/docs/architecture/theme-authoring-contract.mdnew file mode 100644index 0000000000..9b752c1c30--- /dev/null+++ b/docs/architecture/theme-authoring-contract.md@@ -0,0 +1,151 @@+---+schema_version: 1+template_version: 1+kind: architecture+id: architecture:theme-authoring-contract+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/defineTheme.ts,+ packages/core/src/theme/expandColorScale.ts,+ packages/core/src/theme/expandTypeScale.ts,+ packages/core/src/theme/expandRadiusScale.ts,+ packages/core/src/theme/expandMotionScale.ts,+ packages/core/src/theme/mergeComponents.ts,+ packages/core/src/theme/onMediaTokens.ts,+ packages/cli/assets/theme.template.ts,+ ]+verified_by:+ [+ packages/core/src/theme/defineTheme.test.ts,+ packages/core/src/theme/expandColorScale.test.ts,+ packages/core/src/theme/expandTypeScale.test.ts,+ packages/core/src/theme/expandRadiusScale.test.ts,+ packages/core/src/theme/expandMotionScale.test.ts,+ packages/core/src/theme/onMediaTokens.test.ts,+ scripts/check-theme-template.test.mjs,+ ]+deciding_specs: []+---++# Theme authoring contract++This record defines what a theme author may express and how `defineTheme`+normalizes that input into one self-contained theme representation.++## Purpose++A theme author should describe design intent once. Runtime mounting and static+builds should consume the same normalized result instead of reinterpreting the+source configuration independently.++## System model++`DefineThemeInput` accepts:++- a name and optional normalized base theme;+- higher-order color, typography, radius, and motion configuration;+- explicit semantic token overrides;+- component target/style-key overrides;+- icon and indicator registries;+- syntax tokens; and+- `onDark` / `onLight` surface overrides.++`defineTheme` resolves that input into a flat `DefinedTheme`. An extended theme+contains the resolved values it inherits, so a build does not need the base+stylesheet at runtime.++Normalization follows one precedence order:++1. the resolved base theme;+2. values generated from color, typography, radius, and motion configuration;+3. explicit token overrides;+4. generated component typography followed by explicit component overrides;+5. inherited and explicit media-surface overrides;+6. inherited and explicit icon/indicator registry entries.++Explicit values win within their surface. Component maps merge by component,+style key, and CSS property rather than replacing the entire inherited target.++## Boundaries and invariants++- **INV1 — One input produces one normalized theme.** Runtime and build consumers+ receive the same `DefinedTheme`; they do not implement separate authoring+ semantics.+- **INV2 — Precedence is deterministic.** A value's winner follows the documented+ order and does not depend on object traversal outside that order.+- **INV3 — Extension is flattened.** `extends` accepts a real `DefinedTheme`,+ carries forward its resolved tokens, component rules, media surfaces, icons,+ and indicators, and produces a self-contained child.+- **INV4 — Invalid bases fail loudly.** An undefined, namespace, or plain object+ passed to `extends` cannot produce a plausible partial theme.+- **INV5 — Explicit tokens override generated scales.** Generated values provide+ coherent defaults; an explicit semantic token wins token by token.+- **INV6 — Component overrides merge deeply.** Restating one CSS property keeps+ inherited properties on the same component/style key.+- **INV7 — Surface overrides inherit coherently.** `onDark` and `onLight` combine+ system defaults, inherited surface values, and local overrides in that order.+- **INV8 — Authoring and output are separate systems.** This record owns the+ normalized theme definition. The shared compiler owns turning it into styles;+ runtime and build own using or saving that output.++This record does not own:++- semantic token names/defaults;+- turning `DefinedTheme` into style rules, including private-variable expansion+ and cascade/layer behavior;+- runtime mounting, scope lifetime, root synchronization, or DOM observation;+- CLI file generation and packaging; or+- which component targets, states, and public properties participate.++One future `architecture:theme-compilation` record owns platform output. For web,+runtime and static build use one CSS compiler and the same maintained stylesheet+rules. A future native compiler may turn the same theme definition into native+style objects without making CSS concepts part of shared authoring. Runtime+application and CLI packaging use the compiled output without changing it. The+participating public surface belongs to+`architecture:component-theming-surface`.++## Change coupling++- Adding an authoring field defines its normalization, precedence, inheritance,+ validation, template exposure, and negative tests together.+- Changing precedence is a compatibility decision because existing themes may+ contain both generated and explicit values.+- Changing `ComponentStyleMap` merge behavior verifies base, generated, explicit,+ and on-media composition; no layer invents its own merge rule.+- A new generated scale states which semantic tokens it may produce and confirms+ explicit token overrides still win.+- Authoring fields unavailable to the runtime-only path are prohibited; build+ tooling may add emitted type/artifact metadata but not new theme semantics.++## Owning code++- `packages/core/src/theme/defineTheme.ts` owns the public input, normalized IR,+ orchestration, and extension behavior.+- `expandColorScale.ts`, `expandTypeScale.ts`, `expandRadiusScale.ts`, and+ `expandMotionScale.ts` own their derived token/component values.+- `mergeComponents.ts` owns the shared deep-merge rule.+- `onMediaTokens.ts` owns normalization of inverted-surface overrides.+- `packages/cli/assets/theme.template.ts` is an author-facing projection and must+ remain aligned; it does not define additional semantics.++## Deciding specs++None. This record captures the approved shipped authoring and normalization+architecture.++## Verification++| Invariant | Evidence | Failure signal |+| -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |+| INV1, INV2, INV5 | `defineTheme.test.ts` plus representative runtime/build parity | Runtime and build interpret one input differently, or generated values beat explicit tokens |+| INV3, INV4 | extension and invalid-base tests | Child themes require a base stylesheet or silently accept a non-theme base |+| INV6 | component merge tests across base/generated/explicit rules | Restating one property drops inherited component styles |+| INV7 | `onMediaTokens.test.ts` and generated surface-rule tests | A child loses inherited surface customization or surface precedence changes |+| Authoring projection | `scripts/check-theme-template.test.mjs` | A supported authoring concept is missing or misstated in the template |