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.mjsindex 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.tsxindex 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.mjsindex 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.tsxindex 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.mjsindex 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.tsxindex 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.mjsindex 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: [