Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Component Audit] FormLayout: make layout behavior and theming evidence trustworthy (#7784)

Cindy Zhang6c792d8f83eb
diff --git a/.changeset/form-layout-audit-docs.md b/.changeset/form-layout-audit-docs.md
new file mode 100644
index 0000000000..bc216aba7b
--- /dev/null
+++ b/.changeset/form-layout-audit-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Make `FormLayout` documentation match logical fractional grid tracks and viewport collapse, and make the public layout target discoverable from component anatomy.
+
+@cixzhang
diff --git a/.github/scripts/story-play-guard.js b/.github/scripts/story-play-guard.js
index dac31e195b..045657944d 100644
--- a/.github/scripts/story-play-guard.js
+++ b/.github/scripts/story-play-guard.js
@@ -260,6 +260,35 @@ const TARGETS = [
viewport: {width: 481, height: 844},
guards: 'just above the collapse, labels stay beside their controls',
},
+ {
+ component: 'FormLayout audit (phone)',
+ story: 'core-formlayout--audit-matrix',
+ viewport: {width: 320, height: 844},
+ guards:
+ 'all arrangements stay in the 320px viewport, horizontal columns retain order, horizontal-labels collapses, and required-default ARIA remains truthful',
+ },
+ {
+ component: 'FormLayout audit (boundary)',
+ story: 'core-formlayout--audit-matrix',
+ viewport: {width: 481, height: 844},
+ guards:
+ 'at 481px horizontal-labels remains a two-column grid while every arrangement stays in the viewport',
+ },
+ {
+ component: 'FormLayout audit (RTL phone)',
+ story: 'core-formlayout--audit-matrix',
+ direction: 'rtl',
+ viewport: {width: 320, height: 844},
+ guards:
+ 'logical horizontal order mirrors under RTL while the collapsed horizontal-label layout stays in the phone viewport',
+ },
+ {
+ component: 'FormLayout audit (RTL wide)',
+ story: 'core-formlayout--audit-matrix',
+ direction: 'rtl',
+ guards:
+ 'logical horizontal order mirrors under RTL and wide horizontal-label pairs retain inline-start placement',
+ },
{
component: 'Grid',
story: 'core-grid--grid-span-with-long-content',
@@ -358,8 +387,11 @@ function recordStoryOutcome() {
async function probe(page, target) {
await page.addInitScript(recordStoryOutcome);
const pointerQuery = target.hasTouch ? '&storyPlayPointer=coarse' : '';
+ const globalsQuery = target.direction
+ ? `&globals=direction:${target.direction}`
+ : '';
await page.goto(
- `http://localhost:${port}/iframe.html?id=${target.story}&viewMode=story${pointerQuery}`,
+ `http://localhost:${port}/iframe.html?id=${target.story}&viewMode=story${pointerQuery}${globalsQuery}`,
{waitUntil: 'domcontentloaded', timeout: 30000},
);
await page.waitForFunction(
@@ -367,7 +399,25 @@ async function probe(page, target) {
null,
{timeout: 30000},
);
- return page.evaluate(() => window.__storyOutcome);
+ return page.evaluate(expectedDirection => {
+ const outcome = window.__storyOutcome;
+ if (expectedDirection != null) {
+ const directionRoot = document.querySelector('#storybook-root [dir]');
+ if (directionRoot == null) {
+ outcome.errors.push(
+ `direction mismatch — expected ${expectedDirection}, but the story direction wrapper is missing`,
+ );
+ } else {
+ const actualDirection = getComputedStyle(directionRoot).direction;
+ if (actualDirection !== expectedDirection) {
+ outcome.errors.push(
+ `direction mismatch — expected ${expectedDirection}, received ${actualDirection}`,
+ );
+ }
+ }
+ }
+ return outcome;
+ }, target.direction ?? null);
}
async function run() {
diff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsx
index 4aa064832b..4253ef6de6 100644
--- a/apps/storybook/stories/FormLayout.stories.tsx
+++ b/apps/storybook/stories/FormLayout.stories.tsx
@@ -343,3 +343,119 @@ export const DefaultOptionalityRequired: Story = {
);
},
};
+
+// ─── Audit matrix ─────────────────────────────────────────────────────────────
+
+/**
+ * Stable, always-rendered FormLayout states for exact-head visual, accessibility,
+ * RTL, and responsive verification. One fixture keeps all three arrangements and
+ * both optionality exceptions observable without duplicating one story per prop.
+ */
+export const AuditMatrix: Story = {
+ parameters: {layout: 'padded'},
+ render: () => (
+ <div data-form-layout-audit="matrix">
+ <Text type="label">Vertical</Text>
+ <FormLayout data-audit-layout="vertical">
+ <TextInput label="Name" value="Ada Lovelace" onChange={() => {}} />
+ <TextInput
+ label="Email"
+ onChange={() => {}}
+ />
+ </FormLayout>
+
+ <Text type="label">Horizontal</Text>
+ <FormLayout direction="horizontal" data-audit-layout="horizontal">
+ <TextInput label="First name" value="Ada" onChange={() => {}} />
+ <TextInput label="Last name" value="Lovelace" onChange={() => {}} />
+ <TextInput label="Team" value="Analytical Engine" onChange={() => {}} />
+ </FormLayout>
+
+ <Text type="label">Horizontal labels</Text>
+ <FormLayout
+ direction="horizontal-labels"
+ data-audit-layout="horizontal-labels">
+ <TextInput
+ label="Display name"
+ value="Ada Lovelace"
+ onChange={() => {}}
+ />
+ <TextInput
+ label="Contact email"
+ onChange={() => {}}
+ />
+ </FormLayout>
+
+ <Text type="label">Required by default</Text>
+ <FormLayout
+ defaultOptionality="required"
+ data-audit-layout="required-default">
+ <TextInput label="Account name" value="Ada" onChange={() => {}} />
+ <TextInput
+ label="Nickname"
+ value="Enchantress of Numbers"
+ onChange={() => {}}
+ isOptional
+ />
+ </FormLayout>
+ </div>
+ ),
+ play: async ({canvasElement}) => {
+ const layouts = Array.from(
+ canvasElement.querySelectorAll<HTMLElement>('[data-audit-layout]'),
+ );
+ await expect(layouts).toHaveLength(4);
+ for (const layout of layouts) {
+ await expect(layout).toHaveAttribute('data-direction');
+ await expect(layout.className).toContain('astryx-form-layout');
+ const box = layout.getBoundingClientRect();
+ await expect(box.width).toBeGreaterThan(0);
+ await expect(box.left).toBeGreaterThanOrEqual(0);
+ await expect(box.right).toBeLessThanOrEqual(
+ document.documentElement.clientWidth + 1,
+ );
+ }
+
+ const horizontal = canvasElement.querySelector<HTMLElement>(
+ '[data-audit-layout="horizontal"]',
+ );
+ if (!horizontal) {
+ throw new Error('Expected the horizontal audit layout');
+ }
+ const [first, second] = Array.from(horizontal.children).map(child =>
+ child.getBoundingClientRect(),
+ );
+ const isRtl = getComputedStyle(horizontal).direction === 'rtl';
+ if (isRtl) {
+ await expect(first.left).toBeGreaterThan(second.left);
+ } else {
+ await expect(first.left).toBeLessThan(second.left);
+ }
+
+ const horizontalLabels = canvasElement.querySelector<HTMLElement>(
+ '[data-audit-layout="horizontal-labels"]',
+ );
+ if (!horizontalLabels) {
+ throw new Error('Expected the horizontal-labels audit layout');
+ }
+ const shouldCollapse = window.matchMedia('(max-width: 480px)').matches;
+ await expect(getComputedStyle(horizontalLabels).display).toBe(
+ shouldCollapse ? 'flex' : 'grid',
+ );
+
+ const requiredDefault = canvasElement.querySelector<HTMLElement>(
+ '[data-audit-layout="required-default"]',
+ );
+ if (!requiredDefault) {
+ throw new Error('Expected the required-default audit layout');
+ }
+ await expect(
+ requiredDefault.querySelectorAll('[aria-required="true"]'),
+ ).toHaveLength(1);
+ await expect(document.documentElement.scrollWidth).toBeLessThanOrEqual(
+ document.documentElement.clientWidth + 1,
+ );
+ },
+};
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index a969c59139..9b040193ef 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -13,7 +13,7 @@ export const docs = {
name: 'direction',
type: "'vertical' | 'horizontal' | 'horizontal-labels'",
description:
- 'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',
+ 'Controls field arrangement. Vertical stacks top-to-bottom, horizontal uses one fractional grid track per field in logical inline order, and horizontal-labels uses CSS Grid with labels beside inputs on the inline-start side (collapsing to vertical when the viewport is <=480px).',
default: "'vertical'",
},
{
@@ -51,6 +51,7 @@ export const docs = {
{ guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
],
anatomy: [
+ {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
{name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
{name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
@@ -67,7 +68,7 @@ export const docsZh = {
name: 'direction',
type: "'vertical' | 'horizontal' | 'horizontal-labels'",
description:
- '控制字段排列方式。vertical 从上到下堆叠,horizontal 从左到右排列且等比弹性增长,horizontal-labels 使用 CSS Grid 将标签放在输入框左侧(在窄视口 <=480px 时折叠为垂直布局)。',
+ '控制字段排列方式。vertical 从上到下堆叠;horizontal 为每个字段使用一个 1fr 网格轨道,并按逻辑行内方向排列;horizontal-labels 使用 CSS Grid,将标签放在输入框的行内起始侧(当视口宽度 <=480px 时折叠为垂直布局)。',
default: "'vertical'",
},
{
@@ -105,6 +106,7 @@ export const docsZh = {
{ guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
],
anatomy: [
+ {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
{name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
{name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
@@ -127,13 +129,14 @@ export const docsDense = {
{ guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
],
anatomy: [
+ {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
{name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
{name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
],
},
propDescriptions: {
- direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
+ direction: 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
defaultOptionality: 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required). Unset = per-field behavior.',
children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
diff --git a/packages/core/src/FormLayout/FormLayout.spec.md b/packages/core/src/FormLayout/FormLayout.spec.md
new file mode 100644
index 0000000000..bf27f53df8
--- /dev/null
+++ b/packages/core/src/FormLayout/FormLayout.spec.md
@@ -0,0 +1,192 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:FormLayout
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ 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: []
+---
+
+# 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`. |
+
+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: observational only; this draft changes no public prop, default, or behavior.
+- 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` | 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 |
+
+## 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 |
+
+### 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 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. |
+
+### 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
+
+No current component-local or shared design record prescribes a FormLayout-specific representation. Spacing uses the current token scale; exact tuning remains token-owned.
+
+### 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` owns the root target's anatomy mapping and reflected direction axis.
+- `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` |
+
+## Decision log
+
+No component-local decision is asserted. This draft records released behavior and its current shared owners.
+
+## 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 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.
diff --git a/packages/core/src/FormLayout/FormLayout.tsx b/packages/core/src/FormLayout/FormLayout.tsx
index 3c4d782054..f0bdbb991a 100644
--- a/packages/core/src/FormLayout/FormLayout.tsx
+++ b/packages/core/src/FormLayout/FormLayout.tsx
@@ -82,10 +82,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
* Direction of field arrangement.
*
* - `'vertical'` — Fields stack top-to-bottom (default). Most common.
- * - `'horizontal'` — Fields arrange left-to-right in equal-width columns
- * using CSS Grid. Each child occupies one equal column.
- * - `'horizontal-labels'` — CSS Grid with labels to the left of inputs.
- * Collapses to vertical when the container is narrow (≤480px).
+ * - `'horizontal'` — Fields occupy one `1fr` CSS Grid track per child in
+ * logical inline order.
+ * - `'horizontal-labels'` — CSS Grid with labels beside their inputs on the
+ * inline-start side. Collapses to vertical when the viewport is narrow
+ * (≤480px).
*
* @default 'vertical'
*/
diff --git a/packages/core/src/FormLayout/FormLayoutContext.ts b/packages/core/src/FormLayout/FormLayoutContext.ts
index b8151428c8..f72331ebec 100644
--- a/packages/core/src/FormLayout/FormLayoutContext.ts
+++ b/packages/core/src/FormLayout/FormLayoutContext.ts
@@ -20,9 +20,9 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
* Direction of form field arrangement.
*
* - `'vertical'` — Fields stack top-to-bottom (default). Most common.
- * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.
- * - `'horizontal-labels'` — Fields stack vertically but labels sit to the left
- * of their inputs (settings/admin panel pattern).
+ * - `'horizontal'` — Fields occupy one `1fr` grid track per child in logical inline order.
+ * - `'horizontal-labels'` — Fields stack vertically while labels sit beside
+ * their inputs on the inline-start side (settings/admin panel pattern).
*/
export type FormLayoutDirection =
'vertical' | 'horizontal' | 'horizontal-labels';