Skip to content

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

TypeScript

feat(core): add XDSFormLayout — spatial layout for form fields (#438)

Cindy Zhange79f0b401ee4
diff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsx
new file mode 100644
index 0000000000..582ca71751
--- /dev/null
+++ b/apps/storybook/stories/FormLayout.stories.tsx
@@ -0,0 +1,265 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSFormLayout} from '@xds/core/FormLayout';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSSelector} from '@xds/core/Selector';
+import {XDSField} from '@xds/core/Field';
+import {XDSText} from '@xds/core/Text';
+import * as stylex from '@stylexjs/stylex';
+
+const meta: Meta<typeof XDSFormLayout> = {
+ title: 'Form/XDSFormLayout',
+ component: XDSFormLayout,
+ tags: ['autodocs'],
+ args: {
+ direction: 'vertical',
+ },
+ argTypes: {
+ direction: {
+ control: 'select',
+ options: ['vertical', 'horizontal', 'horizontal-labels'],
+ description: 'Direction of field arrangement',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSFormLayout>;
+
+// Helper component that uses args so Storybook controls work
+function FormLayoutDemo({
+ direction,
+}: {
+ direction?: 'vertical' | 'horizontal' | 'horizontal-labels';
+}) {
+ const [name, setName] = useState('');
+ const [email, setEmail] = useState('');
+ const [bio, setBio] = useState('');
+ return (
+ <XDSFormLayout direction={direction}>
+ <XDSTextInput label="Name" value={name} onChange={setName} />
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+ <XDSTextInput label="Bio" value={bio} onChange={setBio} />
+ </XDSFormLayout>
+ );
+}
+
+// ─── Vertical (default) ───────────────────────────────────────────────────
+
+export const Vertical: Story = {
+ name: 'Vertical (Default)',
+ render: args => <FormLayoutDemo direction={args.direction} />,
+};
+
+// ─── Horizontal ───────────────────────────────────────────────────────────
+
+export const Horizontal: Story = {
+ name: 'Horizontal',
+ args: {
+ direction: 'horizontal',
+ },
+ render: args => {
+ const [first, setFirst] = useState('');
+ const [last, setLast] = useState('');
+ return (
+ <XDSFormLayout direction={args.direction}>
+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />
+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />
+ </XDSFormLayout>
+ );
+ },
+};
+
+// ─── Horizontal Labels ────────────────────────────────────────────────────
+
+export const HorizontalLabels: Story = {
+ name: 'Horizontal Labels (Settings)',
+ args: {
+ direction: 'horizontal-labels',
+ },
+ render: args => {
+ const [displayName, setDisplayName] = useState('Jane Doe');
+ const [email, setEmail] = useState('[email protected]');
+ const [timezone, setTimezone] = useState('America/Los_Angeles');
+ return (
+ <XDSFormLayout direction={args.direction}>
+ <XDSTextInput
+ label="Display Name"
+ value={displayName}
+ onChange={setDisplayName}
+ />
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+ <XDSSelector
+ label="Timezone"
+ value={timezone}
+ onChange={v => setTimezone(v as string)}
+ items={[
+ {label: 'Pacific Time', value: 'America/Los_Angeles'},
+ {label: 'Eastern Time', value: 'America/New_York'},
+ {label: 'UTC', value: 'UTC'},
+ ]}
+ />
+ </XDSFormLayout>
+ );
+ },
+};
+
+// ─── Mixed: XDS inputs + XDSField-wrapped custom controls ─────────────────
+
+const checkboxStyles = stylex.create({
+ group: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 4,
+ },
+ label: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: 8,
+ },
+});
+
+export const MixedControls: Story = {
+ name: 'Mixed Controls',
+ render: () => {
+ const [name, setName] = useState('');
+ const [role, setRole] = useState('viewer');
+ return (
+ <XDSFormLayout>
+ <XDSTextInput label="Name" value={name} onChange={setName} />
+ <XDSSelector
+ label="Role"
+ value={role}
+ onChange={v => setRole(v as string)}
+ items={[
+ {label: 'Viewer', value: 'viewer'},
+ {label: 'Editor', value: 'editor'},
+ {label: 'Admin', value: 'admin'},
+ ]}
+ />
+ <XDSField label="Notifications" inputID="notif-group">
+ <div {...stylex.props(checkboxStyles.group)} id="notif-group">
+ <label {...stylex.props(checkboxStyles.label)}>
+ <input type="checkbox" defaultChecked /> Email
+ </label>
+ <label {...stylex.props(checkboxStyles.label)}>
+ <input type="checkbox" /> SMS
+ </label>
+ <label {...stylex.props(checkboxStyles.label)}>
+ <input type="checkbox" defaultChecked /> Push
+ </label>
+ </div>
+ </XDSField>
+ </XDSFormLayout>
+ );
+ },
+};
+
+// ─── Nested Layouts ───────────────────────────────────────────────────────
+
+export const Nested: Story = {
+ name: 'Nested Layouts',
+ render: () => {
+ const [first, setFirst] = useState('');
+ const [last, setLast] = useState('');
+ const [email, setEmail] = useState('');
+ const [city, setCity] = useState('');
+ const [state, setState] = useState('');
+ const [zip, setZip] = useState('');
+ return (
+ <XDSFormLayout>
+ <XDSFormLayout direction="horizontal">
+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />
+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />
+ </XDSFormLayout>
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+ <XDSFormLayout direction="horizontal">
+ <XDSTextInput label="City" value={city} onChange={setCity} />
+ <XDSTextInput label="State" value={state} onChange={setState} />
+ <XDSTextInput label="ZIP" value={zip} onChange={setZip} />
+ </XDSFormLayout>
+ </XDSFormLayout>
+ );
+ },
+};
+
+// ─── In a Dialog (form attribute pattern) ─────────────────────────────────
+
+const dialogStyles = stylex.create({
+ container: {
+ border: '1px solid #ddd',
+ borderRadius: 8,
+ maxWidth: 480,
+ overflow: 'hidden',
+ },
+ header: {
+ padding: 16,
+ borderBottom: '1px solid #eee',
+ },
+ body: {
+ padding: 16,
+ },
+ footer: {
+ display: 'flex',
+ justifyContent: 'flex-end',
+ gap: 8,
+ padding: 16,
+ borderTop: '1px solid #eee',
+ },
+ button: {
+ padding: '8px 16px',
+ borderRadius: 6,
+ border: 'none',
+ cursor: 'pointer',
+ fontSize: 14,
+ },
+ primary: {
+ backgroundColor: '#0064E0',
+ color: '#fff',
+ },
+ secondary: {
+ backgroundColor: '#F1F4F7',
+ color: '#0A1317',
+ },
+});
+
+export const InDialog: Story = {
+ name: 'In a Dialog',
+ render: () => {
+ const [name, setName] = useState('Jane Doe');
+ const [email, setEmail] = useState('[email protected]');
+ return (
+ <div {...stylex.props(dialogStyles.container)}>
+ <div {...stylex.props(dialogStyles.header)}>
+ <XDSText variant="subtitle">Edit Profile</XDSText>
+ </div>
+ <div {...stylex.props(dialogStyles.body)}>
+ <form
+ id="edit-profile"
+ onSubmit={e => {
+ e.preventDefault();
+ alert(`Saved: ${name}, ${email}`);
+ }}>
+ <XDSFormLayout>
+ <XDSTextInput label="Name" value={name} onChange={setName} />
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+ </XDSFormLayout>
+ </form>
+ </div>
+ <div {...stylex.props(dialogStyles.footer)}>
+ <button
+ {...stylex.props(dialogStyles.button, dialogStyles.secondary)}
+ type="button">
+ Cancel
+ </button>
+ <button
+ {...stylex.props(dialogStyles.button, dialogStyles.primary)}
+ type="submit"
+ form="edit-profile">
+ Save
+ </button>
+ </div>
+ </div>
+ );
+ },
+};
diff --git a/packages/core/src/FormLayout/README.md b/packages/core/src/FormLayout/README.md
new file mode 100644
index 0000000000..a25fbc17c5
--- /dev/null
+++ b/packages/core/src/FormLayout/README.md
@@ -0,0 +1,129 @@
+# FormLayout
+
+A spatial layout container for arranging form fields with consistent spacing and direction.
+
+<!-- SYNC: When files in this directory change, update this document. -->
+
+## Features
+
+- **Three Layout Modes**: Vertical (default), horizontal, and horizontal-labels
+- **Direction Context**: Provides layout direction to children via React context
+- **Responsive**: Horizontal-labels collapses to vertical on narrow viewports (≤480px)
+- **Nestable**: FormLayout inside FormLayout works naturally — inner overrides context
+- **Purely Spatial**: Does not manage form state or render `<form>` — form submission is separate
+- **Styled with StyleX**: Uses XDS design tokens for consistent spacing
+
+## Components
+
+### XDSFormLayout
+
+Arranges form fields with consistent spacing and direction.
+
+```tsx
+<XDSFormLayout direction="vertical">
+ <XDSTextInput label="Name" value={name} onChange={setName} />
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+</XDSFormLayout>
+```
+
+| Prop | Type | Default | Description |
+| ------------- | --------------------------------------------------- | ------------ | -------------------------------------- |
+| `direction` | `'vertical' \| 'horizontal' \| 'horizontal-labels'` | `'vertical'` | Direction of field arrangement |
+| `children` | `ReactNode` | — | Form fields to arrange |
+| `xstyle` | `StyleXStyles` | — | StyleX styles for the layout container |
+| `data-testid` | `string` | — | Test ID for the root element |
+| `ref` | `Ref<HTMLDivElement>` | — | Ref to the root div element |
+
+Also accepts standard HTML `div` attributes (`id`, `role`, `aria-*`, etc.).
+
+## Layout Modes
+
+### Vertical (default)
+
+Fields stack top-to-bottom with consistent gap. Most common pattern for simple forms and dialogs.
+
+```tsx
+<XDSFormLayout>
+ <XDSTextInput label="Name" ... />
+ <XDSTextInput label="Email" ... />
+</XDSFormLayout>
+```
+
+### Horizontal
+
+Fields arrange left-to-right, each getting equal flex-grow. Wraps when the container is too narrow. Used for related fields (first/last name, city/state/zip).
+
+```tsx
+<XDSFormLayout direction="horizontal">
+ <XDSTextInput label="First Name" ... />
+ <XDSTextInput label="Last Name" ... />
+</XDSFormLayout>
+```
+
+### Horizontal Labels
+
+CSS Grid layout with labels to the left of inputs. Collapses to vertical on narrow viewports (≤480px). Used for settings panels and admin forms.
+
+```tsx
+<XDSFormLayout direction="horizontal-labels">
+ <XDSTextInput label="Display Name" ... />
+ <XDSSelector label="Timezone" ... />
+</XDSFormLayout>
+```
+
+## Composition Patterns
+
+### Nesting
+
+```tsx
+<XDSFormLayout direction="vertical">
+ <XDSFormLayout direction="horizontal">
+ <XDSTextInput label="First Name" ... />
+ <XDSTextInput label="Last Name" ... />
+ </XDSFormLayout>
+ <XDSTextInput label="Email" ... />
+</XDSFormLayout>
+```
+
+### With Custom Controls
+
+Use `XDSField` to wrap custom controls that need labels:
+
+```tsx
+<XDSFormLayout>
+ <XDSTextInput label="Name" ... />
+ <XDSField label="Permissions" inputID="perms">
+ <CheckboxGroup id="perms" ... />
+ </XDSField>
+</XDSFormLayout>
+```
+
+### Dialog Composition
+
+FormLayout does not include buttons. In dialogs, connect buttons via the HTML `form` attribute:
+
+```tsx
+<XDSDialog>
+ <form id="edit-form" onSubmit={handleSubmit}>
+ <XDSFormLayout>
+ <XDSTextInput label="Name" ... />
+ </XDSFormLayout>
+ </form>
+ <XDSDialogFooter>
+ <XDSButton label="Save" type="submit" form="edit-form" />
+ </XDSDialogFooter>
+</XDSDialog>
+```
+
+## Context
+
+`XDSFormLayoutContext` provides `{ direction: XDSFormLayoutDirection }` to children. Import from `@xds/core/FormLayout` to read the current layout direction in custom components.
+
+## Files
+
+| File | Role | Purpose |
+| ------------------------- | ------- | --------------------------- |
+| `index.ts` | Entry | Exports component and types |
+| `XDSFormLayout.tsx` | Core | Component implementation |
+| `XDSFormLayoutContext.ts` | Context | Direction context |
+| `XDSFormLayout.test.tsx` | Test | Unit tests |
diff --git a/packages/core/src/FormLayout/XDSFormLayout.test.tsx b/packages/core/src/FormLayout/XDSFormLayout.test.tsx
new file mode 100644
index 0000000000..39799da0f8
--- /dev/null
+++ b/packages/core/src/FormLayout/XDSFormLayout.test.tsx
@@ -0,0 +1,185 @@
+/**
+ * @file XDSFormLayout.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSFormLayout component
+ * @output Unit tests for XDSFormLayout component behavior
+ * @position Testing; validates XDSFormLayout.tsx implementation
+ *
+ * SYNC: When XDSFormLayout.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {useContext} from 'react';
+import {XDSFormLayout} from './XDSFormLayout';
+import {XDSFormLayoutContext} from './XDSFormLayoutContext';
+import type {XDSFormLayoutDirection} from './XDSFormLayoutContext';
+
+// Helper component to read context
+function DirectionReader() {
+ const {direction} = useContext(XDSFormLayoutContext);
+ return <span data-testid="direction">{direction}</span>;
+}
+
+describe('XDSFormLayout', () => {
+ // ─── Basic rendering ────────────────────────────────────────────────────
+
+ it('renders children', () => {
+ render(
+ <XDSFormLayout>
+ <input data-testid="child" />
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('child')).toBeInTheDocument();
+ });
+
+ it('renders a div element', () => {
+ render(<XDSFormLayout data-testid="layout">content</XDSFormLayout>);
+ const el = screen.getByTestId('layout');
+ expect(el.tagName).toBe('DIV');
+ });
+
+ it('forwards ref', () => {
+ const ref = {current: null as HTMLDivElement | null};
+ render(<XDSFormLayout ref={ref}>content</XDSFormLayout>);
+ expect(ref.current).toBeInstanceOf(HTMLDivElement);
+ });
+
+ it('passes data-testid', () => {
+ render(<XDSFormLayout data-testid="my-form">content</XDSFormLayout>);
+ expect(screen.getByTestId('my-form')).toBeInTheDocument();
+ });
+
+ it('passes through HTML attributes', () => {
+ render(
+ <XDSFormLayout data-testid="layout" id="form-1" role="group">
+ content
+ </XDSFormLayout>,
+ );
+ const el = screen.getByTestId('layout');
+ expect(el).toHaveAttribute('id', 'form-1');
+ expect(el).toHaveAttribute('role', 'group');
+ });
+
+ // ─── Direction modes ────────────────────────────────────────────────────
+
+ it('defaults to vertical direction', () => {
+ render(
+ <XDSFormLayout data-testid="layout">
+ <DirectionReader />
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('direction')).toHaveTextContent('vertical');
+ });
+
+ it('supports horizontal direction', () => {
+ render(
+ <XDSFormLayout direction="horizontal" data-testid="layout">
+ <DirectionReader />
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('direction')).toHaveTextContent('horizontal');
+ });
+
+ it('supports horizontal-labels direction', () => {
+ render(
+ <XDSFormLayout direction="horizontal-labels" data-testid="layout">
+ <DirectionReader />
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('direction')).toHaveTextContent(
+ 'horizontal-labels',
+ );
+ });
+
+ // ─── Context propagation ────────────────────────────────────────────────
+
+ it('provides direction context to children', () => {
+ const directions: XDSFormLayoutDirection[] = [
+ 'vertical',
+ 'horizontal',
+ 'horizontal-labels',
+ ];
+
+ for (const dir of directions) {
+ const {unmount} = render(
+ <XDSFormLayout direction={dir}>
+ <DirectionReader />
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('direction')).toHaveTextContent(dir);
+ unmount();
+ }
+ });
+
+ it('provides default context when no direction is specified', () => {
+ render(
+ <XDSFormLayout>
+ <DirectionReader />
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('direction')).toHaveTextContent('vertical');
+ });
+
+ // ─── Nesting ────────────────────────────────────────────────────────────
+
+ it('supports nesting — inner layout overrides context', () => {
+ render(
+ <XDSFormLayout direction="vertical" data-testid="outer">
+ <XDSFormLayout direction="horizontal" data-testid="inner">
+ <DirectionReader />
+ </XDSFormLayout>
+ </XDSFormLayout>,
+ );
+ // Inner context should be 'horizontal', not 'vertical'
+ expect(screen.getByTestId('direction')).toHaveTextContent('horizontal');
+ });
+
+ it('renders nested layouts with different elements', () => {
+ render(
+ <XDSFormLayout data-testid="outer">
+ <input data-testid="outer-child" />
+ <XDSFormLayout direction="horizontal" data-testid="inner">
+ <input data-testid="inner-child-1" />
+ <input data-testid="inner-child-2" />
+ </XDSFormLayout>
+ </XDSFormLayout>,
+ );
+ expect(screen.getByTestId('outer')).toBeInTheDocument();
+ expect(screen.getByTestId('inner')).toBeInTheDocument();
+ expect(screen.getByTestId('outer-child')).toBeInTheDocument();
+ expect(screen.getByTestId('inner-child-1')).toBeInTheDocument();
+ expect(screen.getByTestId('inner-child-2')).toBeInTheDocument();
+ });
+
+ // ─── Snapshot tests ─────────────────────────────────────────────────────
+
+ it('matches snapshot for vertical direction', () => {
+ const {container} = render(
+ <XDSFormLayout data-testid="layout">
+ <input placeholder="Name" />
+ <input placeholder="Email" />
+ </XDSFormLayout>,
+ );
+ expect(container.firstChild).toMatchSnapshot();
+ });
+
+ it('matches snapshot for horizontal direction', () => {
+ const {container} = render(
+ <XDSFormLayout direction="horizontal" data-testid="layout">
+ <input placeholder="First" />
+ <input placeholder="Last" />
+ </XDSFormLayout>,
+ );
+ expect(container.firstChild).toMatchSnapshot();
+ });
+
+ it('matches snapshot for horizontal-labels direction', () => {
+ const {container} = render(
+ <XDSFormLayout direction="horizontal-labels" data-testid="layout">
+ <label>Name</label>
+ <input placeholder="Name" />
+ </XDSFormLayout>,
+ );
+ expect(container.firstChild).toMatchSnapshot();
+ });
+});
diff --git a/packages/core/src/FormLayout/XDSFormLayout.tsx b/packages/core/src/FormLayout/XDSFormLayout.tsx
new file mode 100644
index 0000000000..95b7ac452e
--- /dev/null
+++ b/packages/core/src/FormLayout/XDSFormLayout.tsx
@@ -0,0 +1,162 @@
+/**
+ * @file XDSFormLayout.tsx
+ * @input Uses React forwardRef, XDSFormLayoutContext, StyleX
+ * @output Exports XDSFormLayout component and XDSFormLayoutProps
+ * @position Core implementation; consumed by index.ts, tested by XDSFormLayout.test.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/README.md (props table, features, implementation notes)
+ * - /packages/core/src/FormLayout/XDSFormLayout.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/FormLayout/index.ts (exports if types change)
+ * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
+ */
+
+import {forwardRef, useMemo, type HTMLAttributes, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
+import {
+ XDSFormLayoutContext,
+ type XDSFormLayoutDirection,
+} from './XDSFormLayoutContext';
+
+// =============================================================================
+// Responsive breakpoint for horizontal-labels collapse
+// =============================================================================
+
+const HORIZONTAL_LABELS_COLLAPSE = '@media (max-width: 480px)';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ base: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-4'],
+ },
+ horizontal: {
+ flexDirection: 'row',
+ flexWrap: 'wrap',
+ },
+ horizontalLabels: {
+ display: 'grid',
+ gridTemplateColumns: 'auto 1fr',
+ gap: `${spacingVars['--spacing-3']} ${spacingVars['--spacing-4']}`,
+ alignItems: 'start',
+ [HORIZONTAL_LABELS_COLLAPSE]: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-4'],
+ },
+ },
+});
+
+// =============================================================================
+// Props
+// =============================================================================
+
+export interface XDSFormLayoutProps extends Omit<
+ HTMLAttributes<HTMLDivElement>,
+ 'style' | 'className'
+> {
+ /**
+ * Form fields to arrange. Accepts XDS inputs (XDSTextInput, XDSSelector, etc.)
+ * and XDSField-wrapped custom controls.
+ */
+ children?: ReactNode;
+
+ /**
+ * Direction of field arrangement.
+ *
+ * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
+ * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.
+ * Each child gets equal flex-grow.
+ * - `'horizontal-labels'` — CSS Grid with labels to the left of inputs.
+ * Collapses to vertical on narrow viewports (≤480px).
+ *
+ * @default 'vertical'
+ */
+ direction?: XDSFormLayoutDirection;
+
+ /**
+ * StyleX styles to apply to the layout container.
+ */
+ xstyle?: StyleXStyles;
+
+ /**
+ * Test ID for the root element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Spatial layout container for form fields.
+ *
+ * Arranges form fields with consistent spacing and direction. Renders a `<div>`
+ * (not a `<form>` — form submission is a separate concern). For label wrapping
+ * of custom controls, use `XDSField` directly.
+ *
+ * Provides direction context to children via `XDSFormLayoutContext`.
+ * Supports nesting — a horizontal layout inside a vertical layout works naturally.
+ *
+ * @example
+ * ```tsx
+ * // Vertical (default) — simple form
+ * <XDSFormLayout>
+ * <XDSTextInput label="Name" value={name} onChange={setName} />
+ * <XDSTextInput label="Email" value={email} onChange={setEmail} />
+ * </XDSFormLayout>
+ *
+ * // Horizontal — related fields side by side
+ * <XDSFormLayout direction="horizontal">
+ * <XDSTextInput label="First Name" value={first} onChange={setFirst} />
+ * <XDSTextInput label="Last Name" value={last} onChange={setLast} />
+ * </XDSFormLayout>
+ *
+ * // Horizontal labels — settings panel pattern
+ * <XDSFormLayout direction="horizontal-labels">
+ * <XDSTextInput label="Display Name" value={name} onChange={setName} />
+ * <XDSSelector label="Timezone" value={tz} onChange={setTz} options={tzs} />
+ * </XDSFormLayout>
+ *
+ * // Dialog composition via HTML form attribute
+ * <form id="edit-form" onSubmit={handleSubmit}>
+ * <XDSFormLayout>
+ * <XDSTextInput label="Name" value={name} onChange={setName} />
+ * </XDSFormLayout>
+ * </form>
+ * <XDSButton label="Save" type="submit" form="edit-form" />
+ * ```
+ */
+export const XDSFormLayout = forwardRef<HTMLDivElement, XDSFormLayoutProps>(
+ function XDSFormLayout(
+ {children, direction = 'vertical', xstyle, ...props},
+ ref,
+ ) {
+ const contextValue = useMemo(() => ({direction}), [direction]);
+
+ return (
+ <XDSFormLayoutContext.Provider value={contextValue}>
+ <div
+ ref={ref}
+ {...stylex.props(
+ styles.base,
+ direction === 'horizontal' && styles.horizontal,
+ direction === 'horizontal-labels' && styles.horizontalLabels,
+ xstyle,
+ )}
+ {...props}>
+ {children}
+ </div>
+ </XDSFormLayoutContext.Provider>
+ );
+ },
+);
+
+XDSFormLayout.displayName = 'XDSFormLayout';
diff --git a/packages/core/src/FormLayout/XDSFormLayoutContext.ts b/packages/core/src/FormLayout/XDSFormLayoutContext.ts
new file mode 100644
index 0000000000..77f44c5d47
--- /dev/null
+++ b/packages/core/src/FormLayout/XDSFormLayoutContext.ts
@@ -0,0 +1,32 @@
+/**
+ * @file XDSFormLayoutContext.ts
+ * @input Uses React createContext
+ * @output Exports XDSFormLayoutContext and XDSFormLayoutDirection type
+ * @position Context for form layout direction detection
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/README.md
+ */
+
+import {createContext} from 'react';
+
+/**
+ * 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).
+ */
+export type XDSFormLayoutDirection =
+ | 'vertical'
+ | 'horizontal'
+ | 'horizontal-labels';
+
+/**
+ * Context for detecting which form layout direction a component is rendered in.
+ * Children can use this to adapt their rendering based on the parent layout.
+ */
+export const XDSFormLayoutContext = createContext<{
+ direction: XDSFormLayoutDirection;
+}>({direction: 'vertical'});
diff --git a/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap b/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap
new file mode 100644
index 0000000000..99f6e100bd
--- /dev/null
+++ b/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap
@@ -0,0 +1,46 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`XDSFormLayout > matches snapshot for horizontal direction 1`] = `
+<div
+ class="XDSFormLayout__styles.base x78zum5 x18g69wz XDSFormLayout__styles.horizontal x1q0g3np x1a02dak"
+ data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:34; @xds/core:src/FormLayout/XDSFormLayout.tsx:39"
+ data-testid="layout"
+>
+ <input
+ placeholder="First"
+ />
+ <input
+ placeholder="Last"
+ />
+</div>
+`;
+
+exports[`XDSFormLayout > matches snapshot for horizontal-labels direction 1`] = `
+<div
+ class="XDSFormLayout__styles.base xdt5ytf XDSFormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
+ data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:34; @xds/core:src/FormLayout/XDSFormLayout.tsx:43"
+ data-testid="layout"
+>
+ <label>
+ Name
+ </label>
+ <input
+ placeholder="Name"
+ />
+</div>
+`;
+
+exports[`XDSFormLayout > matches snapshot for vertical direction 1`] = `
+<div
+ class="XDSFormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
+ data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:34"
+ data-testid="layout"
+>
+ <input
+ placeholder="Name"
+ />
+ <input
+ placeholder="Email"
+ />
+</div>
+`;
diff --git a/packages/core/src/FormLayout/index.ts b/packages/core/src/FormLayout/index.ts
new file mode 100644
index 0000000000..a391796edb
--- /dev/null
+++ b/packages/core/src/FormLayout/index.ts
@@ -0,0 +1,14 @@
+/**
+ * @file index.ts
+ * @input Uses XDSFormLayout, XDSFormLayoutContext
+ * @output Re-exports public API for FormLayout
+ * @position Entry point for FormLayout module
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/README.md
+ */
+
+export {XDSFormLayout} from './XDSFormLayout';
+export type {XDSFormLayoutProps} from './XDSFormLayout';
+export type {XDSFormLayoutDirection} from './XDSFormLayoutContext';
+export {XDSFormLayoutContext} from './XDSFormLayoutContext';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index b171d9d86f..5512c98f83 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -30,6 +30,7 @@ export * from './Stack';
export * from './Switch';
export * from './DateInput';
export * from './Field';
+export * from './FormLayout';
export * from './Grid';
export * from './Section';
export * from './Selector';