An open source design system that's fully customizable and agent ready
TypeScript
docs: separate theme construction from validation (#5965)
Cindy Zhangbe8ea2dc913b
diff --git a/docs/architecture/theme-authoring-contract.md b/docs/architecture/theme-authoring-contract.mdindex 139f9ce663..6b0469d311 100644--- a/docs/architecture/theme-authoring-contract.md+++ b/docs/architecture/theme-authoring-contract.md@@ -12,6 +12,7 @@ owners: [cixzhang, imdreamrunner]applies_to:[packages/core/src/theme/defineTheme.ts,+ packages/core/src/theme/syntax/defineSyntaxTheme.ts,packages/core/src/theme/expandColorScale.ts,packages/core/src/theme/expandTypeScale.ts,packages/core/src/theme/expandRadiusScale.ts,@@ -19,11 +20,13 @@ applies_to:packages/core/src/theme/mergeComponents.ts,packages/core/src/theme/onMediaTokens.ts,packages/core/src/theme/localTokens.ts,+ packages/themes/,packages/cli/assets/theme.template.ts,]verified_by:[packages/core/src/theme/defineTheme.test.ts,+ packages/core/src/theme/syntax/serverSafeSyntax.test.ts,packages/core/src/theme/expandColorScale.test.ts,packages/core/src/theme/expandTypeScale.test.ts,packages/core/src/theme/expandRadiusScale.test.ts,@@ -38,6 +41,7 @@ deciding_specs:spec:AST-006/DEC-3,spec:AST-006/DEC-4,spec:AST-006/DEC-6,+ spec:AST-017/DEC-1,]---@@ -109,6 +113,15 @@ style key, and CSS property rather than replacing the entire inherited target.- **INV9 — Authoring and output are separate systems.** This record owns thenormalized theme definition. The shared compiler owns turning it into styles;runtime and build own using or saving that output.+- **INV10 — `defineTheme` validates only what it constructs.** It owns theme+ creation and normalization. It may reject malformed input that affects normalized+ theme behavior or generated values as a construction precondition. Authoring or+ reference data used only for validation stays outside `DefineThemeInput` and+ `DefinedTheme`.+- **INV11 — Theme `define*` helpers construct theme values.** They transform,+ derive, or normalize input into a durable typed theme value used by a current+ supported consumer; validating and returning the exact input unchanged is+ insufficient.This record does not own:@@ -129,8 +142,21 @@ public surface belongs to## Change coupling-- Adding an authoring field defines its normalization, precedence, inheritance,- validation, template exposure, and negative tests together.+- Admission asks: **What normalized theme behavior or generated value does this+ field or `define*` helper construct, and how do runtime and static build consume+ it?** No concrete answer keeps it out of Core runtime authoring. An admitted+ field's normalization, precedence, inheritance, validation, template exposure,+ and negative tests change together.+- Validation-only theme data stays in theme-package tests, internal test utilities,+ or an explicit CLI checker/doctor workflow used by a current supported consumer.+ It does not enter Core runtime merely to share a validator.+- `spec:AST-017` owns breaking classification and migration. A maintained theme+ release enters that path when its source or build stops working unchanged with a+ Core version inside the theme's currently supported peer/dependency range, even+ if its normalized tokens and CSS are unchanged. A validation-only Core field,+ helper, or export that causes that failure is a real compatibility cost, not+ harmless metadata. A targeted, coordinated break may proceed only through that+ compatibility owner; this record does not define its remedy.- A local-token change preserves explicit enrollment, exact owner namespaces,source/built lineage parity, and the separation from portable `tokens`. Onename cannot appear in both maps because CSS output and portable token helpers@@ -141,13 +167,18 @@ public surface belongs toand on-media composition; no layer invents its own merge rule.- A new generated scale states which semantic tokens it may produce and confirmsexplicit 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.+- Authoring fields unavailable to the runtime-only path remain prohibited.+ Build/CLI metadata without a normalized-theme effect may exist only for a named+ current supported reader, stays outside `DefineThemeInput` and `DefinedTheme`,+ and must not impose Core/runtime compatibility. A hypothetical sidecar is+ insufficient.## Owning code- `packages/core/src/theme/defineTheme.ts` owns the public input, normalized IR,orchestration, and extension behavior.+- `syntax/defineSyntaxTheme.ts` constructs syntax themes before `defineTheme`+ adopts their tokens.- `expandColorScale.ts`, `expandTypeScale.ts`, `expandRadiusScale.ts`, and`expandMotionScale.ts` own their derived token/component values.- `mergeComponents.ts` owns the shared deep-merge rule.@@ -162,15 +193,20 @@ public surface belongs toAST-006 decisions 1–4 and 6 establish the shipped theme-local authoring shape,exact naming and inheritance rules, enrolled-only validation, and shared valuecontract. The remaining authoring and normalization architecture predates that-spec and remains unchanged.+spec and remains unchanged. AST-017 decision 1 owns released compatibility+classification and migration; this record identifies only the theme/Core trigger+that enters that path.## 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 |-| INV8 | `defineTheme.test.ts` and CLI source/built inheritance tests | Enrollment, validation, or lineage differs across runtime and static authoring paths |-| Authoring projection | `scripts/check-theme-template.test.mjs` | A supported authoring concept is missing or misstated in the template |+| 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 |+| INV8 | `defineTheme.test.ts` and CLI source/built inheritance tests | Enrollment, validation, or lineage differs across runtime and static authoring paths |+| INV10 | `DefineThemeInput`/output diff plus runtime/build fixtures | Validation-only data enters the normalized theme, or productive input loses construction validation |+| INV11 | Core theme export diff, constructed-value evidence, and current-consumer callsite | A theme `define*` helper only checks input and returns that exact input unchanged |+| Theme/Core compatibility | Maintained theme source/build against the minimum Core in its currently supported peer/dependency range | A theme update silently requires newer in-range Core or bypasses the `spec:AST-017` path |+| Authoring projection | `scripts/check-theme-template.test.mjs` | A supported authoring concept is missing or misstated in the template |