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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mdindex 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`.## Purposediff --git a/packages/lab/src/Stepper/Stepper.doc.mjs b/packages/lab/src/Stepper/Stepper.doc.mjsindex 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.mdindex 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 tonalpalette in `butterPalettes`. Categorical badges, cards, and banner textroles 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, iconsTo 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.mdindex 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 theoutput CSS contains no `light-dark()`, so the theme renders identicallywhether 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.mdindex 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