An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): narrow AST-034 family build contract (#6296)
Cindy Zhang8e5e42637ef2
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.mdindex 541aee276e..475d9817cb 100644--- a/docs/architecture/cli-surface.md+++ b/docs/architecture/cli-surface.md@@ -31,7 +31,7 @@ verified_by:clients/cli/commands/upgrade.integration-policy.test.mjs,clients/cli/formatters/index.test.mjs,]-deciding_specs: [spec:AST-017/DEC-4, spec:AST-034/DEC-1]+deciding_specs: [spec:AST-017/DEC-4]---# CLI surface architecture@@ -219,17 +219,6 @@ non-interactive guarantee.- `spec:AST-017/DEC-4` — stable response fields and their complete projectionsare current compatibility authority.-- `spec:AST-034/DEC-1` — the accepted family command composition and- caller-supplied artifact-key boundary.--`spec:AST-034` is current authority for the accepted, unshipped family-build-surface. `theme build --family <base> <children...>` requires one value flag,-`--family-key <key>`. The flag names only the coordinated output stem:-`<key>.css`, `<key>.js`, `<key>.d.ts`, and `<key>.manifest.json`; it does not rename-members or change theme semantics. It is required exactly in family mode and refused-otherwise, before writes. Family mode is refused with `--watch` and `--out` and-composes with `--check` and `--icons-specifier`. The accepted contract adds no-response field or error code. Implementation remains unshipped.## Verificationdiff --git a/docs/architecture/theme-authoring-contract.md b/docs/architecture/theme-authoring-contract.mdindex 404db5d1cf..58aa56d53a 100644--- a/docs/architecture/theme-authoring-contract.md+++ b/docs/architecture/theme-authoring-contract.md@@ -39,6 +39,7 @@ verified_by:deciding_specs:[spec:AST-006/DEC-1,+ spec:AST-006/DEC-2,spec:AST-006/DEC-3,spec:AST-006/DEC-4,spec:AST-006/DEC-6,@@ -47,8 +48,6 @@ deciding_specs:spec:AST-012/DEC-3,spec:AST-012/DEC-4,spec:AST-017/DEC-1,- spec:AST-034/DEC-1,- spec:AST-034/DEC-4,]---@@ -79,9 +78,7 @@ source configuration independently.`defineTheme` resolves that input into a flat `DefinedTheme`. An extended themecontains the resolved values it inherits, so its normalized representation is-complete. A standalone build does not need the base stylesheet. The accepted family-contract may share compiled declarations only within one keyed family output set; it-does not change normalized authoring semantics.+complete. A standalone build does not need the base stylesheet.Normalization follows one precedence order:@@ -107,9 +104,7 @@ style key, and CSS property rather than replacing the entire inherited target.- **INV3 — Extension is semantically flattened.** `extends` accepts a real`DefinedTheme` and carries forward its resolved tokens, local-token owner andlineage metadata, component rules, media surfaces, adaptations and axes, icons,- and indicators. The normalized child is complete. Family packaging may factor- physical output only after preserving that complete member semantics in the one- keyed family set.+ and indicators. The normalized child is complete.- **INV4 — Invalid bases fail loudly.** An undefined, namespace, or plain objectpassed to `extends` cannot produce a plausible partial theme.- **INV5 — Explicit tokens override generated scales.** Generated values provide@@ -219,24 +214,21 @@ public surface belongs to## Deciding specs-AST-006 decisions 1, 3, 4, and 6 establish the shipped theme-local authoring-shape, enrollment, inheritance, shared validation, and value contract. AST-034-DEC-4 supersedes all of AST-006 DEC-2 and only DEC-4's reserved-prefix-classification and validation clauses; explicit enrollment, shared runtime/static-validation, exact lineage, collision and cycle checks, and legacy unenrolled behavior-remain. AST-012 decisions 1–4 establish the fixed width map, named closed conditions,+AST-006 decisions 1–4 and 6 establish the shipped theme-local authoring shape,+enrollment, exact-name preservation, inheritance, shared validation, and value contract.+Its 2026-09-12 amendment makes key validity and ownership prefix-independent while+retaining exact owner metadata, lineage, collisions, cycles, and legacy unenrolled+behavior. AST-012 decisions 1–4 establish the fixed width map, named closed conditions,ordered rule cascade, and source/built adaptation metadata parity. AST-017 decision 1-owns released compatibility classification and migration. AST-034 DEC-1 establishes-that family packaging projects complete normalized members without changing authoring-identity or semantics.--`spec:AST-034` is current authority. It supersedes all of AST-006 decision 2 and-only the reserved-prefix clauses of decision 4 with exact, prefix-independent owner-and lineage validation. It also projects each complete normalized member into one-caller-keyed family artifact set owned by `architecture:theme-compilation`, without-adding per-member artifacts or changing authoring semantics. The artifact key controls-filenames only; it does not change theme identity, local-token ownership, or CSS-custom-property names. The implementation remains unshipped.+owns released compatibility classification and migration.++## Known conformance and verification gaps++Prefix-independent `localTokens` key acceptance is accepted but unshipped. The current+validator still requires the original theme-derived prefix and uses that prefix to+classify local references. Until the implementation lands, INV8's prefix-independent+clauses are current authority but not enforcement. Existing explicit enrollment,+owner, lineage, collision, cycle, and legacy-unenrolled behavior remains shipped.## Verification@@ -246,7 +238,7 @@ custom-property names. The implementation remains unshipped.| INV3, INV4 | extension and invalid-base tests | Child themes require a base stylesheet or silently accept a non-theme base || INV6 | component merge tests across base/generated/explicit rules | Restating one property drops inherited component styles || INV7 | `onMediaTokens.test.ts` and generated surface-rule tests | A child loses inherited surface customization or surface precedence changes |-| INV8 | Shipping gate: AST-034 runtime/static validator and source/built inheritance tests | A valid name fails because of its prefix, ownership follows spelling, or lineage/reference/collision/cycle checks diverge |+| INV8 | AST-006 runtime/static validator and source/built inheritance tests | A valid name fails because of its prefix, ownership follows spelling, or lineage/reference/collision/cycle checks diverge || INV10 | `themeAdaptations.test.ts` and CLI build fixtures | Width metadata, rule order, or child re-resolution diverges across source and built themes || INV11 | `DefineThemeInput`/output diff plus runtime/build fixtures | Validation-only data enters the normalized theme, or productive input loses construction validation || INV12 | Core theme export diff, constructed-value evidence, and current-consumer callsite | A theme `define*` helper only checks input and returns that exact input unchanged |diff --git a/docs/architecture/theme-compilation.md b/docs/architecture/theme-compilation.mdindex 158c938695..7040ffec93 100644--- a/docs/architecture/theme-compilation.md+++ b/docs/architecture/theme-compilation.md@@ -31,13 +31,10 @@ verified_by:]deciding_specs:[+ spec:AST-006/DEC-2,spec:AST-006/DEC-4,spec:AST-012/DEC-3,spec:AST-012/DEC-4,- spec:AST-034/DEC-1,- spec:AST-034/DEC-2,- spec:AST-034/DEC-3,- spec:AST-034/DEC-4,]---@@ -131,12 +128,6 @@ Platform-specific details stay inside that compiler.adaptation blocks remain separate in authored order, and media-surface overridesemit last. Duplicate conditions and later root-restoring writes are preservedexactly; runtime and static output use the same blocks.-- **INV13 — Accepted family packaging is one keyed native set.** Family compilation- starts from one complete plan per selected member, then emits exactly one keyed CSS- containing all members, one CSS-free ESM exporting all complete members, one- matching declaration, one manifest, and receipts. Shared CSS uses zero-specificity- declarations and member deltas use `:scope`. The artifact key changes filenames- only. Per-member family artifacts and runtime manifest assembly are prohibited.This record does not own:@@ -196,11 +187,6 @@ This record does not own:- Adding a platform compiler names the shared concepts it supports and teststhat they keep the same meaning. Unsupported concepts fail clearly instead ofdisappearing.-- A family-packaging change follows `spec:AST-034`: it preserves complete member- plans across separate CSS, ESM, type, and receipt tracks; emits only the exact keyed- set; verifies zero-delta members and collision-safe bindings; and keeps manifest- ownership, transactional publication, cleanup, and check behavior out of consumer- runtime assembly.- Build packaging may change without changing compiled theme behavior.## Owning code@@ -227,24 +213,12 @@ This record does not own:## Deciding specs-AST-006 DEC-4 continues to establish atomic shared validation for enrolled themes;-AST-034 DEC-4 supersedes AST-006 DEC-2 and only DEC-4's reserved-prefix clauses with-exact prefix-independent ownership. AST-012 decisions 3 and 4 establish ordered-adaptation blocks and source/built metadata parity. AST-034 decisions 1–3 establish-the keyed family artifact set, complete-plan-before-factoring rule, and-manifest-owned transactional generation. The system owner separately selected one-definition with platform-specific outputs and the guaranteed, best-effort,-public-semantic, and private implementation tiers.--`spec:AST-034` is current authority. It requires one native-`<artifactKey>.css` containing all selected members, one separate standard-`<artifactKey>.js` with all complete member exports, one `<artifactKey>.d.ts`, and one-`<artifactKey>.manifest.json` plus receipts. The caller-supplied key changes only the-coordinated filename stem. Complete plans precede factoring; shared CSS has zero-specificity; bindings are collision-safe; and the manifest owns transactional-generation, cleanup, and check behavior. Per-member family artifacts are prohibited.-The implementation remains unshipped, so the current standalone build remains the-only implemented path until conformance lands.+AST-006 decisions 2 and 4, as amended on 2026-09-12, establish+prefix-independent local-token names and atomic shared validation for enrolled themes.+AST-012 decisions 3 and 4 establish ordered adaptation blocks and source/built metadata+parity. The system owner separately selected one definition with platform-specific+outputs and the guaranteed, best-effort, public-semantic, and private implementation+tiers.## Verification@@ -258,15 +232,16 @@ only implemented path until conformance lands.| INV9, INV10 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears || INV11 | `defineTheme.test.ts` and `build.test.mjs` local-token fixtures | Runtime/static output rewrites a local name, disagrees, or leaves partial output after failure || INV12 | `themeAdaptations.test.ts` and CLI adaptation build fixtures | Rule blocks merge/reorder/drop, surfaces lose precedence, or runtime/static CSS diverges |-| INV13 | AST-034 implementation suite plus real-browser and type checks | Keyed output is incomplete, emits per-member files, conflates tracks, or needs runtime assembly || Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |## Known conformance and verification gaps-The accepted AST-034 family-build contract is unshipped. The current CLI has no-family artifact set or `--family-key`; implementation must satisfy the spec's complete-structural, browser, type, transaction, cleanup, and check gates before this invariant-is treated as enforced.+Prefix-independent `localTokens` key acceptance is accepted but unshipped. The current+compiler still requires the original theme-derived prefix and uses that prefix to+classify local references. Until implementation lands, INV11's prefix-independent+clauses are current authority but not enforcement; exact-name emission and the existing+enrollment, owner, lineage, collision, cycle, and legacy-unenrolled behavior remain+shipped.The remaining invariants above describe the approved current contract. The followingshipped behavior does not yet conform and must not be treated as enforcement:diff --git a/docs/contributing/cli-conventions.md b/docs/contributing/cli-conventions.mdindex e68c77f42b..9fbfdcd1c5 100644--- a/docs/contributing/cli-conventions.md+++ b/docs/contributing/cli-conventions.md@@ -87,36 +87,14 @@ decide each cell. There are only three legal answers, and every cell needs one:An undecided cell is the defect. It ships as behaviour nobody chose, and anagent finds it before a person does.-### Worked example: `theme build --family`--`--family <base> <children…>` builds a base theme and the themes that `extends`-it as one unit: the base stylesheet restates the shared declarations once,-scoped to every member, and each member carries only its own deltas.--Its matrix against the flags already on `theme build`:--| Pair | Answer |-| ------------------------------ | ------------------------------------------------------------------------------------------------------- |-| `--family` `--watch` | Refused, explicitly, with a message naming both. |-| `--family` `--out` | Cannot co-occur: `--out` with more than one file is already refused, and `--family` needs at least two. |-| `--family` `--check` | They compose — `--check` verifies the family-shaped output. |-| `--family` `--icons-specifier` | They compose. |--That third row carries a consequence worth writing down: `--check`'s answer now-depends on whether `--family` was passed, because the two modes emit different-CSS. CI has to check with the same flags it built with. A cell that changes what-another flag _means_ is a documentation obligation, not just a test.-## Flags with the same nameA name is a promise across the whole CLI. Two rules:- **The same flag name means the same thing everywhere, and is spelled the same- way.** `--family` means "a base plus the themes that extend it, built as one- unit". Nothing else may take that name for another idea.-- **No command is forced to carry a flag because a sibling has it.** Alignment- is on meaning, not on presence. `--family` rests on `extends`, which only- themes have, so no other command has anything to point it at.+ way.** Nothing else may take a flag name for another idea.+- **No command is forced to carry a flag because a sibling has it.** Alignment is on+ meaning, not on presence.## Output: use the shared functionsdiff --git a/docs/specs/AST-006/spec.md b/docs/specs/AST-006/spec.mdindex b322208b8e..b921647905 100644--- a/docs/specs/AST-006/spec.md+++ b/docs/specs/AST-006/spec.md@@ -18,7 +18,7 @@ affects_architecture:]affects_families: []affects_contributing: []-affects_consumer_docs: []+affects_consumer_docs: [theme]---# Theme-local tokens system spec@@ -31,21 +31,21 @@ Theme authors get one explicit, checked path for theme-family-local reuse;component and application authors keep the same portable token contract they havetoday.-The shipped API is one optional `DefineThemeInput.localTokens` field. Supplying-it explicitly enrolls a theme in the new contract; omitting it preserves existing-behavior, even when legacy component overrides already mention-`--astryx-theme-*`. A local token is declared with its complete CSS-custom-property name and referenced by that same name in the defining theme's-component overrides. Descendants inherit enrollment and may replace exact names-only through an enrolled exact `extends` lineage. Mere emitted CSS creates no-contract, but a shipped enrolled definition recorded by its owning theme spec-does: its exact name and semantic meaning are public within that theme family,-not portable across themes or intended for Core component source.--This current record governs the shipped cross-theme API and invariants-independently of whether any particular theme has completed its own adoption-evidence. Theme-local names, meanings, values, mappings, and rendered evidence-remain owned by each adopting theme's colocated record.+The shipped API is one optional `DefineThemeInput.localTokens` field. Supplying it+explicitly enrolls a theme in the contract; omitting it preserves existing behavior. A+local token is declared with any valid CSS custom-property name and referenced by that+same exact name. Prefixes do not grant, reserve, or restrict ownership. Descendants+inherit enrollment and may replace exact names only through an enrolled exact+`extends` lineage. Mere emitted CSS creates no contract, but a shipped enrolled+definition recorded by its owning theme spec does: its exact name and semantic meaning+are public within that theme family, not portable across themes or intended for Core+component source.++This current record governs the cross-theme API and invariants independently of+whether any particular theme has completed its own adoption evidence. The original+local-token surface is shipped; the 2026-09-12 naming amendment is accepted and awaits+its implementation. Theme-local names, meanings, values, mappings, and rendered+evidence remain owned by each adopting theme's colocated record.## Non-goals@@ -65,7 +65,7 @@ remain owned by each adopting theme's colocated record.## Requirements-The requirements below are the shipped cross-theme contract.+The requirements below are the current cross-theme contract.- **FR1 — Local tokens are purely additive, optional, and explicitly enrolled.**`DefineThemeInput` MUST gain at most one new authoring surface: optional@@ -89,15 +89,11 @@ The requirements below are the shipped cross-theme contract.exact string MUST be used in `var(...)` references, `DefinedTheme` data,runtime CSS, static CSS, inherited replacement, and generated theme-specifictypes or metadata. No transform may create a second identifier.-- **FR4 — Enrollment requires an exact stable theme name.** A theme supplying- `localTokens` MUST already have a `DefineThemeInput.name` that is a valid,- stable, lower-kebab theme identifier. No hidden normalization or rewritten- namespace is allowed. Every newly declared name MUST follow- `--astryx-theme-${name}-<purpose-led Astryx token grammar>`, using the input- `name` byte-for-byte. The suffix MUST be purpose-led and lowercase kebab-case.- Generic semantic domains such as `color`, `spacing`, `radius`, or `motion` are- valid inside the theme namespace. Existing themes with other name shapes- remain valid while unenrolled.+- **FR4 — Any valid custom-property key is accepted.** Every newly declared+ `localTokens` key MUST be a valid CSS custom-property name and MUST be preserved+ byte-for-byte. No prefix is required, reserved, rewritten, or interpreted as owner+ or enrollment metadata. A theme name and a local-token key are independent; this+ contract defines no preferred replacement naming pattern.- **FR5 — Local use stays inside the maintained theme family.** A local name MAYbe referenced by the maintained enrolled theme that defines it and bydescendants enrolled through its exact `extends` lineage. It MUST NOT become a@@ -107,30 +103,28 @@ The requirements below are the shipped cross-theme contract.exact name and semantic meaning ARE a public compatibility contract of thattheme family.- **FR6 — Extension is exact-name, enrollment, and lineage-aware.** A descendant- inherits enrollment and declarations only from an enrolled exact `extends`- base. It MAY replace an inherited local token only by restating that inherited- complete name. A new local role declared by the descendant MUST use the- descendant's exact stable `name`. Arbitrary legacy names, matching prefixes,- matching suffixes, or coincidental values MUST NOT be retroactively claimed as- lineage. A child MUST NOT forge another theme's namespace.-- **FR7 — Validation is atomic for enrolled themes only.** Runtime and static- build MUST share one recursive validator. For a theme enrolled directly or- through an enrolled exact base, it MUST validate the enrolled lineage's exact- namespaces, declarations, and every `var(--astryx-theme-...)` reference- reachable through local-token values, component overrides, nested pseudo- rules, and media-surface component overrides. It MUST reject malformed local- names, undeclared enrolled references, cyclic local references, exact-name or- lineage mismatch, and foreign local declarations before producing partial- output.+ inherits enrollment and declarations only from an enrolled exact `extends` base. It+ MAY replace an inherited local token only by restating that inherited complete name.+ A newly declared name is owned by the declaring theme regardless of its spelling.+ Prefix, suffix, or value similarity MUST NOT create ownership or lineage, and a child+ MUST NOT claim another theme's declaration.+- **FR7 — Validation is atomic for enrolled themes only.** Runtime and static build+ MUST share one recursive validator. For a theme enrolled directly or through an+ enrolled exact base, it MUST validate each declaration's custom-property syntax,+ exact owner and lineage, collisions with portable `tokens`, and cycles among exact+ declared references across local-token values, component overrides, media surfaces,+ and adaptations before producing partial output. An adaptation `value.tokens` key+ that exactly matches an effective local declaration MUST fail so the write uses+ `value.localTokens` and retains owner, lineage, and cycle validation. A `var()`+ reference is a local edge only when it exactly matches an effective enrolled+ declaration; every other custom-property reference remains external. Prefixes have+ no validation meaning.- **FR8 — Unenrolled legacy behavior is grandfathered unchanged.** When- `localTokens` is absent and the exact base is not enrolled, runtime and static- build MUST NOT scan, reject, warn about, reserve, or reinterpret- `--astryx-theme-*` strings that already appear in token values or component- overrides. Existing same-prefix custom properties continue unchanged. A- maintainer may leave that legacy behavior unenrolled, or explicitly migrate by- supplying `localTokens` and declaring every reserved local name used by the- enrolled theme. Variables outside the reserved namespace and every existing- portable-token path remain untouched in either state.+ `localTokens` is absent and the exact base is not enrolled, runtime and static build+ MUST NOT add a new scan, rejection, warning, reservation, or interpretation for CSS+ custom-property references. Existing custom properties continue unchanged. A+ maintainer may leave that behavior unenrolled or explicitly migrate by supplying+ `localTokens`; no prefix changes either path.- **FR9 — Source and built themes preserve one enrollment lineage.**Source-defined and built themes MUST retain equivalent exact local-token maps,enrollment state, and lineage metadata so descendants accept, inherit,@@ -140,9 +134,8 @@ The requirements below are the shipped cross-theme contract.public contracts of the owning theme family. Renaming the local token or itsenrolled theme, or changing that meaning, MUST use an explicit reviewedmigration or alias that preserves the prior exact-name, meaning, and lineage- contract for its compatibility window. Silent key replacement, semantic- broadening, theme-name rewriting, namespace rewriting, and inferred descendant- migration are prohibited.+ contract for its compatibility window. Silent key replacement, semantic broadening,+ owner reassignment, and inferred descendant migration are prohibited.- **FR11 — The colocated theme spec owns definitions and mappings.** Eachtheme-local token definition MUST live in the owning theme's colocatedtheme-level spec, including its exact name, semantic meaning, value, mappings,@@ -152,35 +145,14 @@ The requirements below are the shipped cross-theme contract.genuinely match the documented meaning and MUST provide rendered evidence forits actual light/dark and relevant interaction states.-### Shipped authoring shape--`defineTheme` remains the only authoring operation. Opt-in requires the existing-`name` to already be the exact lower-kebab identifier used in every local token.-The same complete local name is declared, referenced, preserved in-`DefinedTheme`, inherited, and emitted:--```ts-const exampleTheme = defineTheme({- name: 'example',- localTokens: {- '--astryx-theme-example-color-status-fill-accent': ['#0074e2', '#6d9cfe'],- },- components: {- badge: {- 'variant:info': {- backgroundColor: 'var(--astryx-theme-example-color-status-fill-accent)',- },- },- },-});-```--The declaration key and the name inside `var(...)` are identical. The tuple uses-the complete existing `TokenValue` contract and normalizes exactly as an existing-`tokens` light/dark tuple does. Runtime and static compilation emit-`--astryx-theme-example-color-status-fill-accent` without shortening or-renaming it. An adopting `theme:*` record owns its concrete role, value, and-component mapping.+### Authoring shape++`defineTheme` remains the only authoring operation. Each `localTokens` key is the+complete CSS custom-property name used in `var(...)`, `DefinedTheme`, inheritance, and+emitted output. The key is preserved byte-for-byte and has no required prefix. Values+reuse the existing `TokenValue` contract and normalize exactly as existing `tokens`+values do. An adopting `theme:*` record owns each concrete role, value, and component+mapping.### Platform support@@ -195,10 +167,12 @@ component mapping.## Current-state impact-Current `main` keeps its closed portable core/domain token vocabulary and now-ships a separate first-class local-token field. Unknown keys that reach-permissive legacy paths can still serialize, but only explicit `localTokens`-enrollment creates ownership, reference closure, and lineage validation.+Current `main` keeps its closed portable core/domain token vocabulary and ships the+first-class `localTokens` field with the original prefix-based key validation. The+2026-09-12 amendment broadens only accepted local-token key spelling; implementation+remains pending. Unknown keys that reach permissive legacy paths can still serialize,+but only explicit `localTokens` enrollment creates ownership, reference closure, and+lineage validation.- `architecture:theme-authoring-contract` owns the optional `localTokens`input, its exact-name map, explicit enrollment state, flattened inheritance,@@ -210,25 +184,24 @@ enrollment creates ownership, reference closure, and lineage validation.vocabulary and explicitly excludes theme-local names from its public helpersand documentation.-Those current architecture records are authoritative for the shipped behavior-and cite the applicable AST-006 decisions. A draft theme record may reference-this current spec while keeping its own value, mapping, and evidence decisions-unresolved.+Those current architecture records project the approved behavior and cite the applicable+AST-006 decisions. Prefix-independent key acceptance remains a named conformance gap+until its implementation lands. A draft theme record may reference this current spec+while keeping its own value, mapping, and evidence decisions unresolved.### Compatibility and adoption- Adoption is per maintained theme family and optional. Existing themes are notmigrated merely because the field exists.-- A theme that omits `localTokens` and does not extend an enrolled exact base- remains byte-equivalent across `DefinedTheme`, runtime, static, and package- outputs. Existing component overrides that mention `--astryx-theme-*` receive- no new scan, rejection, warning, reservation, or interpretation.-- An existing same-prefix custom property may continue unchanged while the theme- remains unenrolled. To migrate, the maintainer explicitly supplies- `localTokens`, declares every reserved local name used by that theme, and uses- a valid stable lower-kebab `name` whose bytes match the namespace.-- Existing `tokens` and external-variable behavior remains byte-equivalent,- including permissive broad spreads and runtime inputs.+- A theme that omits `localTokens` and does not extend an enrolled exact base remains+ byte-equivalent across `DefinedTheme`, runtime, static, and package outputs. Its CSS+ custom-property references receive no new scan, rejection, warning, reservation, or+ interpretation.+- Enrollment accepts any valid custom-property key. To migrate an existing custom+ property, the maintainer explicitly declares that exact key in `localTokens`;+ prefixes do not affect eligibility or ownership.+- Existing `tokens` and external-variable behavior remains byte-equivalent, including+ permissive broad spreads and runtime inputs.- Local names and documented meanings become public theme-family compatibilityobligations after release; they never become portable cross-theme or globalCore token promises. Mere custom-property emission from an unenrolled legacy@@ -244,39 +217,37 @@ unresolved.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |-| FR1, FR2, FR8 | Legacy type, runtime, build, resolution, and byte-output fixtures | omitted field; legacy `--astryx-theme-*` component reference; direct tokens; broad spread; cast; external variable; portable reference | Adding a reserved-namespace scan to the omitted-field path makes the legacy same-prefix mutation fixture fail. |-| FR2 | Local `TokenValue` parity fixtures | CSS string; `[light, dark]` tuple; reference value; runtime/static normalization; existing-token control | Local values reject an existing form, normalize differently across paths, or alter the existing `tokens` control. |-| FR3, FR4 | Exact-name authoring, type, and output fixtures | valid lower-kebab exact name; invalid input name; declaration key; `var(...)` reference; `DefinedTheme`; runtime CSS; static CSS | Any stage rewrites `name`, accepts a mismatched namespace, or changes existing name acceptance while unenrolled. |-| FR5, FR6, FR9 | Source- and built-base enrollment/lineage fixtures | root opt-in; child inherits enrolled exact base; child exact replacement; child new role; unenrolled base; unrelated/legacy matching prefix | A child gains lineage from an unenrolled or unrelated name, or source/built enrollment differs. |-| FR7, FR8 | Shared recursive validator fixtures for runtime and static build | enrolled nested references; component/pseudo/media rules; undeclared name; cycle; foreign namespace; unenrolled same-prefix legacy reference | Enrolled errors emit partial output, paths disagree, or the same scan runs on an unenrolled theme. |-| FR8 | Explicit legacy-enrollment migration fixture | same-prefix var omitted and accepted; then declared in `localTokens` and validated | Omitted legacy behavior changes, or explicit enrollment fails to bring the declaration/reference into the checked contract. |-| FR10, FR11 | Theme-package compatibility fixtures, colocated theme spec, and release review | exact name; documented meaning; enrolled theme rename; local-token rename; meaning change; alias window; descendant built from old/new base | A released name or meaning changes silently, a definition lacks an owner, or a descendant loses its inherited contract. |-| FR11 | Per-mapping theme-spec review plus focused rendered evidence | exact role meaning; mapped components/states; light/dark; relevant interaction states | A mapping uses the token outside its documented meaning or ships without contextual rendered evidence. |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR2, FR8 | Legacy type, runtime, build, resolution, and byte-output fixtures | omitted field; direct tokens; broad spread; cast; external custom property; portable reference | Adding a scan to the omitted-field path changes legacy behavior. |+| FR2 | Local `TokenValue` parity fixtures | CSS string; `[light, dark]` tuple; reference value; runtime/static normalization; existing-token control | Local values reject an existing form, normalize differently across paths, or alter the existing `tokens` control. |+| FR3, FR4 | Exact-name authoring, type, and output fixtures | valid custom-property keys with different prefixes; invalid custom-property key; exact reference; runtime and static output | Any stage rewrites a key, or validity/ownership changes because of a prefix. |+| FR5, FR6, FR9 | Source- and built-base enrollment/lineage fixtures | root opt-in; child inherits exact base; child exact replacement; child new role; unenrolled and unrelated names | A child gains ownership from spelling rather than exact lineage, or source/built enrollment differs. |+| FR7, FR8 | Shared recursive validator fixtures for runtime and static build | exact declared reference; external reference; portable collision; adaptation `value.tokens` collision; lineage mismatch; cycle; unenrolled theme | Enrolled errors emit partial output, paths disagree, a local write bypasses `value.localTokens`, or a prefix changes reference classification. |+| FR10, FR11 | Theme-package compatibility fixtures, colocated theme spec, and release review | exact name; documented meaning; enrolled theme rename; local-token rename; meaning change; alias window | A released name or meaning changes silently, a definition lacks an owner, or a descendant loses its inherited contract. |+| FR11 | Per-mapping theme-spec review plus focused rendered evidence | exact role meaning; mapped components/states; light/dark; relevant interaction states | A mapping uses the token outside its documented meaning or ships without contextual rendered evidence. |### Completion criteria-AST-006 is `shipped` because the implementation satisfies these criteria:+AST-006 remains `shipped`; the 2026-09-12 naming amendment reaches conformance when+its implementation satisfies these criteria alongside the already shipped contract:- optional `DefineThemeInput.localTokens` is the only new local-token authoringsurface and its presence is the root enrollment trigger;-- a theme with no `localTokens` and no enrolled exact base is proven- byte-equivalent, including a mutation fixture whose legacy component override- mentions `--astryx-theme-*` without any new scan, rejection, or warning;+- a theme with no `localTokens` and no enrolled exact base is proven byte-equivalent,+ with no new custom-property scan, rejection, or warning;- local values accept both existing `TokenValue` forms—a CSS string and`[light, dark]` tuple—and runtime/static normalization matches the existing`tokens` value path without changing it;-- opt-in requires the existing input `name` to already be a stable lower-kebab- identifier, and one exact local name preserves those bytes through declaration,- `var(...)` use, `DefinedTheme`, source/built inheritance, and emitted output;-- descendants inherit enrollment only from an enrolled exact base; arbitrary- legacy names are never retroactively claimed;-- namespace, exact-lineage, undeclared-reference, malformed-name, and cycle- failures are atomic and equal across runtime and static paths for enrolled- themes only;-- built themes retain enrollment and exact lineage metadata sufficient for- descendants without a base stylesheet;+- every valid CSS custom-property key is accepted and preserved byte-for-byte through+ declaration, `var(...)` use, `DefinedTheme`, source/built inheritance, and emitted+ output, with no prefix semantics;+- descendants inherit enrollment only from an enrolled exact base; spelling never+ creates ownership or lineage;+- custom-property syntax, token collision, exact owner and lineage, and cycle failures+ are atomic and equal across runtime and static paths for enrolled themes only;+- built themes retain enrollment and exact lineage metadata sufficient for descendants+ without a base stylesheet;- every shipped local definition is owned by its colocated theme-level spec, andits exact name and semantic meaning are treated as public compatibilitycontracts within that theme family;@@ -290,76 +261,76 @@ AST-006 is `shipped` because the implementation satisfies these criteria:## Decision log-The decisions below were approved by `cixzhang` as part of this current shipped-specification.+The decisions below were approved by `cixzhang` as part of this current specification.++### Amendment — Make local-token names prefix-independent++**Decider:** `cixzhang`, `2026-09-12`++Any valid CSS custom-property key is accepted in `localTokens`. Prefixes have no effect+on validity, ownership, enrollment, or lineage. This supersedes the naming-pattern and+reserved-prefix clauses previously recorded in FR4, FR6–FR8, DEC-2, DEC-3, and DEC-4.+Exact key preservation, explicit enrollment, owner metadata, exact `extends` lineage,+inheritance, portable-token collision checks, and cycle checks remain in force. This+amendment defines no replacement naming pattern.### DEC-1 — Add one optional local-token field without changing tokens**Reference:** `spec:AST-006/DEC-1`**Decider:** `cixzhang`, `2026-08-31`-Use a purely additive optional `DefineThemeInput.localTokens` field. Supplying-it explicitly enrolls a theme; an exact descendant may inherit that enrollment-from an enrolled base. Keep `defineTheme` as the only authoring operation and-preserve every existing `tokens` type, input, runtime, build, spread, precedence,-inheritance, output, and resolution behavior. A theme with no `localTokens` and-no enrolled exact base remains byte-equivalent even when existing component-overrides mention `--astryx-theme-*`.+Use a purely additive optional `DefineThemeInput.localTokens` field. Supplying it+explicitly enrolls a theme; an exact descendant may inherit that enrollment from an+enrolled base. Keep `defineTheme` as the only authoring operation and preserve every+existing `tokens` type, input, runtime, build, spread, precedence, inheritance, output,+and resolution behavior. A theme with no `localTokens` and no enrolled exact base+remains byte-equivalent regardless of custom-property spelling.-Rejected: a `defineLocalTokens` helper, parallel API, implicit enrollment from a-matching prefix, module augmentation of the portable token vocabulary, or-stricter validation on existing token paths.+Rejected: a `defineLocalTokens` helper, parallel API, implicit enrollment from a key's+spelling, module augmentation of the portable token vocabulary, or stricter validation+on existing token paths.-### DEC-2 — Use one exact theme-owned name through definition and use+### DEC-2 — Preserve one exact, prefix-independent name**Reference:** `spec:AST-006/DEC-2`-**Decider:** `cixzhang`, `2026-08-31`+**Decider:** `cixzhang`, `2026-08-31`; amended `2026-09-12`-To enroll, the existing `DefineThemeInput.name` must already be a stable-lower-kebab identifier. A new local name uses-`--astryx-theme-${name}-<purpose-led Astryx token grammar>`, copying that name-byte-for-byte with no hidden normalization. The declaration key is the CSS-variable, and component overrides use that same name in `var(...)`. Generic-domains such as `color` and `spacing` remain valid inside the owning theme-namespace. Existing themes with other name forms remain valid while unenrolled.+A `localTokens` declaration accepts any valid CSS custom-property key. The declaration+key is the CSS variable, and references use that same byte-for-byte name. No prefix is+required, reserved, rewritten, or interpreted, and the theme name does not determine+the key. This decision defines no preferred replacement naming pattern.-Rejected: normalizing or rewriting the input name, shorter role ids, generated-names, reference aliases, and treating a generic domain word as a collision with-portable tokens.+Rejected: generated names, reference aliases, hidden normalization, and any naming rule+that changes validity or ownership based on a prefix.### DEC-3 — Bind replacement to exact extension lineage**Reference:** `spec:AST-006/DEC-3`-**Decider:** `cixzhang`, `2026-08-31`+**Decider:** `cixzhang`, `2026-08-31`; amended `2026-09-12`-A descendant inherits enrollment only from an enrolled exact `extends` base and-may replace an inherited exact name only when that name arrived through that-lineage. Every new descendant role uses the child's exact stable input `name`.-Source and built themes retain equivalent enrollment and lineage metadata.-Arbitrary legacy names are never retroactively claimed. Released enrolled theme-or token renames require an explicit migration or alias.+A descendant inherits enrollment only from an enrolled exact `extends` base and may+replace an inherited exact name only when that name arrived through that lineage. A+new declaration is owned by the declaring theme regardless of its spelling. Source and+built themes retain equivalent enrollment and lineage metadata. Released enrolled+theme or token renames require an explicit migration or alias.-Rejected: foreign namespace declarations, suffix- or prefix-based enrollment,-value-based lineage inference, and silent theme-name or namespace rewriting-during extension.+Rejected: prefix-, suffix-, or value-based ownership or lineage inference, foreign+owner claims, and silent key rewriting during extension.-### DEC-4 — Validate only the new reserved local namespace+### DEC-4 — Validate the exact enrolled declaration graph**Reference:** `spec:AST-006/DEC-4`-**Decider:** `cixzhang`, `2026-08-31`+**Decider:** `cixzhang`, `2026-08-31`; amended `2026-09-12`++Runtime and static build share one exact validator. After direct or inherited+enrollment, it checks custom-property syntax, portable-token collisions, exact owner+and lineage metadata, and cycles among exact declared references. A reference is local+only when it exactly matches an effective enrolled declaration; every non-matching+custom-property reference remains external. An unenrolled theme receives no new scan,+rejection, or warning. Prefixes play no part in classification.-Runtime and static build share one exact validator. It recursively rejects-malformed local declarations, undeclared or cyclic reserved local references,-and namespace or lineage errors only after a theme is enrolled directly through-`localTokens` or through an enrolled exact base. An unenrolled theme receives no-reserved-prefix scan, rejection, or warning, even when legacy component-overrides mention `--astryx-theme-*`. Existing portable tokens, permissive-spreads, casts, unknown-key behavior, and external variables remain untouched.-A legacy same-prefix variable either continues unchanged while omitted or enters-the checked contract through explicit declaration in `localTokens`.--Rejected: a global reserved-prefix scan, a broad CSS-variable validator, or-using the new field to close legacy runtime permissiveness.+Rejected: prefix-based classification, a broad external-variable validator, or using+the new field to close legacy runtime permissiveness.### DEC-5 — The owning theme spec defines a public theme-family contractdiff --git a/docs/specs/AST-034/spec.md b/docs/specs/AST-034/spec.mdindex 6233947d45..d45fdf2549 100644--- a/docs/specs/AST-034/spec.md+++ b/docs/specs/AST-034/spec.md@@ -10,550 +10,179 @@ approved_by: cixzhangapproved_at: 2026-09-11phase: acceptedowners: [cixzhang]-affects_architecture:- [- architecture:theme-authoring-contract,- architecture:theme-compilation,- architecture:cli-surface,- ]+affects_architecture: [architecture:theme-compilation, architecture:cli-surface]affects_families: []affects_contributing: [contributing:cli-conventions]affects_consumer_docs: [theme]----# Theme family artifact graph system spec+# Theme family build behavior spec## Intent-A consumer application should be able to load one complete theme family without-knowing the family's inheritance graph or ordering its files. The caller supplies one-stable `artifactKey`; the required family output is one native-`<artifactKey>.css` containing every selected member, one standard ESM-`<artifactKey>.js` exporting every complete member, one matching-`<artifactKey>.d.ts`, and one `<artifactKey>.manifest.json` plus its receipt set.-Selecting or switching a loaded member requires only its theme identity.--CSS, JavaScript, and types have separate consumption contracts:--- native CSS is loaded with- `<link rel="stylesheet" href="<artifactKey>.css">`, contains shared declarations- once plus scoped member deltas, and owns visual readiness and cascade behavior;-- standard ESM imports `<artifactKey>.js`, whose named exports are complete resolved- theme objects and which does not make CSS ready; and-- `<artifactKey>.d.ts` describes those exports at compile time and has no runtime- loading or readiness behavior.--`artifactKey` controls only this coordinated set's public filename stem. It does not-change family-member identity, theme inheritance, local-token ownership, or CSS-custom-property names. The literal key `family` and paths in examples are-illustrative; the required suffixes and one-family-set roles are normative. A bundler-CSS import is an adapter over the same `<artifactKey>.css`, not the baseline that-defines correctness.--This contract replaces the delta-stylesheet assumptions in public-[PR #5687](https://github.com/facebook/astryx/pull/5687). That proposal established-useful family-compilation and zero-specificity techniques, but its documented child-CSS was not a failure-atomic consumption unit, zero-delta members could leave stale-output while `--check` passed, and composed registry bindings could generate invalid-JavaScript. Its useful cascade technique remains: shared family declarations use-`:where(:scope)` or an equally zero-specificity construct, while member deltas use-`:scope`, so member values win without specificity escalation even if unrelated-stylesheets in the same layer are reversed. This controls winners after rules exist;-it does not load a missing dependency, remove an `@import` waterfall, define link-readiness, or make partial CSS application atomic.--A completed Chromium, Vite, and TypeScript probe passed 195 assertions with no-failures. With the illustrative `artifactKey` `family`, native `family.css` made one-request, rendered every member correctly on-first paint, supported attribute-only switching with no wrong sampled frames, and-survived folder relocation. Native per-member relative-import wrappers worked when-complete, but a missing parent fired the top-level link's `error` while the child-delta still applied. Therefore this specification does not define or ship them. Any-future lazy per-member packaging needs a separate specification; a bare wrapper-cannot be a correctness boundary.--The same change removes a naming restriction unrelated to artifact safety. A theme-owner may declare a theme-local token with any valid CSS custom-property name. Exact-ownership, lineage, reference, collision, and cycle validation remain mandatory; a-prefix is neither ownership metadata nor an enrollment API.+A theme package author should be able to compile one related theme family without+shipping each member's repeated resolved declarations. The caller selects the family+and supplies one stable key. The build emits one `<key>.css` containing every member,+one `<key>.js` exporting every complete member, and one matching `<key>.d.ts`.+Consumers load the CSS once and switch themes by identity.++Public [PR #5687](https://github.com/facebook/astryx/pull/5687) demonstrates the user+need and the required cascade result. Its separately loaded base and member files are+not the accepted output: they can be incomplete, depend on load order, omit a+zero-delta member, and produce invalid JavaScript when source bindings collide. A+replacement uses one aggregate output trio so consumers never assemble the family.## Non-goals-- Implement the compiler, runtime, validator, CLI, or generated artifacts in this- specification pull request.-- Introduce a family CLI command, response field, error code, package export map, or- output-directory contract beyond the approved `--family` selection shape and this- specification's required `--family-key <key>` input.-- Add or change the portable/global token vocabulary.-- Define component APIs, component design, visual values, or theme-specific token- meanings.-- Add a native renderer or make CSS artifact structure part of shared authoring.-- Add another local-token namespace field, alias API, or authoring operation.-- Make a bundler's CSS graph, chunking, side-effect retention, or import order the- normative family contract.-- Define or ship per-member family CSS, JavaScript, or type entrypoints. Any future- lazy per-member packaging requires a separate specification and cannot treat a bare- relative-import CSS wrapper as failure-atomic.-- Require a family build for standalone themes or for consumers that prefer one- complete standalone theme.+- Implement the compiler, CLI, or generated artifacts in this specification pull+ request.+- Add a new command, response field, error code, or per-member family entrypoint.+- Strengthen the existing theme build's filesystem failure, cleanup, or publication+ guarantees.+- Add or change the portable/global token vocabulary, component APIs, or theme values.## Requirements-### Family identity and graph--- **FR1 — Exact extension lineage defines the family graph.** A family build MUST- derive a directed acyclic graph from the selected themes' exact normalized- `extends` lineage. Each member has one stable theme name and at most one parent.- A selected family has exactly one root, and every other member reaches that root- through selected parent edges. The build MUST reject duplicate names, duplicate- identities, cycles, missing selected ancestors, a parent edge that disagrees with- normalized lineage, and a member whose source cannot be associated with exactly- one graph node. Indirect descendants are valid; a family is not limited to one- base and its direct children.-- **FR2 — One keyed native family set is the required public boundary.** A successful- family build MUST expose exactly one `<artifactKey>.css`, one- `<artifactKey>.js`, one `<artifactKey>.d.ts`, and one- `<artifactKey>.manifest.json` plus its receipt set for the complete selected graph.- The CSS MUST provide every member's complete CSS behavior. The ESM MUST expose one- complete resolved object per member and MUST NOT import CSS or fan out to- per-member generated modules. The declaration file MUST describe every public ESM- member export in that one module. A consumer MUST NOT discover the graph, import an- ancestor, order private sections, or evaluate the manifest to assemble a member.-- The narrow stable CLI spelling is:+### Inputs and outputs++- **FR1 — Selected themes form one valid lineage.** The selected themes MUST form one+ connected, acyclic `extends` tree with exactly one root. Every selected non-root+ member's parent MUST also be selected. Duplicate names or identities, missing+ ancestors, and cycles MUST fail before family output is published. Descendants at+ any depth are valid; a family is not limited to one root and its direct children.+- **FR2 — The CLI emits one caller-keyed output trio.** The stable command shape is:```shastryx theme build --family <base> <children...> --family-key <key>```- `--family-key <key>` is required exactly when `--family` is present and is refused- otherwise, before any output write. It accepts an exact ASCII lower-kebab key- matching `[a-z0-9]+(?:-[a-z0-9]+)*`; the CLI does not normalize it. The key MUST be- collision-checked against every path the invocation would own and against existing- unowned output. Check mode takes the same key and compares the same owned set.- The approved family composition matrix is: family mode is refused with `--watch`- and `--out`, and composes with `--check` and `--icons-specifier`. This adds no- response field or error code.-- **Non-normative native example.** With `artifactKey: 'family'`:-- ```html- <link rel="stylesheet" href="./generated/current/family.css" />- <script type="module">- import {oceanDeepTheme} from './generated/current/family.js';- </script>- ```-- A bundler adapter imports those same files:-- ```ts- import './generated/current/family.css';- import {oceanDeepTheme} from './generated/current/family.js';- ```-- The bundler MUST consume the same CSS and ESM files. Bundler flattening, chunking,- and tree-shaking are adapter behavior, not proof of the native contract; the keyed- ESM remains CSS-free.--- **FR3 — Identity and order are deterministic.** The exact caller-supplied- `artifactKey`, graph identity, section identity, manifest order, generated binding- names, output paths, and provenance MUST determine the coordinated output set.- Graph and content order derive from normalized theme names, exact parent edges,- canonical section kinds, normalized source identity, and content—not invocation- order, object traversal accidents, locale, file timestamps, temporary paths, or- process identifiers. `artifactKey` is only the stable output stem; changing it MUST- NOT change theme identity, graph membership, local-token ownership, CSS- custom-property names, member exports, or compiled values. Canonical graph order repeatedly emits the lexicographically least eligible node- whose parent has already been emitted, using theme name and then normalized source- identity as the comparison key; eligibility is recomputed after every emitted- node. Section kinds use the fixed order in FR5. With the same sources, options,- and tool versions, shuffled input arguments MUST produce byte-identical committed- output.-- **FR4 — A zero-delta member still exists.** A member whose complete logical plan is- byte-identical to its parent still receives its own stable identity, scoped CSS- applicability, ESM export, declaration, manifest membership, receipt evidence, and- cleanup/check coverage inside the one keyed family set. Family generation MUST NOT- emit a distinct per-member file or private payload. The build MUST NOT return- “nothing to build” in a way that skips, preserves, or hides that member's owned- output state.--### Complete authoritative compilation--- **FR5 — One compilation plan accounts for every section.** Runtime mounting,- standalone build, and family build MUST obtain CSS behavior from the same web- compiler. Before packaging or factoring, family compilation MUST create one- canonical complete plan per member, with an explicit disposition for every- current section in this order:- 1. theme-independent data defaults and layer ordering;- 2. prose defaults;- 3. portable tokens and theme-local tokens;- 4. component rules, including derived-variable lowering and generated prop-value- rules; state names and state semantics remain component-owned and are never- theme-generated;- 5. ordered adaptations, their effective width points, generative axes, and- inherited rule order;- 6. `onDark` and `onLight` token and component rules after adaptations;- 7. root and surface `color-scheme` behavior;- 8. syntax values and other domain-token values;- 9. icon and indicator registry values and source-preserving bindings;- 10. font requirements and notices discovered from every effective section;- 11. JavaScript data required for use and source-equivalent extension;- 12. the family ESM exports, family declaration, and every required module- augmentation; and- 13. deterministic provenance, manifests, and build/check receipts.-- Each section MUST identify whether it contributes to CSS, JavaScript, types,- authoring receipts, or more than one track. Dependency behavior in one track MUST- NOT be inferred for another. A section may be empty, but it MUST be represented- deliberately. Adding a new normalized theme surface requires adding it to this- plan before standalone and family packaging may support it.--- **FR6 — Factoring follows complete plans, not ad hoc deltas.** The compiler MUST- first prove each member's complete logical plan. Packaging MAY then emit a shared- CSS declaration block once when all named members require byte-identical semantics,- scope boundaries, order, and values; member-specific differences remain scoped- member deltas in the same family stylesheet. JavaScript and type generation MAY- deduplicate internal values while retaining complete family exports and matching- declarations. Factoring MUST NOT reconstruct completeness by subtracting one- resolved object from another opportunistically, comparing serialized objects- without section semantics, or assuming that a base file loads separately. A- mutation that removes any FR5 section MUST make parity or completeness- verification fail.-- **FR7 — JavaScript and type bindings are collision-safe.** The family ESM and- declaration file MUST allocate legal local bindings from the complete graph, not- copy source-local names into one lexical scope. Allocation MUST be deterministic,- deduplicate the same imported binding when safe, and disambiguate different- specifiers or exports that used the same source-local name. Icons, indicators,- inline values, partial registry maps, inherited values, and type augmentations- receive the same treatment. The family ESM MUST parse, import, and export the- exact registry values selected by every member; the family declaration MUST- type-check those exports and augmentations.-- **FR8 — Family ESM members preserve source-equivalent extension data.** Every- exported member object MUST retain the complete normalized tokens, local-token- owner and lineage metadata, components, media surfaces, adaptations, effective- axes, icons, indicators, and other data required for a child to extend that member- as it would the source member. CSS text remains in the independent stylesheet.- Factoring MUST NOT turn an exported member into a partial base or make ESM import- responsible for stylesheet readiness.--### Native artifacts, manifests, and the cascade--- **FR9 — The manifest owns generation, not runtime assembly.** Each family- generation MUST have one deterministic `<artifactKey>.manifest.json` that records- its schema version, the exact `artifactKey`, family and member identities, exact- parent edges, the public `<artifactKey>.css`/`.js`/`.d.ts` paths, ordered section- identities, owned paths and content digests, source-graph digest, and compiler/tool- versions. The manifest lives inside its immutable,- content-identified generation directory and is the ownership boundary for cleanup- and `--check`; it MUST NOT claim a user-authored or unrelated file. Consumers MUST- NOT evaluate the manifest to discover imports, order sections, select members, or- decide runtime readiness. One stable `current` filesystem indirection (or an- equivalent atomic directory-pointer primitive) selects the active generation.-- **FR10 — `<artifactKey>.css` contains the complete family cascade.** The required- native stylesheet MUST contain reset, base, and theme layer order plus all shared- and member-specific sections needed by the selected graph. Shared declarations appear- once and apply to the exact members that inherit them. Shared family declaration- selectors MUST use `:where(:scope)` or an equally zero-specificity construct;- equivalent shared component selectors MUST also have zero specificity. Member- deltas MUST use `:scope` and the existing `to ([data-astryx-theme])` boundary.- This preserves parent/child winner selection without specificity escalation even- when an unrelated stylesheet in the same layer is physically reversed. It does- not solve missing files, request waterfalls, link readiness, or partial-failure- atomicity. Portable and local declarations, component rules, ordered adaptations,- and media-surface rules MUST keep the same winner as standalone and runtime- compilation. Nested and sibling roots MUST remain isolated. After- `<artifactKey>.css` loads, switching a member MUST require only changing theme- identity and MUST NOT add, remove, or reorder stylesheet links.-- **FR11 — CSS, JavaScript, and types have independent native contracts.**- `<artifactKey>.css` MUST be a standard standalone stylesheet usable by an HTML- `<link>`. `<artifactKey>.js` MUST be the one standard ESM module for the family,- with static, valid, cycle-safe external imports and complete named member exports;- the initial contract emits no per-theme JavaScript modules and no second aggregate- module. A missing module dependency MUST reject the module graph rather than expose- a partial member. `<artifactKey>.d.ts` MUST be the one declaration file for that ESM- surface under supported TypeScript module resolution; the initial contract emits no- per-theme declarations. Types MUST NOT define runtime readiness. JavaScript MUST NOT- import CSS in the required native output, and CSS load does not imply ESM or type- availability. After a public artifact is read through `current`, any retained- external import MUST be static and stable; no public artifact may require a source- theme, manifest evaluation, or filesystem convention at consumer runtime.-- **FR12 — Receipts stay outside runtime artifacts.** Build/check receipts, source- paths used only for diagnostics, and comparison evidence MUST NOT be bundled into- runtime CSS, ESM exports, or consumer declarations. Stable generated provenance- may identify source, command, and tool versions without making a machine-specific- absolute path or timestamp part of output identity. The manifest and receipts MAY- share one generated metadata set, but only the manifest owns published paths and- cleanup.--### Atomic writes, cleanup, and check mode--- **FR13 — The family publishes one immutable generation atomically.** The build- MUST compute every member plan in memory, then write exactly- `<artifactKey>.css`, `<artifactKey>.js`, `<artifactKey>.d.ts`,- `<artifactKey>.manifest.json`, and receipts into a new content-identified- generation directory. It MUST NOT write a per-member artifact or private payload.- Before changing the active family, under one family-output lock, it validates and- durably flushes that directory, writes and flushes a transaction journal containing- the prior and next generation identities, then atomically replaces the single stable- `current` indirection. It MUST durably flush the new indirection and its parent directory- before any superseded generation is eligible for removal. Active family files are- never rewritten one by one. A platform without an equivalent atomic, durably- flushable directory-pointer primitive MUST refuse family output rather than weaken- this guarantee. This is offline artifact generation: consumers MUST begin reading- CSS, JavaScript, and types only after the family build releases the lock. Live- hot-swapping or concurrent reads during a family build are unsupported.-- **FR14 — Recovery and cleanup are manifest-bounded.** On every build or `--check`,- the tool acquires the family lock and resolves any existing journal before normal- work. If `current` names the journal's next generation, it completes post-commit- cleanup; otherwise it restores the prior pointer and removes the uncommitted next- generation. The journal records every new generation path and both manifest- digests. It is removed and that removal is durably flushed only after commit- recovery or rollback completes. A superseded generation becomes eligible for- cleanup only after the new pointer and parent-directory flush in FR13; the tool- may remove it only when its own manifest proves family ownership. It MUST never- infer ownership from a broad filename glob or remove an unmanifested file. A crash- at any instruction boundary therefore recovers to one complete generation before- another build or check proceeds.-- **FR15 — `--check` compares the complete owned family set.** After the mandatory- FR14 preflight recovery—which is the only write check mode may perform—check mode- builds the expected family graph, complete member plans, keyed CSS/ESM/declaration,- keyed manifest, and receipts in memory without writing generated output. It fails- for a missing or outdated expected file, an `artifactKey` mismatch or path- collision, an extra file owned by the prior manifest, stale section or member- order, stale digests or provenance, a removed or renamed member, a missing- zero-delta identity/export/declaration/receipt, an ESM/type mismatch, or CSS that- omits or duplicates an owned shared/member section. Existing- build/check response contracts remain the response boundary unless a separately- accepted change introduces a stable field or error code.--### Theme-local names--- **FR16 — Ownership is explicit metadata, not a prefix.** Supplying `localTokens`,- or extending an exact enrolled base, continues to create the flattened declaration- map plus exact owner and lineage metadata. A newly declared key MUST be a valid CSS- custom-property name and MUST NOT collide with a portable `tokens` key. The- validator MUST NOT require, reserve, rewrite, or infer ownership from any prefix.- External theme owners may therefore use names such as `--ac-selection-ink` without- a new namespace API. Astryx-maintained themes MAY use `--astryx-*` as their own- internal naming convention; that convention places no restriction on external- themes and has no effect on enrollment or ownership.-- **FR17 — Declared local references remain closed.** Enrolled themes still preserve- each complete declaration name byte-for-byte through normalized data, inheritance,- runtime CSS, built CSS, generated types, and metadata. The validator scans- local-token values, root component overrides (including nested pseudos),- `onDark.components`, `onLight.components`, and adaptation- `value.localTokens`/`value.tokens`/`value.components`. On those surfaces, a `var()`- reference that exactly matches a declaration in the effective enrolled lineage is- an owned local edge and participates in exact owner, lineage, collision, and cycle- validation. Under this contract, every non-exact reference—including a case-only- difference—remains an external custom-property dependency; no prefix turns it into- an undeclared local name. An adaptation `value.tokens` key that exactly matches an- effective enrolled local declaration MUST be rejected with guidance to write that- key through `value.localTokens`, where owner, lineage, and cycle validation apply.- Root `tokens`, `onDark.tokens`, and `onLight.tokens` maps remain portable-token- surfaces and their references are not reclassified. A child may replace an- inherited declaration only through its exact enrolled lineage, and a new- declaration records the child as owner. Prefix similarity grants no ownership.--### Compatibility and migration--- **FR18 — Existing names and standalone builds remain compatible.** Existing long- theme-local names remain valid with the same bytes, meanings, owners, references,- and lineage. Relaxing the prefix rule broadens accepted enrolled input; it does not- rename or reinterpret existing declarations and does not change unenrolled legacy- behavior. A standalone theme build continues to emit a complete standalone unit- and requires no family manifest.-- **FR19 — Family optimization is opt-in at one keyed artifact-set boundary.** A theme- package adopts family output by publishing the complete native- `<artifactKey>.css`, `<artifactKey>.js`, `<artifactKey>.d.ts`,- `<artifactKey>.manifest.json`, and receipts together. Consumers load the keyed CSS- and independently import the keyed ESM; they do not add manual ancestor imports or- per-member file ordering. Loading `<artifactKey>.css` downloads every selected- member's delta, an explicit tradeoff for one request, complete first paint, and- attribute-only switching. Consumers that need only one theme may keep a complete- standalone build. The artifact key changes filenames only, not theme semantics.- This contract defines no per-member family output. Any future lazy per-member- packaging requires a separate specification.-- **FR20 — PR #5687 is evidence, not the implementation.** This specification keeps- that pull request's complete-plan goals and zero-specificity shared-declaration- technique but supersedes its required base-plus-delta consumption model. Its- command experiments and tests may inform a replacement, but only the approved- `--family … --family-key <key>` shape in FR2 is stable. Implementation, release- notes, and any required consumer migration belong in a separate replacement pull- request.--### Platform support--- Supported feature/engine floor: the same browser, CSS custom-property, cascade- layer, and `@scope` support as the existing web theme compiler.-- Unsupported behavior: a consumer path that cannot load the native family CSS or- standard ESM MUST use a compatible adapter or complete standalone output. It MUST- NOT load a private delta as a complete member. Family output is not a watch or- live-reload channel, and concurrent reads while its output lock is held are outside- the supported contract.-- Browser evidence: real Chromium MUST verify the raw native link, first paint, all- selected members, representative component states, adaptations, media surfaces,- nested and sibling roots, attribute-only switching, reversed unrelated stylesheet- order in the same layer, and folder relocation. The retained per-member-wrapper- missing-parent negative MUST prove why that output is excluded. A bundler adapter- MUST be verified using the same native CSS and ESM files. Structural tests remain- required for ESM, declarations, manifests, cleanup, and transactional failures.+ `--family-key <key>` is required with `--family` and is refused without it before any+ output is written. It names only `<key>.css`, `<key>.js`, and `<key>.d.ts`. The family+ key is only the filename stem: it does not change a member's identity or serialized+ `data.name`, and it establishes no second output-directory convention. The key uses+ the existing safe lower-kebab filename rules. Family mode composes with `--check`,+ and is refused with `--watch` and `--out`; other options retain the owning build's+ existing semantics. It adds no response field or error code; any future response+ change follows `spec:AST-017`.++### Observable family behavior++- **FR3 — One stylesheet is complete for every member.** `<key>.css` MUST contain all+ CSS needed by every selected member. For each member, every generated declaration and+ resulting computed style MUST match that member's complete standalone build across+ every supported theme surface. A consumer MUST NOT load, order, or discover another+ family stylesheet.+- **FR4 — Theme identity selects the correct cascade.** After `<key>.css` loads,+ selecting or switching a member requires only changing the theme identity. A+ descendant's differing values MUST win over inherited values without consumer+ specificity work or stylesheet-order requirements. Nested theme roots keep the+ existing boundary, sibling roots stay isolated, and unrelated same-layer stylesheets+ produce the same winners in either physical order.+- **FR5 — Deterministic output preserves zero-delta members.** Equivalent selected+ sets MUST produce byte-identical CSS, JavaScript, and declarations regardless of+ argument order. A member with no visual delta still has its selectable identity,+ complete JavaScript export, and declaration.+- **FR6 — JavaScript and types expose every complete member.** `<key>.js` MUST be a+ CSS-free standard ESM module with one complete resolved export for every selected+ member. It MUST parse and import when separate theme sources reuse the same local+ binding name. `<key>.d.ts` MUST describe every member export under supported+ TypeScript module resolution. CSS, JavaScript, and type readiness remain independent.++### Failure, check, and compatibility++- **FR7 — Success means one complete keyed result.** An invalid lineage, key, or+ member MUST fail before the command reports success. A successful build MUST expose+ all three expected keyed files with current bytes. A failed build MUST NOT report+ success for a mixed, missing, or stale expected set. This defines no stronger+ durability guarantee than the existing theme build.+- **FR8 — `--check` verifies the expected keyed outputs.** With the same family+ selection and key, `--check` MUST regenerate the expected CSS, JavaScript, and+ declaration output and compare those three files using the existing theme-build+ check semantics. It MUST report missing or outdated expected files without writing+ generated output. This contract does not add detection or cleanup of unrelated or+ extra files.+- **FR9 — Existing paths remain compatible.** Standalone and ordinary multi-file theme+ builds remain unchanged. Existing theme names, inheritance, generated values, and+ consumer imports keep their meaning. Family mode is opt-in.++### Evidence and implementation relationship++- **FR10 — PR #5687 is evidence, not the replacement implementation.** Its duplication+ measurements, lineage evidence, and cascade experiments may inform replacement work.+ Its public base-plus-member consumption model is superseded. The replacement MUST+ satisfy the completeness, load-order, zero-delta, and binding-safety behavior above+ through one aggregate CSS/JS/d.ts output.## Current-state impact-Current `main` compiles each theme as one complete standalone CSS, JavaScript, and-TypeScript unit. It already uses Core's shared web generators, preserves normalized-adaptation and local-token metadata in built themes, stages a single theme's output-before rename, and compares expected files in check mode.--Implementing this accepted contract will extend those guarantees to one keyed family-generation. It will add complete per-member compilation plans; one native-`<artifactKey>.css`, one CSS-free `<artifactKey>.js`, one `<artifactKey>.d.ts`, and-one `<artifactKey>.manifest.json` plus receipts; graph-wide collision-safe binding-allocation; manifest-bounded cleanup; and one transactional family commit. It will-also relax the enrolled local-token validator from an exact theme-name prefix to any-valid CSS custom-property name while retaining all non-prefix validation.--This accepted specification changes no runtime, compiler, CLI, generated artifact,-package, or token vocabulary by itself. It adds no Changeset. It affects-`architecture:cli-surface` because implementation MUST make-`--family-key <key>` a stable required value flag for the approved-`theme build --family <base> <children...>` shape. It adds no response field or error-code. The literal key `family` remains illustrative; callers choose the stable output-stem under FR2. The worked family example in `docs/contributing/cli-conventions.md`-must be updated with the required key, exact four-file output set, and final-composition matrix in the implementation change.+Current `main` builds one complete CSS, JavaScript, and declaration set per theme.+Implementing this accepted amendment adds the opt-in family command behavior above+while preserving those standalone results.++This specification changes no runtime, compiler, CLI, generated artifact, or package by+itself and adds no Changeset.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR4 | graph, keyed-family-artifact, CLI-composition, and zero-delta fixtures | valid/invalid/colliding key; family-key without family; family without key; direct/indirect descendants; shuffled inputs; zero-delta child | an invalid graph/key builds, key spelling changes theme identity or values, input order changes bytes, one keyed artifact is absent, or a zero-delta identity disappears |-| FR5–FR8 | complete-plan inventory plus runtime/standalone/family structural parity | every CSS/JS/type/receipt section; component-owned states; adaptations; media surfaces; reused bindings; complete ESM exports; matching declarations | deleting a section leaves parity green, a state becomes theme-generated, CSS/JS/type dependency behavior is conflated, an exported member loses extension data, or bindings collide |-| FR9–FR12 | manifest schema, native artifact structure, provenance, and real-browser cascade tests | raw `<link>`; first paint; standard ESM import; `tsc`; all members; nested/sibling roots; states/adaptations/media surfaces; reversed stylesheet order; relocation | runtime must evaluate a manifest, shared declarations duplicate, a member delta loses to shared rules, CSS import is hidden in required ESM, or types imply runtime readiness |-| FR13–FR15 | crash injection and complete-owned-set check fixtures | first build; rebuild; pre/post-pointer crash; journal recovery in check; removed/renamed/zero-delta member; missing/outdated/extra owned file | a crash exposes or recovers mixed generations, cleanup removes an unowned/unflushed predecessor, or check passes stale/incomplete CSS, ESM, declarations, manifest, or receipts |-| FR16–FR18 | shared runtime/static local-token validator matrix | existing long name; `--ac-selection-ink`; case-distinct external name; invalid custom property; portable collision; foreign owner; exact references; direct/adaptation cycle | prefix or non-exact spelling changes external validity, an exact local edge escapes ownership, an existing name changes bytes, or collision/cycle checks weaken |-| FR19–FR20 | native/bundler matrix, rejected-wrapper negative, and replacement-PR review | one-request family load; first paint; attribute switch; Vite adapter over same files; missing wrapper parent; standalone consumer | family CSS does not include every member, switching requests CSS, per-member output enters this scope, a bundler-only behavior becomes normative, or PR #5687's delta model lands as-is |--The completed feasibility probe is retained as evidence, not implementation: Chromium,-Vite, and `tsc` passed 195 assertions with zero failures; the family stylesheet used-one request; all sampled first-paint and switching frames were correct; relative-folder relocation worked; and a missing wrapper parent demonstrated partial CSS-application despite top-level `link.onerror`. Its hand-built fixtures do not satisfy-the implementation gates for transactions, manifest/receipt ownership, zero-delta-cleanup, deterministic generation, prefix-independent validation, component states,-adaptations, or media surfaces.+| Contract | Required evidence | Failure signal |+| -------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR2 | graph and CLI composition tests | a missing ancestor or cycle builds; the key changes identity; family mode emits anything other than the keyed trio |+| FR3–FR5 | standalone-equivalence fixtures plus real Chromium | a component, prose, adaptation, on-media, nested-root, sibling-root, reversed-order, or zero-delta state differs; argument order changes bytes |+| FR6 | ESM parse/import, TypeScript, and binding-collision fixtures | an export is incomplete or absent; reused local names break parsing; declarations disagree with exports |+| FR7–FR9 | invalid-input, write-failure, check, and standalone regression fixtures | invalid input reports success; a successful build exposes mixed, missing, or stale bytes; check falsely passes them; standalone output changes |++Real-browser verification MUST load only `<key>.css` and exercise every selected+identity, representative components and prose, on-media behavior, nested and sibling+roots, a zero-delta member, and an unrelated same-layer stylesheet in both orders.+Structural tests MUST prove deterministic bytes, complete ESM exports, matching types,+and collision-safe imports. Existing standalone fixtures MUST remain unchanged.### Completion criteria-This specification is `accepted`. It moves to `shipped` only when:--- every selected member is represented in one native `<artifactKey>.css`, one- standard CSS-free `<artifactKey>.js`, one `<artifactKey>.d.ts`, and one- `<artifactKey>.manifest.json` plus receipts, including zero-delta members;-- `--family-key <key>` is required exactly for family mode, rejects invalid or- colliding keys before writes, and changes only the coordinated output stem;-- runtime, standalone, and family compilation use one canonical web compilation plan- and pass complete-section parity independently for CSS, JavaScript, and types;-- shared CSS declarations emit once at zero specificity, member deltas use `:scope`,- and nested/sibling members preserve winners without stylesheet-order escalation;-- manifests encode deterministic graph and section order, own exact cleanup, and- require no consumer runtime assembly;-- graph-wide generated bindings parse, type-check, import, and preserve registry- values under source-name collisions;-- immutable-generation staging, pointer/directory durability, journal recovery,- cleanup, and check pass crashes at every instruction boundary plus missing, stale,- extra, removal, and rename states;-- real Chromium proves raw-link first paint, every member, representative component- states, adaptations, media surfaces, nested/sibling roots, attribute-only switching,- reversed unrelated stylesheet order, relocation, and the rejected per-member- wrapper's missing-parent failure; a bundler adapter proves it consumes the same CSS- and ESM files;-- no per-member family artifact is emitted or documented by this implementation; and-- valid external custom-property names enroll without prefix policy while exact- ownership, lineage, reference, collision, and cycle checks remain.+This specification remains `accepted` until one replacement implementation proves:++- one deterministic keyed CSS/JS/d.ts trio for direct and nested descendants;+- complete standalone-equivalent CSS behavior from that single stylesheet;+- selectable zero-delta members and collision-safe aggregate JavaScript/types;+- build and `--check` cannot report success for mixed, missing, or stale expected+ keyed files; and+- real Chromium behavior plus unchanged standalone builds.## Decision log-### DEC-1 — Make one native family set the required boundary+### Amendment — Keep the specification at the observable boundary++**Decider:** `cixzhang`, `2026-09-12`++The accepted 2026-09-11 text coupled the family output contract to a second internal+architecture. This amendment removes that design from the behavior contract. No+earlier family-specific internal architecture requirement remains in force; only the+observable requirements in this amended record govern.++The amendment retains the one-file family result, deterministic order, nested lineage,+zero-delta identity, complete aggregate exports, binding safety, correct cascade, and+real-browser proof.++### DEC-1 — Emit one keyed family output trio**Reference:** `spec:AST-034/DEC-1`-**Decider:** `cixzhang`, `2026-09-11`--A consumer loads one keyed family stylesheet and independently imports one keyed-family ESM. The stylesheet contains shared declarations once plus every scoped member-delta; the ESM is the only generated family module and exports every complete member;-the one declaration matches those exports. Switching a loaded family is an attribute-change. This eliminates consumer graph and import-order management while keeping CSS,-JavaScript, and type readiness separate.--The caller supplies the stable output stem through-`astryx theme build --family <base> <children...> --family-key <key>`. A required-value flag is the narrowest addition because it changes only what the approved family-build job names; it does not create a second command or overload theme identity. The-exact lower-kebab key deterministically names `<key>.css`, `<key>.js`,-`<key>.d.ts`, and `<key>.manifest.json` and is collision-checked before writes. There-is no derived default: deriving the stem from a member would conflate artifact naming-with theme identity and could collide when the selected family changes.--Rejected: requiring separate public entrypoints for every member or documenting a-child delta plus manual base import. A family stylesheet eagerly downloads all member-deltas, but buys one request, complete first paint, and attribute-only switching. A-complete standalone theme remains valid for the one-theme case.--Per-member relative-import wrappers are excluded from this specification. The Chromium-probe showed why a bare wrapper cannot be the baseline: a missing parent raised-`link.onerror` while the child delta still applied. Any future lazy per-member-packaging requires a separate specification.--### DEC-2 — Compile complete plans before family factoring+**Decider:** `cixzhang`, `2026-09-11`; amended `2026-09-12`++The family command emits `<key>.css`, `<key>.js`, and `<key>.d.ts`. The CSS contains all+members, the ESM exports every complete member, and the declaration describes those+exports. The required `--family-key` changes filenames only. Per-member family output+and consumer runtime assembly are rejected because they return graph and load-order+work to the consumer.++### DEC-2 — Preserve complete member behavior in one stylesheet**Reference:** `spec:AST-034/DEC-2`-**Decider:** `cixzhang`, `2026-09-11`--One complete logical plan per member is the proof that family output preserved-behavior. Sharing happens only after the plan accounts for every current compiler,-registry, type, diagnostic, and provenance section. Shared CSS uses-`:where(:scope)` or equivalent zero specificity; member deltas use `:scope`. This-preserves member winners even when unrelated same-layer stylesheet order reverses,-without raising specificity. It does not provide loading, readiness, or failure-atomicity.--Rejected: subtracting resolved objects or serialized CSS and assuming omitted values-will arrive from a separately loaded base.--### DEC-3 — Let the manifest own one transactional generation--**Reference:** `spec:AST-034/DEC-3`-**Decider:** `cixzhang`, `2026-09-11`--A manifest gives generation and check mode an exact, reviewable ownership set for-`<artifactKey>.css`, `<artifactKey>.js`, `<artifactKey>.d.ts`,-`<artifactKey>.manifest.json`, receipts, publication, and cleanup. It does not-instruct consumers how to assemble runtime output. The build durably stages an immutable generation and journal, then atomically replaces and-flushes one `current` filesystem indirection. On restart the tool resolves any-interrupted journal before another build or check proceeds.--Rejected: per-member writes followed by broad filename cleanup or runtime manifest-assembly. A late failure can publish a broken family, and a glob cannot distinguish-generated files from a consumer's files safely.--### DEC-4 — Keep local-token ownership independent of spelling--**Reference:** `spec:AST-034/DEC-4`-**Decider:** `cixzhang`, `2026-09-11`--A valid CSS custom-property name, exact owner metadata, and exact enrolled lineage are-sufficient to own a theme-local token. Existing Astryx-prefixed names remain valid,-but prefix spelling is only an owner convention. This supersedes all of AST-006-decision 2 and only decision 4's clauses that classify or validate references through-that reserved prefix. AST-006's explicit enrollment boundary, shared runtime/static-validator, exact lineage, cycle checks, collision checks, and legacy unenrolled-behavior remain in force.--Rejected: reserving `--astryx-*` for external themes, requiring a theme-name prefix,-or adding a namespace API. Those rules constrain names without strengthening the-owner, reference, collision, or cycle proof.+**Decider:** `cixzhang`, `2026-09-11`; amended `2026-09-12`++Every selected identity produces the same observable CSS behavior as its complete+standalone build. Descendant differences win without a consumer-managed load order or+specificity escalation, including for nested descendants, components, prose,+adaptations, and on-media behavior.## Open questions