@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/IconButton/IconButton.spec.md

@@ -1,197 +0,0 @@
----
-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/Indicator/CheckIndicator.spec.md

@@ -1,164 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CheckIndicator
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, theming, accessibility, visual]
-verified_by:
-  [
-    packages/core/src/Indicator/Indicator.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-  ]
-contributing: []
-system_specs: []
----
-
-# CheckIndicator component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                           |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `CheckIndicator` is exported from `@astryxdesign/core/Indicator`; `state` is required, `size` defaults to `md`, `isDisabled` defaults to `false`, and `children` may replace the built-in mark.                                                                    |
-| Behavior                | The component draws a decorative check glyph only when checked. Shallow-renderable `children` replace that glyph in either state; unchecked without replacement content renders no element.                                                                        |
-| End-user impact         | People receive one selection cue from the owning control without a duplicate accessible object or an empty placeholder beside unselected rows.                                                                                                                     |
-| Builder impact          | Builders may replace the named `check` indicator or compose host-owned classes and styling without taking over the owning control's semantics.                                                                                                                     |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The checked glyph path drops the declared `ref`; listed under Current-state impact, with the fix open (OQ1).                                                                                             |
-| Review checks           | Reject lost `aria-hidden`, a mark in the unchecked default, a missing checked mark, dropped supported DOM/styling passthrough, changed replacement precedence, a new component-owned theme target, or a checked path that still drops the ref once OQ1 is decided. |
-| Governing rules         | `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                                 |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Render the replaceable, decorative checkmark used by a host to show that one option is chosen, without taking ownership of selection semantics, interaction, or persistent control chrome.
-
-## Compatibility and migration
-
-- Released default preserved: yes
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: not applicable; `state` is supplied by the owner
-- Migration decision: none; the public component and `check` registry name remain unchanged
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The checked glyph, unchecked absence, disabled color, size mapping, replacement-content precedence, and decorative root.
-- Supported neutral DOM and styling passthrough on every rendered root. The replacement-content span receives the declared ref; the checked Icon path currently does not.
-
-**Does not own / non-goals**
-
-- Selection role, accessible name, state, focus, keyboard, activation, or busy semantics — owned by the composing control.
-- Persistent checkbox or radio chrome — owned by `component:CheckboxIndicator` or `component:Indicator`.
-- Row placement and logical-edge layout — owned by the host component.
-- The behavior or accessibility of consumer-supplied replacement content.
-
-## Public concepts
-
-| Concept             | Closed values or states     | Meaning                                                                                                                                                                     | Availability by variant/orientation/state             | Default            | Owner                      | Stability                                 | Invalid-value behavior                             |
-| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------ | -------------------------- | ----------------------------------------- | -------------------------------------------------- |
-| state               | `unchecked`, `checked`      | Selects whether the built-in check glyph is absent or present.                                                                                                              | Every render path.                                    | required           | `component:CheckIndicator` | stable                                    | rejected by the public type                        |
-| size                | `sm`, `md`                  | Selects the shared indicator size; both current values use the `sm` Icon glyph.                                                                                             | Checked and replacement-content roots.                | `md`               | `component:CheckIndicator` | stable                                    | rejected by the public type                        |
-| disabled appearance | enabled, disabled           | Mirrors the owning control's disabled color without creating semantics.                                                                                                     | Checked and replacement-content roots.                | enabled            | `component:CheckIndicator` | stable                                    | boolean only                                       |
-| replacement content | shallow renderable or empty | Replaces the built-in mark in either state when `isRenderable(children)` returns true. React elements and containers take this branch even when descendants render nothing. | Every state; replacement content creates a span root. | built-in mark path | `component:CheckIndicator` | stable; empty-container policy open (OQ2) | unsupported values follow React rendering behavior |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                    | Basis                                                              |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
-| FR1 | The component MUST render one decorative check glyph when `state="checked"` and no replacement content is present, and MUST set its own `aria-hidden="true"` after caller passthrough.                                                                                                                                                                       | shipped source; `architecture:public-component-api/INV5`           |
-| FR2 | The default component MUST render no element when `state="unchecked"` and no replacement content is present.                                                                                                                                                                                                                                                 | shipped source, docs, tests, and stories                           |
-| FR3 | Replacement uses shallow `isRenderable(children)` precedence in both states: nullish values, booleans, and the empty string keep the built-in state behavior; React elements and containers replace it even when descendants render nothing (OQ2).                                                                                                           | shipped source and regression tests                                |
-| FR4 | Every rendered root MUST preserve supported DOM props, `className`, `style`, and `xstyle` while keeping component-owned accessibility precedence, and the declared ref MUST reach the rendered root (`architecture:public-component-api/INV8`). Implementation gap: the replacement-content span receives the ref, but the checked Icon path drops it (OQ1). | `architecture:public-component-api/INV5,INV6,INV8`; current source |
-| FR5 | The built-in checked mark MUST remain an Icon-owned painter on the same element as host-supplied classes; CheckIndicator MUST NOT add a wrapper or a distinct public target without an approved contract change.                                                                                                                                             | shipped source; `architecture:component-theming-surface/INV3–INV5` |
-| FR6 | Disabled color and replacement-content color MUST continue to use semantic tokens rather than raw color values.                                                                                                                                                                                                                                              | shipped source; current token and theming architecture             |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** The Icon target and host-owned class may change supported paint without changing state or semantic ownership.
-- **AV2 — Replacement component.** A theme may replace the named `check` indicator when the replacement preserves this public prop and decorative-ownership contract.
-
-### Representative states
-
-| State               | Required invariant                                                                              | Allowed variation                 |
-| ------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------- |
-| unchecked           | No built-in element is rendered.                                                                | A replacement component may draw. |
-| checked             | One decorative check glyph is rendered.                                                         | Icon- and host-owned theme paint. |
-| disabled            | Checked or replacement content keeps the requested state and uses the disabled semantic color.  | Theme-owned inactive treatment.   |
-| replacement content | Shallow-renderable content replaces the built-in mark in a centered fixed-size decorative root. | Caller-owned decorative content.  |
-
-### Transformation and precedence order
-
-- **ORD1 — Render precedence.** Shallow replacement-content decision → unchecked absence or checked Icon → caller passthrough → component-owned `aria-hidden` → merged theme/style inputs.
-
-### Performance and resources
-
-- **PR1 — Pure render.** The component owns no state, Effect, listener, observer, timer, or external resource.
-
-## Accessibility contract
-
-- **AR1 — Decorative ownership.** Every rendered root remains `aria-hidden`; the composing control owns role, name, state, focus, keyboard, activation, and form semantics.
-- **AR2 — Replacement boundary.** Replacement content is decorative within the hidden root and MUST NOT be the only semantic expression of the owning control's selected or busy state.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                      | Representation authority                | Hierarchy role       | Component contract |
-| ---------------- | ------------------------------------------------------- | --------------------------------------- | -------------------- | ------------------ |
-| Chrome           | CheckIndicator intentionally owns no persistent chrome. | observed shipped representation         | not applicable       | FR2, FR5           |
-| State mark       | Checked state renders the shared decorative check Icon. | Icon-owned current theming architecture | supporting state cue | FR1, FR5–FR6       |
-
-The shared `Indicator.doc.mjs` lists anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together, so this record carries no anatomy-theming map. CheckIndicator owns no persistent chrome and delegates its built-in checked mark to Icon.
-
-## Family and system relationships
-
-- `architecture:component-theming-surface` owns target placement and composed-painter ownership.
-- `architecture:public-component-api` owns export, passthrough, styling composition, ref, and compatibility requirements.
-- `architecture:component-test-sufficiency` owns the evidence needed for each critical promise and distinct risk partition.
-
-## Verification map
-
-| Contract      | Verification                                                                                           | Representative states                                       | Mutation or failure expectation                                                                                                                                                                                                                                                                                               | Audit section                        |
-| ------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| FR1, FR2, FR3 | `Indicator.test.tsx` CheckIndicator state and replacement cases; falsy-children cases                  | Checked, unchecked, empty scalar, visible child, `0`        | Removing the glyph, adding unchecked chrome, or choosing the wrong children branch fails.                                                                                                                                                                                                                                     | `audit:CheckIndicator/behavior`      |
-| FR1, AR1      | `Indicator.test.tsx` decorative-contract cases                                                         | Glyph and replacement roots; a caller `aria-hidden={false}` | A root that a caller can expose fails. Evidence gap: no test asserts that replacement content is not the only state expression (AR2).                                                                                                                                                                                         | `audit:CheckIndicator/accessibility` |
-| FR4           | `Indicator.test.tsx` "forwards caller props and styling on both render paths"                          | Both render paths                                           | A caller DOM prop that stops reaching either root, or a `className` that stops reaching the replacement span, fails. Evidence gap: no test asserts `className`, `style`, or `xstyle` on the checked-glyph path, `style` or `xstyle` on the replacement span, or the ref on either path (the checked-path ref is the FR4 gap). | `audit:CheckIndicator/api`           |
-| FR5, FR6      | `themingTargets.test.ts`                                                                               | Checked glyph                                               | A rendered class absent from the documented targets fails. Evidence gap: no test asserts that no wrapper separates host classes from the Icon painter, or that disabled and replacement colors use semantic tokens.                                                                                                           | `audit:CheckIndicator/theming`       |
-| ORD1, PR1     | Covered by the FR1–FR4 rows. Evidence gap: no test asserts the absence of state, effects, or listeners | —                                                           | —                                                                                                                                                                                                                                                                                                                             | `audit:CheckIndicator/behavior`      |
-
-## Current-state impact
-
-- **Checked-path ref (FR4).** The declared ref is `null` when CheckIndicator
-  draws its checked glyph, against `architecture:public-component-api` INV8; the
-  fix is OQ1.
-
-## Decision log
-
-No component-local decision.
-
-## Open questions
-
-- **OQ1 — Should CheckIndicator preserve its declared `HTMLSpanElement` ref by owning a stable span root in the checked path, or should the public ref contract change to match the Icon-owned painter?** (`human-api`) The current checked path returns `null`; either correction changes a released DOM or ref contract.
-- **OQ2 — Should empty React containers continue to suppress the built-in state mark?** (`human-api`) FR3 records that they do today.
-
-## 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/Indicator/CheckboxIndicator.spec.md

@@ -1,164 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CheckboxIndicator
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, theming, accessibility, visual]
-verified_by:
-  [
-    packages/core/src/CheckboxInput/CheckboxInput.test.tsx,
-    packages/core/src/Indicator/Indicator.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-  ]
-contributing: []
-system_specs: []
----
-
-# CheckboxIndicator component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                           |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `CheckboxIndicator` is exported from `@astryxdesign/core/Indicator`; `state` is required, `size` defaults to `md`, `isDisabled` defaults to `false`, and `children` may replace the built-in mark. |
-| Behavior                | A decorative checkbox chrome is always rendered. Checked and indeterminate states draw their matching mark unless the shallow `isRenderable()` predicate treats `children` as replacement content. |
-| End-user impact         | People receive one visible checkbox-state cue while the owning control retains all semantics, focus, keyboard, and activation behavior.                                                            |
-| Builder impact          | Builders may restyle the canonical targets or replace the named indicator without taking over the owning control's semantics.                                                                      |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Only the canonical `checkbox-indicator` target is emitted.                                                                               |
-| Review checks           | Reject lost `aria-hidden`, missing state marks, dropped passthrough/ref/styling, changed replacement precedence, or a second target alias on the root.                                             |
-| Governing rules         | `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV8,INV12`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.           |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Render the replaceable, decorative visual that communicates a checkbox owner's unchecked, checked, or indeterminate state without taking ownership of checkbox semantics or interaction.
-
-## Compatibility and migration
-
-- Released default preserved: yes
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: not applicable; `state` is supplied by the owner
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- Decorative checkbox chrome, state mark, disabled appearance, size, replacement-content precedence, and component theming targets.
-- A root DOM ref plus supported neutral DOM and styling passthrough.
-
-**Does not own / non-goals**
-
-- Checkbox role, accessible name, focus, keyboard, activation, form participation, or busy semantics — owned by the composing control.
-- Row placement and logical-edge layout — owned by the host component.
-- The behavior or accessibility of consumer-supplied replacement content.
-
-## Public concepts
-
-| Concept             | Closed values or states                 | Meaning                                                                                                                                                       | Availability by variant/orientation/state | Default            | Owner                         | Stability                                 | Invalid-value behavior                             |
-| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------ | ----------------------------- | ----------------------------------------- | -------------------------------------------------- |
-| state               | `unchecked`, `checked`, `indeterminate` | Chooses the built-in visual state.                                                                                                                            | All render paths.                         | required           | `component:CheckboxIndicator` | stable                                    | rejected by the public type                        |
-| size                | `sm`, `md`                              | Selects the 20px or 24px visual box and matching mark geometry.                                                                                               | All states.                               | `md`               | `component:CheckboxIndicator` | stable                                    | rejected by the public type                        |
-| disabled appearance | enabled, disabled                       | Mirrors the owning control's disabled presentation without creating semantics.                                                                                | All states.                               | enabled            | `component:CheckboxIndicator` | stable                                    | boolean only                                       |
-| replacement content | shallow renderable or empty             | Replaces both built-in marks when `isRenderable(children)` returns true. React elements and containers take this branch even when descendants render nothing. | All states.                               | built-in mark path | `component:CheckboxIndicator` | stable; empty-container policy open (OQ1) | unsupported values follow React rendering behavior |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                           | Basis                                                              |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| FR1 | The component MUST render one decorative span chrome in every state and MUST set its own `aria-hidden="true"` after caller passthrough.                                                                                             | shipped source; `architecture:public-component-api/INV5`           |
-| FR2 | `unchecked` MUST show no built-in mark, `checked` MUST show the checkmark, and `indeterminate` MUST show the dash.                                                                                                                  | shipped source, docs, tests, and stories                           |
-| FR3 | Replacement uses shallow `isRenderable(children)` precedence: nullish values, booleans, and the empty string keep the state mark; React elements and containers replace it even when descendants render nothing (OQ1).              | shipped source and regression tests                                |
-| FR4 | The root MUST preserve supported DOM props, `ref`, `className`, `style`, and `xstyle` while keeping component-owned accessibility precedence.                                                                                       | `architecture:public-component-api/INV5,INV6,INV8`                 |
-| FR5 | The root target MUST be `checkbox-indicator`, the only target on that element; no alias target is emitted.                                                                                                                          | `architecture:component-theming-surface/INV4,INV6`; current tests  |
-| FR6 | Size, checked or indeterminate (`data-checked`), and disabled state MUST be reflected on the root target; the check and dash MUST retain their dedicated `checkbox-indicator-check` and `checkbox-indicator-dash` painting targets. | shipped source; `architecture:component-theming-surface/INV4,INV6` |
-| FR7 | State transitions MUST honor reduced motion, and checked/indeterminate marks MUST remain perceivable in forced-colors mode.                                                                                                         | shipped source and WCAG 2.2 1.4.11                                 |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** Tokens and canonical component targets may change color, border, radius, opacity, and other admitted visual properties without changing state or semantic ownership.
-- **AV2 — Replacement component.** A theme may replace the named checkbox indicator when the replacement preserves this public prop and decorative-ownership contract.
-
-### Representative states
-
-| State               | Required invariant                                                                          | Allowed variation                |
-| ------------------- | ------------------------------------------------------------------------------------------- | -------------------------------- |
-| unchecked           | Chrome remains visible with no built-in mark.                                               | Theme-owned paint and shape.     |
-| checked             | Chrome and checkmark remain visible.                                                        | Theme-owned paint and shape.     |
-| indeterminate       | Chrome and dash remain visible.                                                             | Theme-owned paint and shape.     |
-| disabled            | The requested state remains legible with muted treatment and no host-driven hover response. | Theme-owned inactive treatment.  |
-| replacement content | Shallow-renderable content replaces both built-in marks inside the same chrome.             | Caller-owned decorative content. |
-
-### Transformation and precedence order
-
-- **ORD1 — Render precedence.** Caller passthrough → component-owned `aria-hidden` → merged theme/style inputs → shallow replacement-content decision → built-in state mark.
-
-### Performance and resources
-
-- **PR1 — Pure render.** The component owns no state, Effect, listener, observer, timer, or external resource.
-
-## Accessibility contract
-
-- **AR1 — Decorative ownership.** The root remains `aria-hidden`; the composing control owns role, name, state, focus, keyboard, activation, and form semantics.
-- **AR2 — Forced colors.** Checked and indeterminate marks remain distinguishable when author colors are forced.
-- **AR3 — Replacement boundary.** Replacement content is decorative within the hidden root and MUST NOT be the only semantic expression of the owning control's state.
-
-## Design relationships
-
-| Anatomy or state   | Design requirement                                  | Representation authority                   | Hierarchy role            | Component contract |
-| ------------------ | --------------------------------------------------- | ------------------------------------------ | ------------------------- | ------------------ |
-| Chrome             | Semantic theme tokens and canonical painting target | prescribed by current theming architecture | supporting control visual | FR1, FR5–FR7       |
-| Checkmark          | Visible checked-state mark                          | observed shipped representation            | supporting state cue      | FR2, FR6–FR7       |
-| Indeterminate mark | Visible partial-state mark                          | observed shipped representation            | supporting state cue      | FR2, FR6–FR7       |
-
-The shared `Indicator.doc.mjs` lists anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together, so this record carries no anatomy-theming map.
-
-## Family and system relationships
-
-- `architecture:component-theming-surface` owns target placement and reflected state.
-- `component:Indicator` owns the registry name `checkbox` and theme replacement.
-- `architecture:public-component-api` owns export, passthrough, styling composition, ref, and compatibility requirements.
-- `architecture:component-test-sufficiency` owns the evidence needed for each critical promise and distinct risk partition.
-
-## Verification map
-
-| Contract  | Verification                                                                                                                                                                                                              | Representative states                                                  | Mutation or failure expectation                                                                                                                                                                                                                                                                                                             | Audit section                           |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| FR1, AR1  | `Indicator.test.tsx` decorative-contract cases                                                                                                                                                                            | Checked state; a caller `aria-hidden={false}`                          | A checked indicator that a caller can expose fails. Evidence gap: no test checks `aria-hidden` in the unchecked or indeterminate state, or that replacement content is not the only state expression (AR3).                                                                                                                                 | `audit:CheckboxIndicator/accessibility` |
-| FR2, FR3  | `Indicator.test.tsx` default-indicator, replacement, and falsy-children cases                                                                                                                                             | Checked with falsy and real children; checked with a replacement child | A removed checkmark element, a falsy child that suppresses it, or real children that do not replace it fails. Evidence gap: no test looks for the dash element, and since both marks render in every state with their display toggled, no test asserts which mark is visible in each state.                                                 | `audit:CheckboxIndicator/behavior`      |
-| FR4       | `Indicator.test.tsx` decorative-contract "still forwards ordinary props" cases                                                                                                                                            | Neutral DOM props                                                      | A dropped `data-testid`, `id`, or `dir` fails. Evidence gap: no test asserts `ref`, `className`, `style`, or `xstyle` on the root.                                                                                                                                                                                                          | `audit:CheckboxIndicator/api`           |
-| FR5, FR6  | `Indicator.test.tsx` checkbox-target and canonical-target cases; `themingTargets.test.ts`                                                                                                                                 | Indeterminate at `sm`; canonical target                                | A missing or aliased `checkbox-indicator` target, or a missing `data-checked="indeterminate"` or `data-size`, fails. Evidence gap: no test asserts `data-checked` in the checked state, checkbox `data-disabled` (the disabled-state case renders RadioIndicator), or the `checkbox-indicator-check` and `checkbox-indicator-dash` targets. | `audit:CheckboxIndicator/theming`       |
-| FR7, AR2  | `CheckboxInput.test.tsx` forced-colors cases ("compiles a forced-colors fill so the indeterminate mark survives Windows High Contrast", "compiles a forced-colors color so the checkmark survives Windows High Contrast") | Checked and indeterminate under forced colors                          | Evidence gap: the forced-colors cases pass on any matching injected rule, so removing the checkmark and dash `CanvasText` rules still passes; no test asserts the reduced-motion transition.                                                                                                                                                | `audit:CheckboxIndicator/visual`        |
-| ORD1, PR1 | Covered by the FR1–FR4 rows. Evidence gap: no test asserts the absence of state, effects, or listeners                                                                                                                    | —                                                                      | —                                                                                                                                                                                                                                                                                                                                           | `audit:CheckboxIndicator/behavior`      |
-
-## Decision log
-
-No component-local decision.
-
-## Open questions
-
-- **OQ1 — Should an empty React container in `children` keep suppressing the
-  built-in state mark?** (`human-api`) FR3 records that it does today.
-
-## 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.