@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/StatusDot/StatusDot.spec.md

@@ -1,101 +1,177 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:StatusDot
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-25
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
-  [packages/core/src/StatusDot/StatusDot.test.tsx, scripts/check-knowledge.mjs]
+  [
+    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:
+  [
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+    architecture:theme-tokens,
+  ]
 contributing: []
-system_specs: []
+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 with an optional status icon.
-This record preserves that runtime behavior while 0.7.0 removes the deprecated
-`statusdot` theming alias.
+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`; canonical `status-dot` behavior is unchanged
-- Removed alias: 0.7.0 stops emitting `statusdot`
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: replace `statusdot` theme keys and `.astryx-statusdot`
-  selectors with `status-dot` and `.astryx-status-dot`, or run
-  `astryx upgrade --from 0.6.3 --apply --path .`
+- 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 and its current `status-dot` theming target.
-- The wrapper that positions optional status-icon content inside the dot.
+- 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 or trigger behavior when `tooltip` is supplied — owned by
-  Tooltip.
-- A built-in icon for each variant — the default dot remains childless.
+- 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
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `StatusDot.doc.mjs`.
+| 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  | Candidate invariant                                                                                            | Basis                           | Draft review state                                 |
-| --- | -------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current render always contains one painted dot carrying the `status-dot` target.                           | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | When renderable icon content is supplied, it appears in an assistive-technology-hidden wrapper inside the dot. | Current source and tests        | Verified current behavior; no new behavior decided |
-| FR3 | The painted dot emits only the canonical `status-dot` target.                                                  | Current source, docs, and tests | Verified canonical behavior; 0.7 alias removed     |
+| 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
 
-- Caller-supplied icon artwork may vary without creating a separate public
-  target.
+- **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
 
-- The anatomy and target ownership are unchanged across semantic variants and
-  pulsing state. The optional status icon is absent when its content is not
-  renderable.
+| 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
 
-- No new rendering, styling, or target precedence rule is introduced.
+- **ORD1 — Dot attributes.** `role="img"` and `aria-label` → component class and
+  `data-variant` → component styles → `xstyle` → `className` → `style` →
+  caller props.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — CSS-only motion.** The pulse is a CSS animation; StatusDot registers
+  no listener, observer, or timer of its own.
 
 ## Accessibility contract
 
-This draft does not change or extend StatusDot's existing role, accessible-name,
-reduced-motion, or decorative-icon behavior.
+- **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 current painted semantic-status signal.      | Current source and public docs | Supporting     | FR1, FR3           |
-| Status icon      | Presents optional caller-supplied artwork inside the dot. | Current source and tests       | Supporting     | FR2                |
+| 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
 
@@ -111,26 +187,38 @@ reduced-motion, or decorative-icon behavior.
 ## Family and system relationships
 
 - `architecture:component-theming-surface` owns anatomy qualification,
-  inheritance, and canonical target naming.
+  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, FR2            | `StatusDot.test.tsx` render and custom-icon suites | Plain dot and dot with supplied icon | Removing the dot or changing optional icon rendering fails existing DOM assertions.   | `audit:StatusDot/anatomy` |
-| FR3                 | `StatusDot.test.tsx` theme-target-name suite       | Canonical target class               | Missing or renamed canonical target fails the target assertion.                       | `audit:StatusDot/theming` |
-| 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` |
+| 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. This draft records current facts and introduces no component-local design
-or API decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
-None.
+- **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, implementation
-steps, or system rules. It links to their owners.
+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/StatusDot/StatusDot.test.tsx

@@ -5,6 +5,7 @@ import {render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {StatusDot} from './StatusDot';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 /** Renders a StatusDot and returns its root element. */
 function renderDot(props: React.ComponentProps<typeof StatusDot>) {
@@ -198,3 +199,15 @@ describe('StatusDot theme target names', () => {
     expect(dot).not.toHaveClass('astryx-statusdot');
   });
 });
+
+// jsdom cannot emulate forced colors, so this asserts the compiled rule the
+// status fill relies on (architecture:theme-tokens INV11): the fill becomes
+// Canvas, and a CanvasText boundary keeps its shape.
+describe('StatusDot forced colors', () => {
+  it('keeps a visible boundary on the status fill', () => {
+    render(<StatusDot variant="error" label="Offline" />);
+    const css = getForcedColorsRules();
+    expect(css).toContain('outline-style: solid;');
+    expect(css).toContain('outline-color: canvastext;');
+  });
+});

package/src/StatusDot/StatusDot.tsx

@@ -89,14 +89,41 @@ const variants = stylex.create({
   success: {
     backgroundColor: colorVars['--color-success'],
     color: colorVars['--color-on-success'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   warning: {
     backgroundColor: colorVars['--color-warning'],
     color: colorVars['--color-on-warning'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   error: {
     backgroundColor: colorVars['--color-error'],
     color: colorVars['--color-on-error'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   accent: {
     backgroundColor: colorVars['--color-accent'],

package/src/Stepper/Step.spec.md

@@ -0,0 +1,206 @@
+---
+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`, it is enabled, and the Stepper is not compact. |
+| 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, and a "Go to step N" name on clickable steps; keyboard users Tab between enabled clickable steps.                    |
+| Builder impact          | None.                                                                                                                                                                                                                                                                        |
+| Compatibility/readiness | Records shipped behavior; no public change. Three 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
+
+- **A disabled step leaves the tab order.** In a clickable Stepper outside
+  compact mode a disabled Step renders no button, so keyboard users cannot reach
+  it or learn that it is disabled, and a focused step that becomes disabled
+  loses its button, dropping focus to the page. `spec:AST-085` FR1, FR4, and FR5
+  have a disabled control stay focusable, keep focus, and expose
+  `aria-disabled="true"`.
+- **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 nothing describes it, so the
+  description, 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 MUST stay focusable with `aria-disabled="true"` and keep its tab stop (`spec:AST-085` FR1, FR5). Implementation gap: it renders no button, so it leaves the tab order, exposes no disabled state, and drops focus when it becomes disabled while focused (`spec:AST-085` FR4). | 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's implementation gap). `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; no activation. Implementation gap: no button (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. Implementation gap: a clickable step's description, optional
+  cue, and `endContent` are not exposed (Current-state impact).
+- **AR4 — Keyboard.** Clickable steps are reached with Tab in document order and
+  activate with Enter or Space; today disabled steps are skipped (FR2's
+  implementation gap).
+
+## 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; the disabled-step and Tab-skip assertions pin FR2's implementation gap (pending conformance). | `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.