Skip to content

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.md
index 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 the
normalized 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`. One
name cannot appear in both maps because CSS output and portable token helpers
@@ -141,13 +167,18 @@ public surface belongs to
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.
+- 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 to
AST-006 decisions 1–4 and 6 establish the shipped theme-local authoring shape,
exact naming and inheritance rules, enrolled-only validation, and shared value
contract. 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 |