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

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);
     },

package/src/InputGroup/InputGroup.spec.md

@@ -0,0 +1,199 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:InputGroup
+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: [packages/core/src/InputGroup/InputGroup.test.tsx]
+modules: []
+families: [family:input-fields]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:component-size-cascade,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-038, spec:AST-085, spec:AST-102]
+---
+
+# InputGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. InputGroup takes `label`, `isLabelHidden`, `description`, `isOptional`, `isRequired`, `isDisabled`, `size`, `status`, `labelTooltip`, and input and addon children.                                                                                             |
+| Behavior                | One Field-labelled `role="group"` row at the shared element height that joins admitted inputs, InputGroupText addons, and Button addons into one connected shape, and gives each grouped input the group's name and description.                                              |
+| End-user impact         | People see a prefix, input, and suffix as one field, and screen-reader users hear the group label with each input's own label. A disabled group disables its inputs and Button addons together.                                                                               |
+| Builder impact          | None.                                                                                                                                                                                                                                                                         |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The row holds a fixed height, Button addons scale under reduced motion, the row accepts root styling against FR10's scope, and the group border does not paint `status`; all are listed under Current-state impact. |
+| Review checks           | Reject a grouped input that loses the group label or description, inner corners that round, a disabled group whose compatible children stay operable, or an internal input button reshaped as an addon.                                                                       |
+| Governing rules         | `family:input-fields` FR3, AV3; `architecture:component-size-cascade` INV3–INV8; `spec:AST-085` FR7; `spec:AST-038` FR7, FR8; `spec:AST-102` FR4; `design:reduced-motion` DR1.                                                                                                |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+InputGroup joins an input with prefix and suffix addons into one connected
+row, as `family:input-fields` assigns: it owns the row height, the connected
+outer shape, edge alignment, and the group's label and supporting text.
+Consumer usage lives in `InputGroup.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; `size="md"`, label visible, not disabled
+- 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**
+
+- The group Field (label, description, optional or required marker, label
+  tooltip, detached status message) and the `role="group"` row.
+- The row height and the size it provides to descendants up to the next layer boundary.
+- The group context that tells admitted children they are grouped and which
+  label and description ids to compose.
+- Connected geometry for direct Button addons.
+- The `input-group` target.
+
+**Does not own / non-goals**
+
+- Each grouped input's own adaptation (hidden inner label, no nested Field,
+  grouped corners, status icon handling) — owned by that input under
+  `family:input-fields` FR3.
+- The text addon — owned by `component:InputGroupText` (this lane).
+- Which inputs are admitted — decided per component under
+  `family:input-fields` FR3; membership alone does not admit one.
+- Disabling caller-owned controls that do not read the group — not provided.
+
+## Public concepts
+
+| Concept  | Closed values or states                         | Meaning                                         | Availability by variant/orientation/state | Default                   | Owner                  | Stability | Invalid-value behavior           |
+| -------- | ----------------------------------------------- | ----------------------------------------------- | ----------------------------------------- | ------------------------- | ---------------------- | --------- | -------------------------------- |
+| Size     | `sm`, `md`, `lg`                                | Row height and default size for children.       | Always.                                   | Inherited size, else `md` | `family:input-fields`  | Stable    | TypeScript rejects other values. |
+| Status   | `error`, `warning`, `success`, optional message | Group validation state.                         | Always; the message is detached.          | none                      | `component:InputGroup` | Stable    | TypeScript rejects other types.  |
+| Disabled | off, on                                         | Disables the group and its compatible children. | Always.                                   | off                       | `component:InputGroup` | Stable    | Not applicable.                  |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                                               |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| FR1 | InputGroup renders one Field in group-label mode with `label` (visible unless `isLabelHidden`), `description`, the optional or required marker, `labelTooltip`, and `status` as a detached message. Inside it, the row is one element with `role="group"`, `aria-labelledby` set to the label, and `aria-describedby` set to the description and status message ids that exist.                                                                                                                                                                                                                                                                    | `family:input-fields` FR3; current tests                                            |
+| FR2 | Grouped inputs receive the label id and description ids through context. Each admitted input is named by the group label plus its own label and described by the group's description and status plus its own.                                                                                                                                                                                                                                                                                                                                                                                                                                      | `family:input-fields` FR3; current tests                                            |
+| FR3 | The row is inline-flex, stretched, and transparent; its height is the shared element height for its size, as a minimum that grows with a set text size under `spec:AST-102` FR4. Implementation gap: the height is fixed at that size. It provides its resolved size to descendants up to the next layer boundary (`spec:AST-038` FR7, FR8): explicit `size`, then the nearest outer provider, then `md`.                                                                                                                                                                                                                                          | `family:input-fields` FR3; `architecture:component-size-cascade`; current source    |
+| FR4 | Direct Button addons join the shape: no inner corner rounding toward a neighbour, full row height, and their keyboard focus ring raised above the adjacent member. Buttons deeper inside a grouped input (clear, calendar, disclosure), and a Button addon wrapped in a Tooltip or HoverCard (not a direct child), keep their own shape. A following popover, template, or dialog element does not count as a neighbour. Addons are `component:Button`s outside a ButtonGroup, so their press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it still applies under reduced motion.                  | Current source; `design:reduced-motion` DR1                                         |
+| FR5 | The `role="group"` row inside the Field box carries `astryx-input-group` and reflects `data-size` and `data-status`. `ref`, `data-testid`, and other DOM props reach the row. InputGroup composes Field, so `family:input-fields` FR10 forbids root `xstyle`, `className`, and `style`. Implementation gap: they are accepted and reach the row.                                                                                                                                                                                                                                                                                                   | `architecture:component-theming-surface`; `family:input-fields` FR10; current tests |
+| FR6 | The group is disabled when its own `isDisabled` or an enclosing InputGroup's is true. A disabled group sets `aria-disabled="true"` on the row, dims it to half opacity with the default cursor, passes the disabled state to the group Field, and disables every compatible child (TextInput, NumberInput, Selector, MultiSelector, DateInput, TimeInput, Typeahead, and Button addons) and nested group up to the next layer boundary; each child then follows its own disabled contract. A child or nested group that disables itself stays disabled when the group is enabled. Caller-owned controls that do not read the group are unaffected. | `spec:AST-085` FR7; `spec:AST-038` FR7, FR8; current tests                          |
+
+### Allowed variation
+
+- **AV1 — Members.** Any admitted input, InputGroupText, Button, and
+  Button-triggered controls may appear in any order.
+- **AV2 — Status paint.** A theme may paint the group from `data-status`; core
+  paints no group border for it.
+
+### Representative states
+
+| State                       | Required invariant                                               | Allowed variation |
+| --------------------------- | ---------------------------------------------------------------- | ----------------- |
+| Prefix text + TextInput     | One row; outer corners only; input named by group and own label. | Size.             |
+| Input + Button suffix       | Button full height, square toward the input.                     | Variant.          |
+| With description and status | Group and inputs described by both; message detached below.      | —                 |
+| Hidden label                | Label visually hidden; still names the group.                    | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Size.** Explicit `size`, then outer provider, then `md`; a grouped
+  input's own explicit `size` still wins for that input.
+- **ORD2 — Description.** Group description, then group status message.
+
+### Performance and resources
+
+- **PR1 — No measurement.** Geometry comes from CSS selectors; InputGroup adds
+  no observer or listener.
+
+## Accessibility contract
+
+- **AR1 — Group name.** `role="group"` labelled by the visible or hidden
+  label (FR1).
+- **AR2 — Input names.** Each admitted input combines the group label with its
+  own label, so its purpose stays specific (FR2).
+- **AR3 — Focus.** A focused member is raised above its neighbours so its
+  focus presentation is not covered.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                             | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Label            | Group label above the row, or hidden.          | Current source           | Prominent      | FR1                |
+| Prefix addon     | Text or Button before the input, joined to it. | Current source           | Supporting     | FR4                |
+| Input            | The admitted input, filling remaining width.   | Current source           | Prominent      | FR2                |
+| Suffix addon     | Text or Button after the input, joined to it.  | Current source           | Supporting     | FR4                |
+
+`design:reduced-motion` governs the Button addons' press scale (FR4); no other
+design record governs InputGroup. The row carries `input-group`; the
+consumer anatomy names no row part, so this record carries no anatomy-theming
+map.
+
+## Family and system relationships
+
+- `family:input-fields` assigns InputGroup the row height, connected surface,
+  edge alignment, and group focus; admission stays with each input.
+- `component:InputGroupText` supplies the text addon.
+- `component:Button` applies FR4's addon geometry from the group context.
+- `architecture:component-size-cascade` owns size inheritance (FR3).
+
+## Verification map
+
+| Contract             | Verification                                                                                                                                    | Representative states                                                                                      | Mutation or failure expectation                                                                                                                                                                                                                                         | Audit section                    |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, AR1             | `InputGroup.test.tsx` label, description, status, hidden-label cases                                                                            | Visible and hidden label; description and status                                                           | A missing group name or description fails. Evidence gap: no test asserts the optional or required marker or the label tooltip. The hidden-label case checks neither the group name nor the visual hiding, and no test asserts the description-then-status order (ORD2). | `audit:InputGroup/accessibility` |
+| FR2, AR2             | `InputGroup.test.tsx` grouped-input naming cases and the grouped DateInput semantics case                                                       | TextInput, NumberInput, DateInput, Typeahead, Selector, MultiSelector                                      | A grouped input that loses the group or its own label fails.                                                                                                                                                                                                            | `audit:InputGroup/accessibility` |
+| FR4                  | Evidence gap: no InputGroup-level test of addon geometry, wrapped addons, or the reduced-motion press; `component:Button` verifies its own side | —                                                                                                          | —                                                                                                                                                                                                                                                                       | `audit:InputGroup/layout`        |
+| FR5                  | `InputGroup.test.tsx` data-testid case                                                                                                          | Root                                                                                                       | A dropped test id fails. Evidence gap: the size case asserts only rendering; no test asserts the target, `data-size`, `data-status`, `ref`, `className`, `style`, or `xstyle`.                                                                                          | `audit:InputGroup/theming`       |
+| FR6                  | `InputGroup.test.tsx` disabled-propagation cases                                                                                                | Every compatible input and Button addon; nested groups; re-enabled group with an explicitly disabled child | A child that stays operable in a disabled group, a nested group that opts out, or a re-enabled explicitly disabled child fails.                                                                                                                                         | `audit:InputGroup/behavior`      |
+| FR3, FR6 (paint)     | Evidence gap: no assertion of row height, size propagation, or disabled dimming                                                                 | —                                                                                                          | —                                                                                                                                                                                                                                                                       | `audit:InputGroup/layout`        |
+| ORD1, ORD2, PR1, AR3 | Evidence gap: no test asserts size precedence, the description-then-status order, the absence of observers, or a raised focused member          | —                                                                                                          | —                                                                                                                                                                                                                                                                       | `audit:InputGroup/behavior`      |
+
+## Current-state impact
+
+- **Fixed height (FR3).** The row holds the fixed shared element height instead
+  of growing with a set text size, against `spec:AST-102` FR4.
+- **Addon press under reduced motion (FR4).** A Button addon scales to 0.98 on a
+  press when the person prefers reduced motion, as `component:Button` FR15
+  records, against `design:reduced-motion` DR1.
+- **Root styling (FR5).** InputGroup accepts root `className`, `style`, and
+  `xstyle` on its row, against the scope of `family:input-fields` FR10. FR10
+  item 3 names InputGroup as the caller's styling surface, and the family
+  coverage test `Field/fieldInputFamily.test.tsx` leaves InputGroup out of its
+  field inputs, so this gap may close by clarifying FR10 rather than by
+  changing code.
+- **Status paint (AV2).** The consumer docs say `status` is applied to the group
+  border; core reflects it as `data-status` and shows the detached message, and
+  paints no group border.
+
+## Decision log
+
+No component-local decision. InputGroup applies `family:input-fields`.
+
+## 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/InputGroup/InputGroup.test.tsx

@@ -20,6 +20,8 @@ import {Typeahead} from '../Typeahead';
 import type {SearchableItem, SearchSource} from '../Typeahead';
 import {Selector} from '../Selector';
 import {MultiSelector} from '../MultiSelector';
+import {TimeInput} from '../TimeInput';
+import {Button} from '../Button';
 
 const fruits: SearchableItem[] = [
   {id: '1', label: 'Apple'},
@@ -276,6 +278,124 @@ describe('InputGroup', () => {
     ).toHaveAttribute('aria-expanded', 'false');
   });
 
+  it('propagates disabled state to all compatible inputs and Button addons', () => {
+    const onChange = () => {};
+    render(
+      <>
+        <InputGroup label="Group" isDisabled>
+          <TextInput label="Text" value="" onChange={onChange} />
+          <Button label="Save" tooltip="Save" />
+        </InputGroup>
+        <InputGroup label="Group" isDisabled>
+          <NumberInput label="Amount" value={2} onChange={onChange} />
+        </InputGroup>
+        <InputGroup label="Group" isDisabled>
+          <Selector label="Single fruit" options={['Apple', 'Banana']} />
+        </InputGroup>
+        <InputGroup label="Group" isDisabled>
+          <MultiSelector
+            label="Multiple fruits"
+            options={['Apple', 'Banana']}
+            value={[]}
+            onChange={onChange}
+          />
+        </InputGroup>
+        <InputGroup label="Group" isDisabled>
+          <DateInput label="Date" presentation="popover" onChange={onChange} />
+        </InputGroup>
+        <InputGroup label="Group" isDisabled>
+          <TimeInput
+            label="Time"
+            presentation="text-input"
+            onChange={onChange}
+          />
+        </InputGroup>
+        <InputGroup label="Group" isDisabled>
+          <Typeahead
+            label="Fruit"
+            value={null}
+            searchSource={fruitSource}
+            onChange={onChange}
+            disabledMessage="Unavailable"
+          />
+        </InputGroup>
+      </>,
+    );
+
+    for (const group of screen.getAllByRole('group', {name: 'Group'})) {
+      expect(group).toHaveAttribute('aria-disabled', 'true');
+    }
+    for (const name of [
+      'Group Text',
+      'Group Amount',
+      'Group Single fruit',
+      'Group Multiple fruits',
+      'Group Date',
+      'Group Time',
+      'Group Fruit',
+    ]) {
+      expect(screen.getByLabelText(name)).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
+    }
+    expect(screen.getByRole('button', {name: 'Save'})).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+  });
+
+  it('does not let nested groups or children opt out of ancestor disablement', () => {
+    render(
+      <InputGroup label="Outer" isDisabled>
+        <InputGroup label="Inner" isDisabled={false}>
+          <TextInput
+            label="Text"
+            value=""
+            isDisabled={false}
+            onChange={() => {}}
+          />
+        </InputGroup>
+      </InputGroup>,
+    );
+
+    expect(screen.getByRole('group', {name: 'Inner'})).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+    expect(screen.getByRole('textbox', {name: 'Inner Text'})).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+  });
+
+  it('re-enables inherited children without re-enabling explicitly disabled children', () => {
+    function Example({disabled}: {disabled: boolean}) {
+      return (
+        <InputGroup label="Group" isDisabled={disabled}>
+          <TextInput label="Text" value="" onChange={() => {}} />
+          <TextInput label="Explicit" value="" isDisabled />
+        </InputGroup>
+      );
+    }
+    const {rerender} = render(<Example disabled />);
+    expect(screen.getByRole('textbox', {name: 'Group Text'})).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+
+    rerender(<Example disabled={false} />);
+    expect(screen.getByRole('group', {name: 'Group'})).not.toHaveAttribute(
+      'aria-disabled',
+    );
+    expect(
+      screen.getByRole('textbox', {name: 'Group Text'}),
+    ).not.toHaveAttribute('aria-disabled');
+    expect(
+      screen.getByRole('textbox', {name: 'Group Explicit'}),
+    ).toHaveAttribute('aria-disabled', 'true');
+  });
+
   it('renders the visible label', () => {
     render(
       <InputGroup label="Price">