@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/HoverCard/HoverCard.spec.md

@@ -1,244 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:HoverCard
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/HoverCard/HoverCard.test.tsx,
-    packages/core/src/Layer/layerDismissalFamilies.test.tsx,
-    apps/storybook/stories/HoverCard.stories.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:overlay-dismissal]
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:layer-runtime,
-  ]
-contributing: []
-system_specs: []
----
-
-# HoverCard component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                       |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `HoverCard` with `children` (trigger), `content`, `label`, `placement` (`above`), `alignment` (`center`), `delay` (300), `hideDelay` (200), `focusTrigger`, `touchTrigger`, `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`.                                                                             |
-| Behavior                | A floating card of rich, possibly interactive content anchored to a trigger. It opens on hover after `delay`, on focus, and on a qualifying tap, stays open while the pointer is on the trigger or card, and closes on leave, Escape, or a tap outside. With `label` it is a named dialog the trigger advertises; without, a group that describes the trigger. |
-| End-user impact         | Mouse, keyboard, and touch users can open the preview, move into it to use its actions, and dismiss it; screen-reader users hear it as a named popup dialog or as the trigger's description.                                                                                                                                                                   |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                          |
-| Compatibility/readiness | Records shipped behavior; no public change. Seven implementation gaps (see Current-state impact).                                                                                                                                                                                                                                                              |
-| Review checks           | Reject an unnamed `dialog`, a card that cannot be hovered or dismissed (WCAG 1.4.13), Escape in the page that also closes a layer underneath, or `aria-expanded` set on a trigger whose role does not support it.                                                                                                                                              |
-| Governing rules         | WCAG 1.4.13; `family:overlay-dismissal`; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`.                                                                                                                                                                                                          |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-HoverCard previews more information about a trigger, such as a profile or a
-link summary, without navigating away. It owns the trigger wiring, when the
-card opens and closes for each input, the card's semantics, and its surface.
-Consumer usage lives in `HoverCard.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: uncontrolled by default; `isOpen` forces the
-  state, and a controlled card reports close requests through
-  `onOpenChange(false)` without closing itself (FR7)
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **A held-closed card still opens on focus.** With `isOpen={false}`, the hover
-  path stays shut but focus on the trigger opens the card, so a caller cannot
-  hold it closed. Escape then only reports `onOpenChange(false)`, which the
-  caller already holds, so the card stays until focus or the pointer leaves the
-  trigger or the card (FR7).
-- **Hover timing does not use the shared hover recognizer.** The card runs its
-  own show and hide timers. `architecture:interaction-modality` INV11 has
-  `useHoverCard` take its hover timing from the shared hover recognizer.
-- **A roving trigger may not open on focus.** Under `focusTrigger="auto"` the
-  card reads the tab order only when the trigger's listeners attach, so a
-  trigger rendered with `tabindex="-1"` opens only on mouse hover after it takes
-  keyboard focus, until a re-render re-attaches them. A focusable trigger
-  `auto` does not recognize, such as a `<summary>` or an SVG link, never opens
-  on focus. `architecture:interaction-modality` INV4 keeps hover from being the
-  only discovery path.
-- **A replaced trigger loses its wiring.** The card wires its trigger element
-  when it opens or closes, when `label` changes, or when its listeners
-  re-attach. A trigger element replaced after mount gets no popup attributes,
-  description, or hover and focus opening until one of those happens (FR2,
-  FR3).
-- **Escape cannot close a card in another document.** HoverCard listens for
-  Escape only in the page's document, so a card rendered into an iframe or a
-  Picture-in-Picture window with no layer beneath it is never closed by
-  Escape. WCAG 1.4.13 requires such content to be dismissible (FR6).
-- **The hold follows only the pointer.** The card stays open only while the
-  pointer is on the trigger or the card. A card opened by keyboard focus closes
-  once the pointer crosses the trigger and leaves, while the trigger keeps
-  focus, and a hover-opened card the user has tabbed into closes when the
-  pointer leaves the trigger, dropping focus to the page. WCAG 1.4.13 requires
-  content shown on focus to persist until focus moves or the user dismisses it.
-- **Mixed text children get no trigger.** Text children that reach React as
-  several strings, such as `Edited {when}`, have no element to attach to: no
-  focusable span or popup attributes are added, and hover and focus never open
-  the card (FR2).
-
-## Ownership boundary
-
-**Owns**
-
-- Trigger wiring, open and close behavior per input, card semantics, and the
-  `hover-card` surface (FR1–FR8).
-
-**Does not own / non-goals**
-
-- The trigger element and the card's body and actions — owned by the caller.
-- Layer hosting, positioning, and inline-safe portaling — owned by
-  `architecture:layer-runtime`; shared Escape ordering — owned by
-  `family:overlay-dismissal`.
-- The `useHoverCard` hook's public contract — an uncontracted module; this
-  record covers HoverCard's observable behavior.
-
-## Public concepts
-
-| Concept       | Closed values or states   | Meaning                                                                            | Availability by variant/orientation/state | Default | Owner                 | Stability | Invalid-value behavior           |
-| ------------- | ------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- | ------- | --------------------- | --------- | -------------------------------- |
-| Popup role    | named dialog, group       | `label` makes the card a named `dialog`; without it the card is a `group`.         | Every card.                               | group   | `component:HoverCard` | Stable    | Not applicable.                  |
-| Focus trigger | `auto`, `always`, `never` | Whether focus opens the card: on focusable triggers (FR4's gap), always, or never. | Every trigger.                            | `auto`  | `component:HoverCard` | Stable    | TypeScript rejects other values. |
-| Touch trigger | `auto`, `tap`, `none`     | Whether a tap opens it: unless the trigger performs its own action, always, never. | Touch without hover.                      | `auto`  | `component:HoverCard` | Stable    | TypeScript rejects other values. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                    |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | The open card is one surface carrying only the `hover-card` target, padded on every logical edge, with `content` inside and the theme's body font. `xstyle`, `className`, and `style` apply to the card.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests |
-| FR2 | Trigger wiring: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element inside an inline-safe wrapper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-| FR3 | With `label`, the card is `role="dialog"` named by `label`; the trigger gets `aria-haspopup="dialog"` and, only when its role supports it, `aria-expanded`, each replacing the trigger's own value while the card is wired, plus `aria-controls` naming the card while open, merged with the trigger's own; the trigger's own values return on cleanup. Without `label`, the card is `role="group"` and the trigger's `aria-describedby` gains the card's id.                                                                                                                                                                                                                                                                 | Current source and tests |
-| FR4 | On a hover-capable pointer, entering the trigger opens the card after `delay` ms; leaving the trigger or the card closes it after `hideDelay` ms, and moving between them keeps it open. Any focus on the trigger, keyboard, pointer, or programmatic, opens it per `focusTrigger`, except the focus a tap leaves behind, the refocus after an Escape dismiss (FR6), and the refocus after a controlled close (FR7). Implementation gap: under `auto` the tab order is read only when the trigger's listeners attach, on mount and on a re-render that re-attaches them, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | WCAG 1.4.13; tests       |
-| FR5 | On touch, a completed tap opens it per `touchTrigger` when the finger lifts; a touch that becomes a scroll does not. A tap on the card's own content keeps it open; a second tap on the trigger, a tap outside, or a scroll starting outside closes it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR6 | Escape closes a visible card through the shared dismissal stack when it is the topmost layer in the page, so a layer underneath stays open. Implementation gap: a card rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). When focus was inside the card, it returns to the trigger, and that refocus does not reopen the card.                                                                                                                                                                                                                                                                                     | WCAG 1.4.13; tests       |
-| FR7 | `isOpen` forces the card shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled card answers Escape by calling `onOpenChange(false)` without hiding, and setting `isOpen={false}` while focus is inside the card returns focus to the trigger. `isDefaultOpen` opens it on mount, still dismissible. Implementation gap: with `isOpen={false}`, focus on the trigger still opens the card, and Escape then only reports `onOpenChange(false)` (Current-state impact). `isEnabled={false}` disables the triggers. `onOpenChange` reports each show and hide.                                                                                                                                     | Current source and tests |
-| FR8 | Content renders only while open; server markup and the first client render match, including a default-open card. `hasHoverIndication` (`auto`: a single string or number child) adds a hover cue to the inline trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Content.** Any content, including interactive actions.
-- **AV2 — Theme styling.** Themes restyle `hover-card`.
-
-### Representative states
-
-| State               | Required invariant                             | Allowed variation |
-| ------------------- | ---------------------------------------------- | ----------------- |
-| Unlabelled          | `role="group"`; trigger described by the card. | Content.          |
-| Labelled            | Named `dialog`; trigger advertises the popup.  | Content.          |
-| Hover into card     | Stays open; actions usable.                    | Delays.           |
-| Escape from content | Closes; focus back on trigger; no reopen.      | —                 |
-| Tap-open            | Opens on lift; survives taps on its content.   | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Open state.** `isOpen`, then the input triggers, apart from FR7's
-  focus gap.
-
-### Performance and resources
-
-- **PR1 — Listeners.** An unchanged rerender does not rebind the trigger's
-  listeners; an element trigger rebinds them on each open and close, and any
-  trigger rebinds them when `onOpenChange` changes identity.
-
-## Accessibility contract
-
-- **AR1 — Popup semantics.** FR3.
-- **AR2 — Content on hover or focus.** FR4–FR6 keep the card hoverable,
-  dismissible, and persistent per WCAG 1.4.13, except FR6's other-document gap,
-  FR7's held-closed Escape gap, and the pointer-only hold (Current-state
-  impact).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                               | Representation authority       | Hierarchy role    | Component contract |
-| ---------------- | ------------------------------------------------ | ------------------------------ | ----------------- | ------------------ |
-| Trigger          | Caller element that opens the card.              | Caller content                 | Context-dependent | FR2                |
-| Card             | Padded floating surface anchored to the trigger. | Current source and public docs | Prominent         | FR1                |
-| Body             | Caller content inside the card.                  | Caller content                 | Prominent         | FR1                |
-| Actions          | Optional caller buttons inside the card.         | Caller content                 | Supporting        | FR4                |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Trigger": {
-    "none": {
-      "reason": "intentional: The trigger is the caller's element and carries its own component's target."
-    }
-  },
-  "Card": {"target": "hover-card"},
-  "Body": {"inherits": "hover-card"},
-  "Actions": {
-    "none": {
-      "reason": "intentional: Actions are caller-rendered controls that carry their own components' targets."
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-- `family:overlay-dismissal` owns Escape routing and topmost handling.
-- `architecture:layer-runtime` owns hosting, positioning, and portaling.
-- `architecture:interaction-modality` owns the focus modality FR4 uses and,
-  through INV11, the hover timing source for FR4.
-- `architecture:component-theming-surface` owns the `hover-card` target.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                       | Representative states                                    | Mutation or failure expectation                                                       | Audit section                   |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, FR2, FR8       | `HoverCard.test.tsx` render, wrapper, portal, theme font, and SSR tests                                                            | Text and element triggers; default open                  | A stray target, lost font, or hydration mismatch fails.                               | `audit:HoverCard/anatomy`       |
-| FR3, AR1            | `HoverCard.test.tsx` role and trigger-attribute tests                                                                              | Labelled and unlabelled; supported and unsupported roles | Wrong role, or trigger attributes that are not replaced and restored as stated, fail. | `audit:HoverCard/accessibility` |
-| FR4–FR6, AR2        | `HoverCard.test.tsx` hover, Escape, refocus, and touch tests                                                                       | Hover, focus, tap, Escape from trigger and content       | A card that cannot be reached or dismissed fails.                                     | `audit:HoverCard/behavior`      |
-| FR7                 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, and onOpenChange tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open                                   | Wrong state reporting fails.                                                          | `audit:HoverCard/behavior`      |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                      | Consumer anatomy and current target                      | Missing, extra, or stale mappings fail validation.                                    | `audit:HoverCard/theming`       |
-
-Read from source, with no focused test yet:
-
-- FR1: the card's padding, and `xstyle`, `className`, and `style` reaching it.
-- FR3: restoring the trigger's own attributes on unmount.
-- FR4: the `delay` and `hideDelay` timing, and moving between the trigger and
-  the card keeping it open.
-- FR7: `isOpen` forcing the card, and the focus return after a controlled
-  close.
-- FR8: `hasHoverIndication`.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, or layer-system
-rules. It links to their owners.

package/src/Icon/Icon.spec.md

@@ -1,244 +0,0 @@
----
-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/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: `yes` for explicit sizes and standalone Icons
-- Compatibility class: component-owned Icon slots may supply a contextual default;
-  explicit Icon sizes and the standalone `md` fallback remain unchanged
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: no consumer migration; omit `size` when 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.                                         |
-
-### 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 → standalone `md` fallback.
-- **ORD2 — Presentation.** Apply the target, resolved size, and component color
-  styles, then merge consumer `xstyle`, `className`, inline `style`, 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 `label` MUST 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
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Glyph": {"target": "icon"}
-}
-```
-
-## Family and system relationships
-
-- `architecture:component-size-cascade` owns the shared explicit → nearest
-  provider → component fallback pattern and requires provider ownership to be
-  declared. Icon retains its own `xsm | sm | md | lg` axis outside the standard
-  element-size cascade and adopts that precedence for component-owned defaults.
-- `architecture:component-theming-surface` owns the qualification and validation
-  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.
-  The Button family currently maps `sm` and `md` controls to `sm` Icons and `lg`
-  controls to `md` Icons.
-- 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` 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.
-
-## 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.