Skip to content

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

TypeScript

docs(deslop): batch 5 - remove AI-slop tells from doc files (30 files) (#2663)

Joeyb6790cc1deee
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 1add8afc9f..d44ca620c8 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -19,7 +19,7 @@ export const docs = {
name: 'label',
type: 'string',
description:
- 'Label text for the input — always rendered for accessibility.',
+ 'Label text for the input: always rendered for accessibility.',
required: true,
},
{
@@ -106,7 +106,7 @@ export const docs = {
name: 'status',
type: "{type: 'error' | 'warning' | 'success', message?: string}",
description:
- 'Validation status — applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
+ 'Validation status: applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
},
{
name: 'hasClear',
@@ -138,12 +138,12 @@ export const docs = {
'TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.',
bestPractices: [
{guidance: true, description: 'Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.'},
- {guidance: true, description: 'Use validation status with a message to explain what went wrong — "Email must include @" is better than just turning the border red.'},
- {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs.'},
+ {guidance: true, description: 'Use validation status with a message to explain what went wrong: "Email must include @" is better than just turning the border red.'},
+ {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type: small for zip codes, medium for names, large for URLs.'},
{guidance: true, description: 'Add a clear button for search and filter inputs so users can quickly reset without selecting all text.'},
- {guidance: false, description: "Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},
- {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},
- {guidance: false, description: "Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."},
+ {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
+ {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
+ {guidance: false, description: "Don't mark every field as required; only flag truly mandatory fields so users are not overwhelmed by validation errors."},
],
anatomy: [
{name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -172,7 +172,7 @@ export const docsZh = {
name: 'label',
type: 'string',
description:
- '输入框的标签文本 — 始终渲染以确保无障碍性。',
+ '输入框的标签文本:始终渲染以确保无障碍性。',
required: true,
},
{
@@ -259,7 +259,7 @@ export const docsZh = {
name: 'status',
type: "{type: 'error' | 'warning' | 'success', message?: string}",
description:
- '验证状态 — 应用彩色边框和状态图标。如果提供了 message,在输入框下方显示浮动消息。错误类型还会设置 aria-invalid。',
+ '验证状态:应用彩色边框和状态图标。如果提供了 message,在输入框下方显示浮动消息。错误类型还会设置 aria-invalid。',
},
{
name: 'hasClear',
@@ -290,12 +290,12 @@ export const docsZh = {
'TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.',
bestPractices: [
{guidance: true, description: 'Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.'},
- {guidance: true, description: 'Use validation status with a message to explain what went wrong — "Email must include @" is better than just turning the border red.'},
- {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs.'},
+ {guidance: true, description: 'Use validation status with a message to explain what went wrong: "Email must include @" is better than just turning the border red.'},
+ {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type: small for zip codes, medium for names, large for URLs.'},
{guidance: true, description: 'Add a clear button for search and filter inputs so users can quickly reset without selecting all text.'},
- {guidance: false, description: "Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},
- {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},
- {guidance: false, description: "Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."},
+ {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
+ {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
+ {guidance: false, description: "Don't mark every field as required; only flag truly mandatory fields so users are not overwhelmed by validation errors."},
],
anatomy: [
{name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -317,12 +317,12 @@ export const docsDense = {
'TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.',
bestPractices: [
{guidance: true, description: 'Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.'},
- {guidance: true, description: 'Use validation status with a message to explain what went wrong — "Email must include @" is better than just turning the border red.'},
- {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs.'},
+ {guidance: true, description: 'Use validation status with a message to explain what went wrong: "Email must include @" is better than just turning the border red.'},
+ {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type: small for zip codes, medium for names, large for URLs.'},
{guidance: true, description: 'Add a clear button for search and filter inputs so users can quickly reset without selecting all text.'},
- {guidance: false, description: "Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},
- {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},
- {guidance: false, description: "Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."},
+ {guidance: false, description: "Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers."},
+ {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead."},
+ {guidance: false, description: "Don't mark every field as required; only flag truly mandatory fields so users are not overwhelmed by validation errors."},
],
anatomy: [
{name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
index ec7b818dc1..402d41ae8f 100644
--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs
+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
@@ -48,17 +48,17 @@ export const docs = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
{
name: 'className',
type: 'string',
- description: 'CSS class name for the root element. Prefer xstyle for styling — className is provided for integration with non-StyleX systems.',
+ description: 'CSS class name for the root element. Prefer xstyle for styling; className is provided for integration with non-StyleX systems.',
},
{
name: 'style',
type: 'CSSProperties',
- description: 'Inline styles for the root element. Prefer xstyle for styling — inline styles bypass StyleX optimization.',
+ description: 'Inline styles for the root element. Prefer xstyle for styling; inline styles bypass StyleX optimization.',
},
{
name: 'data-testid',
@@ -77,9 +77,9 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover.'},
{guidance: true, description: 'Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available.'},
- {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image — the thumbnail adds button semantics and a hover shadow automatically.'},
- {guidance: false, description: "Don't use Thumbnail for non-image file types like PDFs or spreadsheets — use a file attachment component with an appropriate icon instead."},
- {guidance: false, description: "Don't omit alt text when a src is provided — screen readers need a description of the image content, not just the file name from label."},
+ {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image; the thumbnail adds button semantics and a hover shadow automatically.'},
+ {guidance: false, description: "Don't use Thumbnail for non-image file types like PDFs or spreadsheets; use a file attachment component with an appropriate icon instead."},
+ {guidance: false, description: "Don't omit alt text when a src is provided; screen readers need a description of the image content, not just the file name from label."},
],
anatomy: [
{name: 'Image', required: false, description: 'The preview image, displayed as a square with cover fit.'},
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index f239843041..e8a15bad7c 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -160,7 +160,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
],
theming: {
diff --git a/packages/core/src/Toast/useXDSToast.doc.mjs b/packages/core/src/Toast/useXDSToast.doc.mjs
index 1ae89b29e2..2507d861e3 100644
--- a/packages/core/src/Toast/useXDSToast.doc.mjs
+++ b/packages/core/src/Toast/useXDSToast.doc.mjs
@@ -21,8 +21,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for transient success/error feedback that does not require user action.'},
{guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'},
- {guidance: false, description: 'Use for critical errors that require acknowledgment — use AlertDialog instead.'},
- {guidance: false, description: 'Call useXDSToast in the same component that renders XDSLayerProvider — it must be called from a child component inside the provider.'},
+ {guidance: false, description: 'Use for critical errors that require acknowledgment; use AlertDialog instead.'},
+ {guidance: false, description: 'Call useXDSToast in the same component that renders XDSLayerProvider; it must be called from a child component inside the provider.'},
],
},
relatedComponents: ['Toast', 'Banner', 'AlertDialog'],
@@ -42,8 +42,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for transient success/error feedback not requiring user action.'},
{guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'},
- {guidance: false, description: 'Use for critical errors requiring acknowledgment — use AlertDialog instead.'},
- {guidance: false, description: 'Call useXDSToast in same component that renders XDSLayerProvider — must be called from child component inside provider.'},
+ {guidance: false, description: 'Use for critical errors requiring acknowledgment; use AlertDialog instead.'},
+ {guidance: false, description: 'Call useXDSToast in same component that renders XDSLayerProvider; must be called from child component inside provider.'},
],
},
};
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index 97e5f87c17..167240b11f 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -65,16 +65,16 @@ export const docs = {
description:
'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
bestPractices: [
- {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example.'},
+ {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example.'},
{guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},
{guidance: true, description: 'Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.'},
- {guidance: false, description: "Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\" — those are regular Buttons, not toggles."},
- {guidance: false, description: "Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup."},
- {guidance: false, description: "Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates \"setting\" semantics."},
+ {guidance: false, description: "Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\"; those are regular Buttons, not toggles."},
+ {guidance: false, description: "Don't mix ToggleButtons with regular Buttons inside the same group; use only ToggleButtons in a ToggleButtonGroup."},
+ {guidance: false, description: "Don't use a ToggleButton for on/off settings that persist across sessions; use a Switch instead, which better communicates \"setting\" semantics."},
],
anatomy: [
{name: 'Icon', required: false, description: 'A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.'},
- {name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.'},
+ {name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed: typically a filled version of the default icon to reinforce the active state.'},
{name: 'Label', required: true, description: 'The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.'},
{name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by pressedChangeAction.'},
],
@@ -126,16 +126,16 @@ export const docsZh = {
description:
'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
bestPractices: [
- {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example.'},
+ {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example.'},
{guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},
{guidance: true, description: 'Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.'},
- {guidance: false, description: "Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\" — those are regular Buttons, not toggles."},
- {guidance: false, description: "Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup."},
- {guidance: false, description: "Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates \"setting\" semantics."},
+ {guidance: false, description: "Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\"; those are regular Buttons, not toggles."},
+ {guidance: false, description: "Don't mix ToggleButtons with regular Buttons inside the same group; use only ToggleButtons in a ToggleButtonGroup."},
+ {guidance: false, description: "Don't use a ToggleButton for on/off settings that persist across sessions; use a Switch instead, which better communicates \"setting\" semantics."},
],
anatomy: [
{name: 'Icon', required: false, description: 'A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.'},
- {name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.'},
+ {name: 'Pressed icon', required: false, description: 'An alternate icon shown when pressed: typically a filled version of the default icon to reinforce the active state.'},
{name: 'Label', required: true, description: 'The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.'},
{name: 'Spinner', required: false, description: 'Replaces the icon during async operations triggered by pressedChangeAction.'},
],
@@ -152,9 +152,9 @@ export const docsDense = {
{guidance: true, description: 'Filled/colored icon for pressed state so users see current state at a glance.'},
{guidance: true, description: 'Keep label identical between states. Let visual treatment communicate the change.'},
{guidance: true, description: 'Wrap related toggles in ToggleButtonGroup with accessible label.'},
- {guidance: false, description: "Don't use ToggleButton for one-time actions — use regular Button for submit/delete."},
+ {guidance: false, description: "Don't use ToggleButton for one-time actions; use regular Button for submit/delete."},
{guidance: false, description: "Don't mix ToggleButtons with regular Buttons in the same group."},
- {guidance: false, description: "Don't use ToggleButton for persistent settings — use Switch instead."},
+ {guidance: false, description: "Don't use ToggleButton for persistent settings; use Switch instead."},
],
},
components: [
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
index 041088a8de..3bfa24a348 100644
--- a/packages/core/src/Token/Token.doc.mjs
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -84,7 +84,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
], theming: {
targets: [
@@ -93,13 +93,13 @@ export const docs = {
},
usage: {
description:
- 'Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.',
+ 'Token is a small, inline element for representing discrete pieces of associated data, like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.',
bestPractices: [
- {guidance: true, description: 'Use color to distinguish categories — for example, green for "Active", red for "Blocked", blue for "In Review" — so users can scan status at a glance.'},
+ {guidance: true, description: 'Use color to distinguish categories (for example, green for "Active", red for "Blocked", blue for "In Review") so users can scan status at a glance.'},
{guidance: true, description: 'Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.'},
{guidance: true, description: 'Add a leading icon when it helps identify the token type faster, like a person icon for user tokens or a tag icon for labels.'},
- {guidance: true, description: 'Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows.'},
- {guidance: false, description: 'Don\'t use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.'},
+ {guidance: true, description: 'Keep labels short: one to three words. Tokens truncate with ellipsis when the text overflows.'},
+ {guidance: false, description: 'Don\'t use tokens for primary actions or navigation; use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.'},
{guidance: false, description: 'Don\'t hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.'},
{guidance: false, description: 'Don\'t mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.'},
],
@@ -188,7 +188,7 @@ export const docsZh = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是内联样式对象如 style={{}}。',
+ '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,不能是内联样式对象如 style={{}}。',
},
],
theming: {
@@ -198,13 +198,13 @@ export const docsZh = {
},
usage: {
description:
- 'Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.',
+ 'Token is a small, inline element for representing discrete pieces of associated data, like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.',
bestPractices: [
- {guidance: true, description: 'Use color to distinguish categories — for example, green for "Active", red for "Blocked", blue for "In Review" — so users can scan status at a glance.'},
+ {guidance: true, description: 'Use color to distinguish categories (for example, green for "Active", red for "Blocked", blue for "In Review") so users can scan status at a glance.'},
{guidance: true, description: 'Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values.'},
{guidance: true, description: 'Add a leading icon when it helps identify the token type faster, like a person icon for user tokens or a tag icon for labels.'},
- {guidance: true, description: 'Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows.'},
- {guidance: false, description: 'Don\'t use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.'},
+ {guidance: true, description: 'Keep labels short: one to three words. Tokens truncate with ellipsis when the text overflows.'},
+ {guidance: false, description: 'Don\'t use tokens for primary actions or navigation; use Button or Link instead. Tokens are for displaying metadata, not triggering workflows.'},
{guidance: false, description: 'Don\'t hide the label unless the icon alone is universally understood. A color dot without text is ambiguous.'},
{guidance: false, description: 'Don\'t mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable.'},
],
@@ -222,13 +222,13 @@ export const docsDense = {
description: 'compact chip/tag for inline metadata, filters, selections. 11 colors, 3 sizes, removable, clickable, linkable.',
usage: {
description:
- 'Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use for labeling content, showing active filters, or representing removable items.',
+ 'Token is a small, inline element for representing discrete pieces of associated data, like tags, categories, or selections. Use for labeling content, showing active filters, or representing removable items.',
bestPractices: [
- {guidance: true, description: 'Color-code categories — green for active, red for blocked, blue for review — for fast scanning.'},
+ {guidance: true, description: 'Color-code categories (green for active, red for blocked, blue for review) for fast scanning.'},
{guidance: true, description: 'Provide onRemove when tokens represent dismissible user selections like filters or multi-select values.'},
- {guidance: true, description: 'Add a leading icon when it helps identify the token type — person icon for users, tag icon for labels.'},
+ {guidance: true, description: 'Add a leading icon when it helps identify the token type: person icon for users, tag icon for labels.'},
{guidance: true, description: 'Keep labels to one to three words. Tokens truncate with ellipsis on overflow.'},
- {guidance: false, description: 'Don\'t use tokens for actions or navigation — use Button or Link. Tokens display metadata, not trigger workflows.'},
+ {guidance: false, description: 'Don\'t use tokens for actions or navigation; use Button or Link. Tokens display metadata, not trigger workflows.'},
{guidance: false, description: 'Don\'t hide the label unless the icon alone is universally clear.'},
{guidance: false, description: 'Don\'t mix too many colors in one group. Two or three meaningful colors keeps it scannable.'},
],
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index c1387198a8..4d6d2bf2d3 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -101,9 +101,9 @@ export const docs = {
description:
'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
bestPractices: [
- {guidance: true, description: 'Keep tooltip content concise — aim for under 140 characters of plain text.'},
+ {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
{guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
- {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.'},
+ {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
{guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
],
},
@@ -200,9 +200,9 @@ export const docsZh = {
description:
'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
bestPractices: [
- {guidance: true, description: 'Keep tooltip content concise — aim for under 140 characters of plain text.'},
+ {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
{guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
- {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.'},
+ {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
{guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
],
},
@@ -215,9 +215,9 @@ export const docsDense = {
description:
'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
bestPractices: [
- {guidance: true, description: 'Keep tooltip content concise — aim for under 140 characters of plain text.'},
+ {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
{guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
- {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.'},
+ {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
{guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
],
},
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 48486f2335..beeeb76e6d 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -69,8 +69,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
{guidance: true, description: 'Pre-expand important branches so users see key content immediately.'},
- {guidance: false, description: 'Nest more than 4–5 levels deep — flatten the structure or use a different pattern.'},
- {guidance: false, description: 'Use a tree for flat, non-hierarchical data — use a List instead.'},
+ {guidance: false, description: 'Nest more than 4–5 levels deep; flatten the structure or use a different pattern.'},
+ {guidance: false, description: 'Use a tree for flat, non-hierarchical data; use a List instead.'},
],
},
};
@@ -133,8 +133,8 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
{guidance: true, description: 'Pre-expand important branches so users see key content immediately.'},
- {guidance: false, description: 'Nest more than 4–5 levels deep — flatten the structure or use a different pattern.'},
- {guidance: false, description: 'Use a tree for flat, non-hierarchical data — use a List instead.'},
+ {guidance: false, description: 'Nest more than 4–5 levels deep; flatten the structure or use a different pattern.'},
+ {guidance: false, description: 'Use a tree for flat, non-hierarchical data; use a List instead.'},
],
},
};
@@ -149,8 +149,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
{guidance: true, description: 'Pre-expand important branches so users see key content immediately.'},
- {guidance: false, description: 'Nest more than 4–5 levels deep — flatten the structure or use a different pattern.'},
- {guidance: false, description: 'Use a tree for flat, non-hierarchical data — use a List instead.'},
+ {guidance: false, description: 'Nest more than 4–5 levels deep; flatten the structure or use a different pattern.'},
+ {guidance: false, description: 'Use a tree for flat, non-hierarchical data; use a List instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 53dde8c85d..e7f2247ceb 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -149,7 +149,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
], },
{
@@ -315,8 +315,8 @@ export const docs = {
{guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
{guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
{guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
- {guidance: false, description: 'Use for short, static option lists — use Selector for better discoverability.'},
- {guidance: false, description: 'Use for multi-selection — use Tokenizer instead.'},
+ {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},
+ {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},
{guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
@@ -467,7 +467,7 @@ export const docsZh = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是内联样式对象如 style={{}}。',
+ '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,不能是内联样式对象如 style={{}}。',
},
],
},
@@ -633,8 +633,8 @@ export const docsZh = {
{guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
{guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
{guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
- {guidance: false, description: 'Use for short, static option lists — use Selector for better discoverability.'},
- {guidance: false, description: 'Use for multi-selection — use Tokenizer instead.'},
+ {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},
+ {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},
{guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
@@ -650,8 +650,8 @@ export const docsDense = {
{guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
{guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
{guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
- {guidance: false, description: 'Use for short, static option lists — use Selector for better discoverability.'},
- {guidance: false, description: 'Use for multi-selection — use Tokenizer instead.'},
+ {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},
+ {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},
{guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
diff --git a/packages/core/src/hooks/useClickableContainer.doc.mjs b/packages/core/src/hooks/useClickableContainer.doc.mjs
index f6c85c1e79..47d7daa650 100644
--- a/packages/core/src/hooks/useClickableContainer.doc.mjs
+++ b/packages/core/src/hooks/useClickableContainer.doc.mjs
@@ -68,7 +68,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Attach both onClick and onMouseUp to the container element for full click handling including middle-click.' },
{ guidance: true, description: 'Use inside XDSClickableCard or XDSSelectableCard for the standard card interaction pattern.' },
- { guidance: false, description: 'Use when the entire container is a single interactive element — just use a <button> or <a> directly.' },
+ { guidance: false, description: 'Use when the entire container is a single interactive element; just use a <button> or <a> directly.' },
],
},
relatedComponents: ['ClickableCard', 'SelectableCard'],
@@ -100,7 +100,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Attach both onClick + onMouseUp to container element for full click handling incl. middle-click.' },
{ guidance: true, description: 'Use inside XDSClickableCard / XDSSelectableCard for standard card interaction pattern.' },
- { guidance: false, description: 'Use when entire container is single interactive element — just use <button> / <a> directly.' },
+ { guidance: false, description: 'Use when entire container is single interactive element; just use <button> / <a> directly.' },
],
},
};
diff --git a/packages/core/src/hooks/useEntryAnimation.doc.mjs b/packages/core/src/hooks/useEntryAnimation.doc.mjs
index 22c2c5b664..dbfaa65ae4 100644
--- a/packages/core/src/hooks/useEntryAnimation.doc.mjs
+++ b/packages/core/src/hooks/useEntryAnimation.doc.mjs
@@ -23,11 +23,11 @@ export const docs = {
],
usage: {
description:
- 'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint — elements rendered on page load are not animated. Uses XDS motion tokens (duration, easing) for consistent animation timing. Requires "use client" — does not support SSR.',
+ 'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses XDS motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
bestPractices: [
{ guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, or expanding sections.' },
{ guidance: true, description: 'Spread the returned style into stylex.props() alongside other styles.' },
- { guidance: false, description: 'Use for elements that should be visible on initial page load — they will not animate.' },
+ { guidance: false, description: 'Use for elements that should be visible on initial page load; they will not animate.' },
],
},
relatedComponents: ['FieldStatus'],
@@ -39,7 +39,7 @@ export const docs = {
/** @type {import('../docs-types').HookTranslationDoc} */
export const docsDense = {
description:
- 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint — elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client" — does not support SSR.',
+ 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
paramDescriptions: {
preset: 'animation preset applied on mount.',
},
@@ -48,11 +48,11 @@ export const docsDense = {
},
usage: {
description:
- 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint — elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client" — does not support SSR.',
+ 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
bestPractices: [
{ guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },
{ guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },
- { guidance: false, description: 'Use for elements that should be visible on initial page load — they will not animate.' },
+ { guidance: false, description: 'Use for elements that should be visible on initial page load; they will not animate.' },
],
},
};
diff --git a/packages/core/src/hooks/useFocusTrap.doc.mjs b/packages/core/src/hooks/useFocusTrap.doc.mjs
index 380a764f42..da096236b3 100644
--- a/packages/core/src/hooks/useFocusTrap.doc.mjs
+++ b/packages/core/src/hooks/useFocusTrap.doc.mjs
@@ -39,11 +39,11 @@ export const docs = {
],
usage: {
description:
- 'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted — use a light-dismiss handler for that.',
+ 'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.',
bestPractices: [
{ guidance: true, description: 'Call focusFirst() when opening a dialog/modal to move focus into the trapped region.' },
{ guidance: true, description: 'Provide an onEscape callback to close the dialog when Escape is pressed.' },
- { guidance: false, description: 'Use on non-modal content like tooltips or dropdowns — those need light-dismiss, not focus trapping.' },
+ { guidance: false, description: 'Use on non-modal content like tooltips or dropdowns; those need light-dismiss, not focus trapping.' },
],
},
relatedComponents: ['Dialog', 'DatePicker'],
@@ -55,7 +55,7 @@ export const docs = {
/** @type {import('../docs-types').HookTranslationDoc} */
export const docsDense = {
description:
- 'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted — use light-dismiss handler for that.',
+ 'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
paramDescriptions: {
options: 'config for focus trap.',
'options.isActive': 'whether focus trap currently active.',
@@ -67,11 +67,11 @@ export const docsDense = {
},
usage: {
description:
- 'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted — use light-dismiss handler for that.',
+ 'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
bestPractices: [
{ guidance: true, description: 'Call focusFirst() when opening dialog/modal to move focus into trapped region.' },
{ guidance: true, description: 'Provide onEscape callback to close dialog when Escape pressed.' },
- { guidance: false, description: 'Use on non-modal content like tooltips / dropdowns — those need light-dismiss, not focus trapping.' },
+ { guidance: false, description: 'Use on non-modal content like tooltips / dropdowns; those need light-dismiss, not focus trapping.' },
],
},
};
diff --git a/packages/core/src/hooks/useGridFocus.doc.mjs b/packages/core/src/hooks/useGridFocus.doc.mjs
index d39f5d7938..5ef202d207 100644
--- a/packages/core/src/hooks/useGridFocus.doc.mjs
+++ b/packages/core/src/hooks/useGridFocus.doc.mjs
@@ -81,9 +81,9 @@ export const docs = {
description:
'Manages keyboard navigation within a 2D grid following the WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, and Page Up/Down for custom callbacks (e.g., month navigation in calendars). Boundary navigation callbacks allow seamless cross-grid navigation.',
bestPractices: [
- { guidance: true, description: 'Use for calendar date grids — wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
+ { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
{ guidance: true, description: 'Attach both gridRef and handleKeyDown to the grid container element.' },
- { guidance: false, description: 'Use for simple linear lists — prefer useListFocus for 1D navigation.' },
+ { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
],
},
relatedComponents: ['Calendar'],
@@ -116,9 +116,9 @@ export const docsDense = {
description:
'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow seamless cross-grid navigation.',
bestPractices: [
- { guidance: true, description: 'Use for calendar date grids — wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
+ { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
{ guidance: true, description: 'Attach both gridRef + handleKeyDown to grid container element.' },
- { guidance: false, description: 'Use for simple linear lists — prefer useListFocus for 1D navigation.' },
+ { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
],
},
};
diff --git a/packages/core/src/hooks/useImageMode.doc.mjs b/packages/core/src/hooks/useImageMode.doc.mjs
index 44ad0e1052..b7d7d9defd 100644
--- a/packages/core/src/hooks/useImageMode.doc.mjs
+++ b/packages/core/src/hooks/useImageMode.doc.mjs
@@ -48,11 +48,11 @@ export const docs = {
],
usage: {
description:
- 'Detects whether an image is predominantly dark or light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading and falls back gracefully on CORS or network errors.',
+ 'Detects whether an image is predominantly dark or light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading and falls back gracefully on CORS or network errors.',
bestPractices: [
{ guidance: true, description: 'Pair with XDSMediaTheme to automatically adapt text color over dynamic background images.' },
{ guidance: true, description: 'Use the region option to sample only the area where text overlays will appear for more accurate results.' },
- { guidance: false, description: 'Use for images that change rapidly (e.g., video frames) — each src change triggers a new fetch and analysis.' },
+ { guidance: false, description: 'Use for images that change rapidly (e.g., video frames); each src change triggers a new fetch and analysis.' },
],
},
relatedComponents: ['MediaTheme'],
@@ -64,7 +64,7 @@ export const docs = {
/** @type {import('../docs-types').HookTranslationDoc} */
export const docsDense = {
description:
- 'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',
+ 'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',
paramDescriptions: {
src: 'image source URL to analyze. When null/undefined, returns fallback value.',
options: 'optional config for image analysis.',
@@ -77,11 +77,11 @@ export const docsDense = {
},
usage: {
description:
- 'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',
+ 'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',
bestPractices: [
{ guidance: true, description: 'Pair w/ XDSMediaTheme to automatically adapt text color over dynamic background images.' },
{ guidance: true, description: 'Use region option to sample only area where text overlays will appear for more accurate results.' },
- { guidance: false, description: 'Use for images that change rapidly (e.g. video frames) — each src change triggers new fetch + analysis.' },
+ { guidance: false, description: 'Use for images that change rapidly (e.g. video frames); each src change triggers new fetch + analysis.' },
],
},
};
diff --git a/packages/core/src/hooks/useInputContainer.doc.mjs b/packages/core/src/hooks/useInputContainer.doc.mjs
index 948d3a92d2..525b15a1e2 100644
--- a/packages/core/src/hooks/useInputContainer.doc.mjs
+++ b/packages/core/src/hooks/useInputContainer.doc.mjs
@@ -46,11 +46,11 @@ export const docs = {
],
usage: {
description:
- 'Makes an input container wrapper clickable, delegating focus to the inner input/textarea when the user clicks non-interactive areas (icons, padding, status indicators). Built on top of useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) are handled safely — clicking them does NOT steal focus from the input. Automatically detects input type: text-like inputs receive .focus(), while other types (checkbox, radio, file) receive .click().',
+ 'Makes an input container wrapper clickable, delegating focus to the inner input/textarea when the user clicks non-interactive areas (icons, padding, status indicators). Built on top of useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) are handled safely; clicking them does NOT steal focus from the input. Automatically detects input type: text-like inputs receive .focus(), while other types (checkbox, radio, file) receive .click().',
bestPractices: [
{ guidance: true, description: 'Use inside input wrapper components (XDSTextInput, XDSNumberInput, XDSTimeInput, XDSTextArea) to make the full container area clickable.' },
{ guidance: true, description: 'Attach both onClick and onMouseUp to the wrapper div for full interaction handling.' },
- { guidance: false, description: 'Use on bare inputs without a wrapper — there is no benefit if the input already fills the full clickable area.' },
+ { guidance: false, description: 'Use on bare inputs without a wrapper; there is no benefit if the input already fills the full clickable area.' },
],
},
relatedComponents: ['TextInput', 'NumberInput', 'TimeInput', 'TextArea'],
@@ -62,7 +62,7 @@ export const docs = {
/** @type {import('../docs-types').HookTranslationDoc} */
export const docsDense = {
description:
- 'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely — clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',
+ 'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely; clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',
paramDescriptions: {
options: 'config for input container.',
'options.containerRef': 'ref to outer container/wrapper element.',
@@ -75,11 +75,11 @@ export const docsDense = {
},
usage: {
description:
- 'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely — clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',
+ 'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely; clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',
bestPractices: [
{ guidance: true, description: 'Use inside input wrapper components (XDSTextInput, XDSNumberInput, XDSTimeInput, XDSTextArea) to make full container area clickable.' },
{ guidance: true, description: 'Attach both onClick + onMouseUp to wrapper div for full interaction handling.' },
- { guidance: false, description: 'Use on bare inputs w/o wrapper — no benefit if input already fills full clickable area.' },
+ { guidance: false, description: 'Use on bare inputs w/o wrapper; no benefit if input already fills full clickable area.' },
],
},
};
diff --git a/packages/core/src/hooks/useListFocus.doc.mjs b/packages/core/src/hooks/useListFocus.doc.mjs
index 6bcff0aa36..53c38de0d1 100644
--- a/packages/core/src/hooks/useListFocus.doc.mjs
+++ b/packages/core/src/hooks/useListFocus.doc.mjs
@@ -73,7 +73,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: "Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus." },
{ guidance: true, description: 'Provide an onEscape callback for menus/dropdowns to return focus to the trigger.' },
- { guidance: false, description: 'Use for 2D grid navigation — prefer useGridFocus for grids and calendars.' },
+ { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids and calendars.' },
],
},
relatedComponents: ['TabMenu', 'Toolbar'],
@@ -106,7 +106,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: "Set orientation to 'horizontal' for toolbars + tab bars, 'vertical' for dropdown menus." },
{ guidance: true, description: 'Provide onEscape callback for menus/dropdowns to return focus to trigger.' },
- { guidance: false, description: 'Use for 2D grid navigation — prefer useGridFocus for grids + calendars.' },
+ { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids + calendars.' },
],
},
};
diff --git a/packages/core/src/hooks/useMediaQuery.doc.mjs b/packages/core/src/hooks/useMediaQuery.doc.mjs
index 1777eab0ed..a0998b68d3 100644
--- a/packages/core/src/hooks/useMediaQuery.doc.mjs
+++ b/packages/core/src/hooks/useMediaQuery.doc.mjs
@@ -25,7 +25,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
{ guidance: true, description: 'Prefer XDS responsive tokens and component props over manual breakpoint logic when possible.' },
- { guidance: false, description: 'Use for server-rendered content that must match on first paint — the hook always returns false initially.' },
+ { guidance: false, description: 'Use for server-rendered content that must match on first paint; the hook always returns false initially.' },
],
},
relatedComponents: [],
@@ -48,7 +48,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
{ guidance: true, description: 'Prefer XDS responsive tokens + component props over manual breakpoint logic when possible.' },
- { guidance: false, description: 'Use for server-rendered content that must match on first paint — hook always returns false initially.' },
+ { guidance: false, description: 'Use for server-rendered content that must match on first paint; hook always returns false initially.' },
],
},
};
diff --git a/packages/core/src/hooks/useOverflow.doc.mjs b/packages/core/src/hooks/useOverflow.doc.mjs
index 02f4b40366..12ca272d06 100644
--- a/packages/core/src/hooks/useOverflow.doc.mjs
+++ b/packages/core/src/hooks/useOverflow.doc.mjs
@@ -75,7 +75,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Render all items into the measureRef container (hidden) and only the first visibleCount items into the containerRef container (visible).' },
{ guidance: true, description: 'Include an overflow indicator (e.g., "+N more" button) as the last child of the measurement container with a data-overflow-indicator attribute.' },
- { guidance: false, description: 'Use for vertical overflow — this hook measures horizontal width only.' },
+ { guidance: false, description: 'Use for vertical overflow; this hook measures horizontal width only.' },
],
},
relatedComponents: ['OverflowList', 'Breadcrumb'],
@@ -108,7 +108,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Render all items into measureRef container (hidden) + only first visibleCount items into containerRef container (visible).' },
{ guidance: true, description: 'Include overflow indicator (e.g. "+N more" button) as last child of measurement container w/ data-overflow-indicator attribute.' },
- { guidance: false, description: 'Use for vertical overflow — this hook measures horizontal width only.' },
+ { guidance: false, description: 'Use for vertical overflow; this hook measures horizontal width only.' },
],
},
};
diff --git a/packages/core/src/hooks/useScrollLock.doc.mjs b/packages/core/src/hooks/useScrollLock.doc.mjs
index 4bbe702907..52f5c25327 100644
--- a/packages/core/src/hooks/useScrollLock.doc.mjs
+++ b/packages/core/src/hooks/useScrollLock.doc.mjs
@@ -20,7 +20,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Use when opening full-screen modals or dialogs to prevent background content from scrolling.' },
{ guidance: true, description: 'Pass the same boolean that controls dialog visibility (e.g., isOpen) as the isLocked parameter.' },
- { guidance: false, description: 'Use for non-modal overlays like popovers or tooltips — users should be able to scroll away from those.' },
+ { guidance: false, description: 'Use for non-modal overlays like popovers or tooltips; users should be able to scroll away from those.' },
],
},
relatedComponents: ['Dialog'],
@@ -42,7 +42,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Use when opening full-screen modals / dialogs to prevent background content from scrolling.' },
{ guidance: true, description: 'Pass same boolean that controls dialog visibility (e.g. isOpen) as isLocked parameter.' },
- { guidance: false, description: 'Use for non-modal overlays like popovers / tooltips — users should be able to scroll away from those.' },
+ { guidance: false, description: 'Use for non-modal overlays like popovers / tooltips; users should be able to scroll away from those.' },
],
},
};
diff --git a/packages/core/src/hooks/useScrollOverflow.doc.mjs b/packages/core/src/hooks/useScrollOverflow.doc.mjs
index e81633a663..c47babc17e 100644
--- a/packages/core/src/hooks/useScrollOverflow.doc.mjs
+++ b/packages/core/src/hooks/useScrollOverflow.doc.mjs
@@ -34,7 +34,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Use to show/hide scroll navigation buttons or fade edges on carousels and horizontal lists.' },
{ guidance: true, description: 'Apply the scrollRef to a container with overflow-x: auto or overflow-x: scroll.' },
- { guidance: false, description: 'Use for vertical scroll tracking — this hook only measures horizontal overflow.' },
+ { guidance: false, description: 'Use for vertical scroll tracking; this hook only measures horizontal overflow.' },
],
},
relatedComponents: ['Carousel'],
@@ -59,7 +59,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Use to show/hide scroll navigation buttons / fade edges on carousels + horizontal lists.' },
{ guidance: true, description: 'Apply scrollRef to container w/ overflow-x: auto / overflow-x: scroll.' },
- { guidance: false, description: 'Use for vertical scroll tracking — this hook only measures horizontal overflow.' },
+ { guidance: false, description: 'Use for vertical scroll tracking; this hook only measures horizontal overflow.' },
],
},
};
diff --git a/packages/core/src/hooks/useXDSStreamingText.doc.mjs b/packages/core/src/hooks/useXDSStreamingText.doc.mjs
index 92f984ffdd..c178f0f1f6 100644
--- a/packages/core/src/hooks/useXDSStreamingText.doc.mjs
+++ b/packages/core/src/hooks/useXDSStreamingText.doc.mjs
@@ -43,10 +43,10 @@ export const docs = {
description:
'Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from XDS motion tokens via useXDSTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.',
bestPractices: [
- { guidance: true, description: 'Pass the accumulated text (not individual chunks) as targetText — the hook handles incremental reveal internally.' },
+ { guidance: true, description: 'Pass the accumulated text (not individual chunks) as targetText; the hook handles incremental reveal internally.' },
{ guidance: true, description: 'Set isStreaming to false when the stream completes to snap to the final text.' },
{ guidance: true, description: "Use speed='instant' for non-animated contexts like search results or when reduced motion is preferred." },
- { guidance: false, description: 'Use for static text that does not change — the hook adds unnecessary overhead for non-streaming content.' },
+ { guidance: false, description: 'Use for static text that does not change; the hook adds unnecessary overhead for non-streaming content.' },
],
},
relatedComponents: ['Markdown'],
@@ -72,10 +72,10 @@ export const docsDense = {
description:
'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useXDSTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
bestPractices: [
- { guidance: true, description: 'Pass accumulated text (not individual chunks) as targetText — hook handles incremental reveal internally.' },
+ { guidance: true, description: 'Pass accumulated text (not individual chunks) as targetText; hook handles incremental reveal internally.' },
{ guidance: true, description: 'Set isStreaming to false when stream completes to snap to final text.' },
{ guidance: true, description: "Use speed='instant' for non-animated contexts like search results / when reduced motion preferred." },
- { guidance: false, description: 'Use for static text that does not change — hook adds unnecessary overhead for non-streaming content.' },
+ { guidance: false, description: 'Use for static text that does not change; hook adds unnecessary overhead for non-streaming content.' },
],
},
};
diff --git a/packages/core/src/theme/MediaTheme.doc.mjs b/packages/core/src/theme/MediaTheme.doc.mjs
index c195456cad..0bb82410ab 100644
--- a/packages/core/src/theme/MediaTheme.doc.mjs
+++ b/packages/core/src/theme/MediaTheme.doc.mjs
@@ -58,7 +58,7 @@ export const docs = {
},
usage: {
description:
- 'Provides token overrides for content rendered on inverted surfaces — media overlays, scrims, toasts, and tooltips. The base behavior flips color-scheme so all light-dark() tokens resolve to the correct side. Only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), with both token overrides (e.g. "--color-accent": "#90CAF9") and component overrides (e.g. ghost buttons get a border on dark surfaces).',
+ 'Provides token overrides for content rendered on inverted surfaces: media overlays, scrims, toasts, and tooltips. The base behavior flips color-scheme so all light-dark() tokens resolve to the correct side. Only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), with both token overrides (e.g. "--color-accent": "#90CAF9") and component overrides (e.g. ghost buttons get a border on dark surfaces).',
bestPractices: [
{
guidance: true,
@@ -104,7 +104,7 @@ export const docs = {
export const docsDense = {
usage: {
description:
- 'Token overrides for content on inverted surfaces — media overlays, scrims, toasts, tooltips. Base behavior flips color-scheme so all light-dark() tokens resolve to correct side; only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), w/ token overrides (e.g. "--color-accent": "#90CAF9") + component overrides (e.g. ghost buttons get border on dark surfaces).',
+ 'Token overrides for content on inverted surfaces: media overlays, scrims, toasts, tooltips. Base behavior flips color-scheme so all light-dark() tokens resolve to correct side; only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), w/ token overrides (e.g. "--color-accent": "#90CAF9") + component overrides (e.g. ghost buttons get border on dark surfaces).',
bestPractices: [
{
guidance: true,
@@ -129,6 +129,6 @@ export const docsDense = {
],
},
propDescriptions: {
- mode: 'surface luminance context — dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions). **(required)**',
+ mode: 'surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions). **(required)**',
},
};
diff --git a/packages/lab/README.md b/packages/lab/README.md
index a27ca7fdd6..3436ecd933 100644
--- a/packages/lab/README.md
+++ b/packages/lab/README.md
@@ -1,6 +1,6 @@
# @xds/lab
-Experimental XDS components. This package is **not published** — it exists as a staging area for components being developed before graduating to `@xds/core`.
+Experimental XDS components. This package is **not published**; it exists as a staging area for components being developed before graduating to `@xds/core`.
## Purpose
diff --git a/packages/lab/src/Stepper/Stepper.doc.mjs b/packages/lab/src/Stepper/Stepper.doc.mjs
index d4f2d336e5..a1408acf7f 100644
--- a/packages/lab/src/Stepper/Stepper.doc.mjs
+++ b/packages/lab/src/Stepper/Stepper.doc.mjs
@@ -12,11 +12,11 @@ export const docs = {
description:
'Steppers display progress through a sequence of logical and numbered steps. Use them for multi-step workflows like forms, onboarding flows, or checkout processes where users need to see their position and the steps ahead.',
bestPractices: [
- {guidance: true, description: 'Keep step labels short and descriptive — "Payment" not "Enter your payment information".'},
+ {guidance: true, description: 'Keep step labels short and descriptive: "Payment" not "Enter your payment information".'},
{guidance: true, description: 'Use the vertical orientation for narrow containers or when steps have longer descriptions.'},
{guidance: true, description: 'Provide onStepClick for non-linear workflows where users may need to revisit earlier steps.'},
- {guidance: false, description: 'Use a stepper for fewer than 3 steps — a simple heading or progress bar works better.'},
- {guidance: false, description: 'Use more than 7 steps — consider grouping related steps or using a different pattern.'},
+ {guidance: false, description: 'Use a stepper for fewer than 3 steps; a simple heading or progress bar works better.'},
+ {guidance: false, description: 'Use more than 7 steps; consider grouping related steps or using a different pattern.'},
],
anatomy: [
{name: 'Step indicator', required: true, description: 'A numbered circle showing the step position. Shows a checkmark when completed.'},
diff --git a/packages/themes/butter/README.md b/packages/themes/butter/README.md
index 9376c05708..fd0ba2ef3f 100644
--- a/packages/themes/butter/README.md
+++ b/packages/themes/butter/README.md
@@ -38,9 +38,9 @@ plus Error / Warning / Success) is published as a smooth 21-step tonal
palette in `butterPalettes`. Categorical badges, cards, and banner text
roles read from these palettes via:
-- `T90` light / `T15` dark — background surfaces
-- `T80` light / `T25` dark — borders, dark-mode text
-- `T25` light / `T80` dark — light-mode text, icons
+- `T90` light / `T15` dark: background surfaces
+- `T80` light / `T25` dark: borders, dark-mode text
+- `T25` light / `T80` dark: light-mode text, icons
To regenerate the palettes after changing a source color, edit the
`SOURCES` map in `scripts/generate-palettes.mjs`, run the script, and
@@ -48,7 +48,7 @@ paste the output back into `src/butterTheme.ts`.
## Typography
-- **Display**: Sarina (cursive) — applied per-page via inline style.
+- **Display**: Sarina (cursive), applied per-page via inline style.
- **Heading & Body**: Outfit, base 14px, ratio 1.25.
- **Code**: JetBrains Mono.
diff --git a/packages/themes/gothic/README.md b/packages/themes/gothic/README.md
index ace3fb803b..ad7d3be1b1 100644
--- a/packages/themes/gothic/README.md
+++ b/packages/themes/gothic/README.md
@@ -2,7 +2,7 @@
**Dark-only** atmospheric gothic theme for XDS — deep blue-gray surfaces, distressed display heading, and pastel categorical accents that glow against the dark page like illuminated panels. Uses Manufacturing Consent for headings, Fustat for body text, and [Lucide](https://lucide.dev) icons.
-> Gothic is a single-mode theme — it always renders dark, regardless of the user's system color preference. For best browser-chrome integration (scrollbars, native form controls), pass `mode="dark"` to your `XDSTheme` provider.
+> Gothic is a single-mode theme: it always renders dark, regardless of the user's system color preference. For best browser-chrome integration (scrollbars, native form controls), pass `mode="dark"` to your `XDSTheme` provider.
## Install
@@ -47,16 +47,16 @@ Add the theme CSS to your stylesheet:
## Aesthetic
-Gothic is dark-only by design — every token is a single value, and the
+Gothic is dark-only by design: every token is a single value, and the
output CSS contains no `light-dark()`, so the theme renders identically
whether the user prefers light or dark.
| Aspect | Choice |
| ------------ | ------------------------------------------------------ |
-| Mode | Dark only — no light variant |
+| Mode | Dark only, no light variant |
| Neutral | Cool blue-gray (#101314 → #E8F1F6) |
| Status | Forest moss, blood crimson, candlelight amber |
-| Categorical | Pastel-on-dark — light backgrounds, dark text |
+| Categorical | Pastel-on-dark: light backgrounds, dark text |
| Radius | Subtle rounding (2–24px) |
| Motion | Slower / theatrical (150ms → 800ms, 0.75 ratio) |
| Type scale | 14px base, 1.2 ratio |
diff --git a/packages/themes/neutral/README.md b/packages/themes/neutral/README.md
index 10650e5eeb..85cdb69e56 100644
--- a/packages/themes/neutral/README.md
+++ b/packages/themes/neutral/README.md
@@ -41,7 +41,7 @@ Add the theme CSS to your stylesheet:
This is required for component-level theme overrides (colors, radii, typography) to take effect.
-This theme uses system fonts — no external font loading is required.
+This theme uses system fonts; no external font loading is required.
## Related Packages