Skip to content

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

TypeScript

spec(AST-087): icon variants, theme sizes, and componentIcons state resolvers (#7847)

Xinzi Zhouad2646109072
diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.md
index 84298ca1d0..80b0bffd7e 100644
--- a/docs/architecture/component-theming-surface.md
+++ b/docs/architecture/component-theming-surface.md
@@ -36,6 +36,7 @@ deciding_specs:
spec:AST-012/DEC-3,
spec:AST-012/DEC-5,
spec:AST-017/DEC-1,
+ spec:AST-087/DEC-9,
]
---
@@ -172,7 +173,9 @@ but acceptance alone is best effort, not a compatibility promise.
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.
+ `themeProps`; they do not create parallel targets solely for each state. An
+ artwork request, such as `Icon.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 `guaranteedProperties` lists the rational catalog subset it guarantees
@@ -212,8 +215,13 @@ but acceptance alone is best effort, not a compatibility promise.
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.type` qualifies because required `Heading.level` provides that
- baseline. `Icon.size` does not: no missing custom size can be inferred without
- silently changing geometry, alignment, or composition. Behavioral, structural,
+ baseline. `Icon.variant` qualifies 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: the `icon` target does not reflect
+ it, so it has no `themeProps()` reflection, `visualProps` entry, or
+ component styling map. `Icon.size` does
+ 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
@@ -358,7 +366,11 @@ how themes become output, or the design rationale for a component's appearance.
and every ineligible axis stays closed. A focused component test covers the
custom value with no matching active theme rule. `extensibleAxes.test.ts`
checks only the structural wiring: the public map, `themeProps()` reflection,
- and consumer metadata.
+ 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 the `themeProps()` reflection and `visualProps` checks only,
+ by an explicit list of artwork-request maps, currently `IconVariantMap`. Its
+ focused fallback test renders an unlisted name.
- Adding a property to a target's `guaranteedProperties` records its purpose and
scope, proves a rational observable effect on the owned anatomy part, and adds
representative compiler/runtime coverage. Catalog membership alone does not add
@@ -412,6 +424,8 @@ how themes become output, or the design rationale for a component's appearance.
writes to the closed ordered rule model. `spec:AST-012/DEC-5` makes component
validation shared with root themes and reserves effective-root presence for
values whose validity depends on theme enrollment.
+- `spec:AST-087/DEC-9` makes `Icon.variant` a theme-extensible axis whose names
+ each theme lists once and whose fallback is the request without a variant.
- `spec:AST-017/DEC-1` owns 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.
@@ -428,7 +442,7 @@ how themes become output, or the design rationale for a component's appearance.
| 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 | An ineligible axis opens, a missing rule changes behavior unpredictably, or the map/reflection/docs wiring drifts |
+| 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:
diff --git a/docs/architecture/icon-resolution-and-component-slots.md b/docs/architecture/icon-resolution-and-component-slots.md
index 7baa5f3763..a90b1c4f9f 100644
--- a/docs/architecture/icon-resolution-and-component-slots.md
+++ b/docs/architecture/icon-resolution-and-component-slots.md
@@ -23,7 +23,14 @@ verified_by:
packages/core/src/Selector/Selector.test.tsx,
packages/cli/api/theme/build/build.test.mjs,
]
-deciding_specs: []
+deciding_specs:
+ [
+ spec:AST-087/DEC-2,
+ spec:AST-087/DEC-4,
+ spec:AST-087/DEC-5,
+ spec:AST-087/DEC-6,
+ spec:AST-087/DEC-10,
+ ]
---
# Icon resolution and component slots
@@ -34,7 +41,16 @@ deciding_specs: []
{
"scope": "global",
"triggers": {
- "component-slots": ["INV1", "INV2", "INV3", "INV6", "INV7", "INV10"]
+ "component-slots": [
+ "INV1",
+ "INV2",
+ "INV3",
+ "INV6",
+ "INV7",
+ "INV10",
+ "INV11",
+ "INV12"
+ ]
}
}
```
@@ -63,7 +79,8 @@ extension keys. Some component-owned artwork uses those extension keys directly.
This record does not invalidate or require migration of that shipped behavior.
The target model adds one rule for future component roles: new semantic component
-slots use `componentIcons`. Shipped extension keys remain supported until a
+slots use `componentIcons`. No Core slot has shipped. Selector's selected-option
+mark is drawn by the `check` indicator, so it is not a component icon slot. Shipped extension keys remain supported until a
separate compatibility decision changes them. This record does not decide the
outcome for any existing component.
@@ -80,6 +97,14 @@ The general resolver chooses artwork in this order:
2. a process-wide `registerIcons()` entry; and
3. a matching entry in `defaultIcons`.
+An entry is a React node or a pure synchronous function of `{size, variant}`.
+A nullish static entry falls through to the next source. Once a function entry
+is selected, its result is final for that resolution: a nullish result renders
+no glyph and never falls through, so artwork never mixes two sources. `component:Icon`
+supplies the resolved size and a variant the active theme lists, or `undefined`;
+a theme-supplied entry, including an inherited one, receives a variant only when
+the theme that defined it also lists it.
+
This record does not change which shared or extension keys the general resolver
accepts. Theme application owns how the active theme is selected. Theme
authoring owns how `icons` is normalized and inherited. The Icon component
@@ -94,44 +119,77 @@ The public `@astryxdesign/core/Icon` subpath owns an augmentable map:
```ts
// Public @astryxdesign/core/Icon module
-export interface ComponentIconSlotMap {
- 'selector-selected-option': true;
-}
+export interface ComponentIconSlotMap {}
export type ComponentIconSlotName = keyof ComponentIconSlotMap & string;
-export type ComponentIconMap = Partial<
- Record<ComponentIconSlotName, IconName | null>
->;
+export type ComponentIconRequest = Readonly<{
+ icon?: IconName | null;
+ variant?: IconVariant;
+ size?: 'xsm' | 'sm' | 'md' | 'lg';
+}>;
+
+export type ComponentIconValue<State> =
+ | IconName
+ | null
+ | ComponentIconRequest
+ | ((state: Readonly<State>) => ComponentIconRequest | null | undefined);
+
+export type ComponentIconMap = {
+ [Slot in ComponentIconSlotName]?: ComponentIconSlotMap[Slot] extends true
+ ? IconName | null | ComponentIconRequest
+ : ComponentIconValue<ComponentIconSlotMap[Slot]>;
+};
```
+A slot's map value is `true` for a stateless slot or an object type that lists
+the slot's readonly state fields. The type shapes above are conceptual; the
+public names and the precise mapped type belong to the implementation.
+
The interface must be declared in the public module that consumers augment. An
interface declared only in an implementation file and re-exported from the
public subpath will not widen the type used by consumers. Runtime resolver code
imports the map from its public owner.
External component packages add their slots by augmenting the same public
-`@astryxdesign/core/Icon` module. A slot uses
+`@astryxdesign/core/Icon` module:
+
+```ts
+declare module '@astryxdesign/core/Icon' {
+ interface ComponentIconSlotMap {
+ 'example-panel-dismiss': true;
+ 'example-nav-item-leading': {selected: boolean; disabled: boolean};
+ }
+}
+```
+
+Core slots are declared the same way in the public module. A slot uses
`<component-kebab>-<semantic-role>`. The role describes why the icon exists, not
its current shape or direction.
-`defineTheme({componentIcons})` maps a component slot to a shared `IconName` or
-to `null`. It is separate from `defineTheme({icons})`:
+`defineTheme({componentIcons})` maps a component slot to a shared `IconName`,
+to `null`, to a static partial request, or, for a stateful slot, to a pure
+synchronous function of the slot's state that returns a partial request. It is
+separate from `defineTheme({icons})`:
-```ts
+```tsx
defineTheme({
name: 'brand',
+ iconVariants: ['outline', 'filled'],
componentIcons: {
- 'selector-selected-option': 'success',
+ 'example-panel-dismiss': 'close',
+ 'example-nav-item-leading': ({selected}) => ({
+ variant: selected ? 'filled' : 'outline',
+ }),
},
icons: {
- success: <BrandSuccessIcon />,
+ close: <BrandCloseIcon />,
},
});
```
-The slot map says which shared meaning a component role uses. The icon map says
-which artwork draws that shared meaning.
+The slot map says which shared meaning, variant, and size a component role uses.
+The icon map says which artwork draws that shared meaning.
### Component slot precedence
@@ -144,16 +202,35 @@ A component resolves an icon-bearing role in this order:
`undefined` means “use the next fallback.” `null` means “render no icon.” A
mapped `IconName` continues through shared icon resolution.
+A request applies field by field. A request `icon` replaces the fallback name,
+and `icon: null` or a `null` result renders no icon. A missing `icon` keeps the
+fallback name, a missing `variant` keeps the variant the component would
+otherwise request (or none), and a missing `size` keeps the component's size.
+An `undefined` result changes nothing. Request `variant` and `size` apply to
+whichever name renders. An unknown `icon`, a variant the theme does not list, or
+an unsupported `size` is treated as missing, with one development-only warning.
+
Shared resolver modules apply this order consistently:
-- `getComponentIconName(slot, fallback, source)` resolves the slot to a shared
- `IconName | null`;
-- `getComponentIcon(slot, fallback, source)` resolves that shared name to
- artwork; and
-- the client hook resolves the same slot and fallback from the active theme.
+- one function resolves a slot, its state, and its fallback to a request of
+ shared `IconName | null`, variant, and size;
+- one function resolves that request to artwork through shared icon resolution;
+ and
+- the client hook resolves the same slot, state, and fallback from the active
+ theme.
+
+Components, including packages that augment `ComponentIconSlotMap`, pass their
+slot state to these resolvers instead of reading `componentIcons` directly. The
+resolvers are the only callers of a theme's slot functions. The resolver does not
+own a component's slot name, state meaning, fallback, or rendering rules.
+
+### Indicators stay separate
-Components use these resolvers instead of reading `componentIcons` directly.
-The resolver does not own a component's slot name, fallback, or rendering rules.
+A stateful control mark that a component draws through an indicator, such as the
+selection check, the radio, or the checkbox box, is not a component icon slot.
+The indicator receives its family's state, and a theme replaces it by name
+through `defineTheme({indicators})`. One visual is never both an indicator and a
+`componentIcons` slot.
This record defines the meaning of an active theme's `componentIcons` map. The
theme-authoring architecture owns `DefineThemeInput`, normalization, and
@@ -180,7 +257,9 @@ This record does not choose the migration design or timeline.
`ComponentIconSlotMap`. External packages extend that map instead of adding
unowned Core strings.
- **INV3 — Slots map to shared meanings.** A `componentIcons` value is an
- `IconName` or `null`, never concrete artwork.
+ `IconName`, `null`, a static partial request of `icon`, `variant`, and `size`,
+ or, for a stateful slot, a pure synchronous function of the slot's declared
+ state that returns such a request. It is never concrete artwork.
- **INV4 — Null suppresses a slot.** `componentIcons[slot] = null` intentionally
renders no icon. An absent mapping uses the component fallback.
- **INV5 — Every slot declares a fallback.** The owning component declares one
@@ -190,15 +269,23 @@ This record does not choose the migration design or timeline.
artwork.
- **INV7 — Component slots do not grow the shared name set.** Adding a slot does
not widen `IconName`.
-- **INV8 — Component behavior stays with the component.** State changes,
- transforms, placement, size, color, and accessibility remain owned by the
- component that renders the slot.
+- **INV8 — Component behavior stays with the component.** State meaning,
+ transforms, placement, color, accessibility, and control geometry remain owned
+ by the component that renders the slot. A theme slot request may choose the
+ slot's Icon size and variant; the component's own size and variant are the
+ fallback. A slot size never changes the control's height, touch target, or
+ outer dimensions.
- **INV9 — Theme lifecycle stays single-owned.** This record defines what a
`componentIcons` entry means. Theme authoring owns its normalization and
inheritance; theme application owns active-theme selection.
- **INV10 — Existing keys coexist.** Shipped slots and extension keys remain
supported until a separate compatibility decision changes them. New Core slots
use `ComponentIconSlotMap` and `componentIcons`.
+- **INV11 — A selected function answers the request.** Once a function entry or slot
+ function is selected, its result is final for that resolution. Public theme
+ reads never call or return a slot function.
+- **INV12 — Indicators and slots do not overlap.** A visual drawn by an indicator
+ is replaced through `indicators`; it is not also a `componentIcons` slot.
This record does not own:
@@ -220,7 +307,8 @@ each slot locally.
A component `.doc.mjs` theming entry records:
- the slot name;
-- its fallback `IconName | null`; and
+- its fallback `IconName | null`;
+- its state fields, for a stateful slot; and
- a short description of the role and whether `null` may hide it.
A component spec records behavior that a theme author must understand, such as
@@ -240,6 +328,8 @@ theme-level role.
module from that package and adds the same owner-local docs and tests.
- Changing a slot fallback or precedence is a compatibility change because a
theme may omit the slot and rely on the old result.
+- Adding, renaming, removing, or reinterpreting a released slot state field is a
+ compatibility change because theme resolvers read it.
- Renaming, removing, or reinterpreting a shipped slot or extension key requires
an explicit compatibility plan and an allowed breaking-change path when one
cannot preserve existing behavior.
@@ -257,8 +347,8 @@ theme-level role.
- The public `@astryxdesign/core/Icon` subpath owns `ComponentIconSlotMap` and
the public slot types that consumers augment.
-- `packages/core/src/Icon/globalIconRegistry.tsx` owns `getIcon`,
- `getExtendedIcon`, `getComponentIconName`, and `getComponentIcon`.
+- `packages/core/src/Icon/globalIconRegistry.tsx` owns shared icon resolution and
+ component slot resolution, including the only calls to theme slot functions.
- `packages/core/src/Icon/useIcon.ts` owns active-theme client resolution for
shared names and component slots.
- The Icon component and its component contract own public source modes,
@@ -277,18 +367,23 @@ theme-level role.
## Deciding specs
-None. This record consolidates the existing shared registry behavior and the
-approved typed component-slot model.
+This record consolidates the existing shared registry behavior and the approved
+typed component-slot model. `spec:AST-087` decisions 2, 4, 5, 6, and 10 add
+function entries, static and state-resolver slot requests, the indicator
+boundary, final function results, and slot functions that only slot resolution
+calls.
## Verification
-| Invariant | Evidence | Failure signal |
-| ---------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| INV1, INV3, INV6 | Registry resolver tests and one rendered component fixture | A component slot resolves concrete artwork directly or skips shared icon resolution |
-| INV2, INV5 | Type tests plus component `.doc.mjs` metadata checks | A Core slot is an untyped string or has no owner/fallback |
-| INV4 | Resolver and component tests with `componentIcons[slot] = null` | A null mapping falls through and still renders an icon |
-| INV7 | Shared-name type and registry snapshot tests | Adding a component slot widens `IconName` |
-| INV8 | Representative Selector and component-owner tests | A theme must know component rendering details to replace artwork |
-| INV9 | Theme-authoring, application, and compilation owner tests | This record invents a second normalization or active-theme path |
-| INV10 | Shipped-key compatibility fixtures and new-slot negative tests | A shipped key stops working without a separate compatibility decision |
-| Documentation | Component metadata and generated CLI/docsite fixtures | A themeable slot cannot be discovered with its owner, fallback, and purpose |
+| Invariant | Evidence | Failure signal |
+| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| INV1, INV3, INV6 | Registry resolver tests and one rendered component fixture | A component slot resolves concrete artwork directly or skips shared icon resolution |
+| INV2, INV5 | Type tests plus component `.doc.mjs` metadata checks | A Core slot is an untyped string or has no owner/fallback |
+| INV4 | Resolver and component tests with `componentIcons[slot] = null` | A null mapping falls through and still renders an icon |
+| INV7 | Shared-name type and registry snapshot tests | Adding a component slot widens `IconName` |
+| INV8 | Representative component-owner tests with state and slot sizes | A theme must know component rendering details, or a slot size moves control geometry |
+| INV9 | Theme-authoring, application, and compilation owner tests | This record invents a second normalization or active-theme path |
+| INV10 | Shipped-key compatibility fixtures and new-slot negative tests | A shipped key stops working without a separate compatibility decision |
+| INV11 | Resolver tests for function entries, slot functions, and reads | A nullish function result falls through to another source, or a read returns a function |
+| INV12 | Slot and indicator inventory check | One visual is reachable as both an indicator and a `componentIcons` slot |
+| Documentation | Component metadata and generated CLI/docsite fixtures | A themeable slot cannot be discovered with its owner, fallback, and purpose |
diff --git a/docs/architecture/theme-application.md b/docs/architecture/theme-application.md
index 8e6b841650..b9e978fdf3 100644
--- a/docs/architecture/theme-application.md
+++ b/docs/architecture/theme-application.md
@@ -25,7 +25,7 @@ verified_by:
packages/core/src/theme/themeRegistry.test.ts,
packages/core/src/AppShell/AppShell.test.tsx,
]
-deciding_specs: [spec:AST-012/DEC-1]
+deciding_specs: [spec:AST-012/DEC-1, spec:AST-087/DEC-2]
---
# Theme application
@@ -36,7 +36,7 @@ deciding_specs: [spec:AST-012/DEC-1]
{
"scope": "global",
"triggers": {
- "theming": ["INV1", "INV2", "INV3", "INV7", "INV8", "INV9"]
+ "theming": ["INV1", "INV2", "INV3", "INV7", "INV8", "INV9", "INV11"]
}
}
```
@@ -52,7 +52,10 @@ duplicate styles or let one provider remove styles another provider still uses.
## System model
-`Theme` receives a `DefinedTheme`, a color mode, and children.
+`Theme` receives a `DefinedTheme`, a color mode, and children. A theme that holds
+function icon entries or slot functions is passed to `Theme` from client code.
+Server code may resolve icons with such a theme; passing it as a prop from a
+Server Component to a Client Component is unsupported.
- It registers the theme by name.
- For a theme that was not built ahead of time, it asks the web compiler for CSS
@@ -119,6 +122,9 @@ standard width map.
`sm`/`md`/`lg`/`xl`/`2xl` from the nearest active theme through the same root
fallback as other no-provider consumers. Its mobile side is strictly below the
point; equality belongs to the wider layout.
+- **INV11 — Icon resolution agrees across server and client.** Server rendering
+ and hydration resolve every icon and slot request to the same node for the
+ active theme.
This record does not own theme authoring, token definitions, compiler output, or
which component parts are public theme targets.
@@ -151,6 +157,8 @@ which component parts are public theme targets.
## Deciding specs
- `spec:AST-012/DEC-1` owns the fixed width-point vocabulary AppShell consumes.
+- `spec:AST-087/DEC-2` makes theme icon entries functions, so a theme holding
+ them reaches `Theme` from client code.
## Verification
@@ -162,3 +170,4 @@ which component parts are public theme targets.
| INV8 | `MediaTheme.dom.test.tsx` | Surface mode replaces the theme, loses parent component rules, or remounts children |
| INV9 | Runtime/build compiler comparison | Provider-mounted CSS differs from built CSS for the same theme |
| INV10 | `AppShell.test.tsx` | A named point ignores the nearest theme or treats equality as mobile |
+| INV11 | SSR and hydration icon fixtures | A server-rendered icon differs from the hydrated icon for the same theme |
diff --git a/docs/architecture/theme-authoring-contract.md b/docs/architecture/theme-authoring-contract.md
index 7e9d0e484e..a439149242 100644
--- a/docs/architecture/theme-authoring-contract.md
+++ b/docs/architecture/theme-authoring-contract.md
@@ -48,6 +48,10 @@ deciding_specs:
spec:AST-012/DEC-3,
spec:AST-012/DEC-4,
spec:AST-017/DEC-1,
+ spec:AST-087/DEC-2,
+ spec:AST-087/DEC-7,
+ spec:AST-087/DEC-9,
+ spec:AST-087/DEC-10,
]
---
@@ -59,7 +63,16 @@ deciding_specs:
{
"scope": "global",
"triggers": {
- "theming": ["INV1", "INV3", "INV8", "INV9", "INV11", "INV12"]
+ "theming": [
+ "INV1",
+ "INV3",
+ "INV8",
+ "INV9",
+ "INV11",
+ "INV12",
+ "INV13",
+ "INV14"
+ ]
}
}
```
@@ -82,7 +95,8 @@ source configuration independently.
- explicit semantic token overrides;
- optional theme-family-local token declarations;
- component target/style-key overrides;
-- icon and indicator registries;
+- icon and indicator registries, the `componentIcons` slot map, and the
+ `iconVariants` list;
- syntax tokens;
- `onDark` / `onLight` surface overrides; and
- ordered environmental `adaptations` with a fixed named width map.
@@ -100,10 +114,28 @@ Normalization follows one precedence order:
5. inherited and explicit media-surface overrides;
6. inherited and explicit theme-local declarations, validated against the
resolved token, component, and media surfaces; and
-7. inherited and explicit icon/indicator registry entries.
+7. inherited and explicit icon/indicator registry entries, `componentIcons`
+ entries, and the `iconVariants` list.
Explicit values win within their surface. Component maps merge by component,
style key, and CSS property rather than replacing the entire inherited target.
+An explicit icon, indicator, or `componentIcons` entry replaces the inherited
+entry for the same key whole. An explicit `iconVariants` list replaces the
+inherited list; an omitted list is inherited. An inherited function entry keeps
+the list of the theme that defined it, so it receives a requested variant only
+when both that list and the active theme's list contain it, and `undefined`
+otherwise.
+
+An `icons` entry is a React node or a pure synchronous function of
+`{size, variant}`, and a stateful `componentIcons` entry may be a pure
+synchronous function of the slot's state. The normalized theme keeps those
+functions for Astryx resolution. Its public reads stay plain:
+`DefinedTheme['icons']` is node-valued, with each function read at
+`{size: 'md'}`; `DefinedTheme['componentIcons']` is a static view of names,
+`null`, and static requests, with resolver slots omitted; and
+`DefinedTheme['iconVariants']` is the theme's list. Inside `defineTheme`, entry
+functions receive `variant`, and static slot requests and slot functions return
+it, typed as that theme's listed names.
## Boundaries and invariants
@@ -115,7 +147,8 @@ 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 and
lineage metadata, component rules, media surfaces, adaptations and axes, icons,
- and indicators. The normalized child is complete.
+ indicators, `componentIcons`, and `iconVariants`. The normalized child is
+ complete.
- **INV4 — Invalid bases fail loudly.** An undefined, namespace, or plain object
passed to `extends` cannot produce a plausible partial theme.
- **INV5 — Explicit tokens override generated scales.** Generated values provide
@@ -150,6 +183,15 @@ style key, and CSS property rather than replacing the entire inherited target.
derive, or normalize input into a durable typed theme value used by a current
supported consumer; validating and returning the exact input unchanged is
insufficient.
+- **INV13 — Theme functions stay behind resolution.** Function icon entries and
+ slot functions are pure and synchronous. Astryx icon resolution and build
+ tooling that enumerates a theme's icon requests (`architecture:theme-compilation`
+ INV15) call icon entries; only slot resolution calls slot functions. Public
+ theme reads return nodes, static slot values, and the variant list, never a
+ function.
+- **INV14 — The variant list is theme-level.** `iconVariants` lists the variant
+ names the whole theme supports. It is never per icon and never combined with
+ another theme's list.
This record does not own:
@@ -231,7 +273,9 @@ Its 2026-09-12 amendment makes key validity and ownership prefix-independent whi
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.
+owns released compatibility classification and migration. AST-087 decisions 2, 7, 9,
+and 10 establish function icon entries, node-valued public reads, the theme-level
+`iconVariants` list, and the static public view of `componentIcons`.
## Known conformance and verification gaps
@@ -253,5 +297,6 @@ owner, lineage, collision, cycle, and legacy-unenrolled behavior remains shipped
| 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 |
+| INV13, INV14 | `defineTheme.test.ts` type and normalization tests for function entries, slot functions, and the list | A public read returns a function, a child merges variant lists, or an entry sees another theme's names |
| Theme/Core compatibility | Maintained theme source/build against the minimum Core in its currently supported peer/dependency range | A theme update silently requires newer in-range Core or bypasses the `spec:AST-017` path |
| Authoring projection | `scripts/check-theme-template.test.mjs` | A supported authoring concept is missing or misstated in the template |
diff --git a/docs/architecture/theme-compilation.md b/docs/architecture/theme-compilation.md
index e80d9edfaf..a661c889a7 100644
--- a/docs/architecture/theme-compilation.md
+++ b/docs/architecture/theme-compilation.md
@@ -35,6 +35,8 @@ deciding_specs:
spec:AST-006/DEC-4,
spec:AST-012/DEC-3,
spec:AST-012/DEC-4,
+ spec:AST-087/DEC-2,
+ spec:AST-087/DEC-9,
]
---
@@ -46,7 +48,7 @@ deciding_specs:
{
"scope": "global",
"triggers": {
- "theming": ["INV2", "INV3", "INV4", "INV6", "INV9", "INV10"]
+ "theming": ["INV2", "INV3", "INV4", "INV6", "INV9", "INV10", "INV15"]
}
}
```
@@ -81,6 +83,10 @@ The current web compiler works like this:
6. A built theme preserves local-token ownership, effective width points,
generative-axis metadata, and normalized ordered rules, and is marked so the
provider does not compile or inject it again.
+7. A built theme carries its function icon entries, `componentIcons` functions,
+ and `iconVariants` list in its JavaScript, so built resolution returns the
+ same nodes as the runtime theme. A function the build cannot carry fails the
+ build.
For top-level declarations in base component target rules, the compiler preserves
generic CSS properties as written. When a guaranteed property needs to reach
@@ -162,6 +168,14 @@ Platform-specific details stay inside that compiler.
diagnostics schema. A CLI paired with an older core retains that core's existing
compilation behavior; it does not pretend to detect drops the older core cannot
report.
+- **INV15 — Built icon resolution matches runtime.** A built theme resolves every
+ icon request and slot request to the same node as its runtime theme, and its
+ public icon and slot exports are the same node-valued and static views. Build
+ tooling that generates or subsets icon artwork enumerates a theme's requests as
+ every entry's key with each of the four sizes and either no variant or one
+ variant that entry can receive under `spec:AST-087` FR4; it never enumerates a
+ variant the entry cannot receive, such as a name only a child theme lists for
+ an entry it inherits.
This record does not own:
@@ -255,24 +269,26 @@ This record does not own:
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
+parity. AST-087 decisions 2 and 9 establish function icon entries and the finite,
+theme-level variant list that built resolution and icon-artwork tooling use. The system owner separately selected one definition with platform-specific
outputs and the guaranteed, best-effort, public-semantic, and private implementation
tiers.
## Verification
-| Invariant | Evidence | Failure signal |
-| ---------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |
-| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |
-| INV5 | Existing per-property fixtures (partial; gap below) | A guaranteed property compiles but does not produce its promised observable effect |
-| INV6, INV7 | Existing registry and CLI public-variable tests (partial) | Private variables become authorable, or a reviewed public semantic variable fails build/runtime |
-| INV8 | Component target metadata and compatibility review | Successful generic emission is treated as a guaranteed public behavior |
-| INV9, INV10 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears |
-| 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, INV14 | Declaration scanner, generator, Theme mounting, CLI receipt tests, and the existing theme-family Chromium guard | One unsafe declaration corrupts neighbors, valid CSS changes, legacy token generation crashes, or reporting changes CSS |
-| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |
+| Invariant | Evidence | Failure signal |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| INV1, INV2, INV3 | Compiler imports and runtime/build comparison fixtures | Runtime and build use different theme-to-CSS logic or produce different web rules |
+| INV4 | `generateThemeRules.test.ts` and source/distribution cascade tests | Scope or layer order differs by output path |
+| INV5 | Existing per-property fixtures (partial; gap below) | A guaranteed property compiles but does not produce its promised observable effect |
+| INV6, INV7 | Existing registry and CLI public-variable tests (partial) | Private variables become authorable, or a reviewed public semantic variable fails build/runtime |
+| INV8 | Component target metadata and compatibility review | Successful generic emission is treated as a guaranteed public behavior |
+| INV9, INV10 | Platform compiler tests when another compiler ships | CSS details enter shared authoring, or shared theme intent silently disappears |
+| 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, INV14 | Declaration scanner, generator, Theme mounting, CLI receipt tests, and the existing theme-family Chromium guard | One unsafe declaration corrupts neighbors, valid CSS changes, legacy token generation crashes, or reporting changes CSS |
+| Built themes | Theme and CLI build tests | Runtime recompiles a built theme, or built output omits canonical rules |
+| INV15 | CLI build fixtures with function entries, slot functions, a variant list, and an inherited entry under a replaced list, compared with runtime resolution | Built and runtime icons differ, a function is dropped silently, or tooling enumerates a variant an entry cannot receive |
## Known conformance and verification gaps
diff --git a/docs/specs/AST-087-icon-variants/spec.md b/docs/specs/AST-087-icon-variants/spec.md
new file mode 100644
index 0000000000..7b71ae26e1
--- /dev/null
+++ b/docs/specs/AST-087-icon-variants/spec.md
@@ -0,0 +1,396 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-087
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-22
+phase: accepted
+owners: [cixzhang, imdreamrunner]
+affects_architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:icon-resolution-and-component-slots,
+ architecture:theme-application,
+ architecture:theme-authoring-contract,
+ architecture:theme-compilation,
+ ]
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: [theme, Icon]
+---
+
+# Icon variants, theme sizes, and component icon slots system spec
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+## Intent
+
+A theme decides how icons look:
+
+- `Icon` takes an optional `variant`. A theme lists the variant names it
+ supports once, and a theme icon entry can be a pure function of the final size
+ and that variant, so the theme maps both to its icon library's own artwork or
+ props.
+- A theme sets the dimension of each Icon size through the Icon stylesheet
+ target.
+- A component exposes a themeable icon as a `componentIcons` slot, and a slot
+ entry can resolve from the component's typed state, so a theme decides what a
+ pressed, selected, or disabled icon looks like.
+
+## Non-goals
+
+- Appearance or weight axes, per-icon capability declarations, adaptive variant
+ trees, or variant names defined by Astryx.
+- New Icon size names.
+- Additional component icon maps, an icon-role concept, nested per-state maps,
+ or compound state keys.
+- Variants for icon components passed directly to `Icon`. They render as given
+ and never receive `variant`; Icon's target, size, and color still apply to
+ them.
+- Replacing stateful control marks that a component draws through an indicator.
+ Those stay with `defineTheme({indicators})` (FR15).
+- How a component-owned icon box follows the theme dimension, and which
+ component glyphs render through `Icon`.
+- DOM or SVG measurement, SVG synthesis, or mixing artwork from two sources for
+ one request.
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+### Variant and theme entries
+
+- **FR1 — A theme icon entry is a node or a function of the request.**
+ `DefineThemeInput.icons` and process-wide registration accept, for a semantic
+ or namespaced key, a React node or a function receiving `{size, variant}`, where
+ `size` is the final Icon size and `variant` is a variant the active theme lists,
+ or `undefined`. Conceptually:
+
+ ```ts
+ type IconRequest<Variant extends string = IconVariant> = Readonly<{
+ size: 'xsm' | 'sm' | 'md' | 'lg';
+ variant?: Variant;
+ }>;
+
+ type IconEntry<Variant extends string = IconVariant> =
+ React.ReactNode | ((request: IconRequest<Variant>) => React.ReactNode);
+ ```
+
+ A theme maps size and variant to its library's own props or artwork:
+
+ ```tsx
+ defineTheme({
+ name: 'brand',
+ iconVariants: ['outline', 'filled'],
+ icons: {
+ info: ({size, variant}) => (
+ <InfoIcon
+ weight={
+ variant === 'filled' ? 'fill' : size === 'sm' ? 'bold' : 'regular'
+ }
+ />
+ ),
+ },
+ });
+ ```
+
+- **FR2 — A theme lists its variant names once.** `DefineThemeInput.iconVariants`
+ is a list of variant names that applies to the whole theme, never to one icon.
+ A child theme that sets `iconVariants` replaces the inherited list; one that
+ omits it inherits the list.
+- **FR3 — The list types the theme and the request.** Inside `defineTheme`, entry
+ functions receive `variant`, and static slot requests and slot resolvers
+ return it, typed as the theme's listed names. `Icon`'s `variant` prop uses
+ `IconVariant`, the names in the public, augmentable `IconVariantMap`. The
+ theme build writes an augmentation of that map from the theme it builds, the
+ same way it augments custom component values, and an application may augment
+ the map itself. Astryx never derives a variant type from several themes'
+ lists; when an application loads several built themes, TypeScript merges their
+ augmentations, and FR4 renders the normal icon wherever the active theme does
+ not list a requested name.
+- **FR4 — An unlisted variant renders the normal icon.** `Icon` passes a
+ requested `variant` to the selected entry only when the active theme lists it
+ and, for an entry a theme supplied, the theme that defined the entry lists it
+ too; an entry a child theme inherits keeps the list of the theme that defined
+ it. Otherwise the entry receives `undefined` and renders its normal artwork:
+ an omitted variant, an unlisted variant, and a request with no active theme
+ list all behave this way. A process-wide registration receives the variants
+ the active theme lists. A node entry renders the same node for every variant.
+- **FR5 — Variant applies to registry icons.** An icon component passed directly
+ to `Icon` renders as given and does not receive `variant`; `Icon` does not
+ forward `variant` to it or to the DOM. `variant` selects artwork only: the
+ `icon` theming target does not reflect it, so it has no styling selector.
+- **FR6 — Sources resolve before the request.** A theme entry wins over a
+ process-wide registration, which wins over the built-in default; a nullish
+ static entry falls through to the next source. The selected function's result is
+ final for that resolution: a nullish result renders no glyph and never falls
+ through to another source.
+- **FR7 — Entries and resolvers are pure and synchronous.** They compute their
+ result from their input only, without hooks, DOM or SVG measurement, browser
+ globals, network access, mutable module state, or side effects.
+- **FR8 — Build tooling can enumerate a theme's icons.** Every request a theme
+ entry can receive is its key with one of the four sizes and either no variant
+ or one variant the entry can receive under FR4. Build tooling that generates or subsets icon artwork may call
+ each entry for exactly that set; the result matches what the entry returns at
+ runtime.
+
+### Sizes
+
+- **FR9 — Entries receive the resolved size.** `Icon` resolves its size by
+ `component:Icon` ORD1 (`xsm`, `sm`, `md`, `lg`) and passes it to the entry,
+ which selects artwork for that size.
+- **FR10 — A theme sets each size's dimension in the stylesheet.** The Icon theming
+ target guarantees `width` and `height` on its size selectors, so
+ `components.icon['size:sm']` sets the `sm` dimension. Without theme styles,
+ sizes are 12, 16, 20, and 24px at a 16px root and scale with the root font size.
+
+### Component icon slots
+
+- **FR11 — Component icons are `componentIcons` slots.** A themeable icon a
+ component owns is a slot in `ComponentIconSlotMap`, mapped through
+ `componentIcons` as `architecture:icon-resolution-and-component-slots`
+ describes. A `true` value declares a stateless slot; an object type declares
+ the slot's readonly state fields.
+- **FR12 — A slot value is a name, `null`, a static request, or a state resolver.**
+ `componentIcons` accepts an `IconName`, `null`, a static partial request, or a
+ pure synchronous function of the slot's state that returns a partial request.
+ Conceptually:
+
+ ```ts
+ type ComponentIconRequest = Readonly<{
+ icon?: IconName | null;
+ variant?: IconVariant;
+ size?: 'xsm' | 'sm' | 'md' | 'lg';
+ }>;
+
+ type ComponentIconValue<State> =
+ | IconName
+ | null
+ | ComponentIconRequest
+ | ((state: Readonly<State>) => ComponentIconRequest | null | undefined);
+ ```
+
+ A stateless slot accepts every form except the function. The component
+ supplies its state; the theme handles state combinations in ordinary resolver
+ code:
+
+ ```tsx
+ componentIcons: {
+ 'example-nav-item-leading': ({selected}) => ({
+ variant: selected ? 'filled' : 'outline',
+ }),
+ }
+ ```
+
+- **FR13 — Partial results fall back field by field.** Icon content passed by the
+ caller wins over the slot. Otherwise a request `icon` replaces the component's
+ fallback name, and `variant` and `size` apply to whichever name renders. A
+ missing `icon` keeps the name the component would otherwise render, a missing
+ `variant` keeps the variant the component would otherwise request (or none),
+ and a missing `size` keeps the component's size. `null`, a `null` result, or
+ `icon: null` hides the icon; an `undefined` result changes nothing.
+- **FR14 — A slot size changes only the icon's size.** A resolved `size` replaces
+ the component's size for that slot's Icon. The control's height, touch target,
+ placement, color, interaction, and accessibility remain set by the component,
+ including any outer dimensions a family contract fixes across states.
+- **FR15 — Themes set state-dependent icons through slots.** A component that
+ exposes a state-dependent icon as a `componentIcons` slot passes that state
+ through the slot so the theme can resolve it. A component that picks a shared
+ icon name from its own state without a slot keeps doing so until its own
+ contract adds one. Per-state icon props passed by a caller, such as
+ `pressedIcon` or `selectedIcon`, act as caller-supplied icon content. A
+ stateful control mark that a component draws through an indicator, such as the
+ selection check, the radio, or the checkbox box, stays an indicator: the
+ indicator receives its family's state, and a theme replaces it by name through
+ `defineTheme({indicators})`. One visual is never both an indicator and a
+ `componentIcons` slot.
+- **FR16 — Slot state is documented theme metadata.** A slot's state fields are
+ listed with its slot metadata in the owner's component docs and in CLI and
+ docsite discovery. Changing a released state field is a compatibility change.
+
+### Reads, built themes, and server rendering
+
+- **FR17 — Slot resolution is the only caller of slot functions.** A component,
+ including one in a package that augments `ComponentIconSlotMap`, passes its
+ slot state to the shared slot resolution that
+ `architecture:icon-resolution-and-component-slots` owns. That resolution calls
+ the theme's function and renders the result through `Icon`. No public theme
+ read calls or returns a slot function.
+- **FR18 — Public reads return nodes and static values.** Registry, extension,
+ snapshot, and hook reads, `IconRegistry`, `DefinedTheme['icons']`, and built-theme
+ icon exports return React nodes; a function entry is read at `{size: 'md'}`.
+ `DefinedTheme['componentIcons']` and built-theme slot exports are a static view:
+ names, `null`, and static requests as authored, with resolver slots omitted.
+ `DefinedTheme['iconVariants']` is the theme's list. Products request a size or
+ variant through `Icon`.
+- **FR19 — Runtime, built, and server themes agree.** Runtime themes, `extends`,
+ built output, server rendering, and hydration resolve to the same nodes. A
+ child theme's entry replaces the inherited entry for the same key. A function
+ the build cannot carry fails the build. Server code may resolve icons with a
+ theme that holds functions; client code passes that theme to `Theme`.
+- **FR20 — Malformed resolver output is treated as missing.** An unknown `icon`,
+ a variant the theme does not list, or a size outside the four names in a
+ request is ignored field by field, with one development-only warning.
+
+### Platform support
+
+- Supported floor: every React, server-rendering, and browser target supported by
+ Astryx Core.
+- Unsupported behavior: asynchronous resolvers, and passing a theme that holds
+ functions as a prop from a Server Component to a Client Component.
+- Browser evidence: theme switching, nested themes, component states, listed and
+ unlisted variants, and each Icon size render the expected node at the theme's
+ dimension and hydrate to it.
+
+## Current-state impact
+
+Existing node entries, direct icon components, namespaced keys, instance props,
+and reads keep working. A theme without `iconVariants`, function entries, or
+size styles renders the same icons. These owners carry the change:
+
+- `component:Icon` — registry mode accepts `variant` (FR4, FR5), selects artwork
+ with the size resolved by ORD1 (FR9), and its target guarantees `width` and
+ `height` on size selectors (FR10).
+- `architecture:component-theming-surface` — INV14 admits `Icon.variant` as a
+ theme-extensible axis whose fallback is the request without a variant (FR3,
+ FR4).
+- `architecture:icon-resolution-and-component-slots` — entries are nodes or
+ functions and a selected function's result is final (FR1, FR6); the
+ never-shipped `selector-selected-option` slot leaves `ComponentIconSlotMap`,
+ because Selector draws its selected-option mark through the `check` indicator
+ (FR15); slot values are
+ `true` or a state shape, and INV3 admits static requests and state resolvers
+ (FR11, FR12); INV8 lets a slot request set the slot's icon size and variant
+ (FR13, FR14); indicators stay separate (FR15); slot resolution is the only
+ caller of slot functions (FR17).
+- `architecture:theme-authoring-contract` — `iconVariants`, function entries, and
+ slot functions are normalized and inherited, and public reads stay node-valued
+ or static (FR2, FR18, FR19).
+- `architecture:theme-compilation` — built output reproduces function entries,
+ slot resolvers, and the variant list, and build tooling may enumerate a theme's
+ requests (FR8, FR19).
+- `architecture:theme-application` — client code passes a theme that holds
+ functions to `Theme` (FR19).
+- Consumer `theme` and `Icon` docs describe `iconVariants`, function entries,
+ `variant`, size styling, and slot resolvers.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| FR1–FR7 | Registry type, resolver, and Icon render tests | node; function; null; omitted, listed, and unlisted variant; no active list; inherited entry under a replaced list; theme, global, default; direct | sources mix, an unlisted variant reaches an entry, `variant` reaches a component or the DOM |
+| FR2–FR3 | Type tests and theme-build augmentation fixtures | listed names in entries and resolvers; child replaces list; built augmentation; unknown name | an entry sees an unlisted name type, a child merges lists, or Astryx derives one type from two themes' lists |
+| FR8 | Build enumeration test against runtime resolution | every key × four sizes × no variant and each variant the entry can receive; inherited entry under a replaced list | an enumerated request differs from runtime output, or a variant the entry cannot receive is enumerated |
+| FR9–FR10 | Theme styling and size tests | each size with and without theme styles | a styled size does not change the glyph dimension, or an unstyled size changes |
+| FR11–FR16 | Slot type, state, fallback, indicator, geometry, and metadata tests | `true` slot; state slot; static request; partial and full results; `null`; caller content; documented state | fallback order changes, `null` stops hiding, a slot size changes the control, or a mark is both kinds |
+| FR17–FR19 | Public read, SSR, hydration, and runtime/build/extends tests | one-argument reads; static view; nested themes; child replacement; built function entries; client theme | a public read returns a function, built and runtime results differ |
+| FR20 | Type and returned-field tests | invalid state shape; unknown icon; unlisted variant; invalid size | malformed fields change the fallback, or production warns |
+
+## Decision log
+
+### DEC-1 — One variant request
+
+**Reference:** `spec:AST-087/DEC-1`
+**Decider:** cixzhang, 2026-10-22
+
+A variant system is standard across design systems. `Icon` carries one optional
+`variant`, and a heavier or lighter stroke is the theme entry's adjustment for
+the final size.
+
+Rejected: appearance and weight axes, because they are product-specific.
+
+### DEC-2 — Theme entries are functions of size and variant
+
+**Reference:** `spec:AST-087/DEC-2`
+**Decider:** cixzhang, 2026-10-22
+
+A theme entry is a node or a pure synchronous function of the final size and
+optional variant that returns supplied artwork, so the theme owns everything
+specific to its icon library.
+
+Rejected: per-icon capability declarations and adaptive variant trees.
+
+### DEC-3 — The stylesheet sets icon dimensions
+
+**Reference:** `spec:AST-087/DEC-3`
+**Decider:** cixzhang, 2026-10-22
+
+A theme sets the dimension of each Icon size through the Icon stylesheet target.
+
+Rejected: theme-added size names, because a component using one has no value
+when the theme is absent.
+
+### DEC-4 — `componentIcons` holds component icons
+
+**Reference:** `spec:AST-087/DEC-4`
+**Decider:** cixzhang, 2026-10-22
+
+The global icon map names what each icon is for, and `componentIcons` overrides
+it per component slot. A slot can resolve its request from typed component state
+in ordinary resolver code.
+
+Rejected: a second component icon map, an icon-role concept, nested per-state
+maps, and compound state keys.
+
+### DEC-5 — Themes set state-dependent icons
+
+**Reference:** `spec:AST-087/DEC-5`
+**Decider:** cixzhang, 2026-10-22
+
+A state-dependent icon that a component exposes as a slot is a theme decision made
+through its resolver, so every instance follows one rule. Indicators keep stateful control marks, because they
+draw a family's state rather than choose an icon.
+
+### DEC-6 — A selected function's result is final
+
+**Reference:** `spec:AST-087/DEC-6`
+**Decider:** cixzhang, 2026-10-22
+
+Once a function entry is selected, its result answers the request, so artwork
+never mixes two sources and a theme can deliberately draw nothing.
+
+### DEC-7 — Products request size and variant through `Icon`
+
+**Reference:** `spec:AST-087/DEC-7`
+**Decider:** cixzhang, 2026-10-22
+
+Size- and variant-aware resolution serves Astryx components and tooling. Public
+reads return React nodes, reading function entries at `{size: 'md'}`, the
+standalone Icon default.
+
+### DEC-8 — Malformed resolver output is ignored field by field
+
+**Reference:** `spec:AST-087/DEC-8`
+**Decider:** cixzhang, 2026-10-22
+
+An invalid field in a resolver result is treated as missing, so the fallback
+still renders, with one development-only warning.
+
+### DEC-9 — A theme lists its variants once
+
+**Reference:** `spec:AST-087/DEC-9`
+**Decider:** cixzhang, 2026-10-22
+
+One theme-level list gives callers typed names, gives build tooling a finite set
+of requests to enumerate, and gives an unlisted variant one fallback that does
+not depend on the theme: the request without a variant.
+
+Rejected: an open `string`, because it gives callers no types and tooling no
+finite set; Astryx deriving one variant type from several themes' lists.
+
+### DEC-10 — Slot functions stay inside slot resolution
+
+**Reference:** `spec:AST-087/DEC-10`
+**Decider:** cixzhang, 2026-10-22
+
+Only the shared slot resolution calls a theme's slot function, with the state
+the component passes. Public theme data shows a static view, so readers never
+handle functions or invent state.
+
+## Open questions
+
+None.
diff --git a/packages/core/src/Icon/Icon.spec.md b/packages/core/src/Icon/Icon.spec.md
index 712cf76b24..83d20a6c0b 100644
--- a/packages/core/src/Icon/Icon.spec.md
+++ b/packages/core/src/Icon/Icon.spec.md
@@ -27,7 +27,7 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-087]
---
# Icon component contract
@@ -53,6 +53,7 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
- Accepting a semantic icon key or a supplied icon component as the glyph source.
+- Passing the resolved size and a variant the entry can receive to a registry entry.
- Resolving explicit, component-owned contextual, and standalone size defaults.
- Applying Icon's size, color, theming target, and accessibility semantics to
the rendered glyph.
@@ -71,12 +72,13 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------- | --------- | ------------------------------------------------------ |
-| Glyph source | semantic key, namespaced extension key, or icon component | Selects the visual symbol. | Every render | Required | `component:Icon` | Stable | TypeScript rejects unsupported built-in string values. |
-| Size | `xsm`, `sm`, `md`, `lg` | Selects the icon box size. | Every rendered glyph | nearest component-owned default; otherwise `md` | `component:Icon` | Stable | TypeScript rejects unsupported values. |
-| Color | documented semantic and palette values | Selects the glyph color or inherits it from context. | Every rendered glyph | `inherit` | `component:Icon` | Stable | TypeScript rejects unsupported values. |
-| Accessibility | decorative or meaningfully labelled | Controls whether assistive technology receives the glyph. | Every rendered glyph | Decorative | `component:Icon` | Stable | Empty labels use the decorative behavior. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------- | --------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------- | --------- | --------------------------------------------------------------------------------- |
+| Glyph source | semantic key, namespaced extension key, or icon component | Selects the visual symbol. | Every render | Required | `component:Icon` | Stable | TypeScript rejects unsupported built-in string values. |
+| Size | `xsm`, `sm`, `md`, `lg` | Selects the icon box size. | Every rendered glyph | nearest component-owned default; otherwise `md` | `component:Icon` | Stable | TypeScript rejects unsupported values. |
+| Color | documented semantic and palette values | Selects the glyph color or inherits it from context. | Every rendered glyph | `inherit` | `component:Icon` | Stable | TypeScript rejects unsupported values. |
+| Accessibility | decorative or meaningfully labelled | Controls whether assistive technology receives the glyph. | Every rendered glyph | Decorative | `component:Icon` | Stable | Empty labels use the decorative behavior. |
+| Variant | names in `IconVariantMap`; the active theme lists its own | Requests a theme's alternate artwork for a registry glyph. | Registry glyphs only; never a supplied component | None | `component:Icon` | Stable | TypeScript rejects unknown names; an unlisted variant renders the normal artwork. |
A namespaced key that does not resolve currently renders nothing. This is
existing behavior, not an intentional fallback promise.
@@ -86,13 +88,15 @@ existing behavior, not an intentional fallback promise.
Requirements identify their basis so observed code is not mistaken for an
intentional decision.
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
-| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component. | Documented promise and current tests. | Settled intent. |
-| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data. | Current source, docs, and theming tests. | Settled intent. |
-| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests. | Settled intent. |
-| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior. | Current source and regression tests. | Current compatibility behavior; verify before changing. |
-| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`. | Component-size precedence and Button sizing decision. | Settled intent. |
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component. | Documented promise and current tests. | Settled intent. |
+| FR2 | Every rendered glyph MUST carry the `icon` theming target with its resolved size and selected color reflected as target data. | Current source, docs, and theming tests. | Settled intent. |
+| FR3 | Icon MUST apply the resolved size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests. | Settled intent. |
+| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior. | Current source and regression tests. | Current compatibility behavior; verify before changing. |
+| FR5 | An explicit Icon `size` MUST win. Without one, Icon MUST use the nearest default supplied by an owning Astryx component for its documented icon slot; without such a default, Icon MUST use `md`. | Component-size precedence and Button sizing decision. | Settled intent. |
+| FR6 | In registry mode, Icon MUST pass `{size, variant}` to the selected entry, where `size` is the size resolved by ORD1 and `variant` is the requested variant when the active theme lists it and, for a theme-supplied entry, the theme that defined the entry lists it too, otherwise `undefined`. A supplied icon component MUST NOT receive `variant`, Icon MUST NOT forward `variant` to the DOM, and the `icon` target MUST NOT reflect it. | `spec:AST-087` FR1–FR5 and FR9. | Settled intent. |
+| FR7 | The `icon` target MUST guarantee `width` and `height` on its `size:*` selectors as reviewed target-specific additions, so a theme sets each size's dimension. Without theme styles, sizes are 12, 16, 20, and 24px at a 16px root and scale with the root font size. | `spec:AST-087` FR10. | Settled intent. |
### Allowed variation
@@ -109,15 +113,18 @@ intentional decision.
### Representative states
-| State | Required invariant | Allowed variation |
-| -------------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
-| Semantic key | One resolved glyph carries the `icon` target. | Theme, registry, or built-in artwork. |
-| Namespaced extension key | A resolved extension glyph carries the `icon` target. | Consumer- or library-owned artwork. |
-| Supplied icon component | The supplied glyph carries the `icon` target. | Component implementation and SVG internals. |
-| Standalone Icon without `size` | The resolved size is `md`. | Glyph source and color. |
-| Owned icon slot without `size` | The nearest documented component default is used. | The owning component's declared size mapping. |
-| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default. | Any supported Icon size. |
-| Unresolved namespaced key | No glyph is currently rendered. | No fallback behavior is established by intent. |
+| State | Required invariant | Allowed variation |
+| -------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------- |
+| Semantic key | One resolved glyph carries the `icon` target. | Theme, registry, or built-in artwork. |
+| Namespaced extension key | A resolved extension glyph carries the `icon` target. | Consumer- or library-owned artwork. |
+| Supplied icon component | The supplied glyph carries the `icon` target. | Component implementation and SVG internals. |
+| Standalone Icon without `size` | The resolved size is `md`. | Glyph source and color. |
+| Owned icon slot without `size` | The nearest documented component default is used. | The owning component's declared size mapping. |
+| Explicit Icon size in owned slot | The explicit Icon size wins over the contextual default. | Any supported Icon size. |
+| Unresolved namespaced key | No glyph is currently rendered. | No fallback behavior is established by intent. |
+| Listed variant | The entry receives the size and the variant when its defining theme also lists it. | The theme's artwork for that request. |
+| Unlisted or omitted variant | The entry receives `variant: undefined`. | The theme's normal artwork. |
+| Variant on a supplied component | The component renders as given without `variant`. | Component implementation. |
### Transformation and precedence order
@@ -172,6 +179,8 @@ not promise a `span`, `svg`, or other element type.
rules for the `icon` target.
- `architecture:icon-resolution-and-component-slots` owns semantic-key and
component-slot resolution before Icon renders the selected source.
+- `spec:AST-087` decides the `variant` request, theme-listed variant names, and
+ theme-set size dimensions.
- `architecture:public-component-api` owns admission and compatibility rules for
Icon's public props and observable defaults.
- The owning component or family specifies each contextual Icon-size mapping.
@@ -181,12 +190,14 @@ not promise a `span`, `svg`, or other element type.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3, FR5 | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions. | `audit:Icon/behavior` |
-| FR2, FR4 | `Icon.test.tsx` target/styling suites plus source inspection | Both source modes; size and color variants | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming` |
-| AR1, AR2, AR3 | `Icon.test.tsx` accessible-name suites | Decorative, labelled, explicit ARIA override | Changing default or labelled semantics fails accessibility assertions. | `audit:Icon/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Icon/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3, FR5 | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions. | `audit:Icon/behavior` |
+| FR2, FR4 | `Icon.test.tsx` target/styling suites plus source inspection | Both source modes; size and color variants | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming` |
+| AR1, AR2, AR3 | `Icon.test.tsx` accessible-name suites | Decorative, labelled, explicit ARIA override | Changing default or labelled semantics fails accessibility assertions. | `audit:Icon/accessibility` |
+| FR6 | `Icon.test.tsx` variant suites (pending) | listed, unlisted, and omitted variant; no active list; inherited entry under a replaced list; supplied component | An unlisted variant, or one the entry's defining theme does not list, reaches an entry, or `variant` reaches a supplied component or the DOM. | `audit:Icon/behavior` |
+| FR7 | Theme styling tests for each size (pending) | each size with and without theme styles | A themed size does not change the glyph dimension, or an unstyled size changes. | `audit:Icon/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Icon/theming` |
Focused coverage for `data-color` on both glyph source modes is a checkable test
gap; source inspection is the current evidence for that part of FR2.