An open source design system that's fully customizable and agent ready
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 whendefaultOptionalityis 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-layouttheme 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, andfamily: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. Exception: CheckboxList, CheckboxInput, and Switch treat an empty selection, an unchecked box, or an off switch as an answer, so defaultOptionality gives them no required state: they take neither aria-required nor native required from it. CheckboxInput and Switch are required only through their own isRequired, and a CheckboxList and its rows take no required state from the form default; the marker rule above applies to them unchanged. |
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
verticaland 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
isRequiredorisOptionalmarks the exception and controls native validation only when explicitly requested. CheckboxList, CheckboxInput, and Switch are the FR5 exception: the default sets no required state for them, so only their ownisRequiredmakes them required.
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. This does not apply to the FR5 exception (CheckboxList, CheckboxInput, Switch), whose unmarked state is an answer, not a missing required value; a control marked
isRequiredstill exposes its required state. - 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
{
"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-fieldsidentifies FormLayout as the owner of outer arrangement, spacing, direction, and form-level optionality.component:Fieldconsumes horizontal-label direction and optionality while retaining label, control, description, and status ownership.architecture:public-component-apiowns root prop, styling, event, ref, and released-type composition.architecture:component-theming-surfacesets the rules theform-layouttarget and its reflected direction follow.architecture:component-test-sufficiencyowns 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 |
| FR5 | FormLayout.test.tsx "required default gives an unmarked checkbox, switch and checkbox group no required state" |
Under defaultOptionality="required", an unmarked CheckboxInput, Switch and CheckboxList (each box) carry no aria-required and no required, while a TextInput beside them still carries aria-required; the markers follow FieldLabel FR4 |
An unmarked checkbox, switch or checkbox group carrying aria-required fails. |
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.