@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Icon/globalIconRegistry.tsx

@@ -2,16 +2,29 @@
 
 /**
  * @file globalIconRegistry.tsx
- * @input None (pure module-level state)
- * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, IconName, IconRegistry
+ * @input Theme icon entries (a DefinedTheme or a registered theme name), the
+ *   process-wide registry, and built-in defaults
+ * @output Exports registerIcons, getIconRegistry, getIcon, getExtendedIcon,
+ *   resetIcons, resolveIcon (internal), IconName, IconRegistry, IconEntry,
+ *   IconRequest
  * @position Global and theme-scoped icon registry; works in server and client environments
  *
  * This module has NO 'use client' directive — it's importable from RSC.
  * Components resolve semantic icons through getIcon() or the client useIcon() hook.
+ *
+ * An entry is a React node or a pure synchronous function of an
+ * {@link IconRequest}. Resolution picks one source — theme entry, then
+ * process-wide registration, then built-in default; a nullish static entry
+ * falls through — and a selected function's result is final. `Icon` passes
+ * its resolved size and a variant the entry can receive (listed by the active
+ * theme and, for a theme entry, by the theme that defined it), otherwise
+ * `undefined`; the public reads below pass `{size: 'md'}`.
  */
 
 import type {ReactNode} from 'react';
 import {defaultIcons} from './defaultIcons';
+import type {IconSize} from './IconSize.stylex';
+import type {IconVariant} from './index';
 import type {DefinedTheme} from '../theme/defineTheme';
 import {getRegisteredTheme} from '../theme/themeRegistry';
 import {warnOnce} from '../utils/devWarning';
@@ -88,13 +101,57 @@ export type ExtendedIconName = IconName | (string & {});
  */
 export type IconRegistry = Record<IconName, ReactNode>;
 
+/**
+ * What `Icon` asks a function icon entry for: the final Icon size, resolved
+ * explicit `size` → owning component's default → `'md'`, and a variant name
+ * or `undefined`.
+ *
+ * Inside `defineTheme`, `Variant` is the theme's listed `iconVariants`; a
+ * process-wide registration receives {@link IconVariant}.
+ */
+export type IconRequest<Variant extends string = IconVariant> = Readonly<{
+  size: IconSize;
+  variant?: Variant;
+}>;
+
+/**
+ * A theme or process-wide icon entry: a React node, or a pure synchronous
+ * function of the {@link IconRequest} that returns one.
+ *
+ * A function computes its result from the request only — no hooks, DOM or
+ * SVG measurement, browser globals, network access, mutable module state, or
+ * side effects. Once selected, its result is final: returning `null` or
+ * `undefined` renders no glyph instead of falling through to another source.
+ *
+ * @example
+ * ```
+ * defineTheme({
+ *   name: 'brand',
+ *   icons: {
+ *     info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />,
+ *   },
+ * });
+ * ```
+ */
+export type IconEntry<Variant extends string = IconVariant> =
+  ReactNode | ((request: IconRequest<Variant>) => ReactNode);
+
+/**
+ * How resolution holds any entry: an entry typed for some variant names
+ * accepts a request with none of them.
+ */
+type StoredIconEntry = IconEntry<never>;
+
 export type IconRegistrySource = DefinedTheme | string | null | undefined;
 
+/** The request every public, one-argument read uses. */
+const PUBLIC_READ_REQUEST: IconRequest<never> = {size: 'md'};
+
 // =============================================================================
 // Global Registry
 // =============================================================================
 
-let globalRegistry: Record<string, ReactNode> = {};
+let globalRegistry: Record<string, StoredIconEntry> = {};
 
 /**
  * A key is namespaced when it carries a `<namespace>:` prefix — the runtime
@@ -106,18 +163,105 @@ function isNamespacedKey(name: string): boolean {
   return name.includes(':');
 }
 
-function getThemeIconOverrides(
-  source: IconRegistrySource,
-): Partial<Record<IconName | NamespacedIconName, ReactNode>> | null {
-  if (source == null) {
+function getTheme(source: IconRegistrySource): DefinedTheme | null {
+  return typeof source === 'string'
+    ? getRegisteredTheme(source)
+    : (source ?? null);
+}
+
+/**
+ * The theme's icon entries, functions included. A theme from `defineTheme`
+ * keeps them in `__icons` when any entry is a function (its public `icons`
+ * is the node view); otherwise `icons` already holds them.
+ */
+function getThemeIconEntries(
+  theme: DefinedTheme | null,
+): Readonly<Record<string, StoredIconEntry>> | null {
+  if (theme == null) {
     return null;
   }
+  return theme.__icons ?? theme.icons ?? null;
+}
 
-  if (typeof source === 'string') {
-    return getRegisteredTheme(source)?.icons ?? null;
+/**
+ * The selected entry, with every variant list a requested variant must be in
+ * for the entry to receive it. No lists: the entry receives no variant.
+ */
+interface IconSelection {
+  entry: StoredIconEntry;
+  variantLists: ReadonlyArray<ReadonlyArray<string> | undefined>;
+}
+
+/**
+ * Pick the one source that answers `name`: the theme entry, then the
+ * process-wide registration, then the built-in default, then `fallback`. A
+ * nullish static entry falls through; a function is returned as-is, because
+ * its result is final.
+ *
+ * A theme entry may receive a variant listed by the active theme and by the
+ * theme that defined the entry (an inherited entry keeps its defining
+ * theme's list). A process-wide registration may receive a variant the
+ * active theme lists.
+ */
+function selectIconEntry(
+  name: string,
+  source: IconRegistrySource,
+  fallback?: ReactNode,
+): IconSelection {
+  const theme = getTheme(source);
+  const activeVariants = theme?.iconVariants;
+  const themeEntry = getThemeIconEntries(theme)?.[name];
+  if (theme != null && themeEntry != null) {
+    const definingVariants =
+      theme.__iconEntryVariants != null &&
+      Object.hasOwn(theme.__iconEntryVariants, name)
+        ? theme.__iconEntryVariants[name]
+        : activeVariants;
+    return {
+      entry: themeEntry,
+      variantLists: [activeVariants, definingVariants],
+    };
+  }
+  const globalEntry = globalRegistry[name];
+  if (globalEntry != null) {
+    return {entry: globalEntry, variantLists: [activeVariants]};
+  }
+  return {entry: defaultIcons[name as IconName] ?? fallback, variantLists: []};
+}
+
+/**
+ * Read a selected entry for a request: call a function, return a node as-is.
+ * The function receives the requested variant only when every list of the
+ * selection contains it; otherwise it receives `undefined`.
+ */
+function readIconEntry(
+  {entry, variantLists}: IconSelection,
+  {size, variant}: IconRequest<string>,
+): ReactNode {
+  if (typeof entry !== 'function') {
+    return entry;
   }
+  const receivable =
+    variant !== undefined &&
+    variantLists.length > 0 &&
+    variantLists.every(list => list?.includes(variant) === true);
+  // A receivable variant is one the entry's theme lists, which is the type
+  // the entry was written against.
+  return entry((receivable ? {size, variant} : {size}) as IconRequest<never>);
+}
 
-  return source.icons ?? null;
+/**
+ * Resolve a key for an Icon request. `Icon` is the caller: it passes the size
+ * it resolved and the variant it was asked for. Public reads use
+ * {@link getIcon} instead.
+ * @internal
+ */
+export function resolveIcon(
+  name: ExtendedIconName,
+  source: IconRegistrySource,
+  request: IconRequest<string>,
+): ReactNode {
+  return readIconEntry(selectIconEntry(name, source), request);
 }
 
 /**
@@ -142,9 +286,16 @@ function getThemeIconOverrides(
  * ```
  * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
  * ```
+ *
+ * An entry may also be a pure synchronous function of `{size, variant}`
+ * ({@link IconEntry}); `Icon` passes it the size it renders at.
+ * @example
+ * ```
+ * registerIcons({ info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} /> });
+ * ```
  */
 export function registerIcons(
-  icons: Partial<Record<ExtendedIconName, ReactNode>>,
+  icons: Partial<Record<ExtendedIconName, IconEntry>>,
 ): void {
   warnOnce(
     'icon-registry:global-register-icons',
@@ -161,6 +312,9 @@ export function registerIcons(
  * Works in both server and client environments. Useful for tooling that needs
  * to derive valid semantic icon-name options from the same registry Icon
  * resolves against.
+ *
+ * Every value is a React node: a function entry is read at `{size: 'md'}`,
+ * exactly as {@link getIcon} reads it.
  */
 export function getIconRegistry(
   source?: IconRegistrySource,
@@ -171,21 +325,18 @@ export function getIconRegistry(
   // contributed by a library or shipped as a component's own default, are
   // resolved via getIcon/getExtendedIcon and intentionally kept out of the
   // typed IconRegistry snapshot.
-  for (const name of Object.keys(defaultIcons) as IconName[]) {
+  const names = new Set(Object.keys(defaultIcons));
+  for (const name of Object.keys(getThemeIconEntries(getTheme(source)) ?? {})) {
+    names.add(name);
+  }
+  for (const name of names) {
     if (isNamespacedKey(name)) {
       continue;
     }
-    registry[name] = globalRegistry[name] ?? defaultIcons[name];
-  }
-
-  const themeIcons = getThemeIconOverrides(source);
-  if (themeIcons != null) {
-    for (const name of Object.keys(themeIcons) as IconName[]) {
-      if (isNamespacedKey(name)) {
-        continue;
-      }
-      registry[name] = themeIcons[name] ?? registry[name];
-    }
+    registry[name] = readIconEntry(
+      selectIconEntry(name, source),
+      PUBLIC_READ_REQUEST,
+    );
   }
 
   return registry as Record<IconName, ReactNode>;
@@ -201,17 +352,15 @@ export function getIconRegistry(
  * {@link IconName}s — useful for library-contributed icons. For a
  * caller-supplied fallback when a key isn't registered, use
  * {@link getExtendedIcon}.
+ *
+ * Returns a React node: a function entry is read at `{size: 'md'}`. Render
+ * `<Icon icon={name} />` to request another size.
  */
 export function getIcon(
   name: ExtendedIconName,
   source?: IconRegistrySource,
 ): ReactNode {
-  const themeIcons = getThemeIconOverrides(source);
-  return (
-    themeIcons?.[name as IconName] ??
-    globalRegistry[name] ??
-    defaultIcons[name as IconName]
-  );
+  return readIconEntry(selectIconEntry(name, source), PUBLIC_READ_REQUEST);
 }
 
 /**
@@ -224,7 +373,9 @@ export function getIcon(
  * widen the core {@link IconName} union.
  *
  * The `fallback` is the library default, overridable by a theme registering the
- * same key (for example `'richtext:bold'`).
+ * same key (for example `'richtext:bold'`). A function entry is read at
+ * `{size: 'md'}`, and its result is final: a nullish result does not fall
+ * back.
  * @example
  * ```
  * getExtendedIcon('richtext:bold', <BoldGlyph />)
@@ -235,12 +386,9 @@ export function getExtendedIcon(
   fallback?: ReactNode,
   source?: IconRegistrySource,
 ): ReactNode {
-  const themeIcons = getThemeIconOverrides(source);
-  return (
-    themeIcons?.[name as IconName] ??
-    globalRegistry[name] ??
-    defaultIcons[name as IconName] ??
-    fallback
+  return readIconEntry(
+    selectIconEntry(name, source, fallback),
+    PUBLIC_READ_REQUEST,
   );
 }
 

package/src/Icon/index.ts

@@ -5,12 +5,38 @@
 /**
  * @file index.ts
  * @input Imports Icon component/types, icon registry, and global registration
- * @output Exports Icon, icon registry helpers, registerIcons, getIconRegistry, getIcon
+ * @output Exports Icon, icon registry helpers, registerIcons, getIconRegistry, getIcon,
+ *   the IconEntry/IconRequest types for theme and registered entries, and the
+ *   augmentable IconVariantMap with its IconVariant names
  * @position Component entry point; re-exported by /packages/core/src/index.ts
  *
  * SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs
  */
 
+/**
+ * Icon variant names an application uses. Astryx defines none: a theme lists
+ * the names it supports in `defineTheme({iconVariants})`, and an application
+ * augments this map with the names it requests.
+ *
+ * A theme icon entry receives a requested variant only when the active theme
+ * lists it; any other request renders the entry's normal artwork.
+ *
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Icon' {
+ *   interface IconVariantMap {
+ *     outline: true;
+ *     filled: true;
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentation point
+export interface IconVariantMap {}
+
+/** A variant name from the augmentable {@link IconVariantMap}. */
+export type IconVariant = keyof IconVariantMap & string;
+
 export {Icon, renderIconSlot} from './Icon';
 export {useIcon} from './useIcon';
 export type {IconProps, IconColor, IconSize, IconType} from './Icon';
@@ -29,4 +55,6 @@ export type {
   NamespacedIconName,
   IconRegistry,
   IconRegistrySource,
+  IconEntry,
+  IconRequest,
 } from './globalIconRegistry';

package/src/Icon/useIcon.ts

@@ -5,7 +5,8 @@
 /**
  * @file useIcon.ts
  * @input Semantic icon name
- * @output Exports useIcon hook for theme-aware icon lookup
+ * @output Exports useIcon hook for theme-aware icon lookup (node-valued; a
+ *   function entry is read at `{size: 'md'}`)
  * @position Client hook for components that render registry icons directly
  */
 
@@ -23,6 +24,9 @@ import {
  *
  * Accepts a namespaced extension key (`'richtext:bold'`) as well as a built-in
  * name; both resolve through the same registry.
+ *
+ * Returns a React node: a function entry is read at `{size: 'md'}`. Render
+ * `<Icon icon={name} />` to resolve the entry at another size.
  */
 export function useIcon(name: IconName | NamespacedIconName): ReactNode {
   const themeName = useThemeName();

package/src/IconButton/IconButton.spec.md

@@ -0,0 +1,197 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:IconButton
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, accessibility]
+verified_by:
+  [
+    packages/core/src/IconButton/IconButton.test.tsx,
+    packages/core/src/Button/__tests__/Button.a11y.test.tsx,
+    packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts,
+  ]
+modules: []
+families: [family:buttons]
+design_specs: [design:reduced-motion]
+architecture:
+  [architecture:component-size-cascade, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-085]
+---
+
+# IconButton component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                  |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. IconButton takes Button's props without `isIconOnly`, `children`, and `endContent`, and requires `icon`.                                                                                    |
+| Behavior                | IconButton always renders Button's icon-only mode: a button, square by default, named by `label` through `aria-label`, with no visible text. Every other behavior is Button's.                            |
+| End-user impact         | People see a compact, square-by-default action with the same feedback as any Button. Screen-reader users hear `label`. Sighted users get a visible hint only when the caller adds one.                    |
+| Builder impact          | None.                                                                                                                                                                                                     |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Button's disabled-focusability, reduced-motion, and self-colored-content gaps apply unchanged; all three are listed under Current-state impact. |
+| Review checks           | Reject an IconButton that renders visible label text or end content, is not square with the default aspect and no `width`, loses its `aria-label`, or behaves differently from Button's icon-only mode.   |
+| Governing rules         | `family:buttons` FR1, FR7, AV2, AV6; `component:Button`; `spec:AST-085` FR1, FR4; `design:reduced-motion` DR1, DR3; `architecture:component-size-cascade`; `architecture:public-component-api`.           |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+IconButton is the explicit icon-only projection of Button that
+`family:buttons` names. It gives callers one greppable component for a compact
+action that shows only an icon, without creating a second action model.
+Consumer usage lives in `IconButton.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; defaults are Button's
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Fixing Button's content mode to icon-only.
+- The prop surface: a required `icon`, and no `isIconOnly`, `children`, or
+  `endContent`.
+
+**Does not own / non-goals**
+
+- Every rendered behavior: element, naming rules, size, default square geometry,
+  click and `clickAction` handling, pending, disabled, link mode, tooltip,
+  elevation, feedback, and the `button` theme target — owned by
+  `component:Button`.
+- An automatic tooltip from `label` — not provided; a caller adds `tooltip`
+  (`family:buttons` AV6).
+- Icon rendering — owned by `component:Icon`.
+
+## Public concepts
+
+| Concept        | Closed values or states | Meaning                               | Availability by variant/orientation/state                                                                           | Default  | Owner                  | Stability | Invalid-value behavior                                         |
+| -------------- | ----------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------- | --------- | -------------------------------------------------------------- |
+| Icon-only mode | always on               | The icon is the only visible content. | Every variant, size, and state.                                                                                     | on       | `component:IconButton` | Stable    | TypeScript rejects `isIconOnly`, `children`, and `endContent`. |
+| Icon           | caller node             | The visible glyph; required.          | Every state; hidden behind the Spinner while pending, unless it paints its own colors (`component:Button` FR8 gap). | required | `component:IconButton` | Stable    | TypeScript rejects a missing `icon`.                           |
+
+Every other concept (variant, size, elevation, pending, availability, link
+mode, width, tooltip) is Button's, with Button's defaults.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                                                      |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| FR1 | IconButton renders exactly one Button in icon-only mode with the caller's `icon` and every other supplied prop, including `ref`. It adds no element, state, or behavior of its own.                                                                                                                                                                                                                                                                   | `family:buttons` AV2; current source                       |
+| FR2 | The accessible name is `label` through `aria-label` whenever `label` is non-empty; no label text is rendered visibly.                                                                                                                                                                                                                                                                                                                                 | `family:buttons` FR1; current source and tests             |
+| FR3 | With the default icon-only aspect and no caller `width`, the control is square at the resolved size with no padding. An Astryx Icon without an explicit size renders `sm` in `sm` and `md` IconButtons and `md` in `lg` ones; an explicit Icon size wins.                                                                                                                                                                                             | `family:buttons` FR7; current tests                        |
+| FR4 | Variant, size, elevation, `onClick`, `clickAction`, loading, disabled, and press feedback follow `component:Button`, including its implementation gaps: disabled follows `component:Button` FR10 and, with `href`, FR11, loading follows FR8, whose Spinner MUST appear at once under reduced motion with a fine pointer (`design:reduced-motion` DR3), and press feedback follows FR15, whose press scale MUST NOT apply under reduced motion (DR1). | `component:Button`; `design:reduced-motion`; current tests |
+
+### Allowed variation
+
+- **AV1 — Icon content.** Any caller node may fill the icon slot; IconButton
+  does not inspect it.
+
+### Representative states
+
+| State                | Required invariant                                             | Allowed variation           |
+| -------------------- | -------------------------------------------------------------- | --------------------------- |
+| At rest              | Square by default, named by `label`; icon only.                | Variant, size, theme paint. |
+| Floating (elevation) | Shadow for the chosen tier on the surface.                     | Tier.                       |
+| Loading              | Button's pending state: Spinner, `aria-busy`, still focusable. | Spinner delay.              |
+| Disabled             | Button's disabled state (`component:Button` FR10).             | Tooltip present or not.     |
+
+### Transformation and precedence order
+
+- **ORD1 — Content mode.** Icon-only always; no caller prop overrides it.
+
+### Performance and resources
+
+- **PR1 — No added work.** IconButton adds no state, effect, listener, or
+  element beyond Button's.
+
+## Accessibility contract
+
+- **AR1 — Name.** `label` is the only accessible name; the icon never
+  substitutes for it (`family:buttons` FR1).
+- **AR2 — Visible hint.** IconButton shows no visible text. A visible hint
+  exists only when the caller sets `tooltip`, which also describes the button
+  (`component:Button` FR12).
+- **AR3 — Target size.** With the default square aspect, the smallest
+  IconButton with no `width` is 28 by 28 CSS pixels, above the WCAG 2.5.8 24 by
+  24 minimum. A caller `width` or theme icon-only aspect that narrows it below
+  24 CSS pixels leaves target size to that caller or theme.
+- **AR4 — Everything else.** Keyboard, focus indicator, loading announcement,
+  and busy or disabled exposure follow `component:Button` AR2–AR5.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                                      | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Square surface   | Button's surface at the default 1 / 1 aspect ratio, unless a caller `width` or theme aspect changes it. | Current source           | Prominent      | FR3                |
+| Icon             | The only visible content, sized from the button.                                                        | Current source and tests | Prominent      | FR3                |
+
+`design:reduced-motion` governs the press scale IconButton inherits (FR4). No
+other design record governs IconButton. IconButton has no theme target of its own;
+it renders Button's `button` target.
+
+## Family and system relationships
+
+- `family:buttons` names IconButton the explicit icon-only projection of
+  Button; IconButton adopts FR1, FR7, AV2, and AV6 through Button.
+- `component:Button` owns every rendered behavior IconButton shows.
+- `spec:AST-085` applies through Button; the gap is recorded there.
+
+## Verification map
+
+| Contract             | Verification                                                                                                                                     | Representative states                                                                     | Mutation or failure expectation                                                                                                                                           | Audit section                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, FR2             | `IconButton.test.tsx` label, visible-text, ref, and displayName cases                                                                            | At rest                                                                                   | Visible label text, a lost `aria-label`, or a dropped ref fails.                                                                                                          | `audit:IconButton/anatomy`       |
+| FR3                  | `IconButton.test.tsx` icon size cases                                                                                                            | `sm`, `md`, `lg`; explicit Icon size                                                      | A wrong default Icon size or an overridden explicit size fails.                                                                                                           | `audit:IconButton/layout`        |
+| FR3 (square)         | Evidence gap: no IconButton test asserts the default square shape or zero padding                                                                | `sm`, `md`, `lg`                                                                          | —                                                                                                                                                                         | `audit:IconButton/layout`        |
+| FR4                  | `IconButton.test.tsx` click, disabled, loading, and elevation cases                                                                              | Click; disabled; loading; `none` and `med` elevation                                      | A click that does not reach `onClick`, a disabled click that does, a busy IconButton without `aria-disabled`, or identical classes for two elevations fails.              | `audit:IconButton/behavior`      |
+| FR4 (variant, size)  | Evidence gap: the variant and size cases assert only that a button renders                                                                       | `destructive`; `sm`                                                                       | —                                                                                                                                                                         | `audit:IconButton/behavior`      |
+| FR4 (reduced motion) | Evidence gap: no test presses or loads an IconButton under `prefers-reduced-motion: reduce`; the shipped scale and Spinner fade fail this clause | Mouse and touch press; pending `clickAction` or interruptible loading with a fine pointer | A computed transform other than `none` or `scale(1)` during the press, or a Spinner opacity below 1 after loading starts.                                                 | `audit:IconButton/behavior`      |
+| AR1, AR4             | `Button.a11y.test.tsx` and `Button.a11y.chromium.spec.ts` IconButton states                                                                      | IconButton at rest, disabled, loading                                                     | A missing name or a wrong focusable, operable, or unavailable state fails. The shared disabled state expects native `disabled`, matching the `component:Button` FR10 gap. | `audit:IconButton/accessibility` |
+| AR2, AR3             | Evidence gap: no IconButton test asserts the tooltip hint or the 28 by 28 target                                                                 | —                                                                                         | —                                                                                                                                                                         | `audit:IconButton/accessibility` |
+| ORD1, PR1            | Evidence gap: no test passes a caller `isIconOnly` or asserts that IconButton adds no work                                                       | —                                                                                         | —                                                                                                                                                                         | `audit:IconButton/behavior`      |
+
+## Current-state impact
+
+- **Disabled focusability (FR4).** A disabled IconButton without a tooltip
+  renders native `disabled`, as `component:Button` FR10 records, against
+  `spec:AST-085` FR1 and FR4. Its unit test and the shared button-pattern
+  suite's disabled state both expect native `disabled`. A focused link-mode
+  IconButton that becomes disabled loses focus with or without a `tooltip`,
+  because its anchor is replaced by a `<button>`, as `component:Button` FR11
+  records.
+- **Reduced motion (FR4).** A standalone IconButton scales to 0.98 on a press,
+  and the Spinner of a pending `clickAction` or an interruptible IconButton
+  fades in, when the person prefers reduced motion, as
+  `component:Button` FR8 and FR15 record, against `design:reduced-motion` DR1
+  and DR3.
+- **Self-colored icon while loading (FR4).** An icon that paints its own
+  colors, such as an image or a multicolor SVG, stays visible under the
+  Spinner, as `component:Button` FR8 records.
+
+## Decision log
+
+No component-local decision. IconButton applies `family:buttons` and
+`component:Button`.
+
+## 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/IconButton/IconButton.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {unthemedLength} from '../__tests__/unthemedLength';
 import {Icon} from '../Icon/Icon';
 import {IconButton} from './IconButton';
 
@@ -73,8 +74,10 @@ describe('IconButton', () => {
       expect(wrapper).not.toBeNull();
 
       expect(icon).toHaveAttribute('data-size', iconSize);
-      expect(getComputedStyle(icon).width).toBe(renderedSize);
-      expect(getComputedStyle(icon).height).toBe(renderedSize);
+      // The glyph reads the theme's size vars; with no theme it falls back to
+      // the size's own rem value, which the wrapper declares directly.
+      expect(unthemedLength(getComputedStyle(icon).width)).toBe(renderedSize);
+      expect(unthemedLength(getComputedStyle(icon).height)).toBe(renderedSize);
       expect(getComputedStyle(wrapper!).width).toBe(renderedSize);
       expect(getComputedStyle(wrapper!).height).toBe(renderedSize);
     },