@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/Heading/Heading.spec.md

@@ -0,0 +1,198 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Heading
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    .github/visual-baseline/manifest.json,
+    packages/core/src/Heading/Heading.test.tsx,
+    packages/core/src/Text/useTruncation.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/theme/extensibleAxes.test.ts,
+    apps/storybook/stories/Heading.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-024]
+---
+
+# Heading component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A semantic heading with a required `level`, an optional theme-extensible visual `type`, `weight`, `accessibilityLevel`, and the shared text controls documented in `Heading.doc.mjs`.      |
+| Behavior                | `level` picks `h1`–`h6` and the default visual scale; `type` and `weight` change only appearance; `accessibilityLevel` sets `aria-level` when it differs.                                  |
+| End-user impact         | Screen-reader users navigate a document outline that matches the page's sections, whatever size each heading is drawn at.                                                                  |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                               |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                    |
+| Review checks           | Reject a visual `type` or `weight` that changes the element or level, a heading that renders without a level baseline, or a duplicate native tooltip for truncation.                       |
+| Governing rules         | `spec:AST-024` (custom visual types, weight precedence, unchanged accessibility); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Heading marks a section or page title with native heading semantics and themed
+type. It keeps the document outline (`level`, `accessibilityLevel`) separate
+from appearance (`type`, `weight`). Its consumer documentation lives in
+`Text/Heading.doc.mjs`, as a member of the Text documentation; this record is
+Heading's own contract.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Truncation tooltip not reachable by keyboard (FR4).** A truncated Heading
+  is not focusable, so Tooltip attaches no focus trigger and sighted keyboard
+  users cannot reveal the clipped text, where WCAG 2.2 2.1.1 expects
+  functionality to be keyboard operable. The full text stays in the DOM for
+  assistive technology.
+
+## Ownership boundary
+
+**Owns**
+
+- The `h1`–`h6` element, its `heading` theming target, and `aria-level`.
+- Level-based and built-in display-type sizing, weight defaults, color, and the
+  shared text layout controls on the heading element.
+- Measuring truncation and deciding when to compose the truncation Tooltip.
+
+**Does not own / non-goals**
+
+- Theme enrollment and generated declarations for custom visual types — owned
+  by `spec:AST-024` and the theme build.
+- Non-heading text — owned by `component:Text`.
+- The truncation tooltip surface, layer, and `tooltip` target — owned by
+  Tooltip.
+- Heading content — owned by the caller.
+
+## Public concepts
+
+| Concept             | Closed values or states                                             | Meaning                                                       | Availability by variant/orientation/state | Default               | Owner               | Stability | Invalid-value behavior                                                                             |
+| ------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- | --------------------- | ------------------- | --------- | -------------------------------------------------------------------------------------------------- |
+| Level               | 1–6                                                                 | Selects `h1`–`h6` and the level's visual scale.               | Always                                    | Required              | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
+| Visual type         | `display-1`, `display-2`, `display-3`; theme additions              | Replaces the level's visual scale without changing semantics. | Always                                    | unset                 | `component:Heading` | Stable    | A theme-added value is reflected on `heading` and keeps the level's baseline (`spec:AST-024` FR4). |
+| Weight              | `normal`, `medium`, `semibold`, `bold`                              | Overrides the type or level default weight.                   | Always                                    | type or level default | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
+| Accessibility level | 1–6                                                                 | The outline level exposed to assistive technology.            | Always                                    | `level`               | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
+| Truncation          | `maxLines` 0 (none), 1, or more; tooltip on, off, or at a placement | Clamps lines and offers the full text in a Tooltip.           | Always                                    | 0; tooltip on         | `component:Heading` | Stable    | —                                                                                                  |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | `level` renders `h1`–`h6`. `accessibilityLevel` adds `aria-level` only when it differs from `level`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
+| FR2 | The heading carries the `heading` target reflecting `level`, `color`, and any supplied `type` and `weight`. A built-in `type` applies its display scale and default weight; otherwise the level's scale applies. A theme-added `type` keeps the level's scale as its baseline. An explicit `weight` wins over the type and level defaults.                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
+| FR3 | `color` defaults to `primary`; a theme-added color keeps the primary baseline until a theme paints it. `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `block`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap` and `hasStrikethrough` apply their text treatments.                                                                                                                                                                                                                                                     | Current source and tests |
+| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the heading shows the full text at the given placement (default `above`); no native `title` is added. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the heading is not focusable (Current-state impact). | Current source and tests |
+| FR5 | `ref` reaches the heading element. Supported DOM, ARIA, data, and event props reach it after the derived `aria-level`, so a caller `aria-level` wins; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may restyle `heading` per `level`, `color`,
+  `type`, and `weight` without changing the element or level.
+- **AV2 — Visual reuse.** Any level may use any visual type.
+
+### Representative states
+
+| State                   | Required invariant                                             | Allowed variation |
+| ----------------------- | -------------------------------------------------------------- | ----------------- |
+| Level only              | `h{level}` at the level's scale.                               | Level.            |
+| Display type            | Same element; display scale and weight; `data-type` reflected. | Type.             |
+| Theme-added type        | Same element; level baseline; `data-type` reflected.           | Theme paint.      |
+| Accessibility override  | `aria-level` differs from the element's level.                 | —                 |
+| Truncated with tooltip  | Clamped heading anchors one Tooltip with the full text.        | Placement.        |
+| Truncation, tooltip off | Clamped heading; no measurement; no Tooltip.                   | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Weight.** Explicit `weight` → built-in type default → level default
+  (`spec:AST-024` FR8).
+- **ORD2 — Scale.** Built-in `type` → level scale (also the baseline for a
+  theme-added type).
+- **ORD3 — Display.** `hasCapsize` (`block`) → `maxLines` above 1 (line-clamp
+  box) → `maxLines={1}` (`block`) → `display` prop.
+
+### Performance and resources
+
+- **PR1 — Measured only when needed.** Truncation is measured only when
+  `maxLines` is positive and the tooltip is enabled; re-measuring follows size
+  and content changes without a per-heading observer; the Tooltip module loads
+  only when the text is truncated.
+
+## Accessibility contract
+
+- **AR1 — Native heading.** The element is a native `h1`–`h6`; a visual type or
+  weight never changes the role, level, or name (`spec:AST-024` FR15).
+- **AR2 — Outline override.** `accessibilityLevel` exposes a different outline
+  level through `aria-level` without changing the element.
+- **AR3 — Truncated text.** The full text stays in the heading's DOM; the
+  truncation Tooltip is the only tooltip, and any description it adds is
+  Tooltip's.
+
+## Design relationships
+
+| Anatomy or state   | Design requirement                                      | Representation authority | Hierarchy role | Component contract |
+| ------------------ | ------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Heading            | A section or page title at the level's or type's scale. | Current source and docs  | Prominent      | FR1–FR3, AR1, AR2  |
+| Truncation tooltip | The full text when the heading is clamped.              | Tooltip                  | Supporting     | FR4, AR3           |
+
+Theming: the heading element is the single `heading` target. Its consumer
+documentation is a member of `Text/Heading.doc.mjs` and lists no anatomy, so no
+anatomy-theming block is declared; the truncation tooltip's target belongs to
+Tooltip.
+
+## Family and system relationships
+
+- `spec:AST-024` owns custom visual types, weight precedence, and the rule that
+  visual changes leave accessibility unchanged; FR2, ORD1, and AR1 apply it.
+- `component:Text` shares Heading's type styles and truncation mechanism.
+- `architecture:component-theming-surface` sets the rules the `heading` target
+  follows (INV6) and qualifies `type` as a theme-extensible axis (INV14).
+
+## Verification map
+
+| Contract | Verification                                                                                                | Representative states                     | Mutation or failure expectation                                                                                                                                                                                                                                                    | Audit section            |
+| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, AR2 | `Heading.test.tsx` level and `accessibilityLevel` tests                                                     | Levels 1–6; differing override            | A wrong element, or a missing `aria-level` for a differing override, fails. Gap: no test asserts that an equal `accessibilityLevel` adds no `aria-level`.                                                                                                                          | `audit:Heading/a11y`     |
+| FR2      | `Heading.test.tsx` target, type, theme-added type, weight, and omitted-type tests; `extensibleAxes.test.ts` | Display types, theme-added type, weight   | A lost `heading` class or `data-level`, `data-color`, `data-type`, or `data-weight` reflection, a reflected omitted type, or a theme-added type losing its level baseline fails. Gap: the display scales, default weights, and weight precedence in paint have no automated check. | `audit:Heading/theming`  |
+| FR3      | Stable visual baseline `core-heading--level-1`; `Heading.stories.tsx`                                       | Level 1 default                           | A changed level-1 scale, color, or display comes back changed for review. Gap: the prop tests assert presence only, so color paint, `display` precedence, `justify`, `textWrap`, cap-height trim, strikethrough, and the theme-added color baseline have no automated check.       | `audit:Heading/behavior` |
+| FR4, PR1 | `Heading.test.tsx` truncation-measurement tests; `useTruncation.test.tsx`                                   | Tooltip on and off; content change        | Measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check.                                                            | `audit:Heading/behavior` |
+| FR5      | `Heading.test.tsx` ref, `id`, and passthrough tests                                                         | Rerender; `id`; `data-testid`             | A detached ref, a lost `id`, or a lost test id fails. Gap: no test covers a caller `aria-level` winning, the styling-input merge order, or the line clamp after `style`.                                                                                                           | `audit:Heading/behavior` |
+| AR1      | `Heading.test.tsx` display-type element tests                                                               | Levels with display and theme-added types | A visual type that changes the element fails.                                                                                                                                                                                                                                      | `audit:Heading/a11y`     |
+| AR3      | Source review                                                                                               | Truncated heading                         | Gap: no Heading test asserts the absence of a native `title`.                                                                                                                                                                                                                      | `audit:Heading/a11y`     |
+| AR1, AR2 | Accessibility-tree evidence (`spec:AST-009` FR3)                                                            | Levels, override, display types           | Gap: no accessibility-tree check proves the heading role and level; the unit tests query the DOM.                                                                                                                                                                                  | `audit:Heading/a11y`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/HoverCard/HoverCard.test.tsx

@@ -1049,7 +1049,11 @@ describe('HoverCard', () => {
       __resetInteractionModalityForTest();
     });
 
-    /** A tap: the pointer sequence a finger produces before hover is faked. */
+    /**
+     * A tap, in the order a browser dispatches it: the finger's pointer events,
+     * then the hover it synthesizes, then the `click` that says the touch was a
+     * tap and not the start of a scroll.
+     */
     const tap = (element: HTMLElement) => {
       // A finger's arrival fires pointerenter too, and that is the path a pen
       // must not take — cover it here rather than starting at pointerdown.
@@ -1058,6 +1062,7 @@ describe('HoverCard', () => {
       fireEvent.pointerUp(element, {pointerType: 'touch'});
       // Touch synthesizes hover after the press; the card must not act on it.
       fireEvent.mouseEnter(element);
+      fireEvent.click(element);
     };
 
     it('opens on a tap when the trigger performs no action', async () => {
@@ -1141,6 +1146,8 @@ describe('HoverCard', () => {
         hidden: true,
       });
       fireEvent.pointerDown(action, {pointerType: 'touch'});
+      fireEvent.pointerUp(action, {pointerType: 'touch'});
+      fireEvent.click(action);
 
       await new Promise(resolve => setTimeout(resolve, 50));
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
@@ -1166,10 +1173,93 @@ describe('HoverCard', () => {
         expect(onOpenChange).toHaveBeenCalledWith(true);
       });
 
-      fireEvent.pointerDown(screen.getByRole('button', {name: 'Elsewhere'}), {
-        pointerType: 'touch',
+      const elsewhere = screen.getByRole('button', {name: 'Elsewhere'});
+      fireEvent.pointerDown(elsewhere, {pointerType: 'touch'});
+      // Not yet: a popover closes when the outside tap lifts.
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+      fireEvent.pointerUp(elsewhere, {pointerType: 'touch'});
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('opens when the finger lifts, not when it lands', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByText('Ruby Cheung');
+      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
+      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalled();
+
+      fireEvent.pointerUp(trigger, {pointerType: 'touch'});
+      fireEvent.click(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('never opens for a touch that turns into a scroll', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByText('Ruby Cheung');
+      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
+      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
+      fireEvent.pointerCancel(trigger, {pointerType: 'touch'});
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+
+    it('closes when a scroll starts outside, but not for one inside the card', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <>
+          <HoverCard
+            content={<p>Card content</p>}
+            onOpenChange={onOpenChange}
+            delay={0}
+            hideDelay={0}>
+            Ruby Cheung
+          </HoverCard>
+          <p>Page content</p>
+        </>,
+      );
+
+      tap(screen.getByText('Ruby Cheung'));
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
       });
+      onOpenChange.mockClear();
+
+      // Scrolling the card's own content keeps it.
+      const inside = await screen.findByText('Card content');
+      fireEvent.pointerDown(inside, {pointerType: 'touch'});
+      fireEvent.pointerCancel(inside, {pointerType: 'touch'});
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
 
+      const page = screen.getByText('Page content');
+      fireEvent.pointerDown(page, {pointerType: 'touch'});
+      fireEvent.pointerCancel(page, {pointerType: 'touch'});
       await waitFor(() => {
         expect(onOpenChange).toHaveBeenCalledWith(false);
       });

package/src/Icon/Icon.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
+      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
       description: 'Color variant mapped to Astryx icon color tokens.',
       default: "'inherit'",
     },
@@ -86,7 +86,7 @@ export const docs = {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
       description:
-        'Icon size. An explicit value wins. When omitted, Icon uses the nearest default supplied by an owning Astryx component for its icon slot, then falls back to md when no contextual default exists.',
+        "Icon size. xsm, sm, md, and lg are 12, 16, 20, and 24px at a 16px root and scale with the root font size; a theme sets a size's glyph dimension with width and height, in px or rem, on components.icon['size:sm'] (and the other sizes). An explicit value wins. When omitted, Icon uses the nearest default supplied by an owning Astryx component for its icon slot, then falls back to md when no contextual default exists.",
       default: "Contextual; otherwise 'md'",
     },
     {
@@ -104,6 +104,26 @@ export const docs = {
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
+    vars: [
+      {
+        name: '--_icon-width',
+        description:
+          'Glyph width for the size; set by width on the icon target',
+        default: '0.75rem, 1rem, 1.25rem, or 1.5rem by size',
+        private: true,
+      },
+      {
+        name: '--_icon-height',
+        description:
+          'Glyph height for the size; set by height on the icon target',
+        default: '0.75rem, 1rem, 1.25rem, or 1.5rem by size',
+        private: true,
+      },
+    ],
+    derived: [
+      {property: 'width', vars: ['--_icon-width'], replaces: true},
+      {property: 'height', vars: ['--_icon-height'], replaces: true},
+    ],
   },
   usage: {
     description:
@@ -120,6 +140,11 @@ export const docs = {
         description:
           "Override icons through the theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>, and extends shallow-merges it into derived themes. registerIcons() mutates a process-wide registry and warns in dev, so keep it for app bootstrap rather than making it a library's theming seam.",
       },
+      {
+        guidance: true,
+        description:
+          "To match artwork to the rendered size, make a theme or registered icon entry a pure, synchronous function of {size, variant}: defineTheme({icons: {info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />}}). Icon passes the size it renders at; getIcon(), useIcon(), getIconRegistry() and theme.icons read the function at size md. A function that returns null draws nothing instead of falling back to the default icon. Do not use hooks, measure the DOM, or read browser or mutable state inside it.",
+      },
       {
         guidance: true,
         description:
@@ -183,7 +208,7 @@ export const docsZh = {
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
+      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
       description: '映射到 Astryx 图标颜色令牌的颜色变体。',
       default: "'inherit'",
     },
@@ -191,7 +216,7 @@ export const docsZh = {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg'",
       description:
-        '图标尺寸。显式值优先。省略时，Icon 使用最近的 Astryx 所属组件为其图标槽提供的默认尺寸；如果没有上下文默认值，则回退为 md。',
+        "图标尺寸。xsm、sm、md、lg 在 16px 根字号下分别为 12、16、20、24px，并随根字号缩放；主题在 components.icon['size:sm']（及其他尺寸）上以 px 或 rem 设置 width 和 height，即可决定该尺寸的图标尺寸。显式值优先。省略时，Icon 使用最近的 Astryx 所属组件为其图标槽提供的默认尺寸；如果没有上下文默认值，则回退为 md。",
       default: "上下文默认值；否则为 'md'",
     },
     {
@@ -209,6 +234,24 @@ export const docsZh = {
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
+    vars: [
+      {
+        name: '--_icon-width',
+        description: '该尺寸的图标宽度；由 icon 目标上的 width 设置',
+        default: '按尺寸为 0.75rem、1rem、1.25rem 或 1.5rem',
+        private: true,
+      },
+      {
+        name: '--_icon-height',
+        description: '该尺寸的图标高度；由 icon 目标上的 height 设置',
+        default: '按尺寸为 0.75rem、1rem、1.25rem 或 1.5rem',
+        private: true,
+      },
+    ],
+    derived: [
+      {property: 'width', vars: ['--_icon-width'], replaces: true},
+      {property: 'height', vars: ['--_icon-height'], replaces: true},
+    ],
   },
   usage: {
     description:
@@ -282,6 +325,11 @@ export const docsDense = {
         description:
           'Override icons via theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>; extends shallow-merges into derived themes. registerIcons() mutates a global registry and warns in dev: app bootstrap only, not a library theming seam.',
       },
+      {
+        guidance: true,
+        description:
+          "Size-aware artwork: a theme/registered entry may be a pure sync function of {size, variant}, e.g. info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />. Icon passes its rendered size; getIcon/useIcon/getIconRegistry/theme.icons read it at md. A null result draws nothing (no fallback). No hooks, DOM measurement, or browser/mutable state.",
+      },
       {
         guidance: true,
         description:
@@ -332,7 +380,7 @@ export const docsDense = {
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
-    size: "explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
+    size: "xsm/sm/md/lg = 12/16/20/24px at a 16px root, scale w/ root font size; theme sets a size's glyph dimension via width + height (px or rem) on components.icon['size:sm'] etc. Explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
     label:
       'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
     xstyle:

package/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.