@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/ProgressBar/ProgressBar.spec.md

@@ -1,285 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:ProgressBar
-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/ProgressBar/ProgressBar.test.tsx,
-    packages/core/src/ProgressBar/__tests__/ProgressBar.a11y.test.tsx,
-    packages/core/src/ProgressBar/__tests__/ProgressBar.a11y.chromium.spec.ts,
-    packages/core/src/ProgressBar/__tests__/ProgressBarMotion.a11y.chromium.spec.ts,
-    packages/core/src/theme/themingTargets.test.ts,
-    .github/visual-baseline/manifest.json,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:theme-authoring-contract,
-    architecture:theme-tokens,
-    architecture:internationalization,
-  ]
-contributing: []
-system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2, spec:AST-009]
----
-
-# ProgressBar component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                              |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `label`, `value`, `max`, `isLabelHidden`, `hasValueLabel`, `formatValueLabel`, `variant`, `isIndeterminate`, `marks`, `isDisabled`, root `BaseProps`, and a root `ref`.                                               |
-| Behavior                | A labelled `progressbar` whose fill shows the clamped value against a muted track, or slides while indeterminate, with optional value text and labelled target marks.                                                 |
-| End-user impact         | People see how far an operation has gone, and assistive technology reads the name and value; marks reveal their labels on hover or focus.                                                                             |
-| Builder impact          | A builder's `data-variant` replaces the reflected variant today, so theme rules for the bar's real variant stop matching (FR8 gap); otherwise none.                                                                   |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Implementation gaps are listed under Current-state impact.                                                                                 |
-| Review checks           | Reject a determinate bar whose correctness depends on nearby text, a value outside `[0, max]`, a leaked `NaN`, value semantics while indeterminate, or a target off its part.                                         |
-| Governing rules         | `component:ProgressBar/DEC-1`; `spec:AST-002`; `architecture:component-theming-surface`; `architecture:theme-tokens` INV11; `architecture:internationalization` INV1a; `architecture:public-component-api` INV5–INV8. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-ProgressBar communicates the progress of an operation. A determinate bar is a
-sufficient standalone visual: people can distinguish completed from remaining
-progress without depending on visible text rendered elsewhere. External text
-may supplement the bar, but it is not a prerequisite for the bar to be correct.
-
-Consumer syntax and examples belong in `ProgressBar.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes` — determinate, `value` 0, `max` 100,
-  `accent`, visible label, no value text, no marks.
-- Compatibility class: records shipped behavior; the four canonical
-  `progress-bar*` targets are the only target classes.
-- Controlled/uncontrolled behavior: not applicable; `value` is caller-owned.
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Value text assembled outside the catalog (FR3).** The default value text
-  and `aria-valuetext` are `${percent}%` built in code, so locales that write
-  percentages differently read and see the English form, where
-  `architecture:internationalization` INV1a has Astryx-owned text come from
-  one catalog message.
-- **Marks are focusable without a role or name (FR7).** Each mark is a
-  focusable `span` with no role and no accessible name; its label reaches
-  assistive technology only as a description, and only once the tooltip code
-  has loaded, so screen reader users land on an unnamed stop (WCAG 2.2 SC
-  4.1.2).
-- **Caller `data-variant` replaces the reflected variant (FR8).** Caller props
-  spread after the root's theme attributes, so a caller `data-variant`
-  replaces the reflected value and theme rules for the real variant stop
-  matching, where `architecture:public-component-api` INV5 keeps
-  component-owned behavior from being overwritten.
-- **Theme-added variant has no baseline fill (FR4).** The variant map is
-  exported for themes to extend, but an added variant matches no built-in fill
-  or on-fill mark color, so the fill paints nothing until a theme styles it, where
-  `architecture:component-theming-surface` INV14 asks for a safe baseline.
-- **Indeterminate slide follows any right-to-left ancestor (FR6).** The
-  indeterminate slide and the centering of marks mirror under any
-  right-to-left ancestor rather than the bar's own direction, so in a
-  left-to-right region of a right-to-left page they run against the label,
-  where `architecture:internationalization` INV11 resolves mirroring from the
-  rendered region.
-
-## Ownership boundary
-
-**Owns**
-
-- A sufficient standalone visual distinction between completed and remaining
-  progress for every determinate presentation the component provides.
-- The container, label row, track (the `progressbar` element), fill, and marks,
-  and their `progress-bar`, `progress-bar-track`, `progress-bar-fill`, and
-  `progress-bar-mark` targets.
-- Value clamping, value text, indeterminate motion, and mark placement.
-
-**Does not own / non-goals**
-
-- External visible labels, values, or descriptions — owned by the product
-  callsite and supplementary to the bar.
-- A separate public target for the built-in label or value text; none exists.
-- The exact standalone contrast treatment — a human design decision (OQ1).
-- Theme token definitions — owned by `architecture:theme-tokens`.
-- The mark tooltip's behavior — owned by `component:Tooltip`.
-
-## Public concepts
-
-| Concept          | Closed values or states                                                                                 | Meaning                                                             | Availability by variant/orientation/state | Default                 | Owner                   | Stability                         | Invalid-value behavior                                           |
-| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | ----------------------- | ----------------------- | --------------------------------- | ---------------------------------------------------------------- |
-| Progress mode    | determinate; indeterminate                                                                              | Whether completed progress is known.                                | All variants                              | determinate             | `component:ProgressBar` | Stable                            | —                                                                |
-| Value and range  | finite `value` within `0`–`max`                                                                         | Completed amount.                                                   | Determinate                               | 0 of 100                | caller                  | Stable                            | Clamped to `[0, max]`; a non-finite value or `max` counts as 0.  |
-| Label            | string, visible or visually hidden                                                                      | The bar's accessible name.                                          | Always                                    | visible                 | caller                  | Stable                            | —                                                                |
-| Value text       | hidden; shown; custom formatter                                                                         | Optional visible value beside the label, also the `aria-valuetext`. | Determinate                               | hidden; rounded percent | `component:ProgressBar` | Stable                            | Ignored when indeterminate.                                      |
-| Variant          | `accent`, `success`, `warning`, `error`, `neutral`; theme-added values through the exported variant map | Fill color.                                                         | Always                                    | `accent`                | `component:ProgressBar` | Stable                            | An added value paints no fill until a theme styles it (FR4 gap). |
-| Disabled         | `true`, `false`                                                                                         | Muted fill, label, and marks.                                       | Always                                    | `false`                 | `component:ProgressBar` | Stable                            | —                                                                |
-| Marks            | `{value, label}` list                                                                                   | Labelled ticks on the track.                                        | Determinate                               | none                    | caller                  | Stable                            | Non-finite values are dropped; others clamp to the track.        |
-| Visual treatment | one sufficient standalone treatment; exact form open                                                    | How the graphic distinguishes completed from remaining progress.    | Determinate                               | —                       | `component:ProgressBar` | Decided by DEC-1; form open (OQ1) | No incomplete public mode.                                       |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Basis                                                                   |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| FR1 | Every determinate presentation ProgressBar provides is a sufficient standalone visual for distinguishing completed from remaining progress; external visible text may supplement it but is never required, and supplementary text or graphics never substitute for that distinction. ProgressBar does not make visual correctness depend on caller-declared external content it cannot verify or associate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `component:ProgressBar/DEC-1`; `spec:AST-002`                           |
-| FR2 | New public API that adjusts the visual distinction is considered only after the component has a correct base behavior and a stable caller-owned distinction still remains.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `component:ProgressBar/DEC-1`; `spec:AST-002`                           |
-| FR3 | The root holds a label row and a track. The label names the track (`role="progressbar"`) through `aria-labelledby`; `isLabelHidden` hides it visually only. When determinate, the track exposes `aria-valuenow` (the clamped value), `aria-valuemin` 0, `aria-valuemax` (`max`), and `aria-valuetext` from `formatValueLabel`, which defaults to the rounded percentage; `hasValueLabel` shows the same text beside the label. A zero or non-finite `max` gives 0% and never renders `NaN`. Astryx-owned value text comes from one catalog message (`architecture:internationalization` INV1a). Implementation gap: the default text is assembled in code (Current-state impact).                                                                                                                                                                                                                                                                                                      | Current source and tests                                                |
-| FR4 | The track is 8px high, fully rounded, in `--color-background-muted`, and clips the fill. The determinate fill spans the track and slides along it so its leading edge sits at the clamped percentage, mirrored by the bar's own writing direction, moving over `--duration-medium` when the value changes; under reduced motion a new value lands at once on every pointer (`design:reduced-motion` DR1). The fill paints `--color-accent`, `--color-success`, `--color-warning`, or `--color-error`, or `--color-text-disabled` for `neutral` and disabled bars; a theme-added variant has a safe theme-independent fill (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added variant paints no fill and no on-fill mark color until a theme styles it (Current-state impact). In forced colors the fill is sized to the value instead of sliding and keeps a 1px `CanvasText` outline so its shape stays visible (`architecture:theme-tokens` INV11). | Current source and tests                                                |
-| FR5 | `isDisabled` mutes the fill, label, value text, and marks and adds no ARIA state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests                                                |
-| FR6 | `isIndeterminate` removes every value attribute and the value text and slides a 40% fill across the clipped track, mirrored by the bar's own rendered direction (`architecture:internationalization` INV11); under reduced motion the loop slows from 1.5s to 3s per pass. Whether the loop stops under reduced motion is open (OQ2). Implementation gap: the slide, and the centering of marks, mirror under any right-to-left ancestor rather than the bar's own direction, so in a left-to-right region of a right-to-left page they run against the label (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests                                                |
-| FR7 | Each finite mark renders, outside the `progressbar` element, a tick at its clamped position whose tooltip shows its label on hover and focus; marks inside the filled part take the fill's contrasting color, and marks do not render while indeterminate. A focusable mark exposes its label as its accessible name (WCAG 2.2 SC 4.1.2). Implementation gap: marks are focusable `span`s with no role or name, labelled only as a description once the tooltip loads (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests                                                |
-| FR8 | The root carries `progress-bar` reflecting `variant`, the track `progress-bar-track`, the fill `progress-bar-fill` reflecting the resolved fill variant, and each mark `progress-bar-mark` reflecting the resolved fill variant and placement; the label and value text carry no target. Reflected state stays component-owned (`architecture:public-component-api` INV5). Implementation gap: a caller `data-variant` replaces the root's reflected variant (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                                                |
-| FR9 | `ref` and `data-testid` reach the root; supported DOM, data, ARIA, and event props reach the root, while the reflected theme attributes stay component-owned (FR8); `xstyle`, `className`, and `style` compose after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests; `architecture:public-component-api` INV5–INV8 |
-
-### Allowed variation
-
-- **AV1 — Exact visual treatment.** Shape, token choice, and other rendering
-  details may vary if every resulting presentation satisfies FR1.
-- **AV2 — Themes.** Themes may express their visual language through the
-  targets while preserving the standalone distinction.
-
-### Representative states
-
-| State                | Required invariant                                                                                     | Allowed variation |
-| -------------------- | ------------------------------------------------------------------------------------------------------ | ----------------- |
-| Determinate, partial | Completed and remaining progress are distinguishable from the graphic alone; value attributes present. | Variant.          |
-| With value text      | The graphic still satisfies FR1; the text supplements it.                                              | Formatter.        |
-| Label hidden         | The bar keeps its accessible name.                                                                     | —                 |
-| Indeterminate        | No value attributes; sliding fill; slower under reduced motion (OQ2).                                  | Variant.          |
-| With marks           | Ticks outside the `progressbar`, labelled by tooltip.                                                  | Mark labels.      |
-
-### Transformation and precedence order
-
-- **ORD1 — Value.** Non-finite → 0; clamp to `[0, max]`; a non-positive `max`
-  gives 0%.
-- **ORD2 — Presentation.** Resolve determinate or indeterminate first; external
-  content never weakens the determinate visual requirement.
-
-### Performance and resources
-
-- **PR1 — No external-content inspection.** ProgressBar adds no DOM
-  observation, measurement, or relationship discovery to decide whether nearby
-  text makes a weaker bar acceptable. Mark tooltips load lazily.
-
-## Accessibility contract
-
-- **AR1 — Standalone non-text distinction.** A determinate bar satisfies the
-  applicable non-text contrast requirement without relying on external visible
-  text.
-- **AR2 — Programmatic semantics.** The track is a named `progressbar` with
-  value semantics while determinate and none while indeterminate, independent
-  of the visible treatment.
-- **AR3 — Supplementary text is not inferred.** ProgressBar does not claim that
-  external text is present, visible, equivalent, or associated.
-
-## Design relationships
-
-| Anatomy or state         | Design requirement                                      | Representation authority    | Hierarchy role | Component contract |
-| ------------------------ | ------------------------------------------------------- | --------------------------- | -------------- | ------------------ |
-| Progress bar             | Arranges the label row and track.                       | Current source and docs     | Supporting     | FR3, FR8           |
-| Label and value text     | Name the operation and optionally supplement its value. | Current source and docs     | Supporting     | FR3                |
-| Fill and remaining track | Provide a sufficient standalone distinction.            | DEC-1; treatment open (OQ1) | Prominent      | FR1, FR4           |
-| Mark                     | An optional labelled target on the track.               | Current source and docs     | Supporting     | FR7                |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Progress bar": {"target": "progress-bar"},
-  "Label": {
-    "none": {
-      "reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."
-    }
-  },
-  "Value text": {
-    "none": {
-      "reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."
-    }
-  },
-  "Track": {"target": "progress-bar-track"},
-  "Fill": {"target": "progress-bar-fill"},
-  "Mark": {"target": "progress-bar-mark"}
-}
-```
-
-The `Label` and `Value text` dispositions are current facts, not decisions that
-those parts stay untargeted.
-
-## Family and system relationships
-
-- `architecture:public-component-api` and `spec:AST-002/DEC-1` govern whether a
-  caller-owned distinction justifies a public prop; FR2 applies them.
-- `architecture:component-theming-surface` and
-  `architecture:theme-authoring-contract` govern targets and theme overrides.
-- `architecture:theme-tokens` governs the token vocabulary and forced-colors
-  boundaries; FR4 applies INV11.
-- `architecture:internationalization` governs Astryx-owned text; FR3 records
-  the value-text gap.
-- `component:Tooltip` owns the mark tooltip.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                               | Representative states                                                           | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                            | Audit section                |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1, AR1, AR3       | Stable visual baselines `core-progressbar--default` (neutral) and `core-progressbar--with-target-mark` (probe)                                             | Default; probe theme with a mark                                                | A changed fill or track comes back changed for review. Gap: no real-browser contrast check across shipped themes and color modes proves the standalone distinction (OQ1 holds the treatment).                                                                                                                                                                                                                                                                              | `audit:ProgressBar/visual`   |
-| FR2                 | Public type and consumer-doc review                                                                                                                        | Current props                                                                   | Gap: no automated check; a new visual-distinction prop is a review finding.                                                                                                                                                                                                                                                                                                                                                                                                | `audit:ProgressBar/api`      |
-| FR3, ORD1, AR2      | `ProgressBar.test.tsx` label, value text, formatter, clamp, zero and NaN tests; `ProgressBar.a11y.test.tsx` and `ProgressBar.a11y.chromium.spec.ts` states | Determinate; formatted; complete; label hidden                                  | A missing name, a value outside `[0, max]`, a leaked `NaN`, or wrong `aria-valuetext` fails, including at the accessibility tree. Gap: no test checks the default text in a non-English locale.                                                                                                                                                                                                                                                                            | `audit:ProgressBar/a11y`     |
-| FR4                 | `ProgressBar.test.tsx` track-clip, transform, variant, and forced-colors tests; `ProgressBarMotion.a11y.chromium.spec.ts`                                  | Every variant; value changes; RTL region; reduced motion; forced colors         | A track that does not clip, a fill sized by width outside forced colors, a lost forced-colors outline, a leading edge off the value or unmirrored in an RTL region, a value change that does not land at once under reduced motion, or per-frame layout while moving fails. Gap: the variant colors have no direct check. Gap: the "fixed 8px track height" test only checks that the bar renders, so the track height has no check; no test covers a theme-added variant. | `audit:ProgressBar/visual`   |
-| FR5                 | `ProgressBar.test.tsx` disabled and disabled-mark tests                                                                                                    | Disabled                                                                        | A missing label or undimmed marks fail. Gap: the muted fill and label colors have no direct check.                                                                                                                                                                                                                                                                                                                                                                         | `audit:ProgressBar/visual`   |
-| FR6                 | `ProgressBar.test.tsx` indeterminate suite                                                                                                                 | Every variant; RTL                                                              | Value attributes or value text while indeterminate, a lost label, an unclipped track, or an unmirrored slide fails. Gap: the reduced-motion loop duration has no check. No test covers the slide in a left-to-right region inside a right-to-left page. Gap: the RTL test asserts the right-to-left ancestor selector, so it pins the FR6 gap.                                                                                                                             | `audit:ProgressBar/behavior` |
-| FR7                 | `ProgressBar.test.tsx` target-mark suite                                                                                                                   | None; one; many; clamped; non-finite; on fill; indeterminate; disabled; tooltip | A missing, misplaced, or clipped mark, a mark inside the `progressbar`, a lost tooltip, or a wrong on-fill color fails. Gap: the test asserts that marks have no role and no `aria-label`, which pins the FR7 gap.                                                                                                                                                                                                                                                         | `audit:ProgressBar/a11y`     |
-| FR8                 | `ProgressBar.test.tsx` target-name and mark-target tests; `themingTargets.test.ts`                                                                         | Four canonical targets                                                          | A missing or renamed target fails. Gap: no test covers a caller `data-variant`. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if a part stops carrying its target.                                                                                                                                                                                                                                                                | `audit:ProgressBar/theming`  |
-| FR9                 | `ProgressBar.test.tsx` ref and `data-testid` tests                                                                                                         | Ref; test id                                                                    | A ref that is not a `div` or a lost test id fails. Gap: the ref test checks only that the ref is a `div`, not that it is the root, and no test covers DOM props, `className`, `style`, or the `xstyle` merge order.                                                                                                                                                                                                                                                        | `audit:ProgressBar/api`      |
-| PR1                 | Source review                                                                                                                                              | Every state                                                                     | Gap: no automated check fails if ProgressBar starts inspecting nearby content.                                                                                                                                                                                                                                                                                                                                                                                             | `audit:ProgressBar/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                              | Canonical anatomy and four targets                                              | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                                              | `audit:ProgressBar/theming`  |
-
-## Decision log
-
-### DEC-1 — ProgressBar owns a sufficient standalone visual
-
-**Reference:** `component:ProgressBar/DEC-1`  
-**Decider:** `cixzhang`, `2026-08-30`
-
-ProgressBar must provide a sufficient standalone visual. Visible text inside or
-outside the component may improve understanding, but the bar remains responsible
-for communicating completed versus remaining progress without it.
-
-Public API must not make that correctness depend on external content the
-component cannot carry, associate, or verify. Solve the component behavior first.
-Consider new API only when a stable caller-owned distinction still remains after
-the base behavior is correct.
-
-Rejected: weakening the bar based on a caller claim about nearby content. That
-would move component correctness into an external condition the component cannot
-verify.
-
-## Open questions
-
-- **OQ1 — What exact visual treatment gives every determinate presentation a
-  sufficient standalone completed-versus-remaining distinction across supported
-  variants, themes, and color modes?** (`human-design`)
-- **OQ2 — Under reduced motion, should the indeterminate loop stop or keep
-  sliding at a slower pace?** (`human-design`) Today it slows to 3s per pass.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables or examples, current audit
-results, implementation steps, exact visual values, or system theming rules. It
-links to their owners.

package/src/RadioList/RadioList.spec.md

@@ -1,227 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:RadioList
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers:
-  [
-    public-api,
-    behavior,
-    layout,
-    interaction,
-    motion,
-    theming,
-    styling,
-    accessibility,
-    visual,
-    react-runtime,
-    compatibility,
-  ]
-verified_by:
-  [
-    packages/core/src/RadioList/RadioList.test.tsx,
-    packages/core/src/RadioList/RadioList.fr10.test.tsx,
-    packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
-    packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts,
-  ]
-modules: []
-families: [family:input-fields]
-design_specs: [design:user-states]
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-085]
----
-
-# RadioList component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                   |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. RadioList takes `label`, `value`, `onChange`, `orientation`, `size`, `isDisabled`, `disabledMessage`, `isRequired`, `isOptional`, `status`, `htmlName`, Field props, part props, and RadioListItem children. |
-| Behavior                | A Field-labelled `role="radiogroup"` of native radios sharing one name. Selecting an option calls `onChange(value)`. The group sets the item size, the disabled state, and required semantics.                             |
-| End-user impact         | People choose one option by pointer, touch, or the browser's arrow keys, with a predictable first Tab stop. A group disabled without a reason leaves the tab order, so keyboard users cannot find it.                      |
-| Builder impact          | None.                                                                                                                                                                                                                      |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Native `disabled` on disabled radios conflicts with `spec:AST-085` FR1 and FR7; listed under Current-state impact.                                               |
-| Review checks           | Reject a group without a name, radios that lose their shared name, a selection while disabled, a first Tab stop that lands mid-group with an empty value, or root styling props.                                           |
-| Governing rules         | `family:input-fields` FR10, DEC-7; `spec:AST-085` FR1–FR7; `design:user-states` DR1, DR2 (through RadioListItem); WAI-ARIA radio group pattern.                                                                            |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-RadioList presents a small set of mutually exclusive options as one labelled
-radio group. It owns the group's name, selection value, shared radio name,
-group-level disabled, required, and status semantics, and the entry Tab stop.
-Each option is `component:RadioListItem`. Consumer usage lives in
-`RadioList.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`; `orientation="vertical"`, `size="md"`,
-  not disabled
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: controlled only; `value` is required and
-  `''` means nothing is selected
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The group Field and the `role="radiogroup"` element, its name, description,
-  status, invalid and required state, and the `radio-list` target.
-- The shared radio name, the selected value, and `onChange`.
-- Group disabled and the group disabled-reason tooltip.
-- The entry Tab stop when nothing is selected.
-- Where base, `container*`, and `control*` props land.
-
-**Does not own / non-goals**
-
-- Each option's radio, naming, description, row, disabled item state, and the
-  `radio-list-item` target — owned by `component:RadioListItem`.
-- Arrow-key movement and selection between radios — the browser's native radio
-  group behavior.
-- The radio indicator — owned by the Indicator registry's radio indicator.
-- Group-label and status-message presentation — owned by Field under `family:input-fields` (shared owner section) and
-  `component:FieldStatus`.
-
-## Public concepts
-
-| Concept     | Closed values or states                         | Meaning                                      | Availability by variant/orientation/state | Default      | Owner                 | Stability | Invalid-value behavior                         |
-| ----------- | ----------------------------------------------- | -------------------------------------------- | ----------------------------------------- | ------------ | --------------------- | --------- | ---------------------------------------------- |
-| Value       | string; `''` for none                           | The selected option's value.                 | Always.                                   | required     | `component:RadioList` | Stable    | A value no item carries selects nothing.       |
-| Orientation | `vertical`, `horizontal`                        | Layout of the options.                       | Always.                                   | `vertical`   | `component:RadioList` | Stable    | TypeScript rejects other values.               |
-| Size        | `sm`, `md`                                      | Radio circle size for every item.            | Always.                                   | `md`         | `component:RadioList` | Stable    | TypeScript rejects other values.               |
-| Disabled    | off, on, on with reason                         | Blocks selection on every item.              | A reason applies only with `isDisabled`.  | off          | `component:RadioList` | Stable    | A reason without `isDisabled` renders nothing. |
-| Status      | `error`, `warning`, `success`, optional message | Group validation state.                      | Always; the message is detached.          | none         | `family:input-fields` | Stable    | TypeScript rejects other types.                |
-| Name        | string                                          | The shared radio `name` and form field name. | Always.                                   | generated id | `component:RadioList` | Stable    | Not applicable.                                |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                                                   |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| FR1 | RadioList renders a Field in group-label mode (label rendered as a span, visible unless `isLabelHidden`, description, optional or required marker, label tooltip, detached status) around one `role="radiogroup"` element. The radiogroup is labelled by the group label plus any caller `aria-labelledby`, and described by any caller description, then the description, status message, and disabled reason that exist.                                                                                                                                                                                                                                                              | WAI-ARIA radio group pattern; current tests             |
-| FR2 | Every item's radio shares one `name`: `htmlName` when supplied, otherwise a generated id, so the radios form one native group. The checked radio is the one whose `value` equals the group `value`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current tests                                           |
-| FR3 | Selecting an enabled option calls `onChange(value)` once; RadioList holds no selection of its own.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current tests                                           |
-| FR4 | With an empty `value`, keyboard focus entering the group lands on the first radio that is not natively disabled (in a group disabled with a reason, that is its first `aria-disabled` radio, keeping the enabled focus order under `spec:AST-085` FR1), or stays on the last one when entering backward. Focus moving between radios inside the group is not redirected. With a selection, the selected radio is the Tab stop. Arrow keys follow the browser's native radio behavior, which stops on `aria-disabled` radios.                                                                                                                                                            | WAI-ARIA radio group pattern; current tests             |
-| FR5 | `isDisabled` MUST disable every item: each radio stays focusable with `aria-disabled="true"`, is detached from the form so it does not submit, and refuses selection (`spec:AST-085` FR1–FR3, FR7). With `disabledMessage`, a reason tooltip also opens on group hover and keyboard focus, and the reason MUST describe each focusable radio (`spec:AST-085` FR5, FR7). Implementation gap: the reason describes only the radiogroup, so a focused radio is not described by it; and without a `disabledMessage`, each radio gets native `disabled` instead, which removes it from the tab order, and a radio focused when the group becomes disabled loses focus (`spec:AST-085` FR4). | `spec:AST-085` FR1–FR5, FR7; current tests              |
-| FR6 | `status.type === 'error'` sets `aria-invalid` on the radiogroup. The radiogroup exposes the effective required state (including a form-level default) with `aria-required`, while each radio's native `required` follows only the explicit `isRequired`; a natively required radio's `aria-invalid` follows the same status, so the browser's own invalid state never shows before an error.                                                                                                                                                                                                                                                                                            | Current source and tests                                |
-| FR7 | The radiogroup lays options in a column with a small gap, or a row with a wider gap when horizontal, and passes `size` to every item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                                |
-| FR8 | Base props (`ref`, `id`, `aria-*`, `data-*`, `hidden`, `inert`, `dir`, DOM handlers) reach the radiogroup; a caller `onFocus` runs after FR4's entry handling. `container*` reaches the Field box where one renders (in a `horizontal-labels` FormLayout none renders, and `container*` has no effect and warns), and `control*` the radiogroup; root `xstyle`, `className`, and `style` are not accepted.                                                                                                                                                                                                                                                                              | `family:input-fields` FR10; current tests               |
-| FR9 | The radiogroup carries `astryx-radio-list` and reflects `data-orientation` and `data-size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `architecture:component-theming-surface`; current tests |
-
-### Allowed variation
-
-- **AV1 — Options.** Item content varies under `component:RadioListItem`.
-- **AV2 — Theme paint.** Themes may restyle the group through `radio-list`.
-
-### Representative states
-
-| State                | Required invariant                                                                                                                        | Allowed variation |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| Empty value          | Forward Tab enters on the first radio that is not natively disabled.                                                                      | Orientation.      |
-| One selected         | The selected radio is checked and is the Tab stop.                                                                                        | Size.             |
-| Error status         | `aria-invalid`; detached message describes the group.                                                                                     | Message.          |
-| Disabled with reason | Radios focusable, refuse selection, not submitted; reason tooltip. Implementation gap: a caller `onClick` still runs (RadioListItem FR6). | —                 |
-| Disabled, no reason  | Same as with a reason, without the tooltip. Implementation gap: native `disabled` (FR5).                                                  | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Item availability.** Group disabled or item disabled; the group
-  reason keeps only group-disabled radios focusable.
-- **ORD2 — Required.** Effective required on the radiogroup; explicit required
-  on each radio.
-
-### Performance and resources
-
-- **PR1 — Entry handling.** FR4 runs only on focus events with an empty `value`
-  and adds no global listener.
-
-## Accessibility contract
-
-- **AR1 — Group semantics.** `role="radiogroup"` with a name, description,
-  invalid and required state (FR1, FR6).
-- **AR2 — Keyboard.** Tab reaches the group once (FR4); arrow keys move and
-  select through native radio behavior.
-- **AR3 — Disabled reason.** A group reason stays reachable by keyboard focus
-  and assistive technology (FR5).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                   | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------ | ------------------------ | -------------- | ------------------ |
-| Group label      | Field group label above the options. | Current source           | Prominent      | FR1                |
-| Options          | Column or row of RadioListItem rows. | Current source           | Prominent      | FR7                |
-| Status message   | Detached message after the group.    | Current source           | Supporting     | FR1, FR6           |
-
-`design:user-states` governs the pressed overlay its options paint
-(`component:RadioListItem` FR8); no other design record governs RadioList. The radiogroup carries `radio-list`.
-
-## Family and system relationships
-
-- `spec:AST-085` owns disabled reasons and `family:input-fields` FR10 and DEC-7
-  own prop targets; RadioList
-  meets FR10.
-- `spec:AST-085` owns disabled focusability; FR5 records the gap.
-- `component:RadioListItem` owns each option and reads the group through
-  context.
-
-## Verification map
-
-| Contract       | Verification                                                                                                                                                                                                             | Representative states                                                 | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                            | Audit section                   |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, AR1       | `RadioList.test.tsx` label, span-label, hidden-label, required and optional marker, status, and group-description cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts`                               | Visible and hidden label; each status; description                    | A missing group name or description fails. Evidence gap: no test asserts the caller description first or the disabled reason last, or the label tooltip.                                                                                                                                                                                                                   | `audit:RadioList/accessibility` |
-| FR2, FR3       | `RadioList.test.tsx` selection and form cases                                                                                                                                                                            | Radio, label, and description clicks; `htmlName`; no name             | A wrong value, lost grouping, wrong form value, or a second `onChange` on a radio click fails. Evidence gap: no test counts `onChange` calls on delegated label and description clicks.                                                                                                                                                                                    | `audit:RadioList/behavior`      |
-| FR4, AR2, PR1  | `RadioList.test.tsx` focus-management cases; `RadioGroup.a11y.chromium.spec.ts` `radio-group.focus.entry-and-exit` rule on every `radio-list-group-*` state                                                              | Backward entry; intra-group movement; disabled radios                 | A redirected intra-group move, entry on a natively disabled radio, or Tab entry off the selected or first option fails. Evidence gap: no test enters an empty group disabled with a reason, or asserts a caller `onFocus` after entry handling or the absence of global listeners.                                                                                         | `audit:RadioList/accessibility` |
-| FR5, ORD1, AR3 | `RadioList.test.tsx` disabled, disabledMessage, and form cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` `radio-list-group-disabled-with-message` and `radio-list-option-group-disabled` states | Group and item disabled; with reason                                  | A selection while disabled, or a submitted value from a group disabled with a reason, fails; the binding expects `tabReachable: false` for `radio-list-option-group-disabled`, which fails when that gap closes. Evidence gap: no form case submits an item-disabled option or a group disabled without a reason, and no test disables the group while a radio is focused. | `audit:RadioList/accessibility` |
-| FR6, ORD2      | `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` `radio-list-group-required-invalid-described` state                                                                                                    | Required, invalid, described group                                    | A missing required or invalid state on the group fails. Evidence gap: no test asserts that a form-level required default reaches only `aria-required`.                                                                                                                                                                                                                     | `audit:RadioList/accessibility` |
-| FR7, FR9       | `RadioList.test.tsx` theme-target case                                                                                                                                                                                   | `size="sm"`                                                           | A missing row size fails. Evidence gap: the orientation case asserts only rendering; no test asserts the gaps, horizontal layout, `data-orientation`, `data-size`, or `astryx-radio-list` on the radiogroup.                                                                                                                                                               | `audit:RadioList/layout`        |
-| FR8            | `RadioList.fr10.test.tsx`; `RadioList.test.tsx` data-testid case                                                                                                                                                         | Caller labelledby; hidden, inert, dir; `horizontal-labels` FormLayout | A base prop off the radiogroup, or `container*` off the Field box, fails. Evidence gap: no test asserts a caller `onFocus` runs after entry handling.                                                                                                                                                                                                                      | `audit:RadioList/api`           |
-
-## Current-state impact
-
-- **Group reason (FR5).** A group `disabledMessage` describes only the
-  radiogroup, so a focused disabled radio is not described by it, against
-  `spec:AST-085` FR5 and FR7.
-- **Caller onClick while disabled (FR5).** A radio kept focusable by a group
-  reason still runs a caller's `onClick` on a click or an arrow key onto it,
-  against `spec:AST-085` FR2.
-- **Disabled focusability (FR5).** A group disabled without a reason gives its
-  radios native `disabled`, so they leave the tab order, against `spec:AST-085`
-  FR1 and FR7.
-- **Consumer docs.** `RadioList.doc.mjs` anatomy lists Header, Children, and
-  Label/Value parts; RadioList renders a group label, options, and a status
-  message, and has no header.
-
-## Decision log
-
-- **Keyboard model (FR4).** RadioList keeps the browser's native radio arrow
-  keys and its shipped Tab entry rule; `spec:AST-085` leaves which radios a
-  composite's arrow keys visit to the composite.
-
-RadioList otherwise applies `family:input-fields` FR10 and the WAI-ARIA radio
-group pattern.
-
-## 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.