An open source design system that's fully customizable and agent ready
schema_version: 1 template_version: 1 kind: architecture id: architecture:component-theming-surface authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-24 owners: [cixzhang, imdreamrunner] applies_to: [ packages/core/src/, packages/lab/src/, packages/charts/src/, packages/richtext/src/, packages/core/src/utils/themeProps.ts, packages/core/src/theme/themingTargets.test.ts, packages/core/src/theme/extensibleAxes.test.ts, packages/core/src/theme/derivedVarRegistry.test.ts, docs/contributing/api-conventions.md, docs/templates/knowledge/component-spec.md, scripts/check-knowledge.mjs, ] verified_by: [ scripts/check-knowledge.mjs, packages/core/src/theme/themingTargets.test.ts, packages/core/src/theme/extensibleAxes.test.ts, packages/core/src/theme/derivedVarRegistry.test.ts, ] deciding_specs: [ spec:AST-012/DEC-2, spec:AST-012/DEC-3, spec:AST-012/DEC-5, spec:AST-017/DEC-1, spec:AST-017/DEC-26, spec:AST-087/DEC-9,
]
Component theming surface
{
"scope": "global",
"triggers": {
"theming": [
"INV3",
"INV4",
"INV5",
"INV6",
"INV7",
"INV8",
"INV9",
"INV10",
"INV12",
"INV14",
"INV15"
]
}
}
This record defines how component anatomy relates to the public theming API.
Purpose
Theme authors need stable names for the visible component parts they can style, without exposing every wrapper, slot, state, or implementation detail as a permanent selector.
Component anatomy is the semantic inventory. The theming surface is an explicit, qualified projection of that inventory—not a one-to-one copy.
System model
A machine-readable block in each component spec maps every consumer-facing anatomy entry to one theming disposition. The map is not included in generated consumer docs:
target— this component promises a stable public target for the visible part, such asselector-popup.inherits— the part has no separate target. It uses styles from this component's parent target, such as a Button label inheriting frombutton.delegatesTo— another Astryx component owns the part and its target, such as a Selector label usingField/field-label.nonewith classified reason — no current public target reaches this stable anatomy part. The required reason begins with exactly one factual classification:intentional:— an approved boundary makes the part non-themeable now;reachability-gap:— a current target should reach the part, but does not;unsettled:— whether or how to expose the part still needs an owner decision.
none records current reachability. It does not by itself decide that a part must
remain unthemeable or authorize a future public target.
Every current, non-deprecated public target maps to an anatomy entry or to an
explicit family owner. Consumer .doc.mjs files continue to own anatomy names,
descriptions, and public target documentation. Component specs own the exact map
and explain only non-obvious rationale or exceptions.
Visual prop axes and states are selector capabilities of a target. They are not
separate anatomy parts or separate targets. Runtime themeProps() reflection,
public .doc.mjs theming.targets[].visualProps / states metadata, and checked
component-spec metadata describe those selector axes without exposing maintainer
dispositions to consumers; they do not declare which CSS properties have
guaranteed behavior.
An adaptation rule uses the same component target, axis, value-domain, and
extension validation as root components; it does not create a parallel
component-value policy. Built-in values and values accepted by authoritative open
primitive domains may be styled only inside a rule and need no matching root style
declaration. A custom value whose validity depends on theme enrollment is
introduced on the effective root components map, where build tooling can
generate unconditional module augmentation; adaptation rules may then restyle
that value under conditions.
The shared guaranteed-property catalog is:
| Category | Exact authoring keys |
|---|---|
| Paint | color, backgroundColor, opacity, outlineColor, outlineOffset, outlineStyle, outlineWidth, boxShadow, textShadow |
| Border/shape | borderColor, borderStyle, borderWidth, borderRadius |
| Typography | fontFamily, fontSize, fontStyle, fontWeight, letterSpacing, lineHeight, textAlign, textDecorationColor, textDecorationLine, textDecorationStyle, textDecorationThickness, textTransform |
| Padding | padding, paddingBlock, paddingBlockStart, paddingBlockEnd, paddingInline, paddingInlineStart, paddingInlineEnd |
The initial catalog contains every standard CSS key used by the seven shipped
package themes except height: backgroundColor, borderColor, borderRadius,
borderStyle, borderWidth, color, fontFamily, fontSize, fontWeight,
lineHeight, padding, paddingBlock, and paddingInline. It adds the explicit
paint, typography, and logical-padding keys needed to make those categories
coherent. height remains a target-specific addition because it changes layout.
The catalog is a vocabulary, not an automatic guarantee on every target. Each
target's guaranteedProperties lists the exact rational subset it supports from
this catalog and any exact reviewed target-specific additions. Omission means
best effort; no exception entry is required.
The list is literal. A listed shorthand does not imply its longhands; a logical
property does not imply a physical counterpart; and one property does not imply
an alias such as background, inlineSize, or outline. Properties outside the
catalog, including height, width, gap, positioning, overflow, and grid/flex
structure, require an explicit target addition to become guaranteed.
Every declared property must produce a rational, observable result on the anatomy part the target owns. Generic component styling may accept other CSS properties, but acceptance alone is best effort, not a compatibility promise.
Boundaries and invariants
- INV1 — Participation is capability-based. Core components participate. Lab components are exempt until they opt into public component theming or are prepared for promotion. At that point they must provide the same targets, metadata, anatomy dispositions, and validation as other participating components. Consuming semantic tokens alone does not enroll a component.
- INV2 — Anatomy anchors public targets. Every current target represents a stable semantic part, either locally or through an explicit family owner.
- INV3 — Anatomy does not imply target proliferation. Every participating
anatomy entry has one component-spec mapping, but inheritance, delegation, and
factual
noneare valid outcomes. Anonereason distinguishes an intentional current boundary from a reachability gap or unsettled future exposure; it never silently decides future themeability. When desktop and touch render different parts or use different theming owners, they use separate anatomy rows. Those rows describe alternatives that are never mounted together outside the one transient copy during a presentation switch, and both follow the minimal construction ofarchitecture:component-style-authoringINV7. - INV4 — Targets paint. A target belongs on a stable visible element that paints theme-controlled output—not an event wrapper, speculative internal structure, or a node created only for layout plumbing.
- INV5 — Composition preserves ownership. A part rendered by a shared Astryx primitive delegates to that primitive's target unless the parent guarantees a distinct public visual contract.
- INV6 — State stays on the owning target. Variant, size, selection, disabled,
and interaction state are reflected as target capabilities through
themeProps; they do not create parallel targets solely for each state. An artwork request, such asIcon.variant, selects supplied artwork rather than styling and is not reflected. - INV7 — Guarantees use one catalog and exact target declarations. The shared
catalog defines the supported vocabulary, not an automatic target promise. Each
target's
guaranteedPropertieslists the rational catalog subset it guarantees and any reviewed target-specific additions. Every listed property must produce an observable result on the owned anatomy part, with representative compiler and runtime evidence. - INV8 — Names imply nothing beyond themselves. No shorthand, longhand, logical/physical counterpart, alias, or custom property is guaranteed unless its exact authoring key appears in that target's declaration. Omitted properties remain best effort; no exception mechanism is needed.
- INV9 — Generic styling is best effort. A target may accept CSS properties outside its declared guaranteed set through the generic styling pipeline. That acceptance does not promise a useful effect or compatibility across releases.
- INV10 — Public semantic variables are admitted, not inferred. When no
guaranteed CSS property can express a caller-owned need, a component may expose
a reviewed public custom property with purpose-based meaning, stable default or
fallback, defined target/state scope, consumer docs, and compatibility
coverage. It must pass the admission bar in
architecture:public-component-api; an implementation gap does not automatically justify a new variable. - INV11 — Private expansion stays private. The compiler may translate a
guaranteed public property into one or more private
--_*variables so the owning component can route, compose, or transform the value across its internal painters. By contract, those variables must not be authored directly or relied on by consumers. Exact mappings remain checked code/metadata, not copied prose; known enforcement gaps are recorded inarchitecture:theme-compilation. - INV12 — Aliases are compatibility, not anatomy. Removed target aliases do
not count as current semantic parts. Starting in 0.7.0, runtime target emission,
component metadata, CLI discovery, theme build, and generated docs expose only
canonical targets. Maintained themes, CLI templates, and copyable examples use
canonical keys. The breaking release preserves the complete old-to-new mapping
and migration path below under
spec:AST-017. - INV13 — Family ownership is explicit. A family document may own a shared target for several components, but local docs link to that owner rather than leaving ownership to inference.
- INV14 — Extensible axes need a theme-independent fallback. A prop axis may
be theme-extensible only when it is visual and an unavailable custom value has
one safe, deterministic baseline that does not depend on the active theme.
Heading.typequalifies because requiredHeading.levelprovides that baseline.Icon.variantqualifies because an unlisted variant renders the request without a variant, which is the same for every theme. It is an artwork request, not a styling selector: theicontarget does not reflect it, so it has nothemeProps()reflection,visualPropsentry, or component styling map.Icon.sizedoes not: no missing custom size can be inferred without silently changing geometry, alignment, or composition. Behavioral, structural, placement, directional, and state-machine axes remain closed regardless. A theme may redefine an existing value on a closed axis, but it may not add one. - INV15 — Conditional styling does not create conditional API. Adaptation
component writes use the same shared validation as root component writes. A rule
may style an independently valid built-in or open-primitive value without
duplicating that target or value in root
components. A custom value that becomes valid only through theme enrollment must be enrolled on the effective root surface before a rule uses it, so generated types never depend on a media condition. An unresolved shared-validation result carries into adaptations unchanged and tightens automatically when the shared contract becomes authoritative; it is not a permanent adaptation exemption or an extension point.
Approved deprecated-surface removal
Version 0.7.0 removes the deprecated component-theming compatibility surface
in this section. This is a breaking change under spec:AST-017; the release
includes the exact old-to-new mapping and a staged migration codemod.
The approved target-alias migration is:
| Deprecated target | Canonical target |
|---|---|
base-table |
table |
checkbox |
checkbox-indicator |
codeblock |
code-block |
codeblock-copy-button |
code-block-copy-button |
codeblock-header |
code-block-header |
codeblock-title |
code-block-title |
date-input-clear-icon |
input-clear-icon |
date-range-input-clear-icon |
input-clear-icon |
hovercard |
hover-card |
multi-selector-clear-icon |
input-clear-icon |
navicon |
nav-icon |
popover-surface |
popover |
progressbar |
progress-bar |
progressbar-fill |
progress-bar-fill |
progressbar-mark |
progress-bar-mark |
progressbar-track |
progress-bar-track |
radio |
radio-indicator |
radio-dot |
radio-indicator-dot |
selector-clear-icon |
input-clear-icon |
statusdot |
status-dot |
textarea |
text-area |
The 0.7.0 removal also deletes the compatibility machinery used only for those
aliases: the themeProps(..., {legacyNames}) option,
ThemePropsOptions.legacyNames, ComponentThemingTarget.deprecatedFor, and
alias-only filtering or discovery behavior.
Deprecated bare prop/value and state selector classes such as .primary, .sm,
and .checked are no longer emitted. Their stable replacement is the canonical
astryx-* target plus its explicit reflected data-* attribute. Semantic
defineTheme({components}) keys remain supported; only the 21 deprecated target
spellings in the table above move to their canonical keys. Because an unqualified
bare class does not identify its prop/state axis and may be consumer-authored, the
codemod leaves it for manual review.
Canonical target names, semantic component keys, reflected data-* selectors,
and current target behavior are outside this removal authorization and remain
supported. Built-in and generated themes must migrate to canonical targets before
the aliases disappear. Static inline theme keys receive a supported migration;
dynamic theme objects and custom CSS receive the complete mapping above.
This record does not own semantic token definitions, theme authoring precedence, how themes become output, or the design rationale for a component's appearance.
DEP-0013 — Deprecate the 21 component-theming target aliases
| Field | Value |
|---|---|
| id | DEP-0013 |
| cleanup | CLN-0022 |
| package | @astryxdesign/core, @astryxdesign/cli |
| surface | Theme target names: the 21 aliases in the mapping table above, as defineTheme({components}) keys and as .astryx-<alias> CSS classes, plus the machinery that exists only for them: themeProps(..., {legacyNames}), ThemePropsOptions.legacyNames, ComponentThemingTarget.deprecatedFor, and alias-only discovery and filtering |
| old contract | Each alias is emitted beside its canonical target on the same element, accepted by theme build, and listed by CLI discovery |
| replacement | The canonical target in the mapping table above, as both theme key and CSS class |
| direct authority | architecture:component-theming-surface INV12 and this section. Owners: cixzhang, imdreamrunner |
| warning | Theme build warns Deprecated component target "<alias>". Use "<canonical>" instead.; CLI discovery labels each alias with its replacement |
| migration | Run astryx upgrade --from <0.6 version> --apply --path .; review each TODO(astryx upgrade) it adds |
| codemod | migrate-deprecated-theme-surface: renames static keys in theme components maps and alias classes in CSS. It adds a TODO when an old and a canonical key coexist. The four clear-icon aliases keep their owner scope in CSS with :where(.astryx-<owner> *); a theme key cannot carry that scope, so the codemod adds a TODO. Computed keys and CSS inside strings are reported cases, not rewritten |
| downstream | Maintained themes, CLI templates, and copyable examples use only canonical keys; the bundled and probe themes build with no alias |
| transition | no prior transition |
| state | proposed |
| target plan | CLN-0022 in 0.7.0 |
CLN-0022 — Canonical theme targets only
| Field | Value |
|---|---|
| id | CLN-0022 |
| lifecycle | DEP-0013 |
| delta | Components stop emitting the 21 alias classes. Theme build treats an alias key as an unknown component and suggests the canonical key. CLI discovery and generated docs list only canonical targets. legacyNames, ThemePropsOptions, and deprecatedFor are removed |
| rollback | Restore alias emission, metadata, and discovery from the final 0.6 baseline |
| state | pending — lands in a declared minor with its [breaking] Changeset |
DEP-0014 — Deprecate bare prop and state classes
| Field | Value |
|---|---|
| id | DEP-0014 |
| cleanup | CLN-0023 |
| package | @astryxdesign/core |
| surface | Rendered CSS classes: one bare class per visual prop or state value on every themed element (.primary, .sm, .checked; a value that starts with a digit keeps its prop prefix, such as .level-2), repeated on alias targets |
| old contract | A selector that qualifies an Astryx target with a bare value class, such as .astryx-button.primary, matches that prop or state |
| replacement | The canonical target plus its reflected data-* attribute, such as .astryx-button[data-variant="primary"]. Theme components keys are unchanged |
| direct authority | architecture:component-theming-surface, this section. Owners: cixzhang, imdreamrunner |
| warning | Consumer docs label the classes deprecated and name the replacement |
| migration | Run astryx upgrade --from <0.6 version> --apply --path .. Replace unqualified bare classes by hand, only where they target Astryx |
| codemod | migrate-deprecated-theme-surface: rewrites target-qualified bare classes in .css files to reflected data-* selectors, using every bare class the final 0.6 release emitted. It adds a TODO when a class Astryx once emitted has no known meaning on the target it qualifies. Unqualified classes cannot be classified, because a bare class does not name its axis and may be application-owned |
| downstream | Generated CSS for every maintained theme contains no target-qualified bare class; the probe theme and visual gate exercise only data-* selectors |
| transition | no prior transition |
| state | proposed |
| target plan | CLN-0023 in 0.7.0 |
CLN-0023 — Reflected attributes only
| Field | Value |
|---|---|
| id | CLN-0023 |
| lifecycle | DEP-0014 |
| delta | themeProps() emits one canonical target class and reflected data-* attributes; no bare prop or state class is rendered |
| rollback | Restore bare-class emission from the final 0.6 baseline |
| state | pending — lands in a declared minor with its [breaking] Changeset |
Change coupling
- Adding or renaming a
themeProps()target updates its component-spec map,.doc.mjspublic target metadata, generated/CLI discovery, and validation together. Copyable examples and maintained themes use canonical keys. - The 0.7.0 deprecated-surface removal preserves every canonical target and semantic key, migrates built-in/generated themes first, and supplies the exact alias and bare-selector migration evidence named above.
- Adding consumer anatomy requires a deliberate component-spec mapping to a
target, inheritance, delegation, or factual
none. It does not automatically create CSS API. Anoneentry classifies the current state asintentional,reachability-gap, orunsettled; changing reachability updates the mapping, while future exposure still follows normal public-target review. - Opening a prop axis to theme-defined values classifies the axis and records its
no-match fallback in the owning component contract or governing system spec.
Review proves the axis is visual, the fallback is safe and theme-independent,
and every ineligible axis stays closed. A focused component test covers the
custom value with no matching active theme rule.
extensibleAxes.test.tschecks only the structural wiring: the public map,themeProps()reflection, and consumer metadata. An artwork axis keeps the public map check, because its map is the one theme build augments, but has no styling wiring: the guard exempts it from thethemeProps()reflection andvisualPropschecks only, by an explicit list of artwork-request maps, currentlyIconVariantMap. Its focused fallback test renders an unlisted name. - Adding a property to a target's
guaranteedPropertiesrecords its purpose and scope, proves a rational observable effect on the owned anatomy part, and adds representative compiler/runtime coverage. Catalog membership alone does not add a target guarantee; target-specific behavior outside the catalog is admitted by the same reviewed declaration. Common property-to-variable behavior belongs to theme compilation. - Adding a public semantic custom property first shows why no guaranteed CSS property expresses the need, then updates its component contract, consumer docs, stable fallback/default, scope, runtime evidence, and compatibility coverage together. It is not the default response to an unsupported property.
- Moving target ownership to a family updates every member's disposition and link in the same reviewed change.
- Expanding participation to another package first extends the consistency guard to that package; partial public targets without metadata are defects.
Owning code
- Component
.doc.mjsusage.anatomy[]owns the consumer-facing semantic part inventory and contains no theming disposition or maintainer rationale. - Component
.doc.mjstheming.targets[]owns discoverable canonical public targets and their visual prop/state selector axes. Removed aliases are not present in this metadata and do not count as anatomy.visualPropsdoes not declare CSS property support. - The approved property catalog is owned by this record. Target
guaranteedPropertiesdeclarations will live in component.doc.mjstheming.targets[]once the authoring schema supports them; there is not yet a machine-readable field. - Component
.doc.mjstheming.vars[]owns documented custom properties and marks private implementation variables;theming.derived[]records checked public-property expansion metadata. - A component record's (
docs/specs/components/)### Theming anatomyblock owns the exact, machine-readable anatomy-to-target dispositions. It is optional during migration, checked against consumer anatomy, and excluded from generated consumer docs. Nearby component-spec prose owns non-obvious rationale, exceptions, and links. - Runtime
themeProps()calls emit one canonical target and reflecteddata-*state/prop selectors. - CLI discovery and theme build consume canonical target metadata; copyable examples omit removed aliases.
scripts/check-knowledge.mjs,themingTargets.test.ts,extensibleAxes.test.ts, andderivedVarRegistry.test.tsenforce the source/metadata/generated relationship.extensibleAxes.test.tsproves only structural consistency; component contracts, review, and focused component tests prove whether an axis may be open and whether its fallback is safe.- Family contracts own shared target semantics when multiple components adopt one part contract.
Deciding specs
spec:AST-012/DEC-2andspec:AST-012/DEC-3constrain adaptation component writes to the closed ordered rule model.spec:AST-012/DEC-5makes component validation shared with root themes and reserves effective-root presence for values whose validity depends on theme enrollment.spec:AST-087/DEC-9makesIcon.varianta theme-extensible axis whose names each theme lists once and whose fallback is the request without a variant.spec:AST-017/DEC-26builds components from minimal DOM; desktop and touch rows are never mounted together outside the one transient switch copy (INV3).spec:AST-017/DEC-1owns published compatibility classification and migration: compatibility-path removal is breaking. This record owns the exact deprecated theming cohort and its approved 0.7.0 removal window.
Verification
| Invariant | Evidence | Failure signal |
|---|---|---|
| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |
| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or none silently becomes future policy; or separate desktop and touch rows are mounted at once outside the transient switch copy |
| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |
| INV6 | themingTargets.test.ts and extensibleAxes.test.ts; the visual gate's probe theme gives each declared target, each declared state, and each enumerated value of a reflected prop its own probe colours, so a capture shows which entry last painted each element; entries on one target set the same four colour properties, so a capture proves the winning entry reached the element, not every entry beneath it; props it cannot enumerate are reported unprobed (.github/scripts/visual-gate/generate-probe-theme.mjs) |
State/variant is invisible to the owner target or becomes an unnecessary parallel target |
| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |
| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |
| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |
| INV12, INV13 | Canonical-only runtime emission and discovery, removed-alias rejection, complete codemod mapping/tests, canonical maintained-theme/template inventory, and family-owner fixtures | A removed alias is emitted or discovered, the migration mapping is incomplete, canonical targets change, removed compatibility metadata survives, or ownership stays implicit |
| INV14 | Component contract, owner review, focused no-match fallback test, and structural extensibleAxes.test.ts coverage with its explicit artwork-axis exemption list |
An ineligible axis opens, a missing rule changes behavior unpredictably, the map/reflection/docs wiring drifts, or an artwork axis gains reflection or loses its exemption |
| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |
Known conformance and verification gaps:
Component validation has unresolved domains while the shared contract remains incomplete. Root and adaptation surfaces carry the same result and diagnostic; this is shared validation debt, not an adaptation-specific exception or API admission. When the shared contract becomes authoritative, both surfaces tighten automatically. Independently valid built-in and open primitive values do not require matching root style declarations.
The component schema has no machine-readable axis-classification or fallback field.
extensibleAxes.test.tstherefore checks only structural consistency; it cannot infer whether an axis is visual or its fallback is semantically safe. Component contracts or governing system specs, owner review, and focused fallback tests provide that evidence without treating the structural guard as admission policy.Existing map-backed axes have not all been audited against INV14.
Pagination.variantandBanner.containerare known open structural axes and remain conformance gaps until their vocabularies are closed. Passing the structural guard does not make them eligible for extension.The shared catalog is approved, but the component-doc authoring schema has no
guaranteedPropertiesfield. The follow-up must add the exact-name field, migrate each current target with its rational catalog subset and reviewed additions, expose the declarations to discovery, and reject unknown or implied names. Until that migration lands, the catalog does not automatically guarantee any property on any target.CI does not yet require representative compiler and runtime evidence for each declared target/property pair. The follow-up must make missing output-path or observable runtime evidence fail validation; layout-sensitive additions also require internal-coupling and directionality evidence.
Runtime/build private-variable rejection and media-surface derived expansion are separate compiler conformance gaps owned and specified by
architecture:theme-compilation.The probe theme covers Core targets only (e.g.
rich-text-editorhas no probe entry). It resolves a reflected prop's values only from the top-levelpropsof the doc named by the target's component, so a prop documented elsewhere, such as on another doc or under a subcomponent, goes unprobed; that accounts for 76 of the 83 props the generator reports as skipped (e.g.button-group.size,avatar-status-dot.variant). The other 7 have a type with no enumerable string values, such as a numericgapscale orstring | CodeLanguage. Each entry also sets the same four colour properties, so an entry applied later on the same element covers an earlier one's paint (on Button,elevationcovers base,sizeandvariant).
Migration work from the 2026-08-30 audit
- Forty-three participating Core component docs have no anatomy inventory.
- Several anatomy docs rely on parent/family-owned targets without an explicit owner link.
- Lab components stay exempt until they declare public theming or prepare for promotion. The existing promotion guard checks participating Lab components.
Backfill component-spec maps and Core anatomy before making bidirectional validation mandatory. The audit inventory is migration evidence, not policy.