@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/FieldStatus/FieldStatus.spec.md

@@ -1,224 +0,0 @@
----
-schema_version: 3
-template_version: 1
-kind: component
-id: component:FieldStatus
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-08-30
-owners: [cixzhang, imdreamrunner]
-review_triggers: [public-api, behavior, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/FieldStatus/FieldStatus.test.tsx,
-    packages/core/src/FieldStatus/__tests__/StatusMessage.a11y.test.tsx,
-    packages/core/src/FieldStatus/__tests__/StatusMessage.a11y.chromium.spec.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture: [architecture:component-theming-surface]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-020, spec:AST-021]
----
-
-# FieldStatus component contract
-
-## Intent
-
-FieldStatus presents one validation message for a field or field-like control. It
-owns the visible message treatment and announcement behavior for attached and
-detached presentations; consumer usage remains documented in
-`FieldStatus.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling, and
-  public API remain unchanged, except that delivery inside a mounted live
-  container follows `spec:AST-086` FR4
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: direct `FieldStatus variant="tooltip"` support is rejected.
-  `tooltip` remains a field-family sentinel that MUST be handled before rendering
-  FieldStatus. Narrowing the currently permissive type/runtime path requires a
-  separate compatibility-aware implementation change.
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The attached and detached validation-message presentations.
-- Routing visible messages through the persistent announcement channels.
-- The detached presentation's redundant visual status glyph.
-
-**Does not own / non-goals**
-
-- Whether a caller renders a status message, or which control it describes —
-  owned by the composing field component or product callsite.
-- The bordered control's status treatment and on-field tooltip presentation —
-  owned by the composing field component.
-- General alerts and page-level notices — owned by the corresponding feedback
-  components.
-
-## Public concepts
-
-| Concept      | Closed values or states       | Meaning                                            | Availability by variant/orientation/state                                                                  | Default    | Owner                   | Stability | Invalid-value behavior                                                                                                          |
-| ------------ | ----------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Status type  | `error`, `warning`, `success` | Selects the message tone and announcement channel. | All rendered presentations.                                                                                | Required   | `component:FieldStatus` | Stable    | TypeScript rejects unsupported values.                                                                                          |
-| Presentation | `attached`, `detached`        | Selects the message presentation.                  | All direct FieldStatus usage. The field family's `tooltip` sentinel is handled before FieldStatus renders. | `attached` | `component:FieldStatus` | Stable.   | TypeScript rejects values absent from the extensible variant map; its current acceptance of `tooltip` is an implementation gap. |
-
-The field family's `tooltip` status presentation suppresses FieldStatus and
-surfaces the message from the control's on-field icon. `tooltip` is not a
-FieldStatus presentation. The public extensible variant map currently permits a
-direct `tooltip` value; that is an implementation gap, not supported behavior.
-
-## Behavioral and layout contract
-
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                        | Basis                                               | Draft review state                                      |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
-| FR1 | FieldStatus MUST render the provided message in one visible message box when mounted.                                                                      | Documented promise and current tests.               | Settled intent.                                         |
-| FR2 | The attached presentation MUST render the message without a leading glyph; the detached presentation MUST render its status glyph before the message text. | Documented promise, current DOM, and current tests. | Settled intent.                                         |
-| FR3 | Status type MUST select distinct error, warning, or success treatment and MUST be reflected on the message-box target.                                     | Current behavior and theming tests.                 | Settled intent.                                         |
-| FR4 | The detached glyph MUST reflect status type on its own target; the target MUST be absent from attached presentation.                                       | Current behavior and target tests.                  | Settled intent.                                         |
-| FR5 | The root MUST continue to forward its ref, ID, supported DOM props, and consumer styling escape hatches.                                                   | Current behavior and tests.                         | Current compatibility behavior; verify before changing. |
-| FR6 | Message and status-type updates MUST update the visible output without replacing the component contract.                                                   | Current behavior and tests.                         | Current compatibility behavior; verify before changing. |
-| FR7 | Direct FieldStatus usage MUST support only `attached` and `detached`; the Field family MUST consume its `tooltip` sentinel before rendering FieldStatus.   | Approved component boundary.                        | Settled intent; current type acceptance is a gap.       |
-
-### Allowed variation
-
-- **AV1 — Theme styling.** Theme and consumer overrides may change visual CSS
-  properties through the existing targets and styling escape hatches without
-  changing anatomy, ownership, or presentation behavior.
-- **AV2 — Message length.** The message may wrap; the detached glyph remains
-  aligned with the first text line.
-
-### Representative states
-
-| State            | Required invariant                                             | Allowed variation                                           |
-| ---------------- | -------------------------------------------------------------- | ----------------------------------------------------------- |
-| Attached error   | Message box and text render; no detached glyph renders.        | Theme-controlled visual properties on `field-status`.       |
-| Detached warning | Message box, leading warning glyph, then message text render.  | Theme-controlled visual properties on both current targets. |
-| Detached success | Message box, leading success glyph, then message text render.  | Message length and theme-controlled visual properties.      |
-| Empty message    | The root remains mounted and renders the provided empty value. | No announcement channel is created.                         |
-
-### Transformation and precedence order
-
-- **ORD1 — Presentation styling.** Resolve the default presentation, reflect
-  status and presentation through `themeProps`, apply component styles, then
-  merge `xstyle`, `className`, and inline `style` in their established order.
-- **ORD2 — Detached content.** Render the decorative status glyph before the
-  message text, using the same status-to-glyph mapping as field controls.
-
-### Performance and resources
-
-- **PR1 — Channel-update work.** A message change schedules only the persistent
-  live-region update; FieldStatus owns no global event listeners, observers, or
-  measurements.
-
-## Accessibility contract
-
-- **AR1 — Programmatic announcement channel.** Errors MUST update the persistent
-  assertive region; warnings and successes MUST update the persistent polite
-  region, including on first mount and when message or type changes, without
-  moving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.
-- **AR5 — Assistive-technology output.** Claims about whether, when, or how the
-  message is spoken or presented in braille are recommended real-AT follow-up
-  under `spec:AST-009`, not a merge or release requirement; DOM and
-  accessibility-tree checks prove programmatic exposure and routing.
-- **AR2 — Visible description.** The rendered message box MUST remain available
-  to assistive technology for `aria-describedby` association and MUST NOT become
-  its own newly mounted live region.
-- **AR3 — Non-color cue.** Detached status MUST include a leading status glyph so
-  status is not conveyed only by color or position.
-- **AR4 — Redundant glyph.** The detached glyph MUST remain hidden from assistive
-  technology because the visible message already conveys the status in text;
-  announcement output remains owned by AR5.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                         | Representation authority                        | Hierarchy role | Component contract |
-| ---------------- | ---------------------------------------------------------- | ----------------------------------------------- | -------------- | ------------------ |
-| Message box      | Carries the visible validation treatment.                  | Current behavior and approved component intent. | Supporting     | FR1, FR3           |
-| Detached icon    | Adds a non-color status cue only in detached presentation. | Current behavior and approved component intent. | Supporting     | FR2, FR4, AR3      |
-| Message text     | Communicates the validation result in words.               | Current behavior and approved component intent. | Prominent      | FR1, AR1, AR2, AR5 |
-
-Current behavior renders the detached icon before message text. The intended
-public theming ownership is the exact map below; it does not add a target or
-change either presentation.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Message box": {"target": "field-status"},
-  "Detached icon": {"target": "field-status-icon"},
-  "Message text": {"inherits": "field-status"}
-}
-```
-
-## Family and system relationships
-
-- `architecture:component-theming-surface` owns the qualification and validation
-  rules for the two targets and inherited message text.
-- Field-like controls compose FieldStatus but continue to own control rendering,
-  status placement decisions, and association with the control.
-
-## Verification map
-
-| Contract            | Verification                                                            | Representative states                                         | Mutation or failure expectation                                                                                                       | Audit section                     |
-| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1, FR2, AR3, AR4  | `FieldStatus.test.tsx` rendering and detached-icon suites               | Attached and detached; all status types                       | Removing or reordering presentation parts fails DOM and accessibility assertions.                                                     | `audit:FieldStatus/anatomy`       |
-| FR3, FR4            | `FieldStatus.test.tsx` theme target suites                              | Attached/detached; error/warning/success                      | Removing a target or status reflection fails class/data-attribute assertions.                                                         | `audit:FieldStatus/theming`       |
-| FR5, FR6            | `FieldStatus.test.tsx` forwarding and update suites                     | Initial render and rerender                                   | Breaking the released root or update behavior fails compatibility assertions.                                                         | `audit:FieldStatus/behavior`      |
-| AR1                 | `StatusMessage.a11y.test.tsx` and `StatusMessage.a11y.chromium.spec.ts` | Error, warning, and success; post-mount message replacement   | Removing the persistent channel, changing its role/urgency, or dropping a post-mount update fails the shared status-message contract. | `audit:FieldStatus/accessibility` |
-| AR1                 | `FieldStatus.test.tsx` channel-routing suite                            | First non-empty mount; same-instance message and type changes | Breaking FieldStatus's first-use hook call or severity rerouting fails component-specific assertions.                                 | `audit:FieldStatus/accessibility` |
-| AR5                 | Recommended real-AT follow-up under `spec:AST-009`                      | First mount; message replacement; type/urgency change         | Spoken and braille output stay unverified until a real-AT receipt exists; this does not block merge or release.                       | `audit:FieldStatus/accessibility` |
-| AR2                 | `FieldStatus.test.tsx`                                                  | Attached/detached visible message and empty message           | The visible description becomes a second live region or is hidden from assistive technology.                                          | `audit:FieldStatus/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                           | Consumer anatomy and current targets                          | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                   | `audit:FieldStatus/theming`       |
-
-## Decision log
-
-### DEC-1 — Presentation-specific anatomy remains explicit
-
-**Reference:** `component:FieldStatus/DEC-1`
-**Decider:** cixzhang, 2026-08-30
-
-The detached icon is a separate anatomy part because only detached presentation
-renders it and it owns a target distinct from the message box. Message text
-inherits the message-box target rather than creating a redundant child target.
-
-Rejected: collapsing the glyph into a generic message row, which would hide its
-presentation condition and distinct theming owner.
-
-### DEC-2 — `tooltip` is not a FieldStatus presentation
-
-**Reference:** `component:FieldStatus/DEC-2`
-**Decider:** cixzhang, 2026-08-30
-
-Direct FieldStatus usage supports only `attached` and `detached`. The Field
-family may use `tooltip` as an internal presentation sentinel, but it MUST
-consume that value before rendering FieldStatus and surface the message through
-the control's on-field status treatment instead.
-
-Rejected: defining direct `FieldStatus variant="tooltip"` rendering semantics.
-That would expose a field-composition mechanism as a third FieldStatus
-presentation and preserve currently unintentional output.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop examples, current audit results,
-implementation steps, or family/system rules. It links to their owners.

package/src/FileInput/FileInput.spec.md

@@ -1,199 +0,0 @@
----
-schema_version: 3
-template_version: 4
-kind: component
-id: component:FileInput
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-14
-owners: [cixzhang, imdreamrunner]
-review_triggers: [theming]
-verified_by:
-  [
-    packages/core/src/FileInput/FileInput.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:input-fields]
-design_specs: []
-architecture: [architecture:component-theming-surface]
-contributing: []
-system_specs: []
----
-
-# FileInput component contract
-
-## Intent
-
-FileInput presents a labelled file-selection field in compact input or dropzone
-form. This contract records its current consumer anatomy and approves separate theme
-ownership for the upload affordance that FileInput paints through Icon.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: additive public theming target; no existing target,
-  runtime default, DOM, prop, interaction, or accessibility behavior changes
-- Controlled/uncontrolled behavior: unchanged; FileInput remains controlled
-- Migration decision: `component:FileInput/DEC-1`
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The visible file-selection surface and its input/dropzone mode.
-- Whether, where, and at what default size the upload affordance appears.
-- Reflecting FileInput's mode on its locally owned theme targets.
-
-**Does not own / non-goals**
-
-- The upload artwork or Icon's base color, size, and accessibility semantics —
-  owned by `component:Icon`.
-- Label, description, clear-control, and validation-message presentation — owned
-  by `component:Field` and `component:FieldStatus`.
-- Loading-indicator presentation — owned by `component:Spinner`.
-- A new prop, variant, icon slot, or custom property.
-
-## Public concepts
-
-No consumer prop changes. The `file-input-icon` target gives themes a
-same-element seam for the Upload icon and reflects the existing `mode` axis. The
-existing `file-input` target remains on the visible selection surface and keeps
-its `mode` and `status` axes.
-
-## Behavioral and layout contract
-
-| ID  | Candidate invariant                                                                                                                                                                                                  | Basis                                             | Review state                    |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------- |
-| FR1 | The visible selection surface carries `file-input` and reflects the existing `mode` and resolved status.                                                                                                             | Current source, public docs, and focused tests    | Verified current behavior       |
-| FR2 | When not loading, input mode renders an upload affordance at the small Icon size. Dropzone mode renders it at the medium Icon size only while no file is selected.                                                   | Current source and focused tests                  | Verified current behavior       |
-| FR3 | Icon owns the rendered glyph's base size, color, and accessibility semantics; FileInput owns the affordance's mode-dependent placement and default size.                                                             | Current composition and component boundaries      | Verified current composition    |
-| FR4 | The rendered upload affordance MUST carry `file-input-icon` with the existing `mode` reflected, so a theme can restyle the glyph box without structural selectors or changing every Icon that uses the same artwork. | Owner-approved target contract                    | Approved additive contract      |
-| FR5 | Adding the target MUST NOT change the default artwork, computed layout, interaction, file-selection behavior, accessible name, or decorative Icon semantics.                                                         | Compatibility policy and focused regression tests | Required compatibility behavior |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** A theme may change standard visual
-  properties such as the upload glyph's size or color through
-  `file-input-icon`; FileInput still owns whether and where the affordance renders.
-- **AV2 — Artwork.** Icon registry and future icon-slot decisions may change the
-  artwork without changing this CSS target's ownership of the painted glyph box.
-
-### Representative states
-
-| State                    | Required invariant                                                       | Allowed variation                       |
-| ------------------------ | ------------------------------------------------------------------------ | --------------------------------------- |
-| Input, empty or selected | Small upload affordance renders on the input surface when not loading.   | Files, placeholder, status, theme paint |
-| Dropzone, empty          | Medium upload affordance renders above the placeholder when not loading. | Drag state, placeholder, theme paint    |
-| Dropzone, selected       | File names replace the upload affordance.                                | File names and status                   |
-| Loading                  | Spinner replaces the upload affordance.                                  | Mode and loading presentation           |
-
-### Transformation and precedence order
-
-- **ORD1 — Content selection.** Resolve loading and selected-file state, choose
-  input or dropzone content, then render the mode-sized upload affordance only in
-  the states recorded by FR2.
-- **ORD2 — Theme composition.** Icon applies its base size and color, then the
-  same-element FileInput target participates in the existing theme layer and
-  standard Icon styling merge order.
-
-### Performance and resources
-
-- **PR1 — No new work.** The additive target performs no measurement, listener,
-  observer, state update, or additional render pass.
-
-## Accessibility contract
-
-The upload affordance remains decorative. The existing focusable file-selection
-trigger, label, description, required/invalid state, disabled explanation, and
-selection announcements remain unchanged.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                                  | Representation authority                 | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | ------------------ |
-| Drop zone        | Presents the visible file-selection surface in input or dropzone form.              | Current source and public docs           | Prominent      | FR1                |
-| Upload icon      | Hints at the upload action and changes default size with the selected mode.         | Current source and owner-approved target | Supporting     | FR2, FR3, FR4      |
-| Shared feedback  | Uses Field, FieldStatus, and Spinner for labels, validation, and loading treatment. | Current shared composition               | Supporting     | FR5                |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Label": {
-    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
-  },
-  "Description": {
-    "none": {
-      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
-    }
-  },
-  "Drop zone": {"target": "file-input"},
-  "Upload icon": {"target": "file-input-icon"},
-  "Placeholder": {"inherits": "file-input"},
-  "File name display": {"inherits": "file-input"},
-  "Clear button": {
-    "delegatesTo": {
-      "owner": "component:Field",
-      "target": "input-clear-button"
-    }
-  },
-  "Spinner": {
-    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
-  },
-  "Status message": {
-    "delegatesTo": {
-      "owner": "component:FieldStatus",
-      "target": "field-status"
-    }
-  }
-}
-```
-
-The `file-input-icon` disposition records the approved target state. Icon still
-owns the general `icon` target and base glyph semantics; FileInput's narrower
-target owns only this stable upload position and its existing mode distinction.
-
-## Family and system relationships
-
-- `family:input-fields` owns shared labelled-field and validation behavior.
-- `architecture:component-theming-surface` owns target qualification, anatomy
-  mapping, and the requirement that public targets sit on stable painted parts.
-- Field, FieldStatus, Icon, and Spinner retain their existing public target
-  contracts when composed by FileInput.
-
-## Verification map
-
-| Contract            | Verification                                                      | Representative states                              | Mutation or failure expectation                                                                             | Audit section             |
-| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1, FR2            | `FileInput.test.tsx` rendering and target suites                  | Input/dropzone; empty/selected/loading             | Moving the root target or changing when/at what size the affordance renders breaks focused assertions.      | `audit:FileInput/theming` |
-| FR3, FR4, FR5       | `FileInput.test.tsx`, `themingTargets.test.ts`, probe-theme check | Both modes and same-element Icon target            | Missing the target, reflecting the wrong mode, or moving it off the glyph fails source/docs/probe coverage. | `audit:FileInput/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                     | Nine anatomy entries and two locally owned targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation.                             | `audit:FileInput/anatomy` |
-
-## Decision log
-
-### DEC-1 — Upload icon is stable FileInput theme anatomy
-
-**Reference:** `component:FileInput/DEC-1`
-**Decider:** cixzhang, 2026-09-14
-
-The upload icon is a stable, consumer-recognizable FileInput affordance whose
-mode-dependent placement and default size belong to FileInput. It receives the
-`file-input-icon` target on the same Icon element that paints the glyph, while
-Icon retains its general target and base glyph semantics.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, implementation
-steps, or shared-component contracts. It links to their owners.

package/src/FormLayout/FormLayout.spec.md

@@ -1,201 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:FormLayout
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Layer/layerScopedContext.test.tsx,
-    .github/scripts/story-play-guard.js,
-    .github/visual-baseline/manifest.json,
-    packages/core/src/FormLayout/FormLayout.test.tsx,
-    apps/storybook/stories/FormLayout.stories.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/docPropLiterals.test.ts,
-    packages/core/src/docPropReferences.test.ts,
-  ]
-modules: []
-families: [family:input-fields]
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-  ]
-contributing: []
-system_specs: [spec:AST-038]
----
-
-# FormLayout component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                           |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `FormLayout` arranges caller-owned fields through `vertical`, `horizontal`, and `horizontal-labels` directions, provides a form-level optionality default, exports its context and supporting types, and accepts root `BaseProps`. |
-| Behavior                | Vertical stacks children; horizontal creates one fractional grid track per child in logical inline order; horizontal-labels pairs Field labels and controls, then collapses below a 481px viewport.                                |
-| End-user impact         | People encounter predictable field spacing and order, and assistive technology receives required-state information even when the form-wide visual convention leaves the common case unmarked.                                      |
-| Builder impact          | Builders supply the fields and any semantic `<form>`, title, or footer; nested layouts replace the outer direction and optionality context for their descendants.                                                                  |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or runtime changes.                                                                                                                                                        |
-| Review checks           | Reject lost root props, physical inline ordering, changed collapse boundaries, caller-overridable direction reflection, lost nested-context shadowing, or a visible optionality convention that disagrees with ARIA.               |
-| Governing rules         | Established public FormLayout interface; `family:input-fields` outer-arrangement ownership; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-`FormLayout` owns the outer spatial relationship among caller-owned form fields. It does not create form submission, field state, labels, controls, or action regions.
-
-## Compatibility and migration
-
-- Released default preserved: yes; direction defaults to `vertical`, and optionality remains field-owned when `defaultOptionality` is unset.
-- Compatibility class: records shipped behavior; no public prop, default, or behavior changes.
-- Controlled/uncontrolled behavior: not applicable; FormLayout owns no form value or submission state.
-- Migration decision: none.
-
-## Ownership boundary
-
-**Owns**
-
-- Outer field arrangement, spacing, direction, and the viewport collapse for horizontal labels.
-- Form-level optionality context and nested-layout shadowing.
-- The root DOM element, root prop composition, and the `form-layout` theme target.
-
-**Does not own / non-goals**
-
-- Form semantics, submission, validation, or action placement — owned by the product callsite and native `<form>`.
-- Field labels, controls, status, and internal geometry — owned by `component:Field`, each input, and `family:input-fields`.
-- The content or visual contract of caller-supplied titles and footers — owned by their rendered components or the callsite.
-
-## Public concepts
-
-| Concept             | Closed values or states                         | Meaning                                                                 | Availability by variant/orientation/state                    | Default              | Owner                  | Stability | Invalid-value behavior |
-| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------- | ---------------------- | --------- | ---------------------- |
-| direction           | `vertical`; `horizontal`; `horizontal-labels`   | Selects the outer arrangement and provides that value to descendants.   | All layouts.                                                 | `vertical`           | `component:FormLayout` | Stable    | Type-constrained       |
-| default optionality | unset; `optional`; `required`                   | Marks only exceptions while controls preserve resolved required state.  | All directions; the nearest nested layout shadows the outer. | unset / per-field    | `component:FormLayout` | Stable    | Type-constrained       |
-| root composition    | DOM/data/ARIA/events; ref; class/style/`xstyle` | Extends the root layout container without replacing owned reflection.   | All directions.                                              | no caller decoration | `component:FormLayout` | Stable    | Shared merge contract  |
-| layout context      | direction plus optionality                      | Lets Field and inputs adapt their layout and required-state projection. | Descendants in the same layer scope.                         | vertical / unset     | `component:FormLayout` | Stable    | Nearest provider wins  |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                           |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| FR1 | `vertical` (the default) stacks children in a flex column with a `--spacing-4` gap.                                                                                                                                                                                                                                                                                                | Released source, tests, and stories                             |
-| FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule.                                                                                                                                                                                                                 | Released source, tests, and stories                             |
-| FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap. | Released source, Field composition, and tests                   |
-| FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8).                                                                                                                           | Context source and tests                                        |
-| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators.                                                                                                              | Tests; `family:input-fields` ownership                          |
-| FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target.                                                                                                                                                                                  | `architecture:public-component-api/INV5–INV8`; source and tests |
-
-### Allowed variation
-
-- **AV1 — Caller content.** Any caller-owned field, heading, explanatory content, or action region may be a child; FormLayout does not inspect or rewrite it.
-- **AV2 — Nested arrangement.** Builders may nest vertical and horizontal layouts; each provider owns only its descendant scope.
-- **AV3 — Root styling.** Caller styling may change the container's presentation while preserving the public direction and child contracts.
-
-### Representative states
-
-| State                      | Required invariant                                                                              | Allowed variation                                                                                      |
-| -------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| vertical                   | One block-axis stack with tokenized gaps.                                                       | Any caller-owned children.                                                                             |
-| horizontal                 | One `1fr` grid track per child in logical inline order.                                         | Child count and content.                                                                               |
-| horizontal labels / wide   | Label/control pairs share consistent two-column tracks.                                         | Label and control content.                                                                             |
-| horizontal labels / narrow | One vertical column at 480px or below with a `--spacing-4` gap and no component-owned overflow. | Caller-owned content may wrap; OQ1 asks whether each label and control pair should keep a tighter gap. |
-| optional by default        | Only explicitly required fields show the exception marker.                                      | Field and input type.                                                                                  |
-| required by default        | Only explicitly optional fields show the exception marker.                                      | Field and input type.                                                                                  |
-| nested                     | Inner direction and optionality replace outer values.                                           | Any supported inner direction/default combination.                                                     |
-
-### Transformation and precedence order
-
-- **ORD1 — Context.** Explicit props resolve against `vertical` and unset defaults, then the nearest provider exposes the resolved values to descendants.
-- **ORD2 — Root props.** FormLayout-owned target and direction reflection compose with StyleX and caller styling; caller DOM props reach the same root without replacing owned reflection.
-- **ORD3 — Optionality.** The layout default establishes the unmarked majority; a field-level `isRequired` or `isOptional` marks the exception and controls native validation only when explicitly requested.
-
-### Performance and resources
-
-- **PR1 — Stable context identity.** Descendants receive one memoized context value per direction/optionality pair; FormLayout owns no listener, observer, timer, or external resource.
-
-## Accessibility contract
-
-- **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
-- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology.
-- **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                          | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Layout container | Outer arrangement and spacing of caller fields.             | Current source and docs  | Supporting     | FR1–FR3, FR6       |
-| Form title       | Caller content; not rendered or styled by FormLayout.       | Caller-owned             | Prominent      | —                  |
-| Fields           | Caller Field and input components.                          | Their own components     | Prominent      | FR4, FR5           |
-| Footer           | Caller action region; not rendered or styled by FormLayout. | Caller-owned             | Supporting     | —                  |
-
-No shared design record prescribes a FormLayout-specific representation;
-spacing uses the token scale.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Layout container": {"target": "form-layout"},
-  "Form title": {
-    "none": {
-      "reason": "intentional: A title is caller-owned content; FormLayout neither renders nor styles a title part."
-    }
-  },
-  "Fields": {
-    "none": {
-      "reason": "intentional: Caller-owned Field and input components retain their own theming targets."
-    }
-  },
-  "Footer": {
-    "none": {
-      "reason": "intentional: A footer is caller-owned content; FormLayout neither renders nor styles an action region."
-    }
-  }
-}
-```
-
-The root target reflects the closed `direction` axis. It owns the outer arrangement container and does not claim the visual parts rendered by child components.
-
-## Family and system relationships
-
-- `family:input-fields` identifies FormLayout as the owner of outer arrangement, spacing, direction, and form-level optionality.
-- `component:Field` consumes horizontal-label direction and optionality while retaining label, control, description, and status ownership.
-- `architecture:public-component-api` owns root prop, styling, event, ref, and released-type composition.
-- `architecture:component-theming-surface` sets the rules the `form-layout` target and its reflected direction follow.
-- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence selection.
-
-## Verification map
-
-| Contract       | Verification                                                                                                                        | Representative states                                                    | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Audit section                    |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
-| FR1–FR3        | `FormLayout.test.tsx` direction snapshots; `FormLayout.stories.tsx` play checks; stable visual baseline `core-formlayout--vertical` | Vertical, horizontal, horizontal-labels wide and narrow                  | A changed style class set fails the snapshots; a narrow horizontal-labels control narrower than the layout, or a wide label not before its control, fails the play checks; a changed vertical layout comes back changed for review. The story play guard also runs the AuditMatrix play right-to-left at 320px and the default width, where mirrored horizontal columns are asserted. Gap: no right-to-left check asserts that a horizontal-labels label sits on the inline-start side of its control. | `audit:FormLayout/behavior`      |
-| FR4, ORD1      | `FormLayout.test.tsx` context and nesting tests; `Layer/layerScopedContext.test.tsx`                                                | Default, explicit, nested; content in a fixed Layer and an inline Dialog | A lost default or value, lost shadowing by an inner layout's explicit values, or content inside a layer that still reads the outer `defaultOptionality` fails. Gap: no test covers an inner layout with unset props (which supplies its own defaults) or `direction` across a layer boundary.                                                                                                                                                                                                          | `audit:FormLayout/behavior`      |
-| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. FileInput, Slider, Typeahead, and Tokenizer tests cover a `required` default.                                                                                                                                                                                                                                                                                                                            | `audit:FormLayout/accessibility` |
-| FR6, ORD2      | `FormLayout.test.tsx` ref, passthrough, and owned-metadata tests; `themingTargets.test.ts`                                          | Ref, attributes, colliding `data-direction`                              | A ref on a non-`div`, a dropped `id` or `role`, or a replaced `data-direction` fails. Gap: no test covers event props or the styling-input merge order.                                                                                                                                                                                                                                                                                                                                                | `audit:FormLayout/api`           |
-| AR1, AR3       | `FormLayout.test.tsx` div and passthrough tests; `FormLayout.stories.tsx` play checks                                               | Plain root; caller `role`                                                | A non-`div` root or a dropped caller `role` fails. Horizontal columns that do not mirror right-to-left fail the AuditMatrix play under the story play guard. Gap: no check fails if FormLayout adds a role of its own.                                                                                                                                                                                                                                                                                 | `audit:FormLayout/accessibility` |
-| PR1            | Source review                                                                                                                       | Every direction                                                          | Gap: no automated check covers context identity or added resources.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `audit:FormLayout/behavior`      |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-- **OQ1 — At 480px and below, should each horizontal-label pair preserve a smaller intra-field label/control gap than the gap between adjacent fields?** (`human-design`)
-
-## 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.