@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/FormLayout/FormLayout.spec.md

@@ -44,7 +44,7 @@ system_specs: [spec:AST-038]
 | Behavior                | Vertical stacks children; horizontal creates one fractional grid track per child in logical inline order; horizontal-labels pairs Field labels and controls, then collapses below a 481px viewport.                                |
 | End-user impact         | People encounter predictable field spacing and order, and assistive technology receives required-state information even when the form-wide visual convention leaves the common case unmarked.                                      |
 | Builder impact          | Builders supply the fields and any semantic `<form>`, title, or footer; nested layouts replace the outer direction and optionality context for their descendants.                                                                  |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or runtime changes. One implementation gap is listed under Current-state impact.                                                                                           |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or runtime changes.                                                                                                                                                        |
 | Review checks           | Reject lost root props, physical inline ordering, changed collapse boundaries, caller-overridable direction reflection, lost nested-context shadowing, or a visible optionality convention that disagrees with ARIA.               |
 | Governing rules         | Established public FormLayout interface; `family:input-fields` outer-arrangement ownership; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                     |
 
@@ -61,15 +61,6 @@ This table is a review projection; the body below is authoritative.
 - Controlled/uncontrolled behavior: not applicable; FormLayout owns no form value or submission state.
 - Migration decision: none.
 
-## Current-state impact
-
-- **Required state lost for four controls (FR5, AR2).** Under
-  `defaultOptionality="required"` the visible "Required" marker is hidden,
-  but Typeahead and Tokenizer set no `aria-required`, and FileInput and
-  Slider build their required description from `isRequired` alone. Screen
-  reader users hear those fields as not required, while sighted users see
-  the form-wide convention.
-
 ## Ownership boundary
 
 **Owns**
@@ -95,14 +86,14 @@ This table is a review projection; the body below is authoritative.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                           |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Released source, tests, and stories                             |
-| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule.                                                                                                                                                                                                                                                                                                                                                                                          | Released source, tests, and stories                             |
-| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap.                                                                                                                                                                          | Released source, Field composition, and tests                   |
-| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8).                                                                                                                                                                                                                                                                                                    | Context source and tests                                        |
-| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators. Implementation gap: under `defaultOptionality="required"`, Typeahead and Tokenizer set no `aria-required`, and FileInput and Slider describe required state from `isRequired` alone, so those fields are announced as not required while the marker is hidden (Current-state impact). | Tests; `family:input-fields` ownership                          |
-| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target.                                                                                                                                                                                                                                                                                                                                                           | `architecture:public-component-api/INV5–INV8`; source and tests |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                           |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap.                                                                                                                                                                                                                                                                                                | Released source, tests, and stories                             |
+| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule.                                                                                                                                                                                                                 | Released source, tests, and stories                             |
+| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap. | Released source, Field composition, and tests                   |
+| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8).                                                                                                                           | Context source and tests                                        |
+| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators.                                                                                                              | Tests; `family:input-fields` ownership                          |
+| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target.                                                                                                                                                                                  | `architecture:public-component-api/INV5–INV8`; source and tests |
 
 ### Allowed variation
 
@@ -135,7 +126,7 @@ This table is a review projection; the body below is authoritative.
 ## Accessibility contract
 
 - **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
-- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology. Implementation gap: Typeahead, Tokenizer, FileInput, and Slider do not (FR5).
+- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology.
 - **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
 
 ## Design relationships
@@ -191,7 +182,7 @@ The root target reflects the closed `direction` axis. It owns the outer arrangem
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
 | FR1–FR3        | `FormLayout.test.tsx` direction snapshots; `FormLayout.stories.tsx` play checks; stable visual baseline `core-formlayout--vertical` | Vertical, horizontal, horizontal-labels wide and narrow                  | A changed style class set fails the snapshots; a narrow horizontal-labels control narrower than the layout, or a wide label not before its control, fails the play checks; a changed vertical layout comes back changed for review. The story play guard also runs the AuditMatrix play right-to-left at 320px and the default width, where mirrored horizontal columns are asserted. Gap: no right-to-left check asserts that a horizontal-labels label sits on the inline-start side of its control. | `audit:FormLayout/behavior`      |
 | FR4, ORD1      | `FormLayout.test.tsx` context and nesting tests; `Layer/layerScopedContext.test.tsx`                                                | Default, explicit, nested; content in a fixed Layer and an inline Dialog | A lost default or value, lost shadowing by an inner layout's explicit values, or content inside a layer that still reads the outer `defaultOptionality` fails. Gap: no test covers an inner layout with unset props (which supplies its own defaults) or `direction` across a layer boundary.                                                                                                                                                                                                          | `audit:FormLayout/behavior`      |
-| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. Gap: no test covers Typeahead, Tokenizer, FileInput, or Slider under a `required` default, which do not expose it.                                                                                                                                                                                                                                                                                       | `audit:FormLayout/accessibility` |
+| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. FileInput, Slider, Typeahead, and Tokenizer tests cover a `required` default.                                                                                                                                                                                                                                                                                                                            | `audit:FormLayout/accessibility` |
 | FR6, ORD2      | `FormLayout.test.tsx` ref, passthrough, and owned-metadata tests; `themingTargets.test.ts`                                          | Ref, attributes, colliding `data-direction`                              | A ref on a non-`div`, a dropped `id` or `role`, or a replaced `data-direction` fails. Gap: no test covers event props or the styling-input merge order.                                                                                                                                                                                                                                                                                                                                                | `audit:FormLayout/api`           |
 | AR1, AR3       | `FormLayout.test.tsx` div and passthrough tests; `FormLayout.stories.tsx` play checks                                               | Plain root; caller `role`                                                | A non-`div` root or a dropped caller `role` fails. Horizontal columns that do not mirror right-to-left fail the AuditMatrix play under the story play guard. Gap: no check fails if FormLayout adds a role of its own.                                                                                                                                                                                                                                                                                 | `audit:FormLayout/accessibility` |
 | PR1            | Source review                                                                                                                       | Every direction                                                          | Gap: no automated check covers context identity or added resources.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `audit:FormLayout/behavior`      |

package/src/Heading/Heading.tsx

@@ -45,7 +45,7 @@ import {
 import {useTruncation} from '../Text/useTruncation';
 import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';

package/src/Icon/Icon.tsx

@@ -38,7 +38,7 @@ import {useThemeName} from '../theme/useTheme';
 import {resolveIcon} from './globalIconRegistry';
 import type {IconName, NamespacedIconName} from './globalIconRegistry';
 import type {IconVariant} from './index';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {useIconSize} from './IconDefaultSizeContext';
 import {iconSizeStyles, type IconSize} from './IconSize.stylex';

package/src/Indicator/CheckIndicator.spec.md

@@ -1,20 +1,19 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:CheckIndicator
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: 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,
-    apps/storybook/stories/Indicator.stories.tsx,
   ]
 modules: []
 families: []
@@ -33,17 +32,17 @@ system_specs: []
 
 ## 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 | The released component and default state behavior remain unchanged. The checked glyph path currently drops the declared `ref`; this draft records that current-authority gap without choosing a new DOM or ref contract.                                   |
-| 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 any claim that the checked-path ref gap is resolved. |
-| 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`.                                                                         |
+| 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 only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -52,7 +51,8 @@ Render the replaceable, decorative checkmark used by a host to show that one opt
 ## Compatibility and migration
 
 - Released default preserved: yes
-- Compatibility class: observational only; no runtime or public-type change
+- 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
 
@@ -68,29 +68,29 @@ Consumer migration instructions belong in consumer docs and release notes.
 **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:RadioIndicator`.
+- 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` | observed; empty-container policy unsettled | unsupported values follow React rendering behavior |
+| 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  | Candidate invariant                                                                                                                                                                                                                                                                                                                                              | Basis                                                                     | Draft review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ |
-| 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`                  | verify             |
-| FR2 | The default component MUST render no element when `state="unchecked"` and no replacement content is present.                                                                                                                                                                                                                                                     | shipped source, docs, tests, and stories                                  | verify             |
-| FR3 | The current implementation uses shallow `isRenderable(children)` replacement 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. This draft does not settle whether empty-container behavior should remain public policy. | shipped source and regression tests                                       | verify             |
-| FR4 | Every rendered root MUST preserve supported DOM props, `className`, `style`, and `xstyle` while keeping component-owned accessibility precedence. Under `architecture:public-component-api/INV8`, the declared ref also MUST reach the promised root; the replacement-content span does, but the checked Icon path currently drops it.                           | `architecture:public-component-api/INV5,INV6,INV8`; shipped source review | human decision     |
-| 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`        | verify             |
-| 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                    | verify             |
+| 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
 
@@ -126,7 +126,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | 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` owns anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together. This component draft does not add an `anatomy-theming:v1` block while that shared consumer record remains the canonical cross-component inventory; the block is optional during migration. CheckIndicator owns no persistent chrome and delegates its built-in checked mark to Icon.
+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
 
@@ -136,23 +136,28 @@ The shared `Indicator.doc.mjs` owns anatomy and targets for CheckboxIndicator, C
 
 ## Verification map
 
-| Contract    | Verification                                                | Representative states                                                                   | Mutation or failure expectation                                                                                             | Audit section                   |
-| ----------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1–FR3     | `Indicator.test.tsx` state and replacement-content cases    | checked, unchecked, empty scalar, visible child, numeric 0                              | Removing the glyph, adding unchecked chrome, or choosing the wrong children branch fails DOM assertions.                    | `audit:CheckIndicator/behavior` |
-| FR1, AR1    | `Indicator.test.tsx` decorative-contract cases              | glyph and replacement roots; hostile `aria-hidden` input                                | Removing or reordering owned `aria-hidden` exposes duplicate semantics.                                                     | `audit:CheckIndicator/a11y`     |
-| FR4         | `Indicator.test.tsx`, strict lint, and source review        | neutral DOM props on both roots; replacement-root class; checked-path style composition | Passthrough stops reaching a rendered root or the checked Icon stops receiving composed `className`, `style`, and `xstyle`. | `audit:CheckIndicator/api`      |
-| FR4 ref gap | source review                                               | checked Icon root and replacement-content span                                          | The declared ref remains `null` on the checked path while reaching the replacement span.                                    | `audit:CheckIndicator/api`      |
-| FR5–FR6     | source review, Icon target guards, and rendered evidence    | checked, disabled, replacement content; light/dark                                      | A wrapper separates the host target from the painter or semantic color stops reaching the mark.                             | `audit:CheckIndicator/theming`  |
-| All         | `Indicator.stories.tsx`, component-scoped axe and RTL audit | all states, sizes, disabled, replacement content                                        | A required rendered state is unreachable or gains an accessibility/RTL failure.                                             | `audit:CheckIndicator/testing`  |
+| 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
 
-None. This draft records only verified shipped behavior.
+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`) This observational draft records the current shallow branch without approving it as future policy.
+- **OQ2 — Should empty React containers continue to suppress the built-in state mark?** (`human-api`) FR3 records that they do today.
 
 ## Content boundary
 

package/src/Indicator/CheckIndicator.tsx

@@ -34,7 +34,8 @@ import * as stylex from '@stylexjs/stylex';
 import type {SVGProps} from 'react';
 import {Icon} from '../Icon/Icon';
 import {colorVars} from '../theme/tokens.stylex';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import type {IndicatorProps} from './types';
 
 /** The check glyph matches the control sizes the indicator families share. */

package/src/Indicator/CheckboxIndicator.spec.md

@@ -1,20 +1,20 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:CheckboxIndicator
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: 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,
-    apps/storybook/stories/Indicator.stories.tsx,
   ]
 modules: []
 families: []
@@ -39,11 +39,11 @@ system_specs: []
 | 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 | The released component and legacy `checkbox` target remain supported. This draft records shipped behavior and introduces no API or runtime change.                                                 |
-| Review checks           | Reject lost `aria-hidden`, missing state marks, dropped passthrough/ref/styling, changed replacement precedence, or removal of the legacy target before its approved window.                       |
+| 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 only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -52,9 +52,10 @@ Render the replaceable, decorative visual that communicates a checkbox owner's u
 ## Compatibility and migration
 
 - Released default preserved: yes
-- Compatibility class: observational only; no runtime or public-type change
+- 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: the deprecated `checkbox` target remains emitted beside `checkbox-indicator` under `architecture:component-theming-surface/INV12`
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -73,24 +74,24 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept             | Closed values or states                 | Meaning                                                                                                                                                       | Availability by variant/orientation/state | Default            | Owner                         | Stability                                  | Invalid-value behavior                             |
-| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------ | ----------------------------- | ------------------------------------------ | -------------------------------------------------- |
-| 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` | observed; empty-container policy unsettled | unsupported values follow React rendering behavior |
+| 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  | Candidate invariant                                                                                                                                                                                                                                                                                                                  | Basis                                                              | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------ |
-| 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`           | verify             |
-| 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                           | verify             |
-| FR3 | The current implementation uses shallow `isRenderable(children)` replacement precedence: nullish values, booleans, and the empty string keep the state mark; React elements and containers replace it even when descendants render nothing. This draft does not settle whether empty-container behavior should remain public policy. | shipped source and regression tests                                | verify             |
-| 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`                 | verify             |
-| FR5 | The canonical root target MUST be `checkbox-indicator`; `checkbox` MUST remain a same-element deprecated alias until its approved removal window.                                                                                                                                                                                    | `architecture:component-theming-surface/INV4,INV6,INV12`           | settled            |
-| FR6 | Size, checked/indeterminate, and disabled state MUST be reflected on the root target; the check and dash MUST retain their dedicated painting targets.                                                                                                                                                                               | shipped source; `architecture:component-theming-surface/INV4,INV6` | verify             |
-| 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                                 | verify             |
+| 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
 
@@ -129,32 +130,34 @@ Consumer migration instructions belong in consumer docs and release notes.
 | 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` owns anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together. This component draft does not add an `anatomy-theming:v1` block while that shared consumer record remains the canonical cross-component inventory; the block is optional during migration. The deprecated `checkbox` alias still maps to the CheckboxIndicator chrome for compatibility and is not a separate anatomy part.
+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, reflected state, and deprecated-alias compatibility.
+- `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              | every built-in path; hostile `aria-hidden` input                 | Removing or reordering owned `aria-hidden` exposes duplicate semantics.                      | `audit:CheckboxIndicator/a11y`            |
-| FR2–FR3  | `Indicator.test.tsx` state and replacement-content cases    | unchecked, checked, indeterminate, empty scalar, visible child   | Removing a state mark or choosing the wrong children branch fails observable DOM assertions. | `audit:CheckboxIndicator/behavior`        |
-| FR4      | `Indicator.test.tsx`, strict lint, and public type checks   | neutral DOM props, ref, class/style/xstyle                       | Passthrough, ref, or styling composition stops reaching the root.                            | `audit:CheckboxIndicator/api`             |
-| FR5–FR6  | theming target guards and `Indicator.test.tsx`              | canonical/legacy targets; size/state/disabled axes               | A target disappears, moves off its painter, or loses reflected state.                        | `audit:CheckboxIndicator/theming`         |
-| FR7, AR2 | source review plus exact-head Chromium evidence             | light/dark; checked/indeterminate; reduced motion; forced colors | Motion persists under reduced motion or a state mark disappears in forced colors.            | `audit:CheckboxIndicator/design-rendered` |
-| All      | `Indicator.stories.tsx`, component-scoped axe and RTL audit | all states, sizes, disabled, replacement content                 | A required rendered state is unreachable or gains an accessibility/RTL failure.              | `audit:CheckboxIndicator/testing`         |
+| 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
 
-None. This draft records only verified shipped behavior.
+No component-local decision.
 
 ## Open questions
 
-- Whether empty React containers should continue to suppress the built-in state mark is intentionally unsettled; this observational draft records the current branch without approving it as future policy.
+- **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
 

package/src/Indicator/CheckboxIndicator.tsx

@@ -16,7 +16,9 @@ import {
   easeVars,
   radiusVars,
 } from '../theme/tokens.stylex';
-import {isRenderable, mergeProps, themeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
+import {themeProps} from '../utils/themeProps';
 import {indicatorScope} from './indicator.markers.stylex';
 import type {IndicatorProps} from './types';