@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/FileInput/FileInput.test.tsx

@@ -511,6 +511,84 @@ describe('FileInput', () => {
   });
 
   describe('validation', () => {
+    it.each([
+      {maxSize: 0, expected: '0 B'},
+      {maxSize: 1023, expected: '1023 B'},
+      {maxSize: 1024, expected: '1.0 KB'},
+      {maxSize: 1048575, expected: '1024.0 KB'},
+      {maxSize: 1048576, expected: '1.0 MB'},
+      {maxSize: 1572864, expected: '1.5 MB'},
+    ])(
+      'preserves the English size boundary at $maxSize bytes',
+      ({maxSize, expected}) => {
+        render(
+          <FileInput
+            label="Upload"
+            value={null}
+            onChange={() => {}}
+            maxSize={maxSize}
+          />,
+        );
+        fireEvent.change(fileInputEl(), {
+          target: {files: [createFile('big.txt', maxSize + 1)]},
+        });
+        expect(
+          screen.getByText(`"big.txt" exceeds ${expected} limit`),
+        ).toBeInTheDocument();
+      },
+    );
+
+    it.each([
+      {
+        maxSize: 512,
+        sizeKey: 'bytes',
+        message: '{size, number} octets',
+        expected: '512 octets',
+      },
+      {
+        maxSize: 1536,
+        sizeKey: 'kilobytes',
+        message: '{size, number, ::.0} ko',
+        expected: '1,5 ko',
+      },
+      {
+        maxSize: 1572864,
+        sizeKey: 'megabytes',
+        message: '{size, number, ::.0} Mo',
+        expected: '1,5 Mo',
+      },
+    ])(
+      'localizes the $sizeKey size in validation feedback',
+      ({maxSize, sizeKey, message, expected}) => {
+        const handleChange = vi.fn();
+        render(
+          <InternationalizationProvider
+            locale="fr"
+            overrides={{
+              fr: {
+                '@astryx.fileInput.errorMaxSize':
+                  '{maxSize} maximum pour {fileName}',
+                [`@astryx.fileInput.fileSize.${sizeKey}`]: message,
+              },
+            }}>
+            <FileInput
+              label="Upload"
+              value={null}
+              onChange={handleChange}
+              maxSize={maxSize}
+            />
+          </InternationalizationProvider>,
+        );
+        fireEvent.change(fileInputEl(), {
+          target: {files: [createFile('big.txt', maxSize + 1)]},
+        });
+        expect(
+          screen.getByText(`${expected} maximum pour big.txt`),
+        ).toBeInTheDocument();
+        expect(handleChange).toHaveBeenCalledWith(null);
+      },
+    );
+
     it('rejects files exceeding maxSize', () => {
       const handleChange = vi.fn();
       render(
@@ -650,6 +728,30 @@ describe('FileInput', () => {
       expect(handleChange).toHaveBeenCalledWith(null);
     });
 
+    it('returns focus to the trigger, not the aria-hidden native input, after a keyboard clear', () => {
+      const file = createFile('test.txt', 100);
+      render(<FileInput label="Upload" value={file} onChange={() => {}} />);
+      fireEvent.click(screen.getByRole('button', {name: 'Clear Upload'}), {
+        detail: 0,
+      });
+      expect(screen.getByRole('button', {name: /^Upload/})).toHaveFocus();
+    });
+
+    it('returns focus to the trigger, not the aria-hidden native input, after a pointer clear', async () => {
+      const raf = vi
+        .spyOn(window, 'requestAnimationFrame')
+        .mockImplementation(cb => {
+          cb(0);
+          return 0;
+        });
+      const user = userEvent.setup();
+      const file = createFile('test.txt', 100);
+      render(<FileInput label="Upload" value={file} onChange={() => {}} />);
+      await user.click(screen.getByRole('button', {name: 'Clear Upload'}));
+      expect(screen.getByRole('button', {name: /^Upload/})).toHaveFocus();
+      raf.mockRestore();
+    });
+
     it('calls onChange and changeAction with null when clear is clicked', async () => {
       const user = userEvent.setup();
       const order: string[] = [];

package/src/FileInput/FileInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file FileInput.tsx
- * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
+ * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden, provider-bound translator
  * @output Exports FileInput component, public types, and its root/icon theme targets
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
@@ -68,14 +68,16 @@ import {useTranslator} from '../i18n';
 import type {TranslatorFn} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
-function formatFileSize(bytes: number): string {
+function formatFileSize(bytes: number, t: TranslatorFn): string {
   if (bytes < 1024) {
-    return `${bytes} B`;
+    return t('@astryx.fileInput.fileSize.bytes', {size: bytes});
   }
   if (bytes < 1024 * 1024) {
-    return `${(bytes / 1024).toFixed(1)} KB`;
+    return t('@astryx.fileInput.fileSize.kilobytes', {size: bytes / 1024});
   }
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return t('@astryx.fileInput.fileSize.megabytes', {
+    size: bytes / (1024 * 1024),
+  });
 }
 
 function validateFiles(
@@ -116,7 +118,7 @@ function validateFiles(
         errors.push(
           t('@astryx.fileInput.errorMaxSize', {
             fileName: file.name,
-            maxSize: formatFileSize(maxSize),
+            maxSize: formatFileSize(maxSize, t),
           }),
         );
         return false;
@@ -295,13 +297,13 @@ const styles = stylex.create({
 
 const statusBorderStyles = stylex.create({
   warning: {
-    borderColor: colorVars['--color-warning'],
+    borderColor: colorVars['--color-border-warning'],
   },
   error: {
-    borderColor: colorVars['--color-error'],
+    borderColor: colorVars['--color-border-error'],
   },
   success: {
-    borderColor: colorVars['--color-success'],
+    borderColor: colorVars['--color-border-success'],
   },
 });
 
@@ -485,6 +487,7 @@ export function FileInput({
   const statusMessageID = useId();
   const requiredID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState<string | null>(null);
@@ -649,14 +652,16 @@ export function FileInput({
       }
       if (inputRef.current) {
         inputRef.current.value = '';
-        const targetInput = inputRef.current;
+        // Focus returns to the trigger button, the control a person operates;
+        // the native input is aria-hidden and outside the tab order.
+        const trigger = triggerRef.current;
         if (e.detail === 0) {
-          targetInput.focus();
+          trigger?.focus();
         } else {
           // Defer focus restoration past the button's unmount task so iOS Safari
           // and touch browsers don't jump the page scroll to 0 on tap.
           requestAnimationFrame(() => {
-            targetInput.focus({preventScroll: true});
+            trigger?.focus({preventScroll: true});
           });
         }
       }
@@ -882,6 +887,7 @@ export function FileInput({
             keyboard activation still fires here. */}
         <VisuallyHidden>
           <button
+            ref={triggerRef}
             type="button"
             // A disabled trigger keeps its Tab stop (spec:AST-085 FR1).
             tabIndex={0}

package/src/FormLayout/FormLayout.spec.md

@@ -3,15 +3,18 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:FormLayout
-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: [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,
@@ -28,22 +31,22 @@ architecture:
     architecture:component-test-sufficiency,
   ]
 contributing: []
-system_specs: []
+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 | This draft records released behavior. It changes no public API, default, or runtime behavior.                                                                                                                                                                           |
-| 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. Narrow label/control grouping remains open in OQ1. |
-| Governing rules         | Established public FormLayout interface; `family:input-fields` outer-arrangement ownership; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                                                          |
+| 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. One implementation gap is listed under Current-state impact.                                                                                           |
+| 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.
 
@@ -54,10 +57,19 @@ This table is a review projection; the body below is authoritative.
 ## Compatibility and migration
 
 - Released default preserved: yes; direction defaults to `vertical`, and optionality remains field-owned when `defaultOptionality` is unset.
-- Compatibility class: observational only; this draft changes no public prop, default, or behavior.
+- 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.
 
+## Current-state impact
+
+- **Required state lost for four controls (FR5, AR2).** Under
+  `defaultOptionality="required"` the visible "Required" marker is hidden,
+  but Typeahead and Tokenizer set no `aria-required`, and FileInput and
+  Slider build their required description from `isRequired` alone. Screen
+  reader users hear those fields as not required, while sighted users see
+  the form-wide convention.
+
 ## Ownership boundary
 
 **Owns**
@@ -76,23 +88,21 @@ This table is a review projection; the body below is authoritative.
 
 | 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` | released  | 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` | released  | 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` | released  | 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` | released  | Nearest provider wins  |
+| 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
 
-Draft requirements identify their basis so observed code is not mistaken for an intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                         | Basis                                                               | Draft review state                                    |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
-| FR1 | Vertical direction stacks children with the shared spacing token.                                                                                                                                                                                                                                                           | Established public interface; current source and stories            | settled observation                                   |
-| FR2 | Horizontal direction places every direct child in one `1fr` grid track and follows the document's logical inline order without a component-owned wrap rule.                                                                                                                                                                 | Established public interface; current source and stories            | settled observation                                   |
-| FR3 | Horizontal-labels direction lets Field labels and control groups participate in a two-column grid, with the label on the inline-start side; at a viewport width of 480px or below it becomes one vertical flex column. Whether the collapsed label/control gap distinguishes each pair strongly enough remains open in OQ1. | Established public interface; Field composition and browser fixture | wide behavior settled; narrow grouping human decision |
-| FR4 | A nested FormLayout replaces the outer direction and optionality context for its descendants.                                                                                                                                                                                                                               | Existing context and unit tests                                     | settled observation                                   |
-| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose resolved `aria-required`, while native `required` remains tied to explicit field intent.                                                                                                           | Existing tests; `family:input-fields` ownership                     | settled observation                                   |
-| FR6 | Root ref, DOM/data/ARIA/event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the canonical target.                                                                                                                                                        | `architecture:public-component-api/INV5–INV8`                       | settled observation                                   |
+| 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. Implementation gap: under `defaultOptionality="required"`, Typeahead and Tokenizer set no `aria-required`, and FileInput and Slider describe required state from `isRequired` alone, so those fields are announced as not required while the marker is hidden (Current-state impact). | 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
 
@@ -102,15 +112,15 @@ Draft requirements identify their basis so observed code is not mistaken for an
 
 ### 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 no component-owned overflow. | Label/control grouping remains OQ1; caller-owned content may wrap. |
-| 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.                 |
+| 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
 
@@ -125,12 +135,20 @@ Draft requirements identify their basis so observed code is not mistaken for an
 ## 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.
+- **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. Implementation gap: Typeahead, Tokenizer, FileInput, and Slider do not (FR5).
 - **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
 
 ## Design relationships
 
-No current component-local or shared design record prescribes a FormLayout-specific representation. Spacing uses the current token scale; exact tuning remains token-owned.
+| 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
 
@@ -164,24 +182,23 @@ The root target reflects the closed `direction` axis. It owns the outer arrangem
 - `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` owns the root target's anatomy mapping and reflected direction axis.
+- `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–FR4, ORD1     | `FormLayout.test.tsx`, exact-head `AuditMatrix` story-play guards, and independent rendered inspection | vertical, horizontal, horizontal-label wide/narrow, nested       | Changed display, order, breakpoint, or provider shadowing fails; narrow grouping remains visible for OQ1.     | `audit:FormLayout/behavior`      |
-| FR5, ORD3, AR2    | `FormLayout.test.tsx`, Field tests, and scoped browser accessibility audit                             | required/optional/unset defaults; explicit exceptions            | A redundant marker returns, resolved `aria-required` disappears, or native validation changes.                | `audit:FormLayout/accessibility` |
-| FR6, ORD2         | root composition tests, BaseProps lint, theming-target tests, and exact-head AuditMatrix play          | ref, DOM/data/ARIA/events, class/style/`xstyle`, every direction | A caller input drops, direction reflection is replaced, or the public target disappears.                      | `audit:FormLayout/api`           |
-| AR1, AR3          | DOM tests and exact-head browser/a11y evidence                                                         | plain root, native form wrapper, LTR/RTL                         | Layout invents semantics, changes DOM/keyboard order, or uses physical inline placement.                      | `audit:FormLayout/accessibility` |
-| Theming anatomy   | knowledge validation, consumer-doc projection, and theming-target tests                                | root target; caller-owned title, fields, and footer              | The target loses its semantic owner or FormLayout claims a child component's painter.                         | `audit:FormLayout/theming`       |
-| Documentation     | docs typecheck and prop literal/reference tests                                                        | all directions, breakpoint, optionality, root anatomy            | Docs claim wrapping, physical order, flex growth, or another behavior the released code lacks.                | `audit:FormLayout/docs`          |
-| RTL applicability | verified-N/A registry plus exact-head AuditMatrix logical-order assertion                              | horizontal and horizontal-labels in LTR/RTL                      | A physical side, directional glyph, transform, scroll/drag, overlay, or directional key path makes N/A stale. | `audit:FormLayout/i18n-rtl`      |
+| 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. Gap: no test covers Typeahead, Tokenizer, FileInput, or Slider under a `required` default, which do not expose it.                                                                                                                                                                                                                                                                                       | `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
 
-No component-local decision is asserted. This draft records released behavior and its current shared owners.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
@@ -189,4 +206,5 @@ No component-local decision is asserted. This draft records released behavior an
 
 ## Content boundary
 
-This draft records verified shipped behavior and the unresolved narrow grouping relationship. It does not create form semantics, prescribe caller content, approve a new API or target, or duplicate consumer prop tables and audit-run scores.
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.