Skip to content

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

TypeScript

Improve FormLayout docs and block examples (#1667)

Ted McDonald2f11edb92e80
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs
index 25e19e9cee..49fad1557f 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs
@@ -2,7 +2,7 @@
export const doc = {
type: 'block',
name: 'FormLayout — Horizontal',
- description: 'Side-by-side form fields for short related inputs like names',
+ description: 'Two fields side by side for naturally paired inputs like first and last name',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['FormLayout', 'TextInput'],
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx
index 78ecb9659c..be9b36d89f 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx
@@ -5,8 +5,8 @@ import {XDSFormLayout} from '@xds/core/FormLayout';
import {XDSTextInput} from '@xds/core/TextInput';
export default function FormLayoutHorizontal() {
- const [first, setFirst] = useState('');
- const [last, setLast] = useState('');
+ const [first, setFirst] = useState('Jordan');
+ const [last, setLast] = useState('Rivera');
return (
<XDSFormLayout direction="horizontal">
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs
index c20d5208b9..d000bc920e 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'FormLayout — Settings Form',
- description:
- 'Horizontal-labels layout for settings pages with labels beside inputs',
+ description: 'Settings form with labels placed beside their inputs',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['FormLayout', 'TextInput', 'Selector'],
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs
index 09185ea7c3..2ff1b6b075 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'FormLayout — Mixed Controls',
- description:
- 'Form combining text inputs, a selector, and a custom checkbox group via XDSField',
+ description: 'Form with different control types — text input, selector, and checkboxes',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['FormLayout', 'TextInput', 'Selector', 'Field'],
+ componentsUsed: ['FormLayout', 'TextInput', 'Selector', 'CheckboxList'],
};
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx
index 0cf2169740..01c1a4a044 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx
@@ -4,15 +4,16 @@ import {useState} from '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 {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';
export default function FormLayoutMixedControls() {
- const [name, setName] = useState('');
- const [role, setRole] = useState('viewer');
+ const [name, setName] = useState('Maya Torres');
+ const [role, setRole] = useState('editor');
+ const [notifications, setNotifications] = useState(['email', 'push']);
return (
<XDSFormLayout>
- <XDSTextInput label="Name" value={name} onChange={setName} />
+ <XDSTextInput label="Full Name" value={name} onChange={setName} />
<XDSSelector
label="Role"
value={role}
@@ -23,21 +24,14 @@ export default function FormLayoutMixedControls() {
{label: 'Admin', value: 'admin'},
]}
/>
- <XDSField label="Notifications" inputID="notif-group">
- <div
- id="notif-group"
- style={{display: 'flex', flexDirection: 'column', gap: 4}}>
- <label style={{display: 'flex', alignItems: 'center', gap: 8}}>
- <input type="checkbox" defaultChecked /> Email
- </label>
- <label style={{display: 'flex', alignItems: 'center', gap: 8}}>
- <input type="checkbox" /> SMS
- </label>
- <label style={{display: 'flex', alignItems: 'center', gap: 8}}>
- <input type="checkbox" defaultChecked /> Push
- </label>
- </div>
- </XDSField>
+ <XDSCheckboxList
+ label="Notifications"
+ value={notifications}
+ onChange={setNotifications}>
+ <XDSCheckboxListItem label="Email" value="email" />
+ <XDSCheckboxListItem label="SMS" value="sms" />
+ <XDSCheckboxListItem label="Push" value="push" />
+ </XDSCheckboxList>
</XDSFormLayout>
);
}
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs
index 2f12dc9a8e..e7a6a6436e 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'FormLayout — Nested Address Form',
- description:
- 'Nested vertical and horizontal layouts for a multi-section address form',
+ description: 'Address form mixing vertical and horizontal layouts for grouped fields',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['FormLayout', 'TextInput'],
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx
index 864b319f38..e46dc4bd7d 100644
--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx
+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx
@@ -5,12 +5,12 @@ import {XDSFormLayout} from '@xds/core/FormLayout';
import {XDSTextInput} from '@xds/core/TextInput';
export default function FormLayoutNested() {
- const [first, setFirst] = useState('');
- const [last, setLast] = useState('');
- const [email, setEmail] = useState('');
- const [city, setCity] = useState('');
- const [state, setState] = useState('');
- const [zip, setZip] = useState('');
+ const [first, setFirst] = useState('Priya');
+ const [last, setLast] = useState('Sharma');
+ const [email, setEmail] = useState('[email protected]');
+ const [city, setCity] = useState('San Francisco');
+ const [state, setState] = useState('CA');
+ const [zip, setZip] = useState('94105');
return (
<XDSFormLayout>
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index a5c9cb0d2e..b4de3846a0 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -30,11 +30,14 @@ export const docs = {
],
},
usage: {
- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',
+ description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go — not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
bestPractices: [
- { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },
- { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },
- { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },
+ { guidance: true, description: 'Stack fields vertically for most forms — it\'s the easiest to scan top to bottom.' },
+ { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
+ { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
+ { guidance: false, description: 'Use FormLayout for form state or submission — it\'s just layout. Wrap it in a <form> for that.' },
+ { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout — save it for fields that belong together.' },
+ { guidance: false, description: 'Nest horizontal-labels inside another FormLayout — it uses CSS Grid and needs to be the outermost container.' },
],
anatomy: [
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
@@ -74,11 +77,14 @@ export const docsZh = {
],
},
usage: {
- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',
+ description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go — not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
bestPractices: [
- { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },
- { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },
- { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },
+ { guidance: true, description: 'Stack fields vertically for most forms — it\'s the easiest to scan top to bottom.' },
+ { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
+ { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
+ { guidance: false, description: 'Use FormLayout for form state or submission — it\'s just layout. Wrap it in a <form> for that.' },
+ { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout — save it for fields that belong together.' },
+ { guidance: false, description: 'Nest horizontal-labels inside another FormLayout — it uses CSS Grid and needs to be the outermost container.' },
],
anatomy: [
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
@@ -91,13 +97,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description:
- 'Spatial layout container for arranging form fields w/ consistent spacing + direction.',
+ 'Layout container for form fields w/ consistent spacing + direction.',
usage: {
- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',
+ description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go — not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
bestPractices: [
- { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },
- { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },
- { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },
+ { guidance: true, description: 'Stack fields vertically for most forms — it\'s the easiest to scan top to bottom.' },
+ { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
+ { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
+ { guidance: false, description: 'Use FormLayout for form state or submission — it\'s just layout. Wrap it in a <form> for that.' },
+ { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout — save it for fields that belong together.' },
+ { guidance: false, description: 'Nest horizontal-labels inside another FormLayout — it uses CSS Grid and needs to be the outermost container.' },
],
anatomy: [
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},