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.mdindex 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 maintainerdispositions to consumers; they do not declare which CSS properties haveguaranteed 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. Atheme 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 fallbackfield. `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.mdindex 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. Agenerative axis expands against the root axis metadata, and every produced leafcounts 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. Statesare component-owned and never theme-generated.- **FR5 — Media surfaces remain more specific.** Adaptation values resolve over theroot 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 JavaScriptmodule retains the effective width-breakpoint map, normalized generative-axismetadata, 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 narrowingthe 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 questionsNone.