An open source design system that's fully customizable and agent ready
TypeScript
docs: gate theme-extensible axes on safe fallbacks (#6063)
Cindy Zhangd30591054fc4
diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.mdindex 419bc492e7..ccb6dd580a 100644--- a/docs/architecture/component-theming-surface.md+++ b/docs/architecture/component-theming-surface.md@@ -19,6 +19,7 @@ applies_to:packages/core/src/theme/themingTargets.test.ts,packages/core/src/theme/extensibleAxes.test.ts,packages/core/src/theme/derivedVarRegistry.test.ts,+ docs/contributing/api-conventions.md,docs/templates/knowledge/component-spec.md,scripts/check-knowledge.mjs,]@@ -165,6 +166,14 @@ but acceptance alone is best effort, not a compatibility promise.- **INV13 — Family ownership is explicit.** A family document may own a sharedtarget for several components, but local docs link to that owner rather thanleaving ownership to inference.+- **INV14 — Extensible axes need a theme-independent fallback.** A prop axis may+ be theme-extensible only when it is visual and an unavailable custom value has+ one safe, deterministic baseline that does not depend on the active theme.+ `Heading.type` qualifies because required `Heading.level` provides that+ baseline. `Icon.size` does not: no missing custom size can be inferred without+ 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.This record does not own semantic token definitions, theme authoring precedence,how themes become output, or the design rationale for a component's appearance.@@ -179,6 +188,13 @@ how themes become output, or the design rationale for a component's appearance.create CSS API. A `none` entry classifies the current state as `intentional`,`reachability-gap`, or `unsettled`; changing reachability updates the mapping,while future exposure still follows normal public-target review.+- Opening a prop axis to theme-defined values classifies the axis and records its+ no-match fallback in the owning component contract or governing system spec.+ Review proves the axis is visual, the fallback is safe and theme-independent,+ and every ineligible axis stays closed. A focused component test covers the+ custom value with no matching active theme rule. `extensibleAxes.test.ts`+ checks only the structural wiring: the public map, `themeProps()` reflection,+ and consumer metadata.- Adding a property to a target's `guaranteedProperties` records its purpose andscope, proves a rational observable effect on the owned anatomy part, and addsrepresentative compiler/runtime coverage. Catalog membership alone does not add@@ -216,7 +232,9 @@ how themes become output, or the design rationale for a component's appearance.- Runtime `themeProps()` calls emit the target and state contract.- `scripts/check-knowledge.mjs`, `themingTargets.test.ts`,`extensibleAxes.test.ts`, and `derivedVarRegistry.test.ts` enforce the- source/metadata/generated relationship.+ source/metadata/generated relationship. `extensibleAxes.test.ts` proves only+ structural consistency; component contracts, review, and focused component+ tests prove whether an axis may be open and whether its fallback is safe.- Family contracts own shared target semantics when multiple components adoptone part contract.@@ -227,19 +245,30 @@ capability-based package scope were selected by the system owner.## 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 |+| 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 |Known conformance and verification gaps:+- 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.+ Component contracts or governing system specs, owner review, and focused+ fallback tests provide that evidence without treating the structural guard as+ admission policy.+- Existing map-backed axes have not all been audited against INV14.+ `Pagination.variant` and `Banner.container` are known open structural axes and+ remain conformance gaps until their vocabularies are closed. Passing the+ structural guard does not make them eligible for extension.- The shared catalog is approved, but the component-doc authoring schema has no`guaranteedProperties` field. The follow-up must add the exact-name field,migrate each current target with its rational catalog subset and revieweddiff --git a/docs/contributing/api-conventions.md b/docs/contributing/api-conventions.mdindex 35ae9841dd..028f5cded7 100644--- a/docs/contributing/api-conventions.md+++ b/docs/contributing/api-conventions.md@@ -249,7 +249,18 @@ contract props after `rest` so spread order cannot change semantics.## Open visual vocabularies and closed axes-A theme-extensible visual vocabulary uses a public `*Map` interface in the+The [component theming surface](../architecture/component-theming-surface.md#boundaries-and-invariants)+admits a theme-extensible prop axis only when it is visual and an unavailable+custom value has one safe, deterministic baseline independent of the active+theme. `Heading.type` qualifies because required `Heading.level` supplies that+baseline. `Icon.size` does not: choosing a fallback size would silently change+geometry, alignment, or composition.++Behavioral, structural, placement, directional, and state-machine axes stay+closed. A theme may redefine an existing value on a closed axis, but it may not+add one.++An admitted theme-extensible vocabulary uses a public `*Map` interface in thecomponent subpath barrel. Derive the prop type from its keys.```ts@@ -265,10 +276,11 @@ export interface ButtonVariantMap {export type ButtonVariant = keyof ButtonVariantMap;```-A theme can add a visual value through module augmentation of-`@astryxdesign/core/Button`. Keep behavioral and structural axes closed when a-theme must not invent new meanings. Examples include interaction modes,-directions, placement rules, and finite state-machine states.+A theme can add an admitted visual value through module augmentation of+`@astryxdesign/core/Button`. The component contract or governing system spec and+focused test must show the fallback when no matching theme rule is active; the+shared structural guard checks only the public map, `themeProps()` reflection,+and theming metadata.Do not assume a nested `theme.components.button.variants` shape. Follow the current[theme authoring contract](../architecture/theme-authoring-contract.md) for@@ -409,7 +421,8 @@ Before requesting review:intent.- **Check the shared grammar.** Cover names, optionality, callback/Action order,cancellation, ref target, DOM pass-through, and whether each string axis is- open or closed.+ open or closed. An open axis must name and test its safe theme-independent+ fallback when no matching theme rule is active.- **Protect compatibility.** State defaults and observable behavior. Include amigration for a released breaking change.- **Ship API evidence together.** When consumer usage or a documented promise@@ -441,8 +454,9 @@ out of architecture records.- An Action suppresses its callback, or handler order accidentally removes apromised consumer cancellation path.- A callback is required only because all inputs were assumed to require it.-- A theme-extensible visual value is a closed union, or a behavioral axis is- opened to theme augmentation.+- An eligible theme-extensible visual value is a closed union, an axis opens+ without a safe theme-independent fallback, or a behavioral, structural,+ placement, directional, or state-machine axis is opened to augmentation.- `BaseProps` is applied to a component without one stable contract element, oraccepted DOM props never reach that element.- `xstyle`, `className`, `style`, a ref, or an event handler is dropped ordiff --git a/packages/core/src/theme/extensibleAxes.test.ts b/packages/core/src/theme/extensibleAxes.test.tsindex db1543d419..f68221d06b 100644--- a/packages/core/src/theme/extensibleAxes.test.ts+++ b/packages/core/src/theme/extensibleAxes.test.ts@@ -2,8 +2,11 @@/* eslint-disable @typescript-eslint/no-require-imports *//**- * @file Guards the EXTENSIBLE prop axes — the `*Map` interfaces a theme- * augments — against the theming surface that has to carry them.+ * @file Guards the STRUCTURAL wiring of extensible prop axes — the `*Map`+ * interfaces a theme augments — against the theming surface that has to carry+ * them. Whether an axis may be open, and whether an unavailable custom value+ * has a safe theme-independent fallback, remain component-contract and review+ * decisions with focused fallback tests; source syntax cannot prove either.* @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.* @output Vitest failures naming each map whose axis a theme cannot reach.* @position Third sibling of derivedVarRegistry.test.ts (`vars`, `derived`) and@@ -65,7 +68,9 @@ function sourceFilesUnder(dir: string, out: string[] = []): string[] {for (const entry of readdirSync(dir, {withFileTypes: true})) {const full = join(dir, entry.name);if (entry.isDirectory()) {- if (entry.name === 'node_modules' || entry.name === '__tests__') {continue;}+ if (entry.name === 'node_modules' || entry.name === '__tests__') {+ continue;+ }sourceFilesUnder(full, out);} else if (/\.tsx?$/.test(entry.name) && !entry.name.includes('.test.')) {out.push(full);@@ -97,7 +102,9 @@ function collectKeyofAliases(files: string[]): Map<string, string> {if (ts.isIntersectionTypeNode(type)) {for (const member of type.types) {const found = mapBehind(member);- if (found != null) {return found;}+ if (found != null) {+ return found;+ }}return null;}@@ -117,7 +124,9 @@ function collectKeyofAliases(files: string[]): Map<string, string> {const visit = (node: ts.Node): void => {if (ts.isTypeAliasDeclaration(node)) {const map = mapBehind(node.type);- if (map != null) {aliases.set(node.name.text, map);}+ if (map != null) {+ aliases.set(node.name.text, map);+ }}ts.forEachChild(node, visit);};@@ -146,7 +155,9 @@ function mapsTypingAProp(const visit = (node: ts.Node): void => {if (ts.isInterfaceDeclaration(node) && node.name.text.endsWith('Props')) {for (const member of node.members) {- if (!ts.isPropertySignature(member) || member.type == null) {continue;}+ if (!ts.isPropertySignature(member) || member.type == null) {+ continue;+ }const typeNode = ts.isArrayTypeNode(member.type)? member.type.elementType: member.type;@@ -155,7 +166,9 @@ function mapsTypingAProp(ts.isIdentifier(typeNode.typeName)) {const map = aliases.get(typeNode.typeName.text);- if (map != null) {used.add(map);}+ if (map != null) {+ used.add(map);+ }}}}@@ -183,7 +196,9 @@ function collectExtensibleAxes(const open = propMaps;const axes: ExtensibleAxis[] = [];for (const file of files) {- if (!/\/index\.tsx?$/.test(file)) {continue;}+ if (!/\/index\.tsx?$/.test(file)) {+ continue;+ }const dir = relative(SRC_DIR, file).split('/')[0];const visit = (node: ts.Node): void => {if (@@ -194,7 +209,9 @@ function collectExtensibleAxes(const bare = node.name.text.slice(0, -'Map'.length);// The trailing PascalCase word is the prop.const match = /([A-Z][a-z0-9]*)$/.exec(bare);- if (match == null) {return;}+ if (match == null) {+ return;+ }const prop = match[1].charAt(0).toLowerCase() + match[1].slice(1);axes.push({dir, mapName: node.name.text, prop});}