@astryxdesign/core 0.7.5 → 0.7.6-canary.5cd7a15

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';
 

package/src/Indicator/Indicator.spec.md

@@ -0,0 +1,188 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Indicator
+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]
+verified_by:
+  [
+    packages/core/src/Indicator/Indicator.test.tsx,
+    packages/core/src/Indicator/indicatorRegistry.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+    architecture:theme-authoring-contract,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Indicator component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                   |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. `@astryxdesign/core/Indicator` exports the three built-in indicators (`CheckboxIndicator`, `CheckIndicator`, `RadioIndicator`), the shared indicator props and types, the default registry, and name-based resolution.                                       |
+| Behavior                | Hosts draw a decorative control visual by name (`check`, `checkbox`, `radio`). A theme's `indicators` entry for that name replaces it in every host that resolves indicators by name; otherwise the built-in renders. Every indicator is hidden from assistive technology. |
+| End-user impact         | People see one consistent mark for a chosen option, a checkbox, or a radio across the components that resolve indicators by name, and screen-reader users hear the host control's semantics, never a duplicate.                                                            |
+| Builder impact          | None.                                                                                                                                                                                                                                                                      |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Three hosts render the built-ins directly instead of resolving by name; listed under Current-state impact.                                                                                                       |
+| Review checks           | Reject an indicator that is exposed to assistive technology, a theme override that a host resolving by name ignores, a falsy `children` that suppresses the built-in mark, or a role or tab stop on an indicator.                                                          |
+| Governing rules         | `architecture:component-theming-surface`; `architecture:public-component-api` INV5; `architecture:theme-authoring-contract`.                                                                                                                                               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Indicator is the shared, replaceable set of decorative control visuals: the
+mark on a chosen option, the box a checkbox draws, and the circle a radio
+draws. It owns the indicator names, theme replacement by name, the shared
+decorative prop contract, and RadioIndicator. Consumer usage lives in
+`Indicator.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; with no theme override, `check`,
+  `checkbox`, and `radio` resolve to the built-ins
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: not applicable; hosts supply `state`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The core indicator names and the default registry that maps them to the
+  built-ins.
+- Theme replacement by name and the shared indicator prop contract.
+- RadioIndicator, documented as an inline component of `Indicator.doc.mjs`,
+  with the `radio-indicator` and `radio-indicator-dot` targets.
+- The `indicatorScope` marker hosts put on the element whose hover drives the
+  indicator's hover tint.
+
+**Does not own / non-goals**
+
+- CheckboxIndicator — owned by `component:CheckboxIndicator`.
+- CheckIndicator — owned by `component:CheckIndicator`.
+- Role, name, state, focus, keyboard, and activation of the host control —
+  owned by each host (CheckboxInput, RadioList, Selector, menu rows).
+- `useIndicator` and `getIndicator` as API — a public hook and function without
+  their own module records; uncontracted beyond the resolution FR2 states.
+
+## Public concepts
+
+| Concept             | Closed values or states                                | Meaning                                           | Availability by variant/orientation/state | Default  | Owner                 | Stability | Invalid-value behavior                                              |
+| ------------------- | ------------------------------------------------------ | ------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------- |
+| Indicator name      | `check`, `checkbox`, `radio`, plus augmented names     | Which visual a host draws.                        | Always.                                   | —        | `component:Indicator` | Stable    | An augmented name no theme supplies resolves to nothing.            |
+| State               | `unchecked`, `checked`, and `indeterminate` (checkbox) | The host's selection state.                       | Per indicator family.                     | required | `component:Indicator` | Stable    | TypeScript rejects values outside the family.                       |
+| Size                | `sm`, `md`                                             | Indicator box size.                               | Always.                                   | `md`     | `component:Indicator` | Stable    | TypeScript rejects other values.                                    |
+| Replacement content | renderable `children`                                  | Content drawn instead of the built-in state mark. | Always.                                   | none     | `component:Indicator` | Stable    | Nullish, boolean, and empty-string children keep the built-in mark. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | The default registry maps exactly `check` → CheckIndicator, `checkbox` → CheckboxIndicator, and `radio` → RadioIndicator.                                                                                                                                                                                                                                                                                                                                                                | Current tests                                           |
+| FR2 | A host resolves an indicator by name from the nearest theme: the theme's `indicators` entry for that name wins, otherwise the built-in. One override reaches every host that resolves that name. The Tokenizer bottom sheet and the Lab MobileTokenizer and MobilePowerSearch value editor render CheckboxIndicator and RadioIndicator directly, so a theme's `checkbox` or `radio` entry does not reach them. An augmented name resolves only when a theme supplies it.                 | `architecture:theme-authoring-contract`; current tests  |
+| FR3 | Every built-in indicator root sets `aria-hidden="true"` after caller props, so a caller cannot expose it; the public props type rejects `role` and `tabIndex`. Indicators receive `state`, `size`, `isDisabled`, and `children` and nothing that would give them semantics.                                                                                                                                                                                                              | `architecture:public-component-api` INV5; current tests |
+| FR4 | Renderable `children` replace the built-in state mark inside the indicator; nullish, boolean, and empty-string children keep it, and `0` counts as content.                                                                                                                                                                                                                                                                                                                              | Current tests                                           |
+| FR5 | RadioIndicator renders one circular span (20 or 24 CSS px) whose border and fill follow the state: an emphasized border on the surface when unchecked, an accent fill when checked with an on-accent dot (8 or 10 CSS px) inside. Disabled halves the opacity and mutes the border (and the fill when unchecked). Under a hover-capable pointer, hovering the host's `indicatorScope` tints it. The dot stays visible under forced colors. Transitions are instant under reduced motion. | Current source and tests                                |
+| FR6 | RadioIndicator's root carries `astryx-radio-indicator` with `data-size`, `data-checked`, and `data-disabled`; the dot carries `astryx-radio-indicator-dot` with `data-size`. No alias target is emitted. Caller props, `ref`, `className`, `style`, and `xstyle` reach the root.                                                                                                                                                                                                         | `architecture:component-theming-surface`; current tests |
+
+### Allowed variation
+
+- **AV1 — Replacement.** A theme may replace any named indicator with a
+  component that honors FR3.
+- **AV2 — Theme paint.** Themes may restyle the built-ins through their
+  targets without replacing them.
+
+### Representative states
+
+| State             | Required invariant                                    | Allowed variation |
+| ----------------- | ----------------------------------------------------- | ----------------- |
+| No theme override | Built-ins render for each name.                       | —                 |
+| Theme override    | Every host that resolves the name draws the override. | Override design.  |
+| Radio checked     | Accent circle with dot; `data-checked`.               | Size.             |
+| Falsy children    | Built-in mark still renders.                          | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Resolution.** Nearest theme's `indicators[name]`, then the built-in,
+  then nothing for an unsupplied augmented name.
+- **ORD2 — Attributes.** Caller props, then the indicator's own `aria-hidden`.
+
+### Performance and resources
+
+- **PR1 — Pure render.** Indicators own no state, effect, listener, or
+  observer.
+
+## Accessibility contract
+
+- **AR1 — Decorative.** Indicators are hidden from assistive technology; the
+  host owns all semantics (FR3).
+- **AR2 — Forced colors.** The radio dot stays visible under forced colors.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Radio circle     | Emphasized border unchecked; accent fill checked. | Current source           | Supporting     | FR5, FR6           |
+| Radio dot        | On-accent dot when checked.                       | Current source           | Supporting     | FR5, FR6           |
+
+No design record governs Indicator. The checkbox and check visuals are owned by
+their own records.
+
+## Family and system relationships
+
+- `architecture:theme-authoring-contract` owns how a theme supplies
+  `indicators`.
+- `component:CheckboxIndicator` and `component:CheckIndicator` own the other two
+  built-ins.
+- CheckboxInput, RadioListItem, Selector, and menu selection rows host
+  indicators.
+
+## Verification map
+
+| Contract        | Verification                                                                                               | Representative states                                                                                      | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Audit section                   |
+| --------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| FR1, FR2        | `indicatorRegistry.test.tsx`; `Indicator.test.tsx` useIndicator suite                                      | No theme; theme override; augmented names                                                                  | A wrong default, an ignored override, or a resolved unsupplied name fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `audit:Indicator/behavior`      |
+| FR3             | `Indicator.test.tsx` decorative-contract suite                                                             | Each built-in in the checked state; a caller `aria-hidden={false}`; `role` and `tabIndex` as literal props | An indicator a caller can expose, a dropped ordinary prop, or an accepted literal `role` or `tabIndex` fails. Evidence gap: no test checks `aria-hidden` on the unchecked states.                                                                                                                                                                                                                                                                                                                                                                | `audit:Indicator/accessibility` |
+| FR4             | `Indicator.test.tsx` falsy-children suite                                                                  | `null`, `false`, `''`, `0`, real children                                                                  | A falsy child (`false`, `null`, `undefined`, or `''`) that suppresses any built-in's mark fails, and CheckIndicator treating `0` as empty fails. Evidence gap: no test renders `0` as children of CheckboxIndicator or RadioIndicator.                                                                                                                                                                                                                                                                                                           | `audit:Indicator/behavior`      |
+| FR5, FR6, AR2   | `Indicator.test.tsx` radio-dot, disabled, and target-name cases                                            | Checked and unchecked; disabled; canonical targets                                                         | A dot when unchecked, no dot when checked, a missing checked `data-checked` or disabled `data-disabled`, or an alias target fails. Evidence gap: no test asserts the radio sizes, the state colors (emphasized border, accent fill, on-accent dot), the instant transitions under reduced motion, the disabled opacity and border, the hover tint, the forced-colors dot (the RadioList forced-colors case passes on any matching rule), radio `data-size` on the root and dot, `ref`, or caller `className`, `style`, and `xstyle` on the root. | `audit:Indicator/theming`       |
+| ORD1, ORD2, PR1 | Covered by the FR2 and FR3 rows. Evidence gap: no test asserts the absence of state, effects, or listeners | —                                                                                                          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `audit:Indicator/behavior`      |
+
+## Current-state impact
+
+- **Direct indicator imports (FR2).** The Tokenizer bottom sheet and the Lab
+  MobileTokenizer and MobilePowerSearch value editor render CheckboxIndicator
+  and RadioIndicator directly, so a theme's `checkbox` or `radio` override does
+  not reach them.
+
+## Decision log
+
+No component-local decision.
+
+## 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/RadioIndicator.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';
 

package/src/Item/Item.tsx

@@ -48,7 +48,8 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import {ItemDescriptionContext} from './ItemDescriptionContext';
 import {ItemMarkerColumnsContext} from './ItemMarkerColumnsContext';
 import {useMergedRefs} from '../hooks/useMergedRefs';

package/src/Item/ItemSwipeLayer.tsx

@@ -29,7 +29,7 @@ import {
   spacingVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';