@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Spinner/Spinner.spec.md

@@ -0,0 +1,231 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Spinner
+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/Spinner/Spinner.test.tsx,
+    packages/core/src/FieldStatus/__tests__/StatusMessage.a11y.chromium.spec.ts,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/Spinner.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-086]
+---
+
+# Spinner component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | An animated ring with `size` (`sm`–`xl`), `shade`, an optional visible `label`, and five public theme variables for geometry and color.                                                                                                                     |
+| Behavior                | The ring sits in a named indicator; a visible label renders below it, and a non-empty string label names the indicator through `aria-labelledby` instead of repeating it. A standalone Spinner announces through the shared channel (AR1).                  |
+| End-user impact         | Sighted users see ongoing work; screen-reader users find a named indicator, defaulting to a translated "Loading"; readers who reduce motion see a slowed ring rather than a frozen one.                                                                     |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                                                                |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.                                                                                                                   |
+| Review checks           | Reject an indicator without an accessible name, a duplicated string-label name, a live role mounted already holding its text, a box that a flex host can compress, a caller `style` that overrides the box size, or a ring that stops under reduced motion. |
+| Governing rules         | `spec:AST-086/FR2,FR8,FR11`; `architecture:component-theming-surface/INV6`; `architecture:internationalization/INV1a`; `architecture:public-component-api/INV5,INV6,INV8`.                                                                                  |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Spinner shows that work of unknown duration is in progress. It owns the ring's
+geometry, motion, and shades, the optional visible label beneath it, and the
+status element's accessible name.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable; Spinner holds no state
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Standalone status mounts holding its name (AR1).** A standalone Spinner
+  mounts as `role="status"` with its accessible name already present and
+  writes nothing to the shared announcement channel, where `spec:AST-086` FR2
+  and FR11 require a standalone indicator that appears after page load to
+  announce through the channel and not mount a live role holding its text. A
+  conditionally rendered Spinner is therefore often silent.
+
+- **Empty or lost name (AR1).** `aria-label=""` is used as the name, and
+  `label=""` renders an empty visible Text and names the status from it; either
+  leaves the status with an empty accessible name (WCAG 2.2 4.1.2). With a
+  `label`, a caller `aria-labelledby` reaches the role-less wrapper instead of
+  the status.
+
+## Ownership boundary
+
+**Owns**
+
+- The status element, the ring drawn inside it, and the optional label below
+  it.
+- Ring geometry per `size`, ring and track color per `shade`, the dash motion,
+  and the reduced-motion rate.
+- The five public theme variables and where they are declared.
+- The status element's accessible name, including the translated default.
+
+**Does not own / non-goals**
+
+- Whether a composing component's busy indicator is silent — owned by that
+  component under `spec:AST-086` FR8; a composer silences Spinner through
+  passthrough attributes.
+- Content-shaped loading placeholders — owned by `component:Skeleton`.
+- Determinate progress — owned by `component:ProgressBar`.
+- Rich label content, when `label` is a node — owned by the caller.
+
+## Public concepts
+
+| Concept         | Closed values or states                                                                                              | Meaning                                                                                      | Availability by variant/orientation/state                  | Default            | Owner               | Stability | Invalid-value behavior                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------ | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
+| Size            | `sm`, `md`, `lg`, `xl`                                                                                               | Ring diameter 10, 14, 18, or 28px with stroke 2, 3, 3, or 4px.                               | All spinners                                               | `md`               | `component:Spinner` | Stable    | TypeScript rejects other values.                                                                        |
+| Shade           | `default`, `subtle`, `onMedia`, `inherit`                                                                            | Arc and track colors for light, inline, dark-media, or inherited contexts.                   | All spinners                                               | `default`          | `component:Spinner` | Stable    | TypeScript rejects other values.                                                                        |
+| Label           | absent; string; rich node                                                                                            | Visible content below the ring.                                                              | All spinners                                               | absent             | `component:Spinner` | Stable    | `null` and `undefined` mean absent.                                                                     |
+| Theme variables | `--spinner-diameter`, `--spinner-stroke-width`, `--spinner-arc-fraction`, `--spinner-color`, `--spinner-track-color` | Public geometry and color seams a theme sets per `size`, per `shade`, or on the base target. | Declared on whichever element carries the `spinner` target | Per size and shade | `component:Spinner` | Stable    | A themed stroke width of `0` paints no stroke; the arc fraction applies only once the stylesheet loads. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Without a label, Spinner renders one inline-grid `span` status element that carries the `spinner` target, ref, `data-testid`, and passthrough props. With a label, a column `div` wrapper with `--spacing-2` gap carries the target, ref, `data-testid`, passthrough props, and styling inputs; the status `span` and then the label render inside it.                                                                                                                            | Current source and tests |
+| FR2 | The status element's box is the ring diameter plus one stroke width on each side, set inline after the caller's `style`, so a caller `width` or `height` never resizes it while other caller styles still apply. The box does not shrink in a flex host. With no stylesheet, the box and ring draw at the size's default geometry.                                                                                                                                                | Current source and tests |
+| FR3 | The ring is an `aria-hidden` SVG of two concentric circles: a full track and an arc covering `--spinner-arc-fraction` of the circumference (0.375 by default), starting at twelve o'clock with round caps. The arc's dash moves around the stationary circle at `--duration-slow-min` per cycle, as the theme sets it before `tempo` scales it (`spec:AST-108` FR4), linear, indefinitely; under `prefers-reduced-motion: reduce` the cycle slows to 3 seconds and does not stop. | Current source and tests |
+| FR4 | All mounted rings turn in the same phase, whenever each mounted. Where the browser cannot report running animations, Spinner does no phase work.                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
+| FR5 | `default` paints `--color-accent` on `--color-track`; `subtle` paints `--color-text-secondary` on `--color-track`; `onMedia` paints `--color-on-dark` on itself at track opacity 77/255; `inherit` paints `currentColor` on itself at track opacity 0.3.                                                                                                                                                                                                                          | Current source and tests |
+| FR6 | The five public variables are declared only on the element carrying the `spinner` target, per `size` and `shade`, so a theme rule on that target and its `size:` or `shade:` variants overrides them; the inner status element inherits them when a label moves the target to the wrapper.                                                                                                                                                                                        | Current source and tests |
+| FR7 | A string label renders as bold body Text; a rich-node label renders as supplied.                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
+| FR8 | `xstyle` and `className` reach the element carrying the target and merge after component styles; `style` merges after them except for the status box's `width` and `height` (FR2).                                                                                                                                                                                                                                                                                                | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme geometry and color.** A theme may change the five public
+  variables per size, per shade, or globally; the box follows the themed
+  diameter and stroke.
+- **AV2 — Label content.** Label text and rich content may vary.
+
+### Representative states
+
+| State                 | Required invariant                                                                                   | Allowed variation |
+| --------------------- | ---------------------------------------------------------------------------------------------------- | ----------------- |
+| Unlabelled            | Status `span` carries the target and the translated "Loading" name (`role="status"` is the AR1 gap). | Size, shade.      |
+| String label          | Wrapper carries the target; status named by `aria-labelledby` to the visible Text.                   | Label text.       |
+| Rich label            | Status named by `aria-label` (caller's, else "Loading"); node renders as supplied.                   | Node content.     |
+| Explicit `aria-label` | Status named by that value, with or without a label.                                                 | —                 |
+| Reduced motion        | Arc keeps moving at a 3-second cycle.                                                                | —                 |
+| Narrow flex host      | Status box keeps its full size and overflows rather than compressing.                                | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Accessible name.** Without a `label`, a caller `aria-labelledby`
+  reaches the status element and names it from the referenced element. Then:
+  non-empty caller `aria-label` → non-empty string `label` (by
+  `aria-labelledby` when no `aria-label` is set) → translated
+  `@astryx.spinner.loading` ("Loading"). An empty `aria-label` or `label`, and
+  a caller `aria-labelledby` beside a `label`, are AR1 gaps.
+- **ORD2 — Variable values.** Theme rule on a `size:` or `shade:` variant →
+  theme rule on the base target → the component's per-size and per-shade
+  defaults.
+- **ORD3 — Box size.** Composed box size from the resolved diameter and stroke
+  → the size's default frame when no stylesheet declares it; neither yields to
+  caller `style`.
+
+### Performance and resources
+
+- **PR1 — Mount cost.** Mounting a Spinner causes no document-wide style
+  recalculation, repeated module evaluation does not fail, and a server render
+  does no browser-only work.
+- **PR2 — Bounded phase work.** Rings mounted together cost one round of phase
+  work, and an unmounted ring is never touched.
+
+## Accessibility contract
+
+- **AR1 — Announced, named indicator.** A standalone Spinner that appears after
+  page load announces through the shared channel, and its element carries no
+  live role or `aria-live` (`spec:AST-086` FR2, FR11); a Spinner inside a busy
+  owner is silent (`spec:AST-086` FR8). The indicator has an accessible name by
+  ORD1, and a visible string label is never repeated as `aria-label`. OQ1 holds
+  the role and name it exposes without a live role. Implementation gaps: the
+  element is `role="status"`, mounted already holding its name, and writes
+  nothing to the shared channel; `aria-label=""` or `label=""` leaves it with an
+  empty name; and with a `label`, a caller `aria-labelledby` lands on the
+  role-less wrapper and names nothing.
+
+- **AR2 — Decorative ring.** The SVG is `aria-hidden`.
+- **AR3 — Translated default.** The default name comes from the translation
+  catalog and follows the active locale.
+- **AR4 — Reduced motion.** Motion slows under `prefers-reduced-motion:
+reduce` and keeps moving, so the ring still reads as working.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                        | Representation authority | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Ring             | A moving arc on a track signals indeterminate work.       | Current source           | Prominent      | FR2–FR6, AR2, AR4  |
+| Label            | Optional bold text or caller content describing the work. | Current source and docs  | Supporting     | FR1, FR7, AR1      |
+
+Theming: the element carrying the `spinner` target reflects `size` and `shade`
+and declares the five public variables; the ring circles read them. The
+consumer anatomy names no parts, so no anatomy-theming block is declared.
+
+## Family and system relationships
+
+- `spec:AST-086` owns status-announcement delivery; AR1 records Spinner's gap
+  against FR2 and FR11, and composing busy owners are silent under FR8.
+- `architecture:component-theming-surface` owns target and variable
+  qualification; FR6 records where Spinner declares its variables.
+- `architecture:internationalization` owns the catalog the default name uses.
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR2 and FR8 record the box-size exception to `style` precedence.
+
+## Verification map
+
+| Contract      | Verification                                                              | Representative states                                          | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                      | Audit section            |
+| ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| FR1, FR7, FR8 | `Spinner.test.tsx` render, label, and data-testid tests                   | Unlabelled, string label, rich label                           | A lost label or test id fails. Gap: in both forms no test asserts which element carries the ref, `xstyle`, and `className`, or where the target lands in the labelled form.                                                                                                                                                                                                          | `audit:Spinner/behavior` |
+| FR2           | `Spinner.test.tsx` box-sizing suite; `Spinner.stories.tsx` NarrowFlexHost | Every size; caller `style` width; narrow flex host             | A caller width winning, or a lost fallback frame, fails. Gap: no automated check fails if the box shrinks in a flex host; it is visible in the story.                                                                                                                                                                                                                                | `audit:Spinner/layout`   |
+| FR3, FR4, PR2 | `Spinner.test.tsx` ring suite, including the 135-degree sweep test        | SVG structure, default dash and arc fraction, frame scheduling | A lost circle, a changed default dash or arc fraction, an extra frame, or unbatched pinning fails. Gap: the start-angle test checks only for no SVG `transform` attribute, so removing the CSS start rotation passes; the cycle duration, the 3-second reduced-motion rate, the themed arc fraction, and dropping an unmounted ring from pending phase work have no automated check. | `audit:Spinner/motion`   |
+| FR5, FR6      | `Spinner.test.tsx` theme-variable suite                                   | Size-, shade-, and base-scoped overrides                       | A themed variable emitted on the wrong selector fails. Gap: no test fails if the component declares its defaults on the inner span of a labelled Spinner, and the shade tests assert presence and reflection only, so the default colors and track opacities have no automated check.                                                                                                | `audit:Spinner/theming`  |
+| PR1           | `Spinner.test.tsx` registration suite                                     | Import, repeated evaluation                                    | Doing the work on mount or throwing on a second evaluation fails. Gap: the suite runs only with a DOM, so server-side safety has no automated check.                                                                                                                                                                                                                                 | `audit:Spinner/behavior` |
+| AR1, AR3      | `Spinner.test.tsx` naming and localization tests                          | Default, explicit, string, and rich labels                     | A missing name, a string label repeated as `aria-label`, or an untranslated default fails. Gap: no test covers an empty `aria-label` or `label`, or a caller `aria-labelledby`.                                                                                                                                                                                                      | `audit:Spinner/a11y`     |
+| AR4           | `Spinner.stories.tsx` with reduced motion emulated in a browser           | Reduced motion                                                 | Gap: no automated check; a stopped ring is visible only in a rendered fixture.                                                                                                                                                                                                                                                                                                       | `audit:Spinner/motion`   |
+| AR2           | Source review                                                             | Every state                                                    | Gap: no automated check fails if the ring SVG loses `aria-hidden`.                                                                                                                                                                                                                                                                                                                   | `audit:Spinner/a11y`     |
+| AR1, AR2      | `StatusMessage.a11y.chromium.spec.ts` Spinner states                      | Default label and visible string label, mounted                | A changed role or name fails the accessibility-tree assertions. Gap: rich labels, empty names, the hidden ring, and channel delivery have no accessibility-tree check.                                                                                                                                                                                                               | `audit:Spinner/a11y`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+- **OQ1 — What role and name should a standalone Spinner expose once it no
+  longer carries a live role?** (`human-api`) `spec:AST-086` leaves this outside
+  its scope. Options: a named image, a named generic element with no role, or
+  no exposed node with the channel message as the only output.
+
+## 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/Stack/Stack.spec.md

@@ -1,45 +1,68 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Stack
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-28
 owners: [cixzhang]
-review_triggers: [layout, theming]
+review_triggers: [public-api, layout, theming, accessibility]
 verified_by:
   [
+    packages/core/src/serverSafeComponents.test.ts,
+    .github/visual-baseline/manifest.json,
     packages/core/src/Stack/Stack.test.tsx,
     packages/core/src/Stack/StackItem.test.tsx,
+    packages/core/src/HStack/HStack.test.tsx,
+    packages/core/src/VStack/VStack.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/Stack.stories.tsx,
     scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:layout-primitives]
 design_specs: []
 architecture:
-  [architecture:component-theming-surface, architecture:container-padding]
+  [
+    architecture:component-theming-surface,
+    architecture:container-padding,
+    architecture:public-component-api,
+  ]
 contributing: []
 system_specs: []
 ---
 
 # Stack component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | Stack arranges children on one flex axis with `direction`, alignment, `gap`, per-edge `padding`, sizing, `wrap`, `isScrollable`, and `as`. HStack and VStack fix the direction; StackItem controls one child's participation. |
+| Behavior                | Alignment props resolve to the main or cross axis from the direction; padding resolves per logical edge; padding stays local and publishes no container inset.                                                                |
+| End-user impact         | Readers see consistent spacing and alignment that follows the writing direction.                                                                                                                                              |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                                  |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                                                                                    |
+| Review checks           | Reject physical left/right padding, an alias that wins over an explicit alignment, padding that publishes container inset, or a StackItem without the flex minimum reset.                                                     |
+| Governing rules         | `family:layout-primitives/FR1–FR6,FR8`; `architecture:container-padding/INV8`; `architecture:public-component-api/INV5,INV6,INV8`.                                                                                            |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-Stack arranges caller-supplied content along one flex axis. StackItem optionally
-wraps one item to control its participation in that layout. This draft records
-the current consumer anatomy and theming ownership without changing layout,
-padding, targets, or public API.
+Stack is the one-dimensional layout primitive. It owns direction, axis-aware
+alignment, gap, local padding, sizing, wrapping, and scrolling for a flex
+container, and StackItem owns one child's growth, alignment, and scrolling
+inside it.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
@@ -49,61 +72,84 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The Stack container and its current `stack` theming target.
-- The optional StackItem wrapper and its current `stack-item` theming target.
+- Stack, and HStack, VStack, and StackItem, which `Stack.doc.mjs` documents as
+  inline `components:` entries. This record covers all four; none has its own
+  consumer doc or record.
+- The Stack container and its `stack` target; the StackItem wrapper and its
+  `stack-item` target.
+- Axis resolution for alignment, per-edge padding resolution, gap, sizing,
+  wrapping, and scrolling.
 
 **Does not own / non-goals**
 
 - Content supplied to Stack or StackItem — owned by the caller.
-- Container-inset publication or descendant bleed behavior; Stack padding is
-  currently local and does not participate in the container-padding protocol.
-- New layout, padding, or responsive behavior.
+- Container-inset publication and descendant bleed — owned by publishers under
+  `architecture:container-padding`; Stack padding is local.
+- Two-dimensional layout — owned by `component:Grid`; centering — owned by
+  `component:Center`.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `Stack.doc.mjs`; `family:layout-primitives` owns the shared layout vocabulary.
+| Concept   | Closed values or states                                                                                           | Meaning                                                           | Availability by variant/orientation/state | Default                                       | Owner             | Stability | Invalid-value behavior                                                                                                                                                                 |
+| --------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------- | ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Direction | `horizontal`, `vertical`                                                                                          | Flex row or column. HStack is horizontal; VStack is vertical.     | Stack only; fixed on HStack and VStack    | `vertical`                                    | `component:Stack` | Stable    | TypeScript rejects other values.                                                                                                                                                       |
+| Alignment | main axis `start`, `center`, `end`, `between`, `around`, `evenly`; cross axis `start`, `center`, `end`, `stretch` | `hAlign`/`vAlign` by physical name, or `justify`/`align` by axis. | All stacks                                | browser default (`stretch` on the cross axis) | `component:Stack` | Stable    | Stack accepts every alignment value on `hAlign` and `vAlign` and ignores one that does not apply to the resolved axis; HStack, VStack, `justify`, and `align` reject it in TypeScript. |
+| Gap       | Spacing steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10                                                                | Row and column gap.                                               | All stacks                                | unset                                         | `component:Stack` | Stable    | TypeScript rejects other values.                                                                                                                                                       |
+| Padding   | Spacing steps per edge, per axis, or uniform                                                                      | Local inner padding.                                              | All stacks                                | unset                                         | `component:Stack` | Stable    | TypeScript rejects other values.                                                                                                                                                       |
+| Wrap      | `nowrap`, `wrap`, `wrap-reverse`                                                                                  | Flex wrapping.                                                    | All stacks                                | unset (`nowrap`)                              | `component:Stack` | Stable    | TypeScript rejects other values.                                                                                                                                                       |
+| Item size | `static`, `fill`                                                                                                  | StackItem neither grows nor shrinks, or grows to fill.            | StackItem                                 | `static`                                      | `component:Stack` | Stable    | TypeScript rejects other values.                                                                                                                                                       |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                            | Basis                                   | Draft review state                                 |
-| --- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| FR1 | Stack, HStack, and VStack render caller content in a container carrying the current `stack` target.            | Current source, docs, tests, and family | Verified current behavior; no new behavior decided |
-| FR2 | StackItem renders caller content in its own wrapper carrying the current `stack-item` target.                  | Current source, docs, and tests         | Verified current behavior; no new behavior decided |
-| FR3 | Stack and StackItem render caller-supplied content directly without applying a content-specific public target. | Current source and tests                | Verified current behavior; no target change        |
-| FR4 | Stack's existing padding remains local and does not publish container-padding geometry to descendants.         | Current source and architecture record  | Verified current behavior; no protocol change      |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                | Basis                    |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Stack renders the element named by `as` (default `div`) as a flex container in the given direction, carrying the `stack` target, which reflects `direction`, `gap`, and `wrap`. HStack renders Stack with `direction="horizontal"` and VStack with `direction="vertical"`.                                                                               | Current source and tests |
+| FR2 | `hAlign` and `vAlign` name physical axes: in a horizontal stack `hAlign` sets main-axis justification and `vAlign` cross-axis alignment, and in a vertical stack the reverse. `justify` and `align` name the main and cross axes and apply only when the matching `hAlign` or `vAlign` is absent. Unset alignment leaves the browser defaults.           | Current source and tests |
+| FR3 | `gap` sets equal row and column gaps from the spacing scale. Padding resolves per logical edge: the edge prop, then its axis prop (`paddingInline` or `paddingBlock`), then `padding`; inline edges follow the writing direction.                                                                                                                        | Current source and tests |
+| FR4 | Stack padding is local: it publishes no container-padding variables, so descendants cannot use it for bleed compensation.                                                                                                                                                                                                                                | Current source           |
+| FR5 | `width`, `height`, `maxWidth`, and `minHeight` apply numbers as pixels and strings as given, as inline styles after the caller's `style`. `wrap` sets flex wrapping. `isScrollable` sets `overflow: auto`.                                                                                                                                               | Current source and tests |
+| FR6 | StackItem renders the element named by `as` (default `div`) carrying the `stack-item` target, which reflects `size`; it always resets its minimum width and height to zero, `static` neither grows nor shrinks, `fill` grows to share remaining space, `crossAlignSelf` overrides the stack's cross alignment, and `isScrollable` sets `overflow: auto`. | Current source and tests |
+| FR7 | `ref` reaches the rendered element of Stack, HStack, VStack, and StackItem. Supported DOM, ARIA, data, and event props reach it; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                          | Current source and tests |
 
 ### Allowed variation
 
-- Caller content may render directly in Stack or inside optional StackItem
-  wrappers without changing target ownership.
+- **AV1 — Element.** Callers choose the element through `as`.
+- **AV2 — Theme paint.** A theme may restyle `stack` and `stack-item` without
+  changing axis resolution or padding precedence.
 
 ### Representative states
 
-- Horizontal and vertical Stack forms use the same container target. StackItem
-  uses its item target across static, fill, and scrollable behavior.
+| State                   | Required invariant                                                                      | Allowed variation |
+| ----------------------- | --------------------------------------------------------------------------------------- | ----------------- |
+| Vertical default        | Flex column; `data-direction="vertical"`.                                               | Children.         |
+| Horizontal with aliases | `justify` sets the main axis, `align` the cross axis, unless `hAlign`/`vAlign` are set. | —                 |
+| Per-edge padding        | Each edge resolves independently; inline edges mirror in right-to-left.                 | —                 |
+| Fill and scroll item    | `StackItem size="fill" isScrollable` grows and scrolls its own overflow.                | —                 |
 
 ### Transformation and precedence order
 
-- No new direction, alignment, spacing, sizing, or padding precedence rule is
-  introduced.
+- **ORD1 — Alignment.** `hAlign`/`vAlign` → `justify`/`align` by axis → browser
+  default.
+- **ORD2 — Padding per edge.** Edge prop → axis prop → `padding`.
+- **ORD3 — Sizing.** Caller `style` → sizing props.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — Static render.** Stack, HStack, VStack, and StackItem hold no state and
+  use no hooks.
 
 ## Accessibility contract
 
-This draft does not change or extend Stack's polymorphic element, forwarded DOM
-props, or caller-owned content semantics.
+- **AR1 — No semantics added.** Stack and StackItem add no role, name, or tab
+  stop of their own; their semantics are those of the `as` element.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                         | Representation authority                  | Hierarchy role    | Component contract |
-| ---------------- | ---------------------------------------------------------- | ----------------------------------------- | ----------------- | ------------------ |
-| Stack container  | Presents the one-dimensional layout container.             | Current source, docs, and family contract | Supporting        | FR1, FR4           |
-| Item             | Optionally controls one child's participation in Stack.    | Current source, docs, and family contract | Supporting        | FR2                |
-| Content          | Presents caller-supplied content in either public wrapper. | Caller-supplied content                   | Context-dependent | FR1, FR2, FR3      |
+| Anatomy or state | Design requirement                             | Representation authority                  | Hierarchy role    | Component contract |
+| ---------------- | ---------------------------------------------- | ----------------------------------------- | ----------------- | ------------------ |
+| Stack container  | The one-dimensional layout container.          | Current source, docs, and family contract | Supporting        | FR1–FR5            |
+| Item             | Optionally controls one child's participation. | Current source, docs, and family contract | Supporting        | FR6                |
+| Content          | Caller content in either wrapper.              | Caller-supplied content                   | Context-dependent | AR1                |
 
 ### Theming anatomy
 
@@ -123,26 +169,29 @@ props, or caller-owned content semantics.
 
 ## Family and system relationships
 
-- `family:layout-primitives` owns Stack's shared direction, alignment, spacing,
-  sizing, padding, and item-participation vocabulary.
-- `architecture:container-padding` records that Stack padding is local and does
-  not publish descendant bleed geometry.
-- `architecture:component-theming-surface` owns anatomy qualification and target
-  mapping rules.
+- `family:layout-primitives` owns the shared spacing, padding precedence, and
+  modifier rules; Stack, HStack, VStack, and StackItem are members, and FR2,
+  FR3, and FR6 apply them.
+- `architecture:container-padding` records Stack padding as local (FR4).
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR7 applies them.
 
 ## Verification map
 
-| Contract            | Verification                                       | Representative states                          | Mutation or failure expectation                                                        | Audit section             |
-| ------------------- | -------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------- |
-| FR1, FR3, FR4       | `Stack.test.tsx` render, props, and padding suites | Horizontal/vertical, direct content, padding   | Removing the container/content or changing shipped local padding fails existing tests. | `audit:Stack/anatomy`     |
-| FR2, FR3            | `StackItem.test.tsx` render and behavior suites    | Static, fill, polymorphic, and scrollable item | Removing the wrapper/content or changing current item behavior fails existing tests.   | `audit:StackItem/anatomy` |
-| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`   | Stack and StackItem targets                    | Runtime and documented target metadata drift fails target validation.                  | `audit:Stack/theming`     |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                      | Canonical anatomy and both current targets     | Missing, extra, prefixed, or stale mappings fail repository validation.                | `audit:Stack/theming`     |
+| Contract            | Verification                                                                                                       | Representative states                                            | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                     | Audit section          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1, FR2            | `Stack.test.tsx`, `HStack.test.tsx`, `VStack.test.tsx` element tests; stable visual baseline `core-stack--default` | Default and `as` elements; default stack                         | A wrong default or `as` element fails; a changed default direction, gap, or alignment comes back changed for review. Gap: the direction, alignment, and alias tests assert only that content renders, so direction, `hAlign`/`vAlign` mapping, alias precedence, the `stack` target, and its reflection have no unit check.                                                                         | `audit:Stack/layout`   |
+| FR3                 | `Stack.test.tsx` padding-precedence tests; `@astryx/no-physical-properties` lint rule                              | Uniform, axis, edge, all four edges                              | A missing padding class, edge over axis on the end edges, edge over uniform on the edges the tests pair, or a physical left/right padding property fails. Gap: edge over axis on the start edges, axis over uniform, any untested edge-over-uniform pairing, and the gap value (the gap test asserts only that content renders) have no check, and no browser right-to-left check covers the edges. | `audit:Stack/layout`   |
+| FR5                 | `Stack.test.tsx` sizing and scrolling tests                                                                        | Numeric and string sizes; scrollable                             | A wrong computed width or height, or no class change for `isScrollable`, fails. Gap: `wrap`, `maxWidth`, `minHeight`, and size winning over caller `style` have no check.                                                                                                                                                                                                                           | `audit:Stack/layout`   |
+| FR6                 | `StackItem.test.tsx` element, scroll, and passthrough tests                                                        | Default and `as` elements; scrollable; `size="fill"` with scroll | A wrong element, or no class change for `isScrollable`, fails. Gap: the size and `crossAlignSelf` tests assert only that content renders, so the minimum-size reset, `static`, `fill`, cross alignment, and the `stack-item` target have no check.                                                                                                                                                  | `audit:Stack/layout`   |
+| FR7                 | Ref and pass-through tests in all four suites                                                                      | Default and `as` elements                                        | A dropped ref fails in all four suites, and a dropped `aria-label` in the Stack and StackItem suites (the HStack and VStack pass-through tests assert `data-testid` only). Gap: the ref tests accept any element, so a ref on a wrapper passes, and the styling-input merge order has no check.                                                                                                     | `audit:Stack/behavior` |
+| FR4                 | Source review against `architecture:container-padding`                                                             | Padded stack                                                     | Gap: no automated check fails if Stack publishes container-padding variables.                                                                                                                                                                                                                                                                                                                       | `audit:Stack/layout`   |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                      | Consumer anatomy and current targets                             | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                       | `audit:Stack/theming`  |
+| AR1, PR1            | `serverSafeComponents.test.ts`; source review                                                                      | Every form                                                       | A client API (state, an effect, a context read) added without a client directive fails `serverSafeComponents.test.ts`. Gap: a client API added together with a client directive passes, and no automated check fails if Stack or StackItem adds a role.                                                                                                                                             | `audit:Stack/behavior` |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-layout, or API decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
@@ -150,6 +199,5 @@ None.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables, examples, family layout
-rules, container-padding mechanics, 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.