An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 3 kind: component id: component:Icon authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-08-30 owners: [cixzhang, imdreamrunner] review_triggers: [public-api, behavior, theming, accessibility] verified_by: [ packages/core/src/Icon/Icon.test.tsx, packages/core/src/Icon/tests/IconAudit.a11y.chromium.spec.ts, packages/core/src/IconButton/IconButton.test.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-size-cascade, architecture:component-theming-surface, architecture:icon-resolution-and-component-slots, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-087]
Icon component contract
Intent
Icon presents one visual symbol with consistent size, color, and accessibility
semantics. Consumer usage remains documented in Icon.doc.mjs.
Compatibility and migration
- Released default preserved:
yesfor explicit sizes and standalone Icons - Compatibility class: component-owned Icon slots may supply a contextual default;
explicit Icon sizes and the standalone
mdfallback remain unchanged - Controlled/uncontrolled behavior: not applicable
- Migration decision: no consumer migration; omit
sizewhen the owning Astryx component should select the contextual default
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
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.
Does not own / non-goals
- The shared registry's key-resolution and fallback order — owned by the shared icon system.
- Which contextual default an owning Astryx component selects for its icon slot — owned by that component or family contract.
- The meaning of a glyph in product context or whether nearby text makes it decorative — owned by the product callsite.
- Interaction, focus, or control naming — owned by the interactive parent.
- The artwork supplied by a consumer or registered through a theme.
- A public Icon size-provider API; contextual transport is implementation detail.
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. |
| 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.
Behavioral and layout contract
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. |
| 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. |
| FR8 | ref reaches the svg the resolved glyph renders, for every name; when the glyph renders no svg, ref is null. A glyph that later replaces its own svg is not followed. |
Consistency with Icon's public ref type, Ref<SVGSVGElement>; defect fix. |
Settled intent. |
Allowed variation
- AV1 — Artwork. The path, view box, and internal structure may vary by icon source or theme without changing Icon's one-part consumer anatomy.
- AV2 — Rendering strategy. Icon may render a supplied icon component directly or use an internal wrapper for a resolved key; neither element shape is public anatomy.
- AV3 — Theme and consumer styling. Existing theme and styling escape hatches may change visual CSS properties without changing glyph ownership.
- AV4 — Contextual mapping. An owning Astryx component may map its own public size or variant to an Icon default. That mapping belongs to the owner and MUST preserve explicit Icon sizes and the standalone fallback.
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. |
| 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
- ORD1 — Size resolution. Resolve explicit Icon
size→ nearest component-owned contextual default → standalonemdfallback. - ORD2 — Presentation. Apply the target, resolved size, and component color
styles, then merge consumer
xstyle,className, inlinestyle, and supported pass-through props in their established order.
Performance and resources
- PR1 — Render work. Icon owns no listeners, observers, or layout measurement; semantic and size resolution are synchronous during render.
Accessibility contract
- AR1 — Decorative default. Without a non-empty
label, Icon MUST hide its glyph from assistive technology by default. - AR2 — Meaningful glyph. A non-empty
labelMUST expose the glyph as an image with that accessible name. - AR3 — Parent-owned interaction. Icon MUST NOT add interactive semantics or focus behavior; an interactive parent owns the control and its name.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Glyph | Carries the resolved visual symbol at the resolved size and color. | Consumer or registry selects artwork; Icon owns presentation. | Context-dependent | FR1, FR2, FR3, FR5 |
Glyph is the single conceptual consumer part in both source modes. Current
implementation may render a supplied icon component directly or place a
registry-resolved icon in an internal wrapper; this contract intentionally does
not promise a span, svg, or other element type.
Theming anatomy
{
"Glyph": {"target": "icon"}
}
Family and system relationships
architecture:component-size-cascadeowns the shared explicit → nearest provider → component fallback pattern and requires provider ownership to be declared. Icon retains its ownxsm | sm | md | lgaxis outside the standard element-size cascade and adopts that precedence for component-owned defaults.architecture:component-theming-surfaceowns the qualification and validation rules for theicontarget.architecture:icon-resolution-and-component-slotsowns semantic-key and component-slot resolution before Icon renders the selected source.spec:AST-087decides thevariantrequest, theme-listed variant names, and theme-set size dimensions.architecture:public-component-apiowns admission and compatibility rules for Icon's public props and observable defaults.- The owning component or family specifies each contextual Icon-size mapping.
The Button family currently maps
smandmdcontrols tosmIcons andlgcontrols tomdIcons. - Icon has no current family contract.
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 theming-target reflection and styling-prop suites |
both source modes; every color and size; omitted color; className, style, and xstyle |
Removing the target, dropping data-color or data-size in either mode, or breaking override composition fails assertions. |
audit:Icon/theming |
| FR2, FR3 (rendered) | IconAudit.a11y.chromium.spec.ts sensor receipts |
semantic key and icon component; every size and color; Neutral and Butter in light and dark; right-to-left; 320px | A glyph without its target data, a color that does not paint its token, sizes that do not step 12, 16, 20, and 24px at the Neutral theme, registry artwork that does not fill its box, or a transformed glyph fails a receipt. | audit:Icon/theming |
| AR1, AR2, AR3 | Icon.test.tsx accessible-name suites and the IconAudit.a11y.chromium.spec.ts accessible-name receipts |
decorative, labelled, explicit ARIA override; labelled icon component that writes its own aria-hidden |
Changing default or labelled semantics, or leaving a component's own aria-hidden on a labelled glyph, fails accessibility assertions. |
audit:Icon/accessibility |
| FR6 | Icon.test.tsx variant suite |
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 | Icon.test.tsx theme size dimension suite |
each size with and without theme styles, both source modes | A themed size does not change the glyph dimension, or an unstyled size changes. | audit:Icon/theming |
| FR8 | Icon.test.tsx "ref reaches the rendered svg for every name" suite |
icon component; semantic name; namespaced key; text glyph; glyph change (component to component, svg to text); function entry across rerenders; unmount | A ref that stays empty, or holds anything but the rendered <svg>, for any name kind fails; so do a non-null ref for a text glyph, a ref left on a replaced glyph, a ref re-attached on every rerender, and a ref left set after unmount. |
audit:Icon/ref |
| 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 |
Decision log
DEC-1 — One conceptual Glyph across source modes
Reference: component:Icon/DEC-1
Decider: cixzhang, 2026-08-30
Consumers theme and reason about one visual symbol regardless of whether it
comes from a semantic key or a supplied component. Glyph therefore maps to the
existing icon target without freezing either mode's current element shape.
Icon applies width and height for every source and adds font size where a 1em-
based source needs it. This preserves one consistent icon box without promising
a span, svg, or other element.
Rejected: separate wrapper and SVG anatomy entries, because those describe implementation strategies rather than stable consumer concepts.
DEC-2 — Owning components may provide contextual Icon defaults
Reference: component:Icon/DEC-2
Decider: cixzhang, 2026-09-23
A person should see an icon that is proportionate to the Astryx component that
owns its slot without every caller repeating a size. The owning component may
therefore provide the default while an explicit Icon size remains authoritative
and a standalone Icon remains md. Provider objects, hooks, and context shape
remain private implementation details rather than public API.
Rejected: an unconditional md default inside every composition, forcing every
caller to repeat the owner-derived size, and exposing the provider mechanism as
public API.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or system rules. It links to their owners.