Skip to content

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

TypeScript

Improve Field docs page and block examples (#1580)

rubyycheung7c3ec32050b8
diff --git a/packages/cli/templates/blocks/components/Field/FieldRequired.doc.mjs b/packages/cli/templates/blocks/components/Field/FieldRequired.doc.mjs
index d1d005a000..c53672b466 100644
--- a/packages/cli/templates/blocks/components/Field/FieldRequired.doc.mjs
+++ b/packages/cli/templates/blocks/components/Field/FieldRequired.doc.mjs
@@ -1,9 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Field — Required',
- description: 'Text input marked as required with a visual indicator',
+ name: 'Field — Required & Optional',
+ description:
+ 'Required and optional field indicators side by side. Use isRequired on fields the user must fill in, and isOptional to clarify which fields can be skipped.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TextInput'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TextInput', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Field/FieldRequired.tsx b/packages/cli/templates/blocks/components/Field/FieldRequired.tsx
index 00a1f96076..8397a683eb 100644
--- a/packages/cli/templates/blocks/components/Field/FieldRequired.tsx
+++ b/packages/cli/templates/blocks/components/Field/FieldRequired.tsx
@@ -2,18 +2,31 @@
import {useState} from 'react';
import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSCenter} from '@xds/core/Center';
export default function FieldRequired() {
- const [value, setValue] = useState('');
+ const [username, setUsername] = useState('');
+ const [email, setEmail] = useState('');
+
return (
- <div style={{maxWidth: 320}}>
- <XDSTextInput
- label="Username"
- isRequired
- value={value}
- onChange={setValue}
- placeholder="Enter your username"
- />
- </div>
+ <XDSCenter>
+ <XDSVStack gap={4}>
+ <XDSTextInput
+ label="Username"
+ isRequired
+ value={username}
+ onChange={setUsername}
+ placeholder="Enter your username"
+ />
+ <XDSTextInput
+ label="Backup email"
+ isOptional
+ value={email}
+ onChange={setEmail}
+ placeholder="[email protected]"
+ />
+ </XDSVStack>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Field/FieldStatusVariants.doc.mjs b/packages/cli/templates/blocks/components/Field/FieldStatusVariants.doc.mjs
index e8769deab6..1ec99b3a93 100644
--- a/packages/cli/templates/blocks/components/Field/FieldStatusVariants.doc.mjs
+++ b/packages/cli/templates/blocks/components/Field/FieldStatusVariants.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Field — Validation States',
description:
- 'Text inputs showing error, warning, and success validation states',
+ 'All three validation states: error, warning, and success. Use error for invalid input, warning for potential issues like reserved names, and success to confirm valid entries like API keys.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['TextInput'],
+ componentsUsed: ['TextInput', 'Layout'],
};
diff --git a/packages/cli/templates/blocks/components/Field/FieldStatusVariants.tsx b/packages/cli/templates/blocks/components/Field/FieldStatusVariants.tsx
index f68171ea8d..ac6d618f19 100644
--- a/packages/cli/templates/blocks/components/Field/FieldStatusVariants.tsx
+++ b/packages/cli/templates/blocks/components/Field/FieldStatusVariants.tsx
@@ -2,44 +2,45 @@
import {useState} from 'react';
import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSCenter} from '@xds/core/Center';
export default function FieldStatusVariants() {
const [email, setEmail] = useState('bad-email');
const [username, setUsername] = useState('admin');
- const [apiKey, setApiKey] = useState('valid-user');
+ const [apiKey, setApiKey] = useState('sk-live-abc123');
return (
- <div
- style={{
- display: 'flex',
- flexDirection: 'column',
- gap: 24,
- maxWidth: 400,
- }}>
- <XDSTextInput
- label="Email"
- description="Enter your work email"
- value={email}
- onChange={setEmail}
- status={{type: 'error', message: 'Please enter a valid email address'}}
- />
- <XDSTextInput
- label="Username"
- description="Choose a unique username"
- value={username}
- onChange={setUsername}
- status={{
- type: 'warning',
- message: 'This username is reserved for administrators',
- }}
- />
- <XDSTextInput
- label="API Key"
- description="Paste your API key"
- value={apiKey}
- onChange={setApiKey}
- status={{type: 'success', message: 'API key is valid and active'}}
- />
- </div>
+ <XDSCenter>
+ <XDSVStack gap={4}>
+ <XDSTextInput
+ label="Email"
+ description="Enter your work email"
+ value={email}
+ onChange={setEmail}
+ status={{
+ type: 'error',
+ message: 'Please enter a valid email address',
+ }}
+ />
+ <XDSTextInput
+ label="Username"
+ description="Choose a unique username"
+ value={username}
+ onChange={setUsername}
+ status={{
+ type: 'warning',
+ message: 'This username is reserved for administrators',
+ }}
+ />
+ <XDSTextInput
+ label="API Key"
+ description="Paste your API key"
+ value={apiKey}
+ onChange={setApiKey}
+ status={{type: 'success', message: 'API key is valid and active'}}
+ />
+ </XDSVStack>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Field/FieldWithDescription.doc.mjs b/packages/cli/templates/blocks/components/Field/FieldWithDescription.doc.mjs
index 337380c061..593a3be464 100644
--- a/packages/cli/templates/blocks/components/Field/FieldWithDescription.doc.mjs
+++ b/packages/cli/templates/blocks/components/Field/FieldWithDescription.doc.mjs
@@ -1,9 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Field — With Description',
- description: 'Text input field with a helper description below the label',
+ name: 'Field — Description',
+ description:
+ 'Fields with helper text below the label. Use descriptions to explain format requirements, constraints, or what happens with the data — like "At least 8 characters" or "We will send a confirmation link".',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TextInput'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TextInput', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Field/FieldWithDescription.tsx b/packages/cli/templates/blocks/components/Field/FieldWithDescription.tsx
index ac4b5860d7..88f149028f 100644
--- a/packages/cli/templates/blocks/components/Field/FieldWithDescription.tsx
+++ b/packages/cli/templates/blocks/components/Field/FieldWithDescription.tsx
@@ -2,18 +2,31 @@
import {useState} from 'react';
import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSCenter} from '@xds/core/Center';
export default function FieldWithDescription() {
- const [value, setValue] = useState('');
+ const [email, setEmail] = useState('');
+ const [password, setPassword] = useState('');
+
return (
- <div style={{maxWidth: 320}}>
- <XDSTextInput
- label="Email"
- description="We'll never share your email."
- value={value}
- onChange={setValue}
- placeholder="[email protected]"
- />
- </div>
+ <XDSCenter>
+ <XDSVStack gap={4}>
+ <XDSTextInput
+ label="Email"
+ description="We'll send a confirmation link to this address"
+ value={email}
+ onChange={setEmail}
+ placeholder="[email protected]"
+ />
+ <XDSTextInput
+ label="Password"
+ description="At least 8 characters with one uppercase letter"
+ value={password}
+ onChange={setPassword}
+ placeholder="Create a password"
+ />
+ </XDSVStack>
+ </XDSCenter>
);
}
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index e9088cef04..1c60d79133 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -216,12 +216,22 @@ export const docs = {
},
],
usage: {
- description: 'A form field wrapper that provides consistent labels, descriptions, and validation states around input controls. Use to wrap any input component in a form to ensure accessible labeling, optional/required indicators, and inline status feedback.',
+ description: 'Field wraps any input control with a label, description, and validation status. Use it to build accessible forms with consistent labeling, optional/required indicators, and inline error, warning, or success feedback.',
bestPractices: [
{ guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
{ guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
+ { guidance: true, description: 'Add a description when the label alone does not explain what the field expects, like format hints or constraints.' },
{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
{ guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },
+ { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'Text identifying the field. Always rendered for accessibility, optionally hidden visually.'},
+ {name: 'Description', required: false, description: 'Helper text between the label and input explaining what to enter.'},
+ {name: 'Input slot', required: true, description: 'The input control wrapped by the field — TextInput, Select, DateInput, etc.'},
+ {name: 'Status message', required: false, description: 'Inline validation feedback showing error, warning, or success with a message.'},
+ {name: 'Optional/Required indicator', required: false, description: 'Badge next to the label showing whether the field is optional or required.'},
+ {name: 'Label tooltip', required: false, description: 'Info icon at the end of the label with a tooltip explaining the field.'},
],
},
};
@@ -443,12 +453,14 @@ export const docsZh = {
},
],
usage: {
- description: 'A form field wrapper that provides consistent labels, descriptions, and validation states around input controls. Use to wrap any input component in a form to ensure accessible labeling, optional/required indicators, and inline status feedback.',
+ description: 'Field wraps any input control with a label, description, and validation status. Use it to build accessible forms with consistent labeling, optional/required indicators, and inline error, warning, or success feedback.',
bestPractices: [
{ guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
{ guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
+ { guidance: true, description: 'Add a description when the label alone does not explain what the field expects, like format hints or constraints.' },
{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
{ guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },
+ { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
],
},
};
@@ -458,12 +470,10 @@ export const docsDense = {
description:
'Form field wrapper providing label, description + optional/required indicators.',
usage: {
- description: 'A form field wrapper that provides consistent labels, descriptions, and validation states around input controls. Use to wrap any input component in a form to ensure accessible labeling, optional/required indicators, and inline status feedback.',
+ description: 'Field wraps input controls with label, description, and validation. Use for accessible forms with consistent labeling and inline feedback.',
bestPractices: [
- { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
- { guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
- { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
- { guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },
+ { guidance: true, description: 'Always provide a label. Use status with clear messages. Add description for format hints.' },
+ { guidance: false, description: 'Don\'t set both isOptional and isRequired. Don\'t use detached status on bordered inputs.' },
],
},
components: [