Skip to content

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

TypeScript

Improve TextArea docs page and block examples (#1573)

Kenton Quatmana943d20f29ce
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.doc.mjs
deleted file mode 100644
index 40656405fc..0000000000
--- a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TextArea — Basic',
- description:
- 'Simple textarea with label and description for multi-line text entry.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TextArea'],
-};
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.tsx
deleted file mode 100644
index f36a2b1602..0000000000
--- a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTextArea} from '@xds/core/TextArea';
-
-export default function TextAreaBasicTextArea() {
- const [value, setValue] = useState('');
- return (
- <XDSTextArea
- label="Bio"
- description="Tell us about yourself in a few sentences."
- value={value}
- onChange={setValue}
- placeholder="Write your bio here..."
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.doc.mjs
similarity index 58%
rename from packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.doc.mjs
rename to packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.doc.mjs
index 1914529d93..faa9d73ed3 100644
--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.doc.mjs
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'TextArea — Character Count',
- description:
- 'Textarea with a maximum character limit and live counter display.',
+ description: 'Textareas with maxLength and a live character counter. The counter turns red when the limit is exceeded.',
isReady: true,
- aspectRatio: 4 / 3,
+ aspectRatio: 16 / 9,
componentsUsed: ['TextArea'],
};
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.tsx
new file mode 100644
index 0000000000..a7b4d105d0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.tsx
@@ -0,0 +1,21 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTextArea} from '@xds/core/TextArea';
+
+export default function TextAreaCharacterCount() {
+ const [value, setValue] = useState(
+ 'Excited to announce that our team just shipped the new dashboard! Check it out and let us know what you think.',
+ );
+
+ return (
+ <XDSTextArea
+ label="Status update"
+ value={value}
+ onChange={setValue}
+ placeholder="What's on your mind?"
+ maxLength={280}
+ rows={3}
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaStates.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.doc.mjs
new file mode 100644
index 0000000000..d61a46ebb4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TextArea — States',
+ description: 'Required, disabled, and loading textareas side by side. Shows the interactive states the component supports.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['TextArea', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaStates.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.tsx
new file mode 100644
index 0000000000..cd1c756ce5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.tsx
@@ -0,0 +1,34 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTextArea} from '@xds/core/TextArea';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function TextAreaStates() {
+ const [requiredValue, setRequiredValue] = useState('');
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSTextArea
+ label="Required field"
+ value={requiredValue}
+ onChange={setRequiredValue}
+ placeholder="Describe the issue..."
+ isRequired
+ />
+ <XDSTextArea
+ label="Disabled field"
+ value="This field is read-only and cannot be edited."
+ onChange={() => {}}
+ isDisabled
+ />
+ <XDSTextArea
+ label="Loading field"
+ value=""
+ onChange={() => {}}
+ placeholder="Generating summary..."
+ isLoading
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs
new file mode 100644
index 0000000000..51752300ca
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TextArea — Validation',
+ description: 'All three status variants — error, warning, and success — with status messages. Use to show inline validation feedback as the user types.',
+ isReady: true,
+ aspectRatio: 1,
+ componentsUsed: ['TextArea', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.tsx
new file mode 100644
index 0000000000..3bc936cac3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.tsx
@@ -0,0 +1,45 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTextArea} from '@xds/core/TextArea';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function TextAreaValidation() {
+ const [errorValue, setErrorValue] = useState('Fix the');
+ const [warningValue, setWarningValue] = useState('Summarize the Q2 results');
+ const [successValue, setSuccessValue] = useState(
+ 'Redesign the onboarding flow to reduce drop-off by 15% in Q3. Focus on simplifying the account creation step and adding a progress indicator.',
+ );
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSTextArea
+ label="Error message"
+ value={errorValue}
+ onChange={setErrorValue}
+ status={{
+ type: 'error',
+ message: 'Description must be at least 20 characters.',
+ }}
+ />
+ <XDSTextArea
+ label="Warning message"
+ value={warningValue}
+ onChange={setWarningValue}
+ status={{
+ type: 'warning',
+ message: 'Consider adding more detail for clarity.',
+ }}
+ />
+ <XDSTextArea
+ label="Success message"
+ value={successValue}
+ onChange={setSuccessValue}
+ status={{
+ type: 'success',
+ message: 'Looks good — clear and actionable.',
+ }}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.tsx
deleted file mode 100644
index 5eb1f2ceaf..0000000000
--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTextArea} from '@xds/core/TextArea';
-
-export default function TextAreaWithCharacterCount() {
- const [value, setValue] = useState('');
- return (
- <XDSTextArea
- label="Bio"
- value={value}
- onChange={setValue}
- placeholder="Tell us about yourself..."
- maxLength={150}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.doc.mjs
new file mode 100644
index 0000000000..d9ed36bb0e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TextArea — Icon',
+ description: 'Textareas with a leading icon that hints at the expected content, like a chat bubble for messages or a pencil for notes.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TextArea'],
+};
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.tsx
new file mode 100644
index 0000000000..7eb1c6fab1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.tsx
@@ -0,0 +1,20 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTextArea} from '@xds/core/TextArea';
+import {PencilSquareIcon} from '@heroicons/react/24/outline';
+
+export default function TextAreaWithIcon() {
+ const [value, setValue] = useState('');
+
+ return (
+ <XDSTextArea
+ label="Meeting notes"
+ description="Capture key decisions and action items."
+ value={value}
+ onChange={setValue}
+ placeholder="What was discussed?"
+ startIcon={PencilSquareIcon}
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.doc.mjs
deleted file mode 100644
index 610504e33f..0000000000
--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TextArea — Dynamic Validation',
- description:
- 'Textarea with dynamic validation feedback that changes status as the user types.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TextArea'],
-};
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.tsx
deleted file mode 100644
index 5bbf172808..0000000000
--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTextArea} from '@xds/core/TextArea';
-
-export default function TextAreaWithValidation() {
- const [value, setValue] = useState('');
- return (
- <div style={{maxWidth: 400}}>
- <XDSTextArea
- label="Description"
- description="Provide a comprehensive description of your project"
- value={value}
- onChange={setValue}
- placeholder="Enter description..."
- isRequired
- status={
- value.length > 0 && value.length < 20
- ? {type: 'warning', message: 'Consider adding more detail'}
- : value.length >= 20
- ? {type: 'success', message: 'Description looks good!'}
- : undefined
- }
- />
- </div>
- );
-}
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index bd28038ef1..f02a4f0c19 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -155,12 +155,15 @@ export const docs = {
},
usage: {
description:
- 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',
+ 'TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.',
bestPractices: [
- { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },
- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },
- { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },
- { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },
+ { guidance: true, description: 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.' },
+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit — it helps users stay within bounds before they submit.' },
+ { guidance: true, description: 'Use the status prop to surface validation feedback inline — show success when input is valid, warning for soft limits, and error for hard failures.' },
+ { guidance: true, description: 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail" — but never rely on placeholder alone as the only label.' },
+ { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails — use TextInput instead.' },
+ { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field — placeholders disappear on focus and are not accessible labels.' },
+ { guidance: false, description: 'Don\'t show a status message without also setting the status type — the colored border and icon are what draw the user\'s attention to the message.' },
],
},
};
@@ -177,8 +180,7 @@ export const docsZh = {
{
name: 'label',
type: 'string',
- description:
- '文本域的标签文本 — 始终渲染以确保无障碍性。',
+ description: '文本域的标签文本 — 始终渲染以确保无障碍性。',
required: true,
},
{
@@ -195,14 +197,12 @@ export const docsZh = {
{
name: 'onChangeAction',
type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',
- description:
- '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',
+ description: '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',
},
{
name: 'isLabelHidden',
type: 'boolean',
- description:
- '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。',
+ description: '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。',
default: 'false',
},
{
@@ -213,15 +213,13 @@ export const docsZh = {
{
name: 'isOptional',
type: 'boolean',
- description:
- '在标签旁显示"可选"指示器。与 isRequired 互斥。',
+ description: '在标签旁显示"可选"指示器。与 isRequired 互斥。',
default: 'false',
},
{
name: 'isRequired',
type: 'boolean',
- description:
- '在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。',
+ description: '在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。',
default: 'false',
},
{
@@ -233,8 +231,7 @@ export const docsZh = {
{
name: 'isLoading',
type: 'boolean',
- description:
- '使文本域进入加载状态,在输入框内显示旋转器。',
+ description: '使文本域进入加载状态,在输入框内显示旋转器。',
default: 'false',
},
{
@@ -251,26 +248,22 @@ export const docsZh = {
{
name: 'maxLength',
type: 'number',
- description:
- '允许的最大字符数。设置后,在文本域下方显示字符计数器(当前/最大)。不原生强制限制——超出时计数器显示错误样式。',
+ description: '允许的最大字符数。设置后,在文本域下方显示字符计数器(当前/最大)。不原生强制限制——超出时计数器显示错误样式。',
},
{
name: 'status',
type: "{ type: 'warning' | 'error' | 'success'; message?: string }",
- description:
- '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',
+ description: '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',
},
{
name: 'labelTooltip',
type: 'string',
- description:
- '在标签末尾的信息图标中显示的工具提示文本。',
+ description: '在标签末尾的信息图标中显示的工具提示文本。',
},
{
name: 'startIcon',
type: 'XDSIconType',
- description:
- '在文本域包装器前端内部渲染的图标组件。',
+ description: '在文本域包装器前端内部渲染的图标组件。',
},
{
name: 'hasSpellCheck',
@@ -292,8 +285,7 @@ export const docsZh = {
{
name: 'htmlName',
type: 'string',
- description:
- '文本域元素的 HTML name 属性,用于表单提交。',
+ description: '文本域元素的 HTML name 属性,用于表单提交。',
},
{
name: 'onFocus',
@@ -308,8 +300,7 @@ export const docsZh = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description:
- 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
+ description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象。',
},
],
theming: {
@@ -319,12 +310,15 @@ export const docsZh = {
},
usage: {
description:
- 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',
+ 'TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.',
bestPractices: [
- { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },
- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },
- { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },
- { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },
+ { guidance: true, description: 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.' },
+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit — it helps users stay within bounds before they submit.' },
+ { guidance: true, description: 'Use the status prop to surface validation feedback inline — show success when input is valid, warning for soft limits, and error for hard failures.' },
+ { guidance: true, description: 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail" — but never rely on placeholder alone as the only label.' },
+ { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails — use TextInput instead.' },
+ { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field — placeholders disappear on focus and are not accessible labels.' },
+ { guidance: false, description: 'Don\'t show a status message without also setting the status type — the colored border and icon are what draw the user\'s attention to the message.' },
],
},
};
@@ -334,12 +328,15 @@ export const docsDense = {
description: 'Multi-line text input for collecting longer user input.',
usage: {
description:
- 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',
+ 'Multi-line input for comments, descriptions, messages. Use when input spans multiple lines; use TextInput for single-line.',
bestPractices: [
- { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },
- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },
- { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },
- { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },
+ { guidance: true, description: 'Visible label or isLabelHidden with descriptive label for screen readers.' },
+ { guidance: true, description: 'Set maxLength for character counter when a limit exists.' },
+ { guidance: true, description: 'Use status prop for inline validation — success, warning, error.' },
+ { guidance: true, description: 'Add description or placeholder for context — never placeholder alone as label.' },
+ { guidance: false, description: 'Avoid TextArea for single-line values — use TextInput.' },
+ { guidance: false, description: 'Don\'t use placeholder as only label — disappears on focus, not accessible.' },
+ { guidance: false, description: 'Don\'t show status message without status type — border and icon draw attention.' },
],
},
propDescriptions: {