@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/StatusDot/StatusDot.spec.md

@@ -1,224 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:StatusDot
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-25
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/StatusDot/StatusDot.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/theme/extensibleAxes.test.ts,
-    apps/storybook/stories/StatusDot.stories.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:public-component-api,
-    architecture:theme-tokens,
-  ]
-contributing: []
-system_specs: [spec:AST-009]
----
-
-# StatusDot component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                             |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`.                                                          |
-| Behavior                | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a tooltip is reachable by hover, touch, and keyboard (FR5). |
-| End-user impact         | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark.                                                    |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                         |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Three gaps are listed under Current-state impact.                                                                         |
-| Review checks           | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target.       |
-| Governing rules         | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1.                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-StatusDot renders a compact painted status signal — presence, health, or
-severity — beside content that explains it. It owns the dot's size, tones,
-optional pulse, optional inner mark, and its accessible name.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes. The dot emits only the canonical `status-dot`
-  target; the `statusdot` alias is not emitted
-- Controlled/uncontrolled behavior: not applicable; StatusDot holds no state
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Theme-added variant without paint (FR2).** `StatusDotVariantMap` admits
-  theme-added values, but a value the active theme does not paint renders a
-  transparent dot with no visible signal. The accessible name still carries
-  the status. `architecture:component-theming-surface` INV14 requires an
-  extensible visual axis to have a safe theme-independent baseline.
-- **Tooltip not reachable by keyboard (FR5).** The dot has no tab stop, so
-  Tooltip attaches no focus trigger and sighted keyboard users cannot reveal
-  the tooltip text, where WCAG 2.2 2.1.1 expects functionality to be keyboard
-  operable. The accessible name still carries the status.
-- **Accent and neutral dots in forced colors (FR2).** The `accent` and
-  `neutral` dots draw no border, so in forced-colors mode they lose their plate
-  and disappear; no current record sets their treatment (OQ1). The accessible
-  name still carries the status.
-
-## Ownership boundary
-
-**Owns**
-
-- The painted dot, its `status-dot` theming target, and its fixed size.
-- The variant's plate and ink pairing.
-- The pulse and its reduced-motion suppression.
-- The assistive-technology-hidden wrapper that places optional icon content
-  inside the dot.
-- The dot's image role and accessible name.
-
-**Does not own / non-goals**
-
-- The artwork supplied through `icon` — owned by the caller.
-- The tooltip surface and its open triggers when `tooltip` is supplied — owned
-  by Tooltip.
-- A built-in icon per variant — the default dot stays childless.
-- The visible label or surrounding text that explains the status — owned by
-  the product callsite.
-- The status dot overlaid on an avatar — owned by `component:AvatarStatusDot`.
-
-## Public concepts
-
-| Concept          | Closed values or states                                             | Meaning                                                             | Availability by variant/orientation/state | Default  | Owner                 | Stability | Invalid-value behavior                                                                                                                      |
-| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tone (`variant`) | `success`, `warning`, `error`, `accent`, `neutral`; theme additions | Selects the plate color and the ink an icon paints with.            | All dots                                  | Required | `component:StatusDot` | Stable    | A theme-added value is reflected on `status-dot` and keeps a safe theme-independent baseline (FR2); TypeScript rejects unregistered values. |
-| Pulse            | resting; pulsing                                                    | Signals ongoing activity by fading the dot in and out.              | All tones                                 | resting  | `component:StatusDot` | Stable    | —                                                                                                                                           |
-| Status icon      | present when `icon` is renderable; absent                           | Adds a non-color mark inside the dot.                               | All tones                                 | absent   | `component:StatusDot` | Stable    | `false`, `true`, `null`, `undefined`, and `''` render no icon wrapper.                                                                      |
-| Tooltip          | present when `tooltip` is a non-empty string; absent                | Explains the status; reachable by hover, touch, and keyboard (FR5). | All tones                                 | absent   | `component:StatusDot` | Stable    | An empty string renders no tooltip.                                                                                                         |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                    |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
-| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
-| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
-| FR5 | A non-empty `tooltip` wraps the dot in Tooltip with that text; otherwise no tooltip renders. A tooltip opens from the keyboard as well as on hover and touch (WCAG 2.2 2.1.1). Implementation gap: the dot has no tab stop, so the tooltip opens on hover and touch only (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
-| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** A theme may change the dot's visual properties per
-  `variant` through `status-dot` without changing its size, name, or anatomy.
-- **AV2 — Icon artwork.** Caller-supplied artwork may vary without creating a
-  separate target.
-
-### Representative states
-
-| State        | Required invariant                                                     | Allowed variation |
-| ------------ | ---------------------------------------------------------------------- | ----------------- |
-| Plain dot    | Childless image named by `label`; not focusable.                       | Tone.             |
-| With icon    | Icon inside an `aria-hidden` wrapper; the dot keeps its role and name. | Artwork.          |
-| Pulsing      | Opacity pulse runs; with reduced motion requested, it does not.        | Tone.             |
-| With tooltip | Dot keeps its role and name; Tooltip owns the surface.                 | Tooltip text.     |
-
-### Transformation and precedence order
-
-- **ORD1 — Dot attributes.** `role="img"` and `aria-label` → component class and
-  `data-variant` → component styles → `xstyle` → `className` → `style` →
-  caller props.
-
-### Performance and resources
-
-- **PR1 — CSS-only motion.** The pulse is a CSS animation; StatusDot registers
-  no listener, observer, or timer of its own.
-
-## Accessibility contract
-
-- **AR1 — Name without hover.** The dot exposes `role="img"` with `label` as its
-  accessible name for every variant, with or without a tooltip or icon; a caller
-  `role` or `aria-label` replaces them (FR6).
-- **AR2 — Tab stop.** A dot without a tooltip is a static image and adds no
-  tab stop of its own. For a dot with a tooltip, FR5 governs: the tooltip is
-  reachable from the keyboard, and today the dot adds no tab stop, which is the
-  FR5 gap. A caller `tabIndex` passes through (FR6).
-- **AR3 — Decorative icon.** The icon wrapper is `aria-hidden`, so the label
-  alone names the status.
-- **AR4 — Color is not the only carrier.** The accessible name carries the
-  status for assistive technology. Visually, the default dot is a color-only
-  signal; a non-color mark comes from a per-status `icon` or from the
-  surrounding UI, which the callsite owns.
-- **AR5 — Reduced motion.** The pulse stops when the reader asks for reduced
-  motion (FR3).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                        | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Dot              | Presents the painted semantic-status signal.              | Current source and public docs | Supporting     | FR1–FR3, AR1, AR2  |
-| Status icon      | Presents optional caller-supplied artwork inside the dot. | Current source and tests       | Supporting     | FR4, AR3           |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Dot": {"target": "status-dot"},
-  "Status icon": {"inherits": "status-dot"}
-}
-```
-
-## Family and system relationships
-
-- `architecture:component-theming-surface` owns anatomy qualification,
-  inheritance, canonical target naming, and the extensible `variant` axis; FR2
-  records the unthemed fallback.
-- `architecture:public-component-api` owns ref, passthrough, and styling-input
-  rules; FR6 applies them to the dot.
-- `architecture:theme-tokens` INV11 owns the status color roles and their
-  forced-colors border, which FR2's status plates follow.
-
-## Verification map
-
-| Contract            | Verification                                                          | Representative states                | Mutation or failure expectation                                                                                                                                                                                                                                            | Audit section             |
-| ------------------- | --------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1, FR6            | `StatusDot.test.tsx` render, ref, test-id, and target suites          | Every tone                           | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in `StatusDot.stories.tsx`.                                                        | `audit:StatusDot/anatomy` |
-| FR2                 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts`      | Warning plate and ink; map wiring    | Dropping `variant` reflection fails. The warning-ink test pins the `--color-warning` plate with `--color-on-warning` ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check. | `audit:StatusDot/theming` |
-| FR3, AR5            | `StatusDot.stories.tsx` in a browser, with and without reduced motion | Resting and pulsing                  | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture.                                                                                                                                          | `audit:StatusDot/motion`  |
-| FR4, AR3            | `StatusDot.test.tsx` custom-icon suite                                | Icon, falsy values                   | Exposing the icon or rendering a wrapper for a falsy value fails.                                                                                                                                                                                                          | `audit:StatusDot/anatomy` |
-| FR5, AR1, AR2       | `StatusDot.test.tsx` focusability and accessible-name suites          | Every tone, with and without tooltip | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller `role` or `aria-label` override.             | `audit:StatusDot/a11y`    |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                         | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                                                      | `audit:StatusDot/theming` |
-| AR4, PR1            | Source review; `StatusDot.stories.tsx`                                | Plain dot, dot with icon             | Gap: no automated check covers the non-color mark guidance or fails if StatusDot adds its own listener, observer, or timer.                                                                                                                                                | `audit:StatusDot/a11y`    |
-| AR1, AR3            | Accessibility-tree evidence (`spec:AST-009` FR3)                      | Every tone, with icon and tooltip    | Gap: no accessibility-tree check proves the image role and name or the hidden icon; the unit tests query the DOM.                                                                                                                                                          | `audit:StatusDot/a11y`    |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-- **OQ1 — What forced-colors treatment should the `accent` and `neutral` dots
-  have?** (`human-design`) They are not status roles under
-  `architecture:theme-tokens` INV11, and today they render with no visible plate
-  in forced-colors mode.
-
-## 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/Stepper/Step.spec.md

@@ -1,200 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Step
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/Stepper/Stepper.test.tsx,
-    apps/storybook/stories/Stepper.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [architecture:interaction-modality, architecture:component-theming-surface]
-contributing: []
-system_specs: [spec:AST-085]
----
-
-# Step component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `Step` with `step`, `label`, `description`, `children`, `status`, `indicator` (`auto`, `number`, `none`, or a node; default `auto`), `isDisabled`, `isOptional`, `endContent`, and `density`.                                                                                                                            |
-| Behavior                | One list item of a Stepper. Its progress (completed, in progress, not started) comes from its `step` index against the Stepper's active step; it is a button that asks to go to that step when the Stepper has `onStepClick` and is not compact; a disabled step keeps its button, `aria-disabled`, and never activates. |
-| End-user impact         | Users see each step's progress (number, ring, or check) and its status cue where one applies; screen-reader users hear the current step, a status word, a "Go to step N" name and the step's description on clickable steps; keyboard users Tab between clickable steps, disabled ones included.                         |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                                    |
-| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact).                                                                                                                                                                                                                          |
-| Review checks           | Reject status conveyed only by color under `indicator="auto"`, an indicator exposed to assistive technology, a disabled step that activates, or `aria-current` on anything but the in-progress step.                                                                                                                     |
-| Governing rules         | `component:Stepper` (targets, connector, label paint, compact layout); `architecture:interaction-modality`.                                                                                                                                                                                                              |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Step is one stage of a Stepper flow. It owns its progress derivation, its
-indicator choice, its status cues and text alternatives, its clickable form, its optional cue, and where its content renders. Consumer usage lives in `Step.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: progress follows the Stepper's active step
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Other indicator modes show status by color alone, or not at all.** With
-  `indicator="number"`, a reached step shows status only through badge color
-  and a not-started step shows none. A custom node shows status only through
-  its wrapper's color, on every step. `indicator="none"` shows no indicator, and
-  under `auto` the current step's ring and label keep progress color whatever
-  its `status`, so in both cases status shows only in the visually hidden word. WCAG 1.4.1 requires information
-  not to be conveyed by color alone.
-- **A clickable step's name hides its other text.** The button's name is the
-  step number, label, and status word, and only the description describes it,
-  so the "Optional" cue and `endContent` never reach assistive technology on a
-  clickable step. WCAG 1.3.1 requires information shown to be
-  available programmatically.
-
-## Ownership boundary
-
-**Owns**
-
-- Progress derivation, indicator selection, status glyphs and text, the
-  clickable button, disabled and optional handling, and density fallback
-  (FR1–FR7).
-- Where `children` render and how they stay mounted (FR8), and the focus outline
-  (FR9).
-
-**Does not own / non-goals**
-
-- The `step`, `step-bar`, `step-connector`, `step-indicator`, `step-label`, and
-  `step-description` targets, connector geometry and gap, Label and Description
-  paint, and the compact horizontal presentation — owned by `component:Stepper`
-  FR1–FR16.
-- The active step, orientation, indicator position, and `onStepClick` — owned by
-  the Stepper and its caller.
-- Custom indicator artwork, `endContent`, and `children` — owned by the caller.
-
-## Public concepts
-
-| Concept   | Closed values or states                   | Meaning                                            | Availability by variant/orientation/state | Default                | Owner            | Stability | Invalid-value behavior                                                             |
-| --------- | ----------------------------------------- | -------------------------------------------------- | ----------------------------------------- | ---------------------- | ---------------- | --------- | ---------------------------------------------------------------------------------- |
-| Progress  | `completed`, `in-progress`, `not-started` | Derived from `step` and the Stepper's active step. | Every step.                               | —                      | `component:Step` | Stable    | Not caller-settable.                                                               |
-| Status    | `accent`, `success`, `warning`, `error`   | Semantic color and glyph for the indicator.        | Every step.                               | Unset (progress color) | `component:Step` | Stable    | TypeScript rejects other values.                                                   |
-| Indicator | `auto`, `number`, `none`, node            | What the indicator shows.                          | Every step.                               | `auto`                 | `component:Step` | Stable    | A non-string node renders as given; another string shows the ring, then the check. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Basis                           |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1 | A Step renders one `<li>`. Its progress is `in-progress` when `step` equals the Stepper's active step, `completed` when it is lower, and `not-started` when higher; only the in-progress step carries `aria-current="step"`. It registers its index and a live disabled check with the Stepper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests        |
-| FR2 | With `onStepClick` on the Stepper, an enabled Step outside compact mode wraps its indicator, label, and description in a `<button>` (the content slot stays outside it) named by `@astryx.step.goToStep` ("Go to step N: label") or `.goToStepWithStatus` when a status word applies; activation (click, Enter, Space) calls `onStepClick(step)`. Completed, in-progress, and upcoming steps are all clickable. Any Step without `onStepClick` renders no button. A disabled Step in a clickable Stepper outside compact mode keeps its button, focusable with `aria-disabled="true"` and the same name, keeps its tab stop and its focus when it becomes disabled while focused, and does not activate (`spec:AST-085` FR1, FR4). A clickable Step's description describes its button, so a disabled step's reason reaches assistive technology (`spec:AST-085` FR5). | Current source and tests        |
-| FR3 | `indicator="auto"` shows the number while not started, the ring while in progress, and a check once completed; `number` always shows the number; `none` shows nothing; a non-string node renders as given; any other string falls back to the ring while not started or in progress and the check once completed, with no number, status glyph, or status color. Indicators are `aria-hidden`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests        |
-| FR4 | `status` never recolors the progress bar. Under `indicator="auto"` it recolors a non-current step with `success`, `warning`, or `error` and shows a distinct status glyph (replacing the number on not-started steps); the current step's ring and `accent` keep progress color. Under `number` it recolors reached badges only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests        |
-| FR5 | Each Step exposes a visually hidden status word: `error` or `warning` for those statuses, `completed` when completed or `success`, in every layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests        |
-| FR6 | `isDisabled` dims the indicator with fixed paint and no theme state (the label's disabled paint and its `disabled` selector are `component:Stepper` FR10) and blocks activation (FR2). `isOptional` appends the translated `@astryx.step.optional` ("Optional") after the label. `endContent` sits at the end of the label row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests        |
-| FR7 | `density` sets the Step's padding: block padding in every layout, plus inline padding for spacious separated steps and both axes for vertical on-track steps; it falls back to the Stepper's density.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source                  |
-| FR8 | `children` render below the label and description; in a compact horizontal Stepper they stay mounted, hidden with the expanded details, so local state survives. The label stays on one line and ellipsizes; its full text remains in the accessible name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source, docs, and tests |
-| FR9 | The step button paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source                  |
-
-### Allowed variation
-
-- **AV1 — Indicator artwork.** A custom node may replace the indicator.
-- **AV2 — Layout.** Orientation and indicator position come from the Stepper.
-
-### Representative states
-
-| State                  | Required invariant                                          | Allowed variation |
-| ---------------------- | ----------------------------------------------------------- | ----------------- |
-| Completed, clickable   | Check indicator; "completed" text; named button.            | Status color.     |
-| In progress            | `aria-current="step"`; ring indicator.                      | —                 |
-| Not started with error | Error glyph replaces the number; "error" text.              | —                 |
-| Disabled               | Dimmed; focusable and `aria-disabled`; no activation (FR2). | —                 |
-| Compact horizontal     | No button; content mounted but hidden.                      | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Status word.** `error`, then `warning`, then `completed` (completed
-  progress or `success`).
-- **ORD2 — Density.** Step `density`, then the Stepper's.
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Current step.** FR1's `aria-current="step"`.
-- **AR2 — Non-color status.** With `indicator="auto"`, FR4's glyphs and FR5's
-  hidden text carry status beyond color; indicators stay hidden from assistive
-  technology. Implementation gap: in `number`, custom-node, and `none` modes,
-  and on the `auto` current step, status shows by color alone or only in the
-  hidden word (Current-state
-  impact).
-- **AR3 — Clickable name.** FR2's button name includes the step number, label,
-  and status word, and the step's description describes it. Implementation gap:
-  a clickable step's optional cue and `endContent` are not exposed
-  (Current-state impact).
-- **AR4 — Keyboard.** Clickable steps, disabled ones included, are reached with
-  Tab in document order; enabled ones activate with Enter or Space.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                 | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | -------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Indicator        | Number, check, status glyph, ring, or custom node. | Current source and public docs | Prominent      | FR3, FR4           |
-| Optional cue     | "Optional" after the label.                        | Current source                 | Supporting     | FR6                |
-
-`Step.doc.mjs` declares no anatomy of its own; Step anatomy and targets are in
-`component:Stepper`'s theming map.
-
-## Family and system relationships
-
-- `component:Stepper` owns the targets, connector, Label and Description paint,
-  and compact layout this component renders within.
-
-## Verification map
-
-| Contract     | Verification                                                        | Representative states                 | Mutation or failure expectation                                                                                                                                         | Audit section              |
-| ------------ | ------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1          | `Stepper.test.tsx` list and aria-current tests                      | Each progress                         | Wrong current step fails.                                                                                                                                               | `audit:Step/accessibility` |
-| FR2, AR3–AR4 | `Stepper.test.tsx` onStepClick, keyboard, and accessible-name tests | Completed, active, upcoming, disabled | A missing button or wrong name fails, and so does a disabled step that leaves the tab order, loses focus when it becomes disabled, lacks `aria-disabled`, or activates. | `audit:Step/behavior`      |
-| FR3, FR4     | `Stepper.test.tsx` step-number, indicator, and status glyph tests   | Each indicator mode and status        | Wrong glyph or recolored bar fails.                                                                                                                                     | `audit:Step/behavior`      |
-| FR8          | `Stepper.test.tsx` compact content-mount tests                      | Both indicator positions              | Step content that loses its state while hidden in a compact Stepper fails.                                                                                              | `audit:Step/behavior`      |
-| FR5, AR2     | `Stepper.test.tsx` hidden status text tests                         | Separated and on-track                | Missing status text fails.                                                                                                                                              | `audit:Step/accessibility` |
-
-Read from source, with no focused test yet:
-
-- FR3: the number on a not-started step and the check after completion under
-  `auto`, the empty indicator under `none`, and the string fallback.
-- FR6: the dimmed disabled paint, the optional cue, and `endContent`.
-- FR7.
-- FR8: the one-line label.
-- FR9.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, or Stepper layout
-rules. It links to their owners.