Skip to content

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

TypeScript

docs(spec): align adaptation component validation with root themes (#6139)

Xinzi Zhoue6229f1fc278
diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.md
index ccb6dd580a..14ac4c08dc 100644
--- a/docs/architecture/component-theming-surface.md
+++ b/docs/architecture/component-theming-surface.md
@@ -30,7 +30,7 @@ verified_by:
packages/core/src/theme/extensibleAxes.test.ts,
packages/core/src/theme/derivedVarRegistry.test.ts,
]
-deciding_specs: []
+deciding_specs: [spec:AST-012/DEC-2, spec:AST-012/DEC-3, spec:AST-012/DEC-5]
---
# Component theming surface
@@ -80,6 +80,15 @@ component-spec metadata describe those selector axes without exposing maintainer
dispositions to consumers; they do not declare which CSS properties have
guaranteed behavior.
+An adaptation rule uses the same component target, axis, value-domain, and
+extension validation as root `components`; it does not create a parallel
+component-value policy. Built-in values and values accepted by authoritative open
+primitive domains may be styled only inside a rule and need no matching root style
+declaration. A custom value whose validity depends on theme enrollment is
+introduced on the effective root `components` map, where build tooling can
+generate unconditional module augmentation; adaptation rules may then restyle
+that value under conditions.
+
The shared guaranteed-property catalog is:
| Category | Exact authoring keys |
@@ -174,6 +183,16 @@ but acceptance alone is best effort, not a compatibility promise.
silently changing geometry, alignment, or composition. Behavioral, structural,
placement, directional, and state-machine axes remain closed regardless. A
theme may redefine an existing value on a closed axis, but it may not add one.
+- **INV15 — Conditional styling does not create conditional API.** Adaptation
+ component writes use the same shared validation as root component writes. A rule
+ may style an independently valid built-in or open-primitive value without
+ duplicating that target or value in root `components`. A custom value that
+ becomes valid only through theme enrollment must be enrolled on the effective
+ root surface before a rule uses it, so generated types never depend on a media
+ condition. An unresolved shared-validation result carries into adaptations
+ unchanged and tightens automatically when the shared contract becomes
+ authoritative; it is not a permanent adaptation exemption or an extension
+ point.
This record does not own semantic token definitions, theme authoring precedence,
how themes become output, or the design rationale for a component's appearance.
@@ -240,25 +259,35 @@ how themes become output, or the design rationale for a component's appearance.
## Deciding specs
-None. The qualification rule, consumer boundary, property support tiers, and
-capability-based package scope were selected by the system owner.
+- `spec:AST-012/DEC-2` and `spec:AST-012/DEC-3` constrain adaptation component
+ writes to the closed ordered rule model. `spec:AST-012/DEC-5` makes component
+ validation shared with root themes and reserves effective-root presence for
+ values whose validity depends on theme enrollment.
## Verification
-| Invariant | Evidence | Failure signal |
-| ------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |
-| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy |
-| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |
-| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |
-| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |
-| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |
-| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |
-| INV12, INV13 | Alias and family-owner fixtures | Deprecated aliases count as current parts or cross-doc ownership remains implicit |
-| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage | An ineligible axis opens, a missing rule changes behavior unpredictably, or the map/reflection/docs wiring drifts |
+| Invariant | Evidence | Failure signal |
+| ------------ | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |
+| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy |
+| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |
+| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |
+| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |
+| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |
+| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |
+| INV12, INV13 | Alias and family-owner fixtures | Deprecated aliases count as current parts or cross-doc ownership remains implicit |
+| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage | An ineligible axis opens, a missing rule changes behavior unpredictably, or the map/reflection/docs wiring drifts |
+| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |
Known conformance and verification gaps:
+- Component validation has unresolved domains while the shared contract remains
+ incomplete. Root and adaptation surfaces carry the same result and diagnostic;
+ this is shared validation debt, not an adaptation-specific exception or API
+ admission. When the shared contract becomes authoritative, both surfaces tighten
+ automatically. Independently valid built-in and open primitive values do not
+ require matching root style declarations.
+
- The component schema has no machine-readable axis-classification or fallback
field. `extensibleAxes.test.ts` therefore checks only structural consistency;
it cannot infer whether an axis is visual or its fallback is semantically safe.
diff --git a/docs/specs/AST-012/spec.md b/docs/specs/AST-012/spec.md
index b18964d8f2..fa585e9769 100644
--- a/docs/specs/AST-012/spec.md
+++ b/docs/specs/AST-012/spec.md
@@ -109,8 +109,16 @@ A breakpoint map alone emits no CSS. Only rules with adaptation values do.
rule, values use the root expansion, deep-merge, and kind precedence. A
generative axis expands against the root axis metadata, and every produced leaf
counts as a write by that rule. Missing required scale fields MUST be supplied
- rather than synthesized from approximate built-in defaults. A rule may style an
- existing component visual-prop value but MUST NOT introduce a new value; states
+ rather than synthesized from approximate built-in defaults. Component writes in
+ rules MUST use the same target, axis, value-domain, and extension validation as
+ root `components`; adaptations define no separate component-value validation
+ policy. A rule MAY style a built-in value or a value accepted by an
+ authoritative open primitive domain even when the effective root has no style
+ rule for that target or value. A value whose validity depends on theme
+ enrollment MUST already be enrolled on the effective root `components` surface;
+ a rule MUST NOT introduce it conditionally. An unresolved result from shared
+ root validation carries into adaptation validation unchanged. It is neither a
+ permanent adaptation exemption nor evidence that the axis is extensible. States
are component-owned and never theme-generated.
- **FR5 — Media surfaces remain more specific.** Adaptation values resolve over the
root theme. When an `onDark` or `onLight` override and an adaptation write the
@@ -155,9 +163,15 @@ A breakpoint map alone emits no CSS. Only rules with adaptation values do.
token reads and server-safe token helpers remain root-value reads.
- **IR3 — Tooling sees rule-only values.** Validation, component diagnostics,
private-variable checks, font notices, and `light-dark()` color-scheme detection
- MUST inspect values declared only in rules. Generated variant/type validation
- MUST reject a rule-only visual-prop value absent from the effective root
- component surface.
+ MUST inspect values declared only in rules. Component writes in rules MUST pass
+ through the same shared validation path as root component writes. Adaptation adds
+ only the no-conditional-enrollment check: a value accepted solely through theme
+ enrollment MUST already exist on the effective root component surface. Built-in
+ finite values and values accepted by authoritative open primitive domains do not
+ require a matching root style declaration. Rule validation MUST inherit future
+ improvements to root validation automatically; tooling MUST NOT maintain an
+ adaptation-specific allowlist, unresolved-domain exception, or domain-inference
+ path.
- **IR4 — Built themes preserve extension semantics.** A built theme's JavaScript
module retains the effective width-breakpoint map, normalized generative-axis
metadata, enrolled local-token lineage, and ordered normalized rules required
@@ -195,13 +209,13 @@ extension metadata remain useful implementation evidence.
## Verification
-| Contract | Verification | Representative states | Failure signal |
-| -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3 | Width-breakpoint and condition matrix plus browser boundaries | defaults/overrides; from/below/range; pointer/contrast/motion; multi-field AND; empty/no rules | A point acts as an upper bound, intervals gap/overlap, fields OR together, or an unused map emits CSS. |
-| FR4–FR7 | Shared resolver, surface, cascade-order, and extension tests | enrolled/unenrolled local tokens; incomplete scales; later generated vs earlier explicit leaves; surface collisions; broad/narrow reorder; child append/removal attempts | A rule enrolls a local name, widens vocabulary, approximates missing input, escapes order, beats a surface, or loses inherited order. |
-| FR8 | Theme/AppShell integration | all names/`none`; SSR hint; no/nearest/root/nested theme; exact boundaries | AppShell uses the wrong map, equality, or scope. |
-| IR1–IR3 | Runtime/build and CLI positive/negative fixtures | invalid map/range/field; source axis metadata; duplicate `when`; root-restoring rules; declaration targets; rule-only visual values; non-CSS token reads | Invalid input writes output, metadata disappears, blocks merge/reorder/drop, targets diverge, adaptation leaks into JS reads, or tooling misses values. |
-| IR4 | Generated-module import and size tests | no rules/rules; source/built parent and child; generative/local-token metadata | Breakpoints, rules, order, or metadata disappear; extension diverges; CSS text enters the module; or resolved layers duplicate. |
+| Contract | Verification | Representative states | Failure signal |
+| -------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FR1–FR3 | Width-breakpoint and condition matrix plus browser boundaries | defaults/overrides; from/below/range; pointer/contrast/motion; multi-field AND; empty/no rules | A point acts as an upper bound, intervals gap/overlap, fields OR together, or an unused map emits CSS. |
+| FR4–FR7 | Shared resolver, surface, cascade-order, and extension tests | enrolled/unenrolled local tokens; incomplete scales; finite built-ins; open primitive values absent from root; root-enrolled and rule-only custom values; unresolved shared results; later generated vs earlier explicit leaves; surface collisions | A rule enrolls a local or component value, a valid open value requires a dummy root rule, adaptation validation diverges from root validation, an unresolved result becomes a permanent exemption, or inherited order is lost. |
+| FR8 | Theme/AppShell integration | all names/`none`; SSR hint; no/nearest/root/nested theme; exact boundaries | AppShell uses the wrong map, equality, or scope. |
+| IR1–IR3 | Runtime/build and CLI positive/negative fixtures | invalid map/range/field; source axis metadata; duplicate `when`; root-restoring rules; finite/open/unresolved component domains; declaration targets; root-enrolled and rule-only custom values; non-CSS token reads | Invalid input writes output, root and adaptation component validation disagree, an independently valid value is forced into root, an adaptation conditionally enrolls a custom value, or tooling misses a rule-only value. |
+| IR4 | Generated-module import and size tests | no rules/rules; source/built parent and child; generative/local-token metadata | Breakpoints, rules, order, or metadata disappear; extension diverges; CSS text enters the module; or resolved layers duplicate. |
## Decision log
@@ -259,6 +273,22 @@ data for `extends`, while emitted CSS remains a separate artifact.
Rejected: compiling away authoring intent from built bases and silently narrowing
the existing theme-extension contract.
+### DEC-5 — Reuse root component validation; reserve root for enrollment
+
+**Reference:** `spec:AST-012/DEC-5`
+**Decider:** `cixzhang`, `2026-09-08`
+
+Component writes in adaptation rules use the same target, axis, value-domain, and
+extension validation as root `components`. A built-in finite value or a value
+accepted by an authoritative open primitive domain may appear only in a rule; it
+does not require a matching root style declaration. The effective-root requirement
+applies only when a value's validity comes from theme enrollment. Unresolved shared
+results carry into adaptations unchanged, and future improvements to root
+validation tighten adaptations automatically.
+
+Rejected: adaptation-specific value resolvers, allowlists, unresolved-domain
+exceptions, and dummy root rules for independently valid values.
+
## Open questions
None.