Skip to content

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

TypeScript

docs: define theme property support tiers (#5739)

Cindy Zhangb10c83922e13
diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.md
index 667b99b022..419bc492e7 100644
--- a/docs/architecture/component-theming-surface.md
+++ b/docs/architecture/component-theming-surface.md
@@ -57,19 +57,58 @@ consumer docs:
component's parent target, such as a Button label inheriting from `button`.
3. **`delegatesTo`** — another Astryx component owns the part and its target, such
as a Selector label using `Field/field-label`.
-4. **`none` with reason** — the part is intentionally not themeable. Common
- reasons are consumer-owned content, non-visual structure, or fixed design.
+4. **`none` with classified reason** — no current public target reaches this
+ stable anatomy part. The required reason begins with exactly one factual
+ classification:
+ - `intentional:` — an approved boundary makes the part non-themeable now;
+ - `reachability-gap:` — a current target should reach the part, but does not;
+ - `unsettled:` — whether or how to expose the part still needs an owner decision.
+
+`none` records current reachability. It does not by itself decide that a part must
+remain unthemeable or authorize a future public target.
Every current, non-deprecated public target maps to an anatomy entry or to an
explicit family owner. Consumer `.doc.mjs` files continue to own anatomy names,
descriptions, and public target documentation. Component specs own the exact map
and explain only non-obvious rationale or exceptions.
-Visual props, states, and public CSS properties are capabilities of a target.
-They are not separate anatomy parts or separate targets. Runtime `themeProps()`
-reflection, public `.doc.mjs` theming metadata, and checked component-spec
-metadata describe one public surface without exposing maintainer dispositions to
-consumers.
+Visual prop axes and states are selector capabilities of a target. They are not
+separate anatomy parts or separate targets. Runtime `themeProps()` reflection,
+public `.doc.mjs` `theming.targets[].visualProps` / `states` metadata, and checked
+component-spec metadata describe those selector axes without exposing maintainer
+dispositions to consumers; they do not declare which CSS properties have
+guaranteed behavior.
+
+The shared guaranteed-property catalog is:
+
+| Category | Exact authoring keys |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Paint | `color`, `backgroundColor`, `opacity`, `outlineColor`, `outlineOffset`, `outlineStyle`, `outlineWidth`, `boxShadow`, `textShadow` |
+| Border/shape | `borderColor`, `borderStyle`, `borderWidth`, `borderRadius` |
+| Typography | `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `letterSpacing`, `lineHeight`, `textAlign`, `textDecorationColor`, `textDecorationLine`, `textDecorationStyle`, `textDecorationThickness`, `textTransform` |
+| Padding | `padding`, `paddingBlock`, `paddingBlockStart`, `paddingBlockEnd`, `paddingInline`, `paddingInlineStart`, `paddingInlineEnd` |
+
+The initial catalog contains every standard CSS key used by the seven shipped
+package themes except `height`: `backgroundColor`, `borderColor`, `borderRadius`,
+`borderStyle`, `borderWidth`, `color`, `fontFamily`, `fontSize`, `fontWeight`,
+`lineHeight`, `padding`, `paddingBlock`, and `paddingInline`. It adds the explicit
+paint, typography, and logical-padding keys needed to make those categories
+coherent. `height` remains a target-specific addition because it changes layout.
+
+The catalog is a vocabulary, not an automatic guarantee on every target. Each
+target's `guaranteedProperties` lists the exact rational subset it supports from
+this catalog and any exact reviewed target-specific additions. Omission means
+best effort; no exception entry is required.
+
+The list is literal. A listed shorthand does not imply its longhands; a logical
+property does not imply a physical counterpart; and one property does not imply
+an alias such as `background`, `inlineSize`, or `outline`. Properties outside the
+catalog, including `height`, `width`, `gap`, positioning, overflow, and grid/flex
+structure, require an explicit target addition to become guaranteed.
+
+Every declared property must produce a rational, observable result on the anatomy
+part the target owns. Generic component styling may accept other CSS properties,
+but acceptance alone is best effort, not a compatibility promise.
## Boundaries and invariants
@@ -82,8 +121,10 @@ consumers.
stable semantic part, either locally or through an explicit family owner.
- **INV3 — Anatomy does not imply target proliferation.** Every participating
anatomy entry has one component-spec mapping, but inheritance, delegation, and
- `none` are valid outcomes. When desktop and touch render different parts or
- use different theming owners, they use separate anatomy rows.
+ factual `none` are valid outcomes. A `none` reason distinguishes an intentional
+ current boundary from a reachability gap or unsettled future exposure; it never
+ silently decides future themeability. When desktop and touch render different
+ parts or use different theming owners, they use separate anatomy rows.
- **INV4 — Targets paint.** A target belongs on a stable visible element that
paints theme-controlled output—not an event wrapper, speculative internal
structure, or a node created only for layout plumbing.
@@ -93,13 +134,35 @@ consumers.
- **INV6 — State stays on the owning target.** Variant, size, selection, disabled,
and interaction state are reflected as target capabilities through
`themeProps`; they do not create parallel targets solely for each state.
-- **INV7 — Public properties and private expansion are separate.** This record
- owns which public properties a target supports and their component semantics.
- `architecture:theme-compilation` owns turning those properties into private
- variables. Exact mappings remain checked code/metadata, not copied prose.
-- **INV8 — Aliases are compatibility, not anatomy.** Deprecated target aliases
+- **INV7 — Guarantees use one catalog and exact target declarations.** The shared
+ catalog defines the supported vocabulary, not an automatic target promise. Each
+ target's `guaranteedProperties` lists the rational catalog subset it guarantees
+ and any reviewed target-specific additions. Every listed property must produce
+ an observable result on the owned anatomy part, with representative compiler
+ and runtime evidence.
+- **INV8 — Names imply nothing beyond themselves.** No shorthand, longhand,
+ logical/physical counterpart, alias, or custom property is guaranteed unless
+ its exact authoring key appears in that target's declaration. Omitted properties
+ remain best effort; no exception mechanism is needed.
+- **INV9 — Generic styling is best effort.** A target may accept CSS properties
+ outside its declared guaranteed set through the generic styling pipeline. That
+ acceptance does not promise a useful effect or compatibility across releases.
+- **INV10 — Public semantic variables are admitted, not inferred.** When no
+ guaranteed CSS property can express a caller-owned need, a component may expose
+ a reviewed public custom property with purpose-based meaning, stable default or
+ fallback, defined target/state scope, consumer docs, and compatibility
+ coverage. It must pass the admission bar in
+ `architecture:public-component-api`; an implementation gap does not
+ automatically justify a new variable.
+- **INV11 — Private expansion stays private.** The compiler may translate a
+ guaranteed public property into one or more private `--_*` variables so the
+ owning component can route, compose, or transform the value across its internal
+ painters. By contract, those variables must not be authored directly or relied
+ on by consumers. Exact mappings remain checked code/metadata, not copied prose;
+ known enforcement gaps are recorded in `architecture:theme-compilation`.
+- **INV12 — Aliases are compatibility, not anatomy.** Deprecated target aliases
may remain supported but do not count as current semantic parts.
-- **INV9 — Family ownership is explicit.** A family document may own a shared
+- **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.
@@ -112,11 +175,20 @@ how themes become output, or the design rationale for a component's appearance.
`.doc.mjs` public target metadata, compatibility aliases when required,
generated/CLI discovery, and validation together.
- Adding consumer anatomy requires a deliberate component-spec mapping to a
- target, inheritance, delegation, or `none`. It does not automatically create
- CSS API.
-- Adding a public target property records its semantic purpose in metadata. A
- component-specific exception belongs in its component contract; common
- property-to-variable behavior belongs to theme compilation.
+ target, inheritance, delegation, or factual `none`. It does not automatically
+ 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.
+- 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
+ a target guarantee; target-specific behavior outside the catalog is admitted by
+ the same reviewed declaration. Common property-to-variable behavior belongs to
+ theme compilation.
+- Adding a public semantic custom property first shows why no guaranteed CSS
+ property expresses the need, then updates its component contract, consumer
+ docs, stable fallback/default, scope, runtime evidence, and compatibility
+ coverage together. It is not the default response to an unsupported property.
- Moving target ownership to a family updates every member's disposition and
link in the same reviewed change.
- Expanding participation to another package first extends the consistency guard
@@ -127,11 +199,20 @@ how themes become output, or the design rationale for a component's appearance.
- Component `.doc.mjs` `usage.anatomy[]` owns the consumer-facing semantic part
inventory and contains no theming disposition or maintainer rationale.
- Component `.doc.mjs` `theming.targets[]` owns discoverable public targets and
- their public properties/states.
+ their visual prop/state selector axes. `visualProps` does not declare CSS
+ property support.
+- The approved property catalog is owned by this record. Target
+ `guaranteedProperties` declarations will live in component `.doc.mjs`
+ `theming.targets[]` once the authoring schema supports them; there is not yet a
+ machine-readable field.
+- Component `.doc.mjs` `theming.vars[]` owns documented custom properties and
+ marks private implementation variables; `theming.derived[]` records checked
+ public-property expansion metadata.
- A colocated component `.spec.md` `### Theming anatomy` block owns the exact,
machine-readable anatomy-to-target dispositions. It is optional during
- migration and excluded from generated consumer docs. Nearby prose records only
- non-obvious rationale, exceptions, and links—not the exact mapping.
+ migration, checked against consumer anatomy, and excluded from generated
+ consumer docs. Nearby component-spec prose owns non-obvious rationale,
+ exceptions, and links.
- 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
@@ -141,19 +222,37 @@ how themes become output, or the design rationale for a component's appearance.
## Deciding specs
-None. The qualification rule, consumer boundary, and capability-based package
-scope were selected by the system owner.
+None. The qualification rule, consumer boundary, property support tiers, and
+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 | `scripts/check-knowledge.mjs` | A current target has no semantic part owner, or anatomy mechanically creates unnecessary targets |
-| 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 | Metadata plus compiler registry tests | A public property lacks semantics or private expansion is duplicated in component prose/code |
-| INV8, INV9 | 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 |
+
+Known conformance and verification gaps:
+
+- 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
+ additions, expose the declarations to discovery, and reject unknown or implied
+ names. Until that migration lands, the catalog does not automatically guarantee
+ any property on any target.
+- CI does not yet require representative compiler and runtime evidence for each
+ declared target/property pair. The follow-up must make missing output-path or
+ observable runtime evidence fail validation; layout-sensitive additions also
+ require internal-coupling and directionality evidence.
+- Runtime/build private-variable rejection and media-surface derived expansion are
+ separate compiler conformance gaps owned and specified by
+ `architecture:theme-compilation`.
### Migration work from the 2026-08-30 audit
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index 5189fe9764..bd4d2fd305 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -89,6 +89,11 @@ guidance owns the process used to propose and test APIs.
explicit compatibility decision and migration.
- **INV10 — Shared subcontracts are linked, not copied.** Input Actions, layer
behavior, theming, and family-specific rules stay with their owning records.
+- **INV11 — Public theme seams pass API admission.** A public semantic CSS custom
+ property is admitted only for caller-owned intent that the target's guaranteed
+ CSS property set cannot express. Its theming record owns the exact purpose,
+ stable default/fallback, scope, documentation, evidence, and compatibility
+ contract; an internal styling gap alone does not justify public API.
This record applies to stable public packages. Lab components are not stable
public promises until promotion.
@@ -105,6 +110,10 @@ public promises until promotion.
defect does not by itself require consumer-doc changes.
- A new prop includes the admission argument from `spec:AST-002/DEC-1`; it does
not get accepted only because it solves one callsite.
+- A new public semantic CSS custom property includes the same admission argument
+ and shows why the target's guaranteed CSS property set cannot express the
+ caller-owned need. Its detailed contract and evidence stay in the owning
+ theming/component records.
- A released breaking change includes the compatibility decision and migration
evidence required by the release process.
- Changes to a family-owned API update the family contract rather than copying
@@ -136,6 +145,7 @@ copy the component matrix.
| INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice |
| INV5, INV6, INV7 | BaseProps/passthrough lint and representative runtime tests | Consumer ARIA/data/style/events are dropped, clobber component semantics, or fail to compose |
| INV9 | Published-surface, Changeset, migration, and public-type checks | A released API changes without explicit compatibility evidence |
+| INV11 | Public-API admission review plus owning theming/component tests | A public semantic custom property exposes derivable or unsupported implementation detail |
| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |
Known verification gaps:
diff --git a/docs/architecture/theme-compilation.md b/docs/architecture/theme-compilation.md
index ca22686b3d..3d85690588 100644
--- a/docs/architecture/theme-compilation.md
+++ b/docs/architecture/theme-compilation.md
@@ -54,6 +54,15 @@ The current web compiler works like this:
types.
5. A built theme is marked so the provider does not compile or inject it again.
+For top-level declarations in base component target rules, the compiler preserves
+generic CSS properties as written. When a guaranteed property needs to reach
+internal painters, the checked registry additionally translates it into one or
+more private variables and may replace the source declaration when applying it to
+the target element would be wrong. Reviewed public semantic custom properties
+pass through as direct author input. Direct private `--_*` input is prohibited by
+the contract; current runtime, build, pseudo-rule, and media-surface conformance
+gaps are listed below.
+
A future platform compiler may turn the same theme into a different output type.
Platform-specific details stay inside that compiler.
@@ -68,15 +77,27 @@ Platform-specific details stay inside that compiler.
behavior.
- **INV4 — Web uses one cascade contract.** Runtime and built CSS use the same
scopes, `astryx-theme` layer, component overrides, and consumer precedence.
-- **INV5 — Common property expansion happens once.** A public theme property may
- set several private component variables. That mapping lives in the checked
- compiler registry, not in each component or output path.
-- **INV6 — Private variables stay private.** Theme authors use public properties
- and targets. Direct private `--_*` values are rejected.
-- **INV7 — Platform details stay out of shared authoring.** CSS selectors, layers,
+- **INV5 — Guaranteed properties remain observable.** The compiler preserves a
+ guaranteed target property directly when that produces the promised effect. If
+ internal structure prevents that, one checked registry entry may route,
+ transform, or fan the public property out to one or more private component
+ variables; the implementation choice cannot change the property's promised
+ meaning.
+- **INV6 — Private variables stay private.** Private `--_*` variables are
+ compiler/component implementation details. Theme authors use the guaranteed
+ property that owns them. Runtime and built authoring paths must reject direct
+ private values rather than emitting them as plausible output.
+- **INV7 — Public semantic variables pass through deliberately.** A reviewed
+ public custom property is direct author input only when the component-theming
+ contract admits it because no guaranteed CSS property expresses the need. The
+ compiler must preserve it without turning private machinery into public API.
+- **INV8 — Generic properties do not become promises by compiling.** The generic
+ styling pipeline may emit properties outside a target's guaranteed set. Output
+ alone does not make their effect or compatibility part of the public contract.
+- **INV9 — Platform details stay out of shared authoring.** CSS selectors, layers,
scopes, and custom properties belong to the web compiler. A native compiler
may use native style objects.
-- **INV8 — Shared intent keeps the same meaning.** A token or supported component
+- **INV10 — Shared intent keeps the same meaning.** A token or supported component
override means the same thing across outputs. Platform-only features have an
explicit support boundary.
@@ -93,8 +114,17 @@ This record does not own:
is tested through both runtime mounting and CLI-built output. The Theme
provider and CLI may mount or package compiled rules; they must not implement
their own theme-to-CSS transformations.
-- Adding a public-property expansion updates the checked registry, compiler
- tests, component metadata checks, and representative runtime/built output.
+- Adding or changing a guaranteed property path uses the target's exact
+ `guaranteedProperties` declaration and adds representative compiler and runtime
+ evidence that the property produces its promised effect on that target's
+ anatomy part. Catalog membership alone is not a guarantee. If private expansion
+ is needed, update the checked registry and component metadata in the same
+ change.
+- Adding or changing a public semantic custom property verifies direct runtime
+ and built output, default/fallback behavior, and rejection of any private alias.
+- Generic-property pass-through remains best effort and must not be documented or
+ tested as a compatibility guarantee unless the component-theming record admits
+ that property into the guaranteed set.
- Changing scope or layer output tests both source and distribution builds.
- Adding a platform compiler names the shared concepts it supports and tests
that they keep the same meaning. Unsupported concepts fail clearly instead of
@@ -104,23 +134,60 @@ This record does not own:
## Owning code
- `generateThemeRules.ts` owns the web compiler and canonical CSS output.
-- `derivedVarRegistry.ts` owns checked mappings from public properties to private
- component variables.
- `Theme.tsx` mounts compiled CSS for themes that were not built ahead of time.
-- `packages/cli/api/theme/build/build.mjs` saves and packages compiled CSS.
+- `derivedVarRegistry.ts` owns checked mappings from guaranteed public properties
+ to private component variables.
+- Component `.doc.mjs` `theming.derived[]` mirrors those mappings;
+ `theming.vars[]` distinguishes reviewed public semantic variables from private
+ implementation variables.
+- `packages/cli/api/theme/build/build.mjs` saves and packages compiled CSS. Its
+ private-variable diagnostic is currently non-blocking; rejecting that input is
+ a named conformance gap, not existing enforcement.
- Future platform compilers consume the same `DefinedTheme` behind this boundary.
## Deciding specs
-None. The system owner selected one definition with platform-specific outputs
-while this record was drafted.
+None. The system owner selected one definition with platform-specific outputs and
+the guaranteed, best-effort, public-semantic, and private implementation tiers.
## Verification
-| Invariant | Evidence | Failure signal |
-| ---------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
-| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |
-| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |
-| INV5, INV6 | Registry and CLI public-variable tests | Expansion is duplicated, or private variables become authorable |
-| INV7, INV8 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears |
-| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |
+| Invariant | Evidence | Failure signal |
+| ---------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |
+| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |
+| INV5 | Existing per-property fixtures (partial; gap below) | A guaranteed property compiles but does not produce its promised observable effect |
+| INV6, INV7 | Existing registry and CLI public-variable tests (partial) | Private variables become authorable, or a reviewed public semantic variable fails build/runtime |
+| INV8 | Component target metadata and compatibility review | Successful generic emission is treated as a guaranteed public behavior |
+| INV9, INV10 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears |
+| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |
+
+## Known conformance and verification gaps
+
+The invariants above are the approved current contract. The following shipped
+behavior does not yet conform and must not be treated as enforcement:
+
+- **Private author input is not rejected end to end.** `themeBuild` reports direct
+ `--_*` values as errors in its receipt/log, but continues compiling and emits
+ them. Its validation checks only the top-level declarations under
+ `components`; nested pseudo declarations and media-surface components bypass
+ it. Runtime `defineTheme` has no equivalent validation and accepts them. The
+ follow-up must reject direct private variables recursively before CSS
+ generation across both paths and prove runtime/static parity.
+- **Pseudo and media-surface component overrides bypass derived expansion.**
+ Top-level, non-pseudo base declarations use `derivedVarRegistry`, including
+ `replaces` and container expansion. Base pseudo declarations and
+ `onDark.components` / `onLight.components` declarations currently serialize
+ properties directly. The follow-up must use one component-declaration lowering
+ path for base, pseudo, and media-surface rules, with parity fixtures for a
+ normal mapping, `replaces`, and container padding.
+- **Guaranteed-property coverage is not machine-complete.** The shared catalog is
+ normative, but the component-doc schema has no per-target
+ `guaranteedProperties` declarations. CI therefore cannot prove that a target
+ rationally supports its selected catalog subset or reviewed additions. The
+ follow-up must add and migrate that metadata, then fail when a declared
+ target/property pair lacks both output-path and observable runtime evidence.
+
+These invariants are the approved rules governing implementation and review. The
+nonconformities above are shipped defects against that contract, not proposed
+behavior.
diff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.md
index 9f7008acb6..c0b37b83c9 100644
--- a/docs/templates/knowledge/component-spec.md
+++ b/docs/templates/knowledge/component-spec.md
@@ -1,6 +1,6 @@
---
schema_version: 1
-template_version: 2
+template_version: 3
kind: component
id: component:<Name>
authority: draft
@@ -102,7 +102,9 @@ Optional during migration. When present, this block must map every exact English
anatomy name from <Name>.doc.mjs to one disposition. It is maintainer metadata:
do not copy it into ComponentDoc, generated docsite data, CLI/MCP output, or
consumer prose. Target names omit the `astryx-` prefix. Put only non-obvious
-rationale or exceptions in prose below the block.
+rationale or exceptions in prose below the block. `none` is factual: its reason
+must start with `intentional:`, `reachability-gap:`, or `unsettled:` so absence of
+current reachability never silently decides future themeability.
-->
<!-- anatomy-theming:v1 -->
@@ -114,7 +116,11 @@ rationale or exceptions in prose below the block.
"<delegated part>": {
"delegatesTo": {"owner": "component:<Owner>", "target": "<target>"}
},
- "<unthemed part>": {"none": {"reason": "<required reason>"}}
+ "<currently unreachable part>": {
+ "none": {
+ "reason": "<intentional | reachability-gap | unsettled>: <required factual reason>"
+ }
+ }
}
```
diff --git a/docs/templates/knowledge/versions.json b/docs/templates/knowledge/versions.json
index c7f2d44759..cdfe7feea9 100644
--- a/docs/templates/knowledge/versions.json
+++ b/docs/templates/knowledge/versions.json
@@ -1,6 +1,6 @@
{
"architecture": 1,
- "component": 2,
+ "component": 3,
"design": 1,
"family": 1,
"implementation-plan": 1,
diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjs
index dfd2f659cc..f03bc9c6e0 100644
--- a/scripts/check-knowledge.mjs
+++ b/scripts/check-knowledge.mjs
@@ -206,6 +206,7 @@ export function parseAnatomyThemingBlock(
const THEME_TARGET_NAME = /^(?!astryx-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
const THEMING_DISPOSITIONS = ['target', 'inherits', 'delegatesTo', 'none'];
+const NONE_REASON_PREFIX = /^(?:intentional|reachability-gap|unsettled):\s+\S/;
function exactObjectKeys(value, expected) {
return (
@@ -330,6 +331,10 @@ export function validateAnatomyThemingMap(
const none = disposition.none;
if (!exactObjectKeys(none, ['reason']) || !isNonEmptyString(none.reason)) {
problems.push(`${where}.none requires a non-empty reason.`);
+ } else if (!NONE_REASON_PREFIX.test(none.reason)) {
+ problems.push(
+ `${where}.none.reason must start with intentional:, reachability-gap:, or unsettled:.`,
+ );
}
}
diff --git a/scripts/check-knowledge.test.mjs b/scripts/check-knowledge.test.mjs
index f486206eae..20a856d480 100644
--- a/scripts/check-knowledge.test.mjs
+++ b/scripts/check-knowledge.test.mjs
@@ -170,7 +170,9 @@ describe('component theming anatomy metadata', () => {
Root: {target: 'button'},
Label: {inherits: 'button'},
Icon: {delegatesTo: {owner: 'component:Icon', target: 'icon'}},
- Content: {none: {reason: 'The consumer owns this content.'}},
+ Content: {
+ none: {reason: 'intentional: The consumer owns this content.'},
+ },
};
it('parses the optional versioned JSON block under Design relationships', () => {
@@ -196,6 +198,26 @@ describe('component theming anatomy metadata', () => {
expect(validateAnatomyThemingMap(valid, contract)).toEqual([]);
});
+ it('accepts every classified none reason', () => {
+ for (const classification of [
+ 'intentional',
+ 'reachability-gap',
+ 'unsettled',
+ ]) {
+ expect(
+ validateAnatomyThemingMap(
+ {
+ ...valid,
+ Content: {
+ none: {reason: `${classification}: Current factual state.`},
+ },
+ },
+ contract,
+ ),
+ ).toEqual([]);
+ }
+ });
+
it.each([
[
'multiple dispositions',
@@ -217,6 +239,11 @@ describe('component theming anatomy metadata', () => {
{...valid, Content: {none: {}}},
/requires a non-empty reason/,
],
+ [
+ 'unclassified none reason',
+ {...valid, Content: {none: {reason: 'The consumer owns this content.'}}},
+ /must start with intentional:, reachability-gap:, or unsettled:/,
+ ],
[
'prefixed target',
{...valid, Root: {target: 'astryx-button'}},
@@ -238,8 +265,8 @@ describe('component theming anatomy metadata', () => {
{
Label: {inherits: 'button'},
Icon: {delegatesTo: {owner: 'component:Icon', target: 'icon'}},
- Content: {none: {reason: 'Consumer owned.'}},
- Unknown: {none: {reason: 'Not real.'}},
+ Content: {none: {reason: 'intentional: Consumer owned.'}},
+ Unknown: {none: {reason: 'unsettled: Not real.'}},
},
contract,
).join('\n');
@@ -396,10 +423,10 @@ describe('knowledge validation', () => {
fs.mkdirSync(directory);
fs.writeFileSync(
path.join(directory, 'Button.spec.md'),
- componentRecord({template_version: '3'}),
+ componentRecord({template_version: '4'}),
);
expect(validateKnowledgeRoot(root).join('\n')).toMatch(
- /template_version 3 is newer than 2/,
+ /template_version 4 is newer than 3/,
);
});