Skip to content

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.md
index 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 shared
target for several components, but local docs link to that owner rather than
leaving 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 and
scope, proves a rational observable effect on the owned anatomy part, and adds
representative 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 adopt
one 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 reviewed
diff --git a/docs/contributing/api-conventions.md b/docs/contributing/api-conventions.md
index 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 the
component 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 a
migration 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 a
promised 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, or
accepted DOM props never reach that element.
- `xstyle`, `className`, `style`, a ref, or an event handler is dropped or
diff --git a/packages/core/src/theme/extensibleAxes.test.ts b/packages/core/src/theme/extensibleAxes.test.ts
index 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});
}