An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 1 kind: system-spec id: spec:AST-006 authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-08-31 phase: shipped owners: [cixzhang, rubyycheung, imdreamrunner] affects_architecture: [ architecture:theme-authoring-contract, architecture:theme-tokens, architecture:theme-compilation, ] affects_families: [] affects_contributing: []
affects_consumer_docs: [theme]
Theme-local tokens system spec
{
"scope": "global",
"triggers": {
"tokens": ["DEC-1", "DEC-2", "DEC-3", "DEC-4", "DEC-5", "DEC-6"]
}
}
Intent
Let a maintained theme reuse one of its own semantic decisions across component overrides without adding that decision to Astryx's portable token vocabulary. Theme authors get one explicit, checked path for theme-family-local reuse; component and application authors keep the same portable token contract they have today.
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
- Changing the type, accepted inputs, runtime or build behavior, permissive
spread behavior, names, precedence, inheritance, output, or resolution of the
existing
DefineThemeInput.tokenspath. - Adding a
defineLocalTokenshelper, a second authoring operation, a shorter role identifier, a reference alias, or a parallel local-token API. - Adding theme-local names to
TokenName,tokenVar,tokenVars,resolveThemeToken, generated portable token documentation, or Core component source. - Creating an application-consumer token extension mechanism. A compiled custom property is an implementation output of its maintained theme family, not authorization for application code to depend on it.
- Defining any adopting theme's role meaning, value, component mappings, or evidence. Those belong to that theme's colocated record.
Requirements
The requirements below are the current cross-theme contract.
- FR1 — Local tokens are purely additive, optional, and explicitly enrolled.
DefineThemeInputMUST gain at most one new authoring surface: optionallocalTokens. SupplyinglocalTokensexplicitly enrolls that theme in the new contract. A descendant inherits enrollment only by extending an enrolled exact base. A theme that neither supplies the field nor extends an enrolled exact base remains unenrolled and MUST produce byte-equivalentDefinedThemedata, runtime behavior, static output, package output, and resolution behavior. - FR2 — Existing token behavior is frozen and local values reuse its value
contract. This contract MUST NOT change
tokenstyping, accepted inputs, runtime handling, static handling, permissive unknown-key or broad-spread behavior, names, precedence, inheritance, output, or resolution. Existing casts, spreads, external CSS variables, and legacy token references MUST NOT receive new warnings, failures, reinterpretation, or migration requirements. Inside the opt-inlocalTokensfield, each value MUST accept the complete existingTokenValuecontract: a CSS string or[light, dark]tuple. Runtime and static build MUST apply the same value normalization semantics existingtokensuse, without changing that existing path or normalizing theme names. - FR3 — One exact name survives every stage. A local token declaration MUST
use its complete CSS custom-property name as the
localTokenskey. The same exact string MUST be used invar(...)references,DefinedThemedata, runtime CSS, static CSS, inherited replacement, and generated theme-specific types or metadata. No transform may create a second identifier. - FR4 — Any valid custom-property key is accepted. Every newly declared
localTokenskey 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 MAY
be referenced by the maintained enrolled theme that defines it and by
descendants enrolled through its exact
extendslineage. It MUST NOT become a portable cross-theme token or a dependency in Core component source. Mere CSS emission from an unenrolled legacy path creates no contract. Once an enrolled theme ships a local token documented in its colocated theme-level spec, the exact name and semantic meaning ARE a public compatibility contract of that theme family. - FR6 — Extension is exact-name, enrollment, and lineage-aware. A descendant
inherits enrollment and declarations only from an enrolled exact
extendsbase. 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 adaptationvalue.tokenskey that exactly matches an effective local declaration MUST fail so the write usesvalue.localTokensand retains owner, lineage, and cycle validation. Avar()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
localTokensis 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 supplyinglocalTokens; 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, replace, reject, and emit the same names without requiring a base stylesheet.
- FR10 — Released names and meanings are compatibility obligations. Once an enrolled local token ships, its exact name and documented semantic meaning are public contracts of the owning theme family. Renaming the local token or its enrolled theme, or changing that meaning, MUST use an explicit reviewed migration or alias that preserves the prior exact-name, meaning, and lineage 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. Each theme-local token definition MUST live in the owning theme's colocated theme-level spec, including its exact name, semantic meaning, value, mappings, compatibility, and rendered evidence. A long generated name is acceptable when it accurately names the meaning shared by every context where it is applied. Adding a mapping is a theme-spec compatibility review: the context MUST genuinely match the documented meaning and MUST provide rendered evidence for its actual light/dark and relevant interaction states.
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
- Supported feature/engine floor: the same CSS custom-property,
light-dark(), theme scope, and browser support as existing web themes. - Unsupported behavior: a platform compiler that cannot preserve a local role and its lineage MUST reject that enrolled input clearly rather than silently omit it or expose the CSS spelling as shared cross-platform API.
- Browser evidence: each adopting theme verifies its actual component mappings and color modes in real Chromium. Name, validation, inheritance, and runtime/static parity are structural and testable without visual evidence.
Current-state impact
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-contractowns the optionallocalTokensinput, its exact-name map, explicit enrollment state, flattened inheritance, and lineage metadata;architecture:theme-compilationemits that exact map through the shared runtime/static compiler and applies one recursive validator only to themes enrolled directly or through an enrolled exact base; andarchitecture:theme-tokenscontinues to own the unchanged portable vocabulary and explicitly excludes theme-local names from its public helpers and documentation.
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 not migrated merely because the field exists.
- A theme that omits
localTokensand does not extend an enrolled exact base remains byte-equivalent acrossDefinedTheme, 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
tokensand external-variable behavior remains byte-equivalent, including permissive broad spreads and runtime inputs. - Local names and documented meanings become public theme-family compatibility obligations after release; they never become portable cross-theme or global Core token promises. Mere custom-property emission from an unenrolled legacy path does not create that contract.
- Each local definition and mapping lives in the owning package's colocated theme spec. Every new mapping reviews whether its context genuinely matches the documented meaning and supplies rendered evidence before adoption.
- Descendant compatibility follows explicit enrollment and exact lineage. A released enrolled theme or token rename, or semantic meaning change, requires an explicit migration or alias before descendants move.
- The infrastructure implementation carries its own Changeset. A later adopting theme output change carries a separate release note.
Verification
| 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 remains shipped; the 2026-09-12 naming amendment reaches conformance when
its implementation satisfies these criteria alongside the already shipped contract:
- optional
DefineThemeInput.localTokensis the only new local-token authoring surface and its presence is the root enrollment trigger; - a theme with no
localTokensand no enrolled exact base is proven byte-equivalent, with no new custom-property scan, rejection, or warning; - local values accept both existing
TokenValueforms—a CSS string and[light, dark]tuple—and runtime/static normalization matches the existingtokensvalue path without changing it; - 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, and its exact name and semantic meaning are treated as public compatibility contracts within that theme family;
- every added mapping passes theme-spec compatibility review and rendered light/dark and relevant interaction-state evidence showing that its context genuinely matches the documented meaning;
- public portable token types, helpers, docs, and Core component source do not expose local names as cross-theme API; and
- each adopter's colocated
theme:*record owns its names, meanings, values, mappings, migration, and rendered evidence.
Decision log
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 regardless of custom-property spelling.
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 — Preserve one exact, prefix-independent name
Reference: spec:AST-006/DEC-2
Decider: cixzhang, 2026-08-31; amended 2026-09-12
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: 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; 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. 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: prefix-, suffix-, or value-based ownership or lineage inference, foreign owner claims, and silent key rewriting during extension.
DEC-4 — Validate the exact enrolled declaration graph
Reference: spec:AST-006/DEC-4
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.
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 contract
Reference: spec:AST-006/DEC-5
Decider: cixzhang, 2026-08-31
Theme-local token definitions belong in the owning package's colocated theme-level spec. Once shipped, the exact token name and semantic meaning are a public compatibility contract within that maintained theme family, even though the token is not portable across themes and is not intended for Core component source. Mere output from an unenrolled legacy path is not enough; explicit enrollment, shipment, and the theme spec establish the contract.
A long generated name is acceptable when it accurately describes every context where the theme applies it. Adding any mapping is therefore a theme-spec compatibility review: the context must genuinely mean the documented role and must carry rendered evidence for its actual light/dark and relevant interaction states.
Rejected: treating local names as either global portable tokens or disposable implementation details, defining them outside the owning theme spec, and reusing a name in contexts that only happen to share a value.
DEC-6 — Reuse the complete existing TokenValue contract
Reference: spec:AST-006/DEC-6
Decider: cixzhang, 2026-08-31
localTokens accepts the complete existing TokenValue contract: a CSS string
or [light, dark] tuple. Inside the new opt-in field, both runtime and static
build apply the same value normalization semantics existing tokens use. This
reuses one established light/dark authoring model without changing the existing
tokens path or introducing another value shape.
Rejected: limiting local values to CSS strings only or defining local-specific mode syntax and normalization.
Open questions
None at the cross-theme API level. Adopting theme specs may retain checkable rendered-evidence gates; their ownership, exact names, and semantic meanings are not re-opened by those gates.