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.mdindex 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, suchas 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 anexplicit family owner. Consumer `.doc.mjs` files continue to own anatomy names,descriptions, and public target documentation. Component specs own the exact mapand 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 participatinganatomy 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 thatpaints theme-controlled output—not an event wrapper, speculative internalstructure, 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 aliasesmay 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 sharedtarget for several components, but local docs link to that owner rather thanleaving 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 andlink 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 partinventory 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 auditdiff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 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, layerbehavior, 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 stablepublic 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 doesnot 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 migrationevidence 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.mdindex 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 samescopes, `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 compilermay 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 componentoverride means the same thing across outputs. Platform-only features have anexplicit support boundary.@@ -93,8 +114,17 @@ This record does not own:is tested through both runtime mounting and CLI-built output. The Themeprovider and CLI may mount or package compiled rules; they must not implementtheir 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 teststhat 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.mdindex 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: 3kind: componentid: component:<Name>authority: draft@@ -102,7 +102,9 @@ Optional during migration. When present, this block must map every exact Englishanatomy name from <Name>.doc.mjs to one disposition. It is maintainer metadata:do not copy it into ComponentDoc, generated docsite data, CLI/MCP output, orconsumer 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.jsonindex 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.mjsindex 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.mjsindex 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/,);});