An open source design system that's fully customizable and agent ready
TypeScript
docs(deslop): batch 3 - remove AI-slop tells from doc files (30 files) (#2661)
Joey70917118d03a
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjsindex 1e1cc577db..c41c592c17 100644--- a/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs@@ -6,7 +6,7 @@ export const doc = {exampleFor: 'TextArea',name: 'TextArea — Validation',displayName: 'TextArea — Validation',- description: 'All three status variants — error, warning, and success — with status messages, plus error without a message. Use to show inline validation feedback as the user types.',+ description: 'All three status variants (error, warning, and success) with status messages, plus error without a message. Use to show inline validation feedback as the user types.',isReady: true,aspectRatio: 3 / 4,componentsUsed: ['TextArea', 'Layout'],diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjsindex 74726a5dcc..e7e79ec360 100644--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs@@ -7,7 +7,7 @@ export const doc = {name: 'Toolbar — Card Header',displayName: 'Toolbar — Card Header',description:- 'A toolbar as a card header with a left-aligned title and icon actions on the right. Use Toolbar instead of LayoutHeader when your card header has interactive actions — Toolbar adds start/end slot layout, keyboard navigation, and automatic size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough.',+ 'A toolbar as a card header with a left-aligned title and icon actions on the right. Use Toolbar instead of LayoutHeader when your card header has interactive actions; Toolbar adds start/end slot layout, keyboard navigation, and automatic size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough.',isReady: true,aspectRatio: 16 / 9,componentsUsed: ['Toolbar', 'Button', 'Icon', 'Text', 'Card', 'Section'],diff --git a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjsindex 0cbb8fb500..5433414696 100644--- a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs@@ -6,7 +6,7 @@ export const doc = {exampleFor: 'TreeListItem',name: 'TreeListItem',displayName: 'Tree List Item',- description: 'Tree items with descriptions, icons, badges, selection, disabled state, and nested expand/collapse. TreeList is data-driven — no composed children API.',+ description: 'Tree items with descriptions, icons, badges, selection, disabled state, and nested expand/collapse. TreeList is data-driven: no composed children API.',isReady: true,isShowcase: true,aspectRatio: 4 / 3,diff --git a/packages/cli/templates/pages/ide/template.doc.mjs b/packages/cli/templates/pages/ide/template.doc.mjsindex 1f40829f6f..5d3eb22eec 100644--- a/packages/cli/templates/pages/ide/template.doc.mjs+++ b/packages/cli/templates/pages/ide/template.doc.mjs@@ -6,7 +6,7 @@ export const doc = {name: 'IDE',displayName: 'IDE',description:- 'Code editor workspace with file explorer, tabbed editor, terminal panel, and properties sidebar — all resizable and collapsible.',+ 'Code editor workspace with file explorer, tabbed editor, terminal panel, and properties sidebar, all resizable and collapsible.',isReady: true,category: 'Tools - IDE',};diff --git a/packages/core/README.md b/packages/core/README.mdindex 5bddf8d3c3..b62f4fdcce 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -4,7 +4,7 @@ Core UI components, theme system, and utilities for the XDS design system. For p## Component Docs-Look up any component's full API — props, types, best practices, and theming:+Look up any component's full API (props, types, best practices, and theming):```bashnode node_modules/@xds/core/docs.mjs Button # full docs for a component@@ -15,7 +15,7 @@ node node_modules/@xds/core/docs.mjs --list --brief # brief summaries## Page LayoutsBuilding a full page? Start with a template rather than composing from scratch.-Templates are content-only — they compose `XDSLayout` with header, content, and+Templates are content-only; they compose `XDSLayout` with header, content, andpanel slots into common page patterns (dashboards, settings, forms, detail pages).Wrap them in your own app chrome (`XDSAppShell`, `XDSTopNav`, `XDSSideNav`) to addglobal navigation.@@ -50,7 +50,7 @@ npx xds gap-report # report a missing capability| Package | Description ||---------|-------------|-| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling — component docs, templates, scaffolding, codemods |+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling: component docs, templates, scaffolding, codemods || [`@xds/theme-default`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/default) | Default theme (Heroicons) || [`@xds/theme-neutral`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/neutral) | Muted, minimal theme (Lucide icons) || [`@xds/theme-daily`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/daily) | Warm, productivity-focused theme (Lucide icons) |@@ -74,7 +74,7 @@ Then pick your setup below based on your framework and styling approach.### Next.js + Tailwind (simplest)-No build plugins needed — XDS ships pre-built CSS that works alongside Tailwind.+No build plugins needed; XDS ships pre-built CSS that works alongside Tailwind.**`src/app/globals.css`**@@ -150,7 +150,7 @@ export default function RootLayout({children}: {children: React.ReactNode}) {}```-That's it — start using components:+That's it. Start using components:```tsximport {XDSButton} from '@xds/core/Button';@@ -184,4 +184,4 @@ Providers and layout are the same as the Tailwind example (use `@xds/theme-defaunpm install @xds/core @xds/theme-default```-Same CSS imports and providers as above. No build plugins needed — XDS ships pre-built.+Same CSS imports and providers as above. No build plugins needed; XDS ships pre-built.diff --git a/packages/core/src/ClickableCard/ClickableCard.doc.mjs b/packages/core/src/ClickableCard/ClickableCard.doc.mjsindex 7ec8c21629..9d81bd77a8 100644--- a/packages/core/src/ClickableCard/ClickableCard.doc.mjs+++ b/packages/core/src/ClickableCard/ClickableCard.doc.mjs@@ -11,8 +11,8 @@ export const docs = {description: 'An interactive card for navigation or action targets. Nested interactive elements work independently.',bestPractices: [{guidance: true, description: 'Use for cards that navigate to a detail page or trigger a single action.'},- {guidance: true, description: 'Nest buttons or links freely inside — they handle their own events.'},- {guidance: false, description: 'Use for toggling selection — use SelectableCard for that.'},+ {guidance: true, description: 'Nest buttons or links freely inside; they handle their own events.'},+ {guidance: false, description: 'Use for toggling selection; use SelectableCard for that.'},],anatomy: [{name: 'Container', required: true, description: 'Interactive div with hover/focus/active states.'},@@ -21,7 +21,7 @@ export const docs = {},props: [{name: 'label', type: 'string', description: 'Accessibility label.', required: true},- {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler — fires on card surface only.'},+ {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler: fires on card surface only.'},{name: 'href', type: 'string', description: 'Navigation URL.'},{name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},{name: 'isDisabled', type: 'boolean', description: 'Disables the card.', default: 'false'},@@ -31,7 +31,7 @@ export const docs = {{name: 'width', type: 'SizeValue', description: 'Card width.'},{name: 'height', type: 'SizeValue', description: 'Card height.'},{name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},- {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={{}}.'},+ {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={{}}.'},],theming: {container: true,@@ -46,13 +46,13 @@ export const docsDense = {description: 'Interactive card for navigation/action targets. Nested interactive elements work independently.',bestPractices: [{guidance: true, description: 'Use for cards navigating to detail page or triggering single action.'},- {guidance: true, description: 'Nest buttons/links freely inside — they handle own events.'},- {guidance: false, description: 'Use for toggling selection — use SelectableCard instead.'},+ {guidance: true, description: 'Nest buttons/links freely inside; they handle own events.'},+ {guidance: false, description: 'Use for toggling selection; use SelectableCard instead.'},],},propDescriptions: {label: 'accessibility label **(required)**',- onClick: 'click handler — fires on card surface only',+ onClick: 'click handler: fires on card surface only',href: 'navigation URL',target: 'link target',isDisabled: 'disables card',diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjsindex b6c97b3639..faa57301a9 100644--- a/packages/core/src/Collapsible/Collapsible.doc.mjs+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs@@ -24,7 +24,7 @@ export const docs = {name: 'XDSCollapsible',displayName: 'Collapsible',description:- 'A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',+ 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',props: [{name: 'trigger',@@ -106,10 +106,10 @@ export const docs = {{ guidance: true, description: 'Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.' },{ guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },{ guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },- { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view — don\'t make users click to see essential info.' },- { guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },- { guidance: false, description: 'Nest collapsibles more than two levels deep — it makes content hard to find and navigate.' },- { guidance: false, description: 'Use a collapsible for a single short paragraph — just show the text directly instead.' },+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },+ { guidance: false, description: 'Hide critical or required content behind a collapsible; users may not discover it.' },+ { guidance: false, description: 'Nest collapsibles more than two levels deep; it makes content hard to find and navigate.' },+ { guidance: false, description: 'Use a collapsible for a single short paragraph; just show the text directly instead.' },],anatomy: [{ name: 'Trigger', required: true, description: 'The always-visible button that toggles the content. Shows a label and a chevron indicator.' },@@ -130,10 +130,10 @@ export const docsZh = {{ guidance: true, description: 'Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.' },{ guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },{ guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },- { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view — don\'t make users click to see essential info.' },- { guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },- { guidance: false, description: 'Nest collapsibles more than two levels deep — it makes content hard to find and navigate.' },- { guidance: false, description: 'Use a collapsible for a single short paragraph — just show the text directly instead.' },+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },+ { guidance: false, description: 'Hide critical or required content behind a collapsible; users may not discover it.' },+ { guidance: false, description: 'Nest collapsibles more than two levels deep; it makes content hard to find and navigate.' },+ { guidance: false, description: 'Use a collapsible for a single short paragraph; just show the text directly instead.' },],},theming: {@@ -183,9 +183,9 @@ export const docsDense = {{ guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },{ guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },{ guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },- { guidance: false, description: 'Hide critical content behind a collapsible — users may not discover it.' },- { guidance: false, description: 'Nest collapsibles more than two levels deep — makes content hard to find and navigate.' },- { guidance: false, description: 'Use a collapsible for a single short paragraph — just show the text directly instead.' },+ { guidance: false, description: 'Hide critical content behind a collapsible; users may not discover it.' },+ { guidance: false, description: 'Nest collapsibles more than two levels deep; makes content hard to find and navigate.' },+ { guidance: false, description: 'Use a collapsible for a single short paragraph; just show the text directly instead.' },],},components: [diff --git a/packages/core/src/Collapsible/useXDSCollapsible.doc.mjs b/packages/core/src/Collapsible/useXDSCollapsible.doc.mjsindex 9a45695503..a63e38318b 100644--- a/packages/core/src/Collapsible/useXDSCollapsible.doc.mjs+++ b/packages/core/src/Collapsible/useXDSCollapsible.doc.mjs@@ -40,7 +40,7 @@ export const docs = {bestPractices: [{guidance: true, description: 'Use the hook directly when building custom collapsible components that need XDS collapsible behavior without XDSCollapsible wrapper.'},{guidance: true, description: 'For accordion behavior, wrap items in XDSCollapsibleGroup and pass unique value props.'},- {guidance: false, description: 'Implement your own open/close state when useXDSCollapsible already provides it — the hook handles group coordination automatically.'},+ {guidance: false, description: 'Implement your own open/close state when useXDSCollapsible already provides it; the hook handles group coordination automatically.'},],},relatedComponents: ['Collapsible', 'Card', 'Section'],@@ -66,7 +66,7 @@ export const docsDense = {bestPractices: [{guidance: true, description: 'Use directly when building custom collapsible components needing XDS collapsible behavior w/o XDSCollapsible wrapper.'},{guidance: true, description: 'For accordion behavior, wrap items in XDSCollapsibleGroup + pass unique value props.'},- {guidance: false, description: 'Implement your own open/close state when useXDSCollapsible already provides it — hook handles group coordination automatically.'},+ {guidance: false, description: 'Implement your own open/close state when useXDSCollapsible already provides it; hook handles group coordination automatically.'},],},};diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjsindex 38744631e6..081fd18d19 100644--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs@@ -209,7 +209,7 @@ export const docs = {name: 'children',type: 'ReactNode',description:- 'Item content — render icons, descriptions, keyboard shortcuts, etc.',+ 'Item content: render icons, descriptions, keyboard shortcuts, etc.',required: true,},{@@ -321,8 +321,8 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },{ guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },- { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus — use XDSMenu or XDSSelector for inline selections.' },- { guidance: false, description: 'Add too many groups or items — curate results to keep the palette fast and scannable.' },+ { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use XDSMenu or XDSSelector for inline selections.' },+ { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },],},};@@ -334,8 +334,8 @@ export const docsZh = {bestPractices: [{ guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },{ guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },- { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus — use XDSMenu or XDSSelector for inline selections.' },- { guidance: false, description: 'Add too many groups or items — curate results to keep the palette fast and scannable.' },+ { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use XDSMenu or XDSSelector for inline selections.' },+ { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },],},components: [@@ -429,8 +429,8 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },{ guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },- { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus — use XDSMenu or XDSSelector for inline selections.' },- { guidance: false, description: 'Add too many groups or items — curate results to keep the palette fast and scannable.' },+ { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use XDSMenu or XDSSelector for inline selections.' },+ { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },],},components: [@@ -487,7 +487,7 @@ export const docsDense = {description: 'selectable item; arbitrary children; registers w/ context for kbd nav',propDescriptions: {value: 'unique id for selection',- children: 'item content — icons, descriptions, shortcuts',+ children: 'item content: icons, descriptions, shortcuts',onSelect: 'called on click or Enter',isHighlighted: 'keyboard focus; derived from context inside palette',isSelected: 'selected in picker mode',diff --git a/packages/core/src/ContextMenu/ContextMenu.doc.mjs b/packages/core/src/ContextMenu/ContextMenu.doc.mjsindex b721c6a904..a409ee660c 100644--- a/packages/core/src/ContextMenu/ContextMenu.doc.mjs+++ b/packages/core/src/ContextMenu/ContextMenu.doc.mjs@@ -32,7 +32,7 @@ export const docs = {name: 'children',type: 'ReactNode',description:- 'The trigger area — right-click on this content to open the menu.',+ 'The trigger area: right-click on this content to open the menu.',required: true,},{@@ -56,7 +56,7 @@ export const docs = {{name: 'size',type: "'sm' | 'md' | 'lg'",- description: 'Size of menu items — controls padding density.',+ description: 'Size of menu items: controls padding density.',default: "'md'",},{@@ -112,10 +112,10 @@ export const docs = {usage: {description: 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons.',bestPractices: [- { guidance: true, description: 'Keep menu items concise and action-oriented — users expect quick access to contextual actions.' },+ { guidance: true, description: 'Keep menu items concise and action-oriented; users expect quick access to contextual actions.' },{ guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },{ guidance: true, description: 'Ensure all context menu actions are also accessible via other UI elements for keyboard-only users.' },- { guidance: false, description: 'Use a ContextMenu as the only way to access important actions — not all users know to right-click.' },+ { guidance: false, description: 'Use a ContextMenu as the only way to access important actions; not all users know to right-click.' },{ guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },],},@@ -148,7 +148,7 @@ export const docsZh = {{name: 'children',type: 'ReactNode',- description: '触发区域 — 右键点击此内容以打开菜单。',+ description: '触发区域:右键点击此内容以打开菜单。',required: true,},{@@ -172,7 +172,7 @@ export const docsZh = {{name: 'size',type: "'sm' | 'md' | 'lg'",- description: '菜单项大小 — 控制内边距密度。',+ description: '菜单项大小:控制内边距密度。',default: "'md'",},{@@ -255,7 +255,7 @@ export const docsDense = {displayName: 'Context Menu',description: 'right-click trigger + fixed-position popup menu',propDescriptions: {- children: 'trigger area — right-click to open menu',+ children: 'trigger area: right-click to open menu',items: 'array of menu entries: action item {label, onClick?, icon?, isDisabled?}, divider {type: "divider"}, or section {type: "section", title?, items: [...]}',menuContent: 'custom JSX menu content (compound mode)',menuWidth: 'custom menu width',diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex 890a0bfe30..e0797aa073 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -122,7 +122,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: {@@ -139,7 +139,7 @@ export const docs = {{ guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },- { guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },+ { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },],anatomy: [{name: 'Label', required: true, description: 'Text above the input describing what date is expected.'},@@ -165,7 +165,7 @@ export const docsZh = {{ guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },- { guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },+ { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },],},props: [@@ -223,7 +223,7 @@ export const docsDense = {{ guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },- { guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },+ { guidance: false, description: 'Rely on the calendar alone; the text input lets users type dates directly, which is faster for known dates.' },],},propDescriptions: {diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjsindex 3099e7abad..138a1143d5 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs@@ -43,7 +43,7 @@ export const docs = {{ guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },{ guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },{ guidance: true, description: 'Provide clear labels and descriptions so users understand what the range controls.' },- { guidance: false, description: 'Use DateRangeInput when only a single date is needed — use DateInput instead.' },+ { guidance: false, description: 'Use DateRangeInput when only a single date is needed; use DateInput instead.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },],anatomy: [@@ -68,7 +68,7 @@ export const docsDense = {{ guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },{ guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },{ guidance: true, description: 'Provide clear labels + descriptions so users understand what the range controls.' },- { guidance: false, description: 'Use DateRangeInput when only a single date is needed — use DateInput instead.' },+ { guidance: false, description: 'Use DateRangeInput when only a single date is needed; use DateInput instead.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },],},diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjsindex dbef413ea9..55cba0674b 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs@@ -137,7 +137,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: {@@ -152,8 +152,8 @@ export const docs = {{ guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },{ guidance: true, description: 'Use hasClear when the datetime is optional so the user can easily reset it.' },{ guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience’s locale.' },- { guidance: false, description: 'Use DateTimeInput when only a date is needed — use DateInput instead.' },- { guidance: false, description: 'Use DateTimeInput when only a time is needed — use TimeInput instead.' },+ { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },+ { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },],anatomy: [@@ -179,8 +179,8 @@ export const docsZh = {{ guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },{ guidance: true, description: 'Use hasClear when the datetime is optional so the user can easily reset it.' },{ guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience’s locale.' },- { guidance: false, description: 'Use DateTimeInput when only a date is needed — use DateInput instead.' },- { guidance: false, description: 'Use DateTimeInput when only a time is needed — use TimeInput instead.' },+ { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },+ { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },],},@@ -226,8 +226,8 @@ export const docsDense = {{ guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },{ guidance: true, description: 'Use hasClear when the datetime is optional so the user can easily reset it.' },{ guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale.' },- { guidance: false, description: 'Use DateTimeInput when only a date is needed — use DateInput instead.' },- { guidance: false, description: 'Use DateTimeInput when only a time is needed — use TimeInput instead.' },+ { guidance: false, description: 'Use DateTimeInput when only a date is needed; use DateInput instead.' },+ { guidance: false, description: 'Use DateTimeInput when only a time is needed; use TimeInput instead.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },],},diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex 713bce237b..ac6cbd9cb3 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -81,7 +81,7 @@ export const docs = {name: 'variant',type: "'standard' | 'fullscreen'",description:- 'Dialog variant — fullscreen expands to fill the entire viewport.',+ 'Dialog variant: fullscreen expands to fill the entire viewport.',default: "'standard'",},{@@ -158,24 +158,24 @@ export const docs = {{name: 'show', type: '(content: ReactNode, options?: DialogOptions) => void', description: 'Show the dialog with the given content. Options override or extend defaultOptions for this show call.'},{name: 'hide', type: '() => void', description: 'Hide the dialog.'},{name: 'isOpen', type: 'boolean', description: 'Whether the dialog is currently open.'},- {name: 'element', type: 'ReactNode', description: 'The dialog element — render this in your JSX tree.'},+ {name: 'element', type: 'ReactNode', description: 'The dialog element: render this in your JSX tree.'},],},],usage: {- description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useXDSImperativeDialog` hook — call `dialog.show(content)` and render `dialog.element` in your tree.',+ description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useXDSImperativeDialog` hook: call `dialog.show(content)` and render `dialog.element` in your tree.',bestPractices: [{ guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },{ guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },{ guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },- { guidance: true, description: 'Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead.' },+ { guidance: true, description: 'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.' },{ guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },- { guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },- { guidance: false, description: 'Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms.' },+ { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },+ { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },],anatomy: [{name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},- {name: 'Body', required: true, description: 'The main content area — text, forms, lists, or any layout.'},+ {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},{name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},{name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},],@@ -307,14 +307,14 @@ export const docsZh = {{ guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.' },{ guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },{ guidance: true, description: 'Use purpose="form" for dialogs with inputs so the user can\'t accidentally lose data by clicking the backdrop.' },- { guidance: true, description: 'Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead.' },+ { guidance: true, description: 'Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.' },{ guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },- { guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },- { guidance: false, description: 'Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms.' },+ { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },+ { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.' },],anatomy: [{name: 'Header', required: true, description: 'Title, optional subtitle, and close button. The title receives focus on open for accessibility.'},- {name: 'Body', required: true, description: 'The main content area — text, forms, lists, or any layout.'},+ {name: 'Body', required: true, description: 'The main content area: text, forms, lists, or any layout.'},{name: 'Footer', required: false, description: 'Action buttons like Save/Cancel or Accept/Decline, aligned to the end.'},{name: 'Backdrop', required: true, description: 'Semi-transparent overlay behind the dialog that blocks page interaction.'},],@@ -330,10 +330,10 @@ export const docsDense = {{ guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when user must respond.' },{ guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },{ guidance: true, description: 'Use purpose="form" for dialogs with inputs so user can\'t accidentally lose data by clicking the backdrop.' },- { guidance: true, description: 'Keep dialogs focused on a single task — if content grows beyond what fits, consider a full page instead.' },+ { guidance: true, description: 'Keep dialogs focused on a single task; if content grows beyond what fits, consider a full page instead.' },{ guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },- { guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },- { guidance: false, description: 'Use the fullscreen variant for simple confirmations — it\'s meant for complex content like editors or long forms.' },+ { guidance: false, description: 'Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.' },+ { guidance: false, description: 'Use the fullscreen variant for simple confirmations; it\'s meant for complex content like editors or long forms.' },],},components: [@@ -374,7 +374,7 @@ export const docsDense = {show: 'show the dialog with given content; options = XDSDialog props minus isOpen/onOpenChange/children',hide: 'hide the dialog',isOpen: 'whether the dialog is currently open',- element: 'the dialog element — render this in your JSX tree',+ element: 'the dialog element: render this in your JSX tree',},},],diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjsindex 71432b0acb..967ad40d03 100644--- a/packages/core/src/Divider/Divider.doc.mjs+++ b/packages/core/src/Divider/Divider.doc.mjs@@ -38,7 +38,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: {@@ -51,7 +51,7 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },{ guidance: true, description: 'Add a label to the divider when sections need a visible category heading.' },- { guidance: false, description: 'Overuse dividers — rely on spacing and layout to separate content when possible.' },+ { guidance: false, description: 'Overuse dividers; rely on spacing and layout to separate content when possible.' },],},};@@ -88,7 +88,7 @@ export const docsZh = {name: 'xstyle',type: 'StyleXStyles',description:- '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是 style={{}} 这样的内联样式对象。',+ '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,不能是 style={{}} 这样的内联样式对象。',},],theming: {@@ -101,7 +101,7 @@ export const docsZh = {bestPractices: [{ guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },{ guidance: true, description: 'Add a label to the divider when sections need a visible category heading.' },- { guidance: false, description: 'Overuse dividers — rely on spacing and layout to separate content when possible.' },+ { guidance: false, description: 'Overuse dividers; rely on spacing and layout to separate content when possible.' },],},};@@ -114,7 +114,7 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },{ guidance: true, description: 'Add a label to the divider when sections need a visible category heading.' },- { guidance: false, description: 'Overuse dividers — rely on spacing and layout to separate content when possible.' },+ { guidance: false, description: 'Overuse dividers; rely on spacing and layout to separate content when possible.' },],},propDescriptions: {diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex 9514e82831..e997e67607 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -120,7 +120,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={{}}.',+ description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',},],},@@ -130,7 +130,7 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Keep menu items concise and action-oriented so users can scan options quickly.' },{ guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },- { guidance: false, description: 'Use a DropdownMenu for navigation — use a navigation component instead.' },+ { guidance: false, description: 'Use a DropdownMenu for navigation; use a navigation component instead.' },{ guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },],},@@ -263,7 +263,7 @@ export const docsZh = {bestPractices: [{ guidance: true, description: 'Keep menu items concise and action-oriented so users can scan options quickly.' },{ guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },- { guidance: false, description: 'Use a DropdownMenu for navigation — use a navigation component instead.' },+ { guidance: false, description: 'Use a DropdownMenu for navigation; use a navigation component instead.' },{ guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },],},@@ -277,7 +277,7 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Keep menu items concise and action-oriented so users can scan options quickly.' },{ guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },- { guidance: false, description: 'Use a DropdownMenu for navigation — use a navigation component instead.' },+ { guidance: false, description: 'Use a DropdownMenu for navigation; use a navigation component instead.' },{ guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },],},diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjsindex e205689500..d4235340b3 100644--- a/packages/core/src/EmptyState/EmptyState.doc.mjs+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs@@ -53,7 +53,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={{}}.',},],playground: {@@ -74,13 +74,13 @@ export const docs = {{ guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },{ guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },{ guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },- { guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },- { guidance: false, description: 'Use a generic message like "No data" — be specific about what is empty and why.' },- { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use a Banner instead.' },+ { guidance: false, description: 'Leave an empty state without guidance; always explain what happened and what the user can do next.' },+ { guidance: false, description: 'Use a generic message like "No data"; be specific about what is empty and why.' },+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },],anatomy: [{name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},- {name: 'Title', required: true, description: 'Primary message explaining what is empty — "No projects yet" not "No data".'},+ {name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},{name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},{name: 'Actions', required: false, description: 'One or two buttons guiding the user to a next step, like "Create project" or "Clear filters".'},],@@ -149,9 +149,9 @@ export const docsZh = {{ guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },{ guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },{ guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },- { guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },- { guidance: false, description: 'Use a generic message like "No data" — be specific about what is empty and why.' },- { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use a Banner instead.' },+ { guidance: false, description: 'Leave an empty state without guidance; always explain what happened and what the user can do next.' },+ { guidance: false, description: 'Use a generic message like "No data"; be specific about what is empty and why.' },+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },],},};@@ -159,16 +159,16 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {description:- 'placeholder when a content area has no data — icon, title, description, action buttons',+ 'placeholder when a content area has no data: icon, title, description, action buttons',usage: {description: 'EmptyState shows a placeholder for empty lists, zero search results, first-time setups. Always include a title and next step.',bestPractices: [{ guidance: true, description: 'Include a clear title + call-to-action button so users know how to proceed.' },{ guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },{ guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },- { guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what user can do next.' },- { guidance: false, description: 'Use a generic message like "No data" — be specific about what is empty and why.' },- { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use a Banner instead.' },+ { guidance: false, description: 'Leave an empty state without guidance; always explain what happened and what user can do next.' },+ { guidance: false, description: 'Use a generic message like "No data"; be specific about what is empty and why.' },+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },],},propDescriptions: {diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjsindex 294f0e7208..15bcc768cb 100644--- a/packages/core/src/Field/Field.doc.mjs+++ b/packages/core/src/Field/Field.doc.mjs@@ -126,7 +126,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={{}}.',},{name: 'className',@@ -225,7 +225,7 @@ export const docs = {name: 'variant',type: "'attached' | 'detached'",description:- 'Visual variant — attached overlaps the input, detached floats below.',+ 'Visual variant: attached overlaps the input, detached floats below.',default: "'attached'",},],@@ -238,13 +238,13 @@ export const docs = {{ guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },{ guidance: true, description: 'Add a description when the label alone does not explain what the field expects, like format hints or constraints.' },{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },- { guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },+ { guidance: false, description: 'Use the detached status variant on bordered inputs; reserve it for checkboxes, switches, and sliders.' },{ guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },],anatomy: [{name: 'Label', required: true, description: 'Text identifying the field. Always rendered for accessibility, optionally hidden visually.'},{name: 'Description', required: false, description: 'Helper text between the label and input explaining what to enter.'},- {name: 'Input slot', required: true, description: 'The input control wrapped by the field — TextInput, Select, DateInput, etc.'},+ {name: 'Input slot', required: true, description: 'The input control wrapped by the field: TextInput, Select, DateInput, etc.'},{name: 'Status message', required: false, description: 'Inline validation feedback showing error, warning, or success with a message.'},{name: 'Optional/Required indicator', required: false, description: 'Badge next to the label showing whether the field is optional or required.'},{name: 'Label tooltip', required: false, description: 'Info icon at the end of the label with a tooltip explaining the field.'},@@ -481,7 +481,7 @@ export const docsZh = {{ guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },{ guidance: true, description: 'Add a description when the label alone does not explain what the field expects, like format hints or constraints.' },{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },- { guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },+ { guidance: false, description: 'Use the detached status variant on bordered inputs; reserve it for checkboxes, switches, and sliders.' },{ guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },],},@@ -496,9 +496,9 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },{ guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },- { guidance: true, description: 'Add a description when the label alone does not explain what the field expects — format hints or constraints.' },+ { guidance: true, description: 'Add a description when the label alone does not explain what the field expects: format hints or constraints.' },{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },- { guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },+ { guidance: false, description: 'Use the detached status variant on bordered inputs; reserve it for checkboxes, switches, and sliders.' },{ guidance: false, description: 'Hide the label without providing an alternative way for user to understand the field purpose.' },],},diff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjsindex fe443a8559..8c4d6b72cb 100644--- a/packages/core/src/FileInput/FileInput.doc.mjs+++ b/packages/core/src/FileInput/FileInput.doc.mjs@@ -111,7 +111,7 @@ export const docs = {name: 'status',type: "{type: 'error' | 'warning' | 'success', message?: string}",description:- 'Validation status — applies a colored border. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',+ 'Validation status: applies a colored border. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',},{name: 'labelTooltip',@@ -130,11 +130,11 @@ export const docs = {'FileInput provides file upload with optional drag-and-drop support. Use it for single or multiple file selection with built-in validation for file type, size, and count. Pair with validation status for upload feedback.',bestPractices: [{guidance: true, description: 'Always specify an accept prop to guide users toward valid file types.'},- {guidance: true, description: 'Use maxSize and maxFiles to prevent oversized uploads — the component handles validation and error display automatically.'},+ {guidance: true, description: 'Use maxSize and maxFiles to prevent oversized uploads; the component handles validation and error display automatically.'},{guidance: true, description: 'Add a description to communicate constraints like file size limits or accepted formats.'},{guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},- {guidance: false, description: "Don't use FileInput for directory or folder uploads — that is not supported in v1."},- {guidance: false, description: "Don't avoid dropzone mode unless space is very constrained — drag-and-drop is the expected interaction for file uploads."},+ {guidance: false, description: "Don't use FileInput for directory or folder uploads; that is not supported in v1."},+ {guidance: false, description: "Don't avoid dropzone mode unless space is very constrained; drag-and-drop is the expected interaction for file uploads."},],anatomy: [{name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},@@ -247,7 +247,7 @@ export const docsZh = {{guidance: true, description: 'Use maxSize and maxFiles to prevent oversized uploads.'},{guidance: true, description: 'Add a description to communicate constraints.'},{guidance: false, description: "Don't use FileInput for directory uploads."},- {guidance: false, description: "Don't use mode='input' unless space is very constrained — dropzone mode provides a better experience."},+ {guidance: false, description: "Don't use mode='input' unless space is very constrained; dropzone mode provides a better experience."},],anatomy: [{name: 'Label', required: true, description: 'Text identifying the field.'},@@ -271,7 +271,7 @@ export const docsDense = {{guidance: true, description: 'Add a description to communicate constraints.'},{guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},{guidance: false, description: "Don't use FileInput for directory uploads."},- {guidance: false, description: "Don't use mode='input' unless space is very constrained — dropzone mode provides a better experience."},+ {guidance: false, description: "Don't use mode='input' unless space is very constrained; dropzone mode provides a better experience."},],anatomy: [{name: 'Label', required: true, description: 'Text identifying the field.'},diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjsindex ed7ff7794d..aaaf4cafb3 100644--- a/packages/core/src/Grid/Grid.doc.mjs+++ b/packages/core/src/Grid/Grid.doc.mjs@@ -12,11 +12,11 @@ export const docs = {description:'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',bestPractices: [- { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size — `columns={{minWidth: 280}}`.' },+ { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: `columns={{minWidth: 280}}`.' },{ guidance: true, description: 'Cap the column count with `max` to prevent rows from getting too wide on large screens.' },{ guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },- { guidance: false, description: 'Write manual CSS grid — Grid handles spacing and responsive behavior for you.' },- { guidance: false, description: 'Use `XDSHStack` with wrapping for grids — use Grid instead.' },+ { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },+ { guidance: false, description: 'Use `XDSHStack` with wrapping for grids; use Grid instead.' },],},theming: {@@ -41,7 +41,7 @@ export const docs = {name: 'minChildWidth',type: 'number',description:- 'Deprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',+ 'Deprecated; use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',},{name: 'width',@@ -89,7 +89,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={{}}.',},],},@@ -145,7 +145,7 @@ export const docsZh = {{name: 'minChildWidth',type: 'number',- description: '已弃用 — 请使用 `columns={{minWidth: 280}}` 代替。',+ description: '已弃用,请使用 `columns={{minWidth: 280}}` 代替。',},{name: 'width',@@ -225,11 +225,11 @@ export const docsZh = {description:'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',bestPractices: [- { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size — `columns={{minWidth: 280}}`.' },+ { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: `columns={{minWidth: 280}}`.' },{ guidance: true, description: 'Cap the column count with `max` to prevent rows from getting too wide on large screens.' },{ guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },- { guidance: false, description: 'Write manual CSS grid — Grid handles spacing and responsive behavior for you.' },- { guidance: false, description: 'Use `XDSHStack` with wrapping for grids — use Grid instead.' },+ { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },+ { guidance: false, description: 'Use `XDSHStack` with wrapping for grids; use Grid instead.' },],},};@@ -240,11 +240,11 @@ export const docsDense = {usage: {description: 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',bestPractices: [- { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size — columns={{minWidth: 280}}.' },+ { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: columns={{minWidth: 280}}.' },{ guidance: true, description: 'Cap the column count with max to prevent rows from getting too wide on large screens.' },{ guidance: true, description: 'Use repeat: \'fill\' (the default) for consistent item widths. Use \'fit\' when items should stretch to fill leftover space.' },- { guidance: false, description: 'Write manual CSS grid — Grid handles spacing and responsive behavior for you.' },- { guidance: false, description: 'Use XDSHStack with wrapping for grids — use Grid instead.' },+ { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },+ { guidance: false, description: 'Use XDSHStack with wrapping for grids; use Grid instead.' },],},@@ -256,7 +256,7 @@ export const docsDense = {description: 'Grid container w/ fixed or responsive columns.',propDescriptions: {columns: "Column config. Number for fixed cols. Object {minWidth, max?, repeat?} for responsive. repeat: 'fill' (default, consistent widths) or 'fit' (stretch).",- minChildWidth: 'Deprecated — use columns={{minWidth}} instead.',+ minChildWidth: 'Deprecated; use columns={{minWidth}} instead.',width: 'Container width.',height: 'Container height.',gap: 'Spacing between all items.',diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex 28e00e7b09..fcff3e2e6c 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -30,7 +30,7 @@ export const docs = {name: 'XDSHoverCard',displayName: 'Hover Card',description:- 'Component wrapper for hover card display — a richer, larger overlay triggered on hover or focus.', props: [+ 'Component wrapper for hover card display: a richer, larger overlay triggered on hover or focus.', props: [{name: 'children',type: 'ReactNode',@@ -102,17 +102,17 @@ export const docs = {usage: {description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',bestPractices: [- { guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },+ { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },{ guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },+ { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },+ { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },],anatomy: [- {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus — a button, link, or inline text.'},+ {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},{name: 'Card', required: true, description: 'The floating overlay with the preview content, anchored to the trigger.'},- {name: 'Body', required: true, description: 'The main content area — profile info, link summary, or any rich content.'},+ {name: 'Body', required: true, description: 'The main content area: profile info, link summary, or any rich content.'},{name: 'Actions', required: false, description: 'Optional buttons inside the card for follow-up actions like Follow or Message.'},],},@@ -210,12 +210,12 @@ export const docsZh = {usage: {description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',bestPractices: [- { guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },+ { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },{ guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },+ { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },+ { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },],},};@@ -227,12 +227,12 @@ export const docsDense = {usage: {description: 'HoverCard shows additional info on hover/focus. Use for profile cards, link summaries, inline definitions.',bestPractices: [- { guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },+ { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },{ guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },+ { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },+ { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },],},components: [diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjsindex aab0baebe4..6051d30fdf 100644--- a/packages/core/src/Icon/Icon.doc.mjs+++ b/packages/core/src/Icon/Icon.doc.mjs@@ -35,14 +35,14 @@ export const docs = {usage: {description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',bestPractices: [- { guidance: true, description: 'Use semantic icon names when available — they adapt to theme changes automatically.' },- { guidance: true, description: 'Pair icons with text labels for accessibility — icon-only elements need an accessible label.' },+ { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },+ { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },{ guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },- { guidance: true, description: 'Be mindful of context — decorative icons in compact components can distract rather than help.' },- { guidance: false, description: 'Use icons as the sole means of conveying meaning — always provide a text alternative.' },- { guidance: false, description: 'Resize icons with arbitrary pixel values — use the provided size props.' },+ { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },+ { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },+ { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },{ guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },- { guidance: false, description: 'Render raw SVG elements — always wrap in Icon for consistent sizing and color.' },+ { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },],},};@@ -79,14 +79,14 @@ export const docsZh = {usage: {description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',bestPractices: [- { guidance: true, description: 'Use semantic icon names when available — they adapt to theme changes automatically.' },- { guidance: true, description: 'Pair icons with text labels for accessibility — icon-only elements need an accessible label.' },+ { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },+ { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },{ guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },- { guidance: true, description: 'Be mindful of context — decorative icons in compact components can distract rather than help.' },- { guidance: false, description: 'Use icons as the sole means of conveying meaning — always provide a text alternative.' },- { guidance: false, description: 'Resize icons with arbitrary pixel values — use the provided size props.' },+ { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },+ { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },+ { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },{ guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },- { guidance: false, description: 'Render raw SVG elements — always wrap in Icon for consistent sizing and color.' },+ { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },],},};@@ -98,14 +98,14 @@ export const docsDense = {usage: {description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',bestPractices: [- { guidance: true, description: 'Use semantic icon names when available — they adapt to theme changes automatically.' },- { guidance: true, description: 'Pair icons with text labels for accessibility — icon-only elements need an accessible label.' },+ { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },+ { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },{ guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },- { guidance: true, description: 'Be mindful of context — decorative icons in compact components can distract rather than help.' },- { guidance: false, description: 'Use icons as the sole means of conveying meaning — always provide a text alternative.' },- { guidance: false, description: 'Resize icons with arbitrary pixel values — use the provided size props.' },+ { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },+ { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },+ { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },{ guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },- { guidance: false, description: 'Render raw SVG elements — always wrap in Icon for consistent sizing and color.' },+ { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },],},propDescriptions: {diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjsindex 2ca0552213..165d1d4423 100644--- a/packages/core/src/IconButton/IconButton.doc.mjs+++ b/packages/core/src/IconButton/IconButton.doc.mjs@@ -68,11 +68,11 @@ export const docs = {usage: {description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',bestPractices: [- { guidance: true, description: 'Make the aria-label specific — a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },- { guidance: true, description: 'Add a tooltip — even a gear icon can mean Settings, Preferences, or Configure.' },+ { guidance: true, description: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },+ { guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },{ guidance: true, description: 'Use ghost in toolbars and dense areas to reduce visual clutter.' },- { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone — use Button with text.' },- { guidance: false, description: 'Skip the tooltip — label only reaches screen readers, sighted users need the hover hint.' },+ { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone; use Button with text.' },+ { guidance: false, description: 'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.' },],},};@@ -83,11 +83,11 @@ export const docsDense = {usage: {description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',bestPractices: [- { guidance: true, description: 'Make aria-label specific — trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },- { guidance: true, description: 'Add tooltip — even gear icon can mean Settings/Preferences/Configure.' },+ { guidance: true, description: 'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },+ { guidance: true, description: 'Add tooltip: even gear icon can mean Settings/Preferences/Configure.' },{ guidance: true, description: 'Use ghost in toolbars + dense areas to reduce visual clutter.' },- { guidance: false, description: "Use IconButton if action isn't obvious from icon alone — use Button w/ text instead." },- { guidance: false, description: 'Skip tooltip — label only reaches screen readers; sighted users need hover hint.' },+ { guidance: false, description: "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead." },+ { guidance: false, description: 'Skip tooltip: label only reaches screen readers; sighted users need hover hint.' },],},propDescriptions: {diff --git a/packages/core/src/InputGroup/InputGroup.doc.mjs b/packages/core/src/InputGroup/InputGroup.doc.mjsindex 09fb5dd9ce..4d27d18ec7 100644--- a/packages/core/src/InputGroup/InputGroup.doc.mjs+++ b/packages/core/src/InputGroup/InputGroup.doc.mjs@@ -53,8 +53,8 @@ export const docs = {{guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify the input format (e.g., "$", "kg", "https://").'},{guidance: true, description: 'Use XDSInputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},{guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},- {guidance: false, description: 'Don\'t put multiple text inputs in one group — use separate fields instead.'},- {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs — it\'s for a single input with decorations.'},+ {guidance: false, description: 'Don\'t put multiple text inputs in one group; use separate fields instead.'},+ {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},],anatomy: [{name: 'Label', required: true, description: 'Text above the group.'},@@ -75,8 +75,8 @@ export const docsDense = {{guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify input format (e.g. "$", "kg", "https://").'},{guidance: true, description: 'Use XDSInputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},{guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},- {guidance: false, description: 'Don\'t put multiple text inputs in one group — use separate fields instead.'},- {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs — it\'s for a single input with decorations.'},+ {guidance: false, description: 'Don\'t put multiple text inputs in one group; use separate fields instead.'},+ {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},],},components: [diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjsindex 4395526e36..3c7364bf53 100644--- a/packages/core/src/Item/Item.doc.mjs+++ b/packages/core/src/Item/Item.doc.mjs@@ -51,21 +51,21 @@ export const docs = {],usage: {description:- 'A single, flexible item primitive that unifies the "media + label + description + trailing content" pattern across XDS. Use it wherever you need a structured row — dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',+ 'A single, flexible item primitive that unifies the "media + label + description + trailing content" pattern across XDS. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',bestPractices: [{guidance: true, description: 'Use named slots (media, label, description, trailing) for the common layout. These cover the 80% case.'},{guidance: true, description: 'Use density="compact" for menus and dense lists, "default" for standalone items and spacious layouts.'},{guidance: true, description: 'Set labelLines and descriptionLines to control truncation when content length varies.'},{guidance: true, description: 'Use align="start" when media or trailing content is taller than a single line of text.'},- {guidance: false, description: "Don't nest interactive elements (buttons, links) inside an interactive XDSItem — it creates confusing focus and click targets."},- {guidance: false, description: "Don't use XDSItem for navigation between views — use proper navigation components instead."},- {guidance: false, description: "Don't add read/unread or inbox-specific behavior directly — compose a thin wrapper like XDSPreviewItem instead."},+ {guidance: false, description: "Don't nest interactive elements (buttons, links) inside an interactive XDSItem; it creates confusing focus and click targets."},+ {guidance: false, description: "Don't use XDSItem for navigation between views; use proper navigation components instead."},+ {guidance: false, description: "Don't add read/unread or inbox-specific behavior directly; compose a thin wrapper like XDSPreviewItem instead."},],anatomy: [- {name: 'Media', required: false, description: 'Leading visual — avatar, icon, image, or status indicator.'},+ {name: 'Media', required: false, description: 'Leading visual: avatar, icon, image, or status indicator.'},{name: 'Label', required: true, description: 'Primary text identifying the item.'},{name: 'Description', required: false, description: 'Secondary supporting text below the label.'},- {name: 'Trailing', required: false, description: 'End-aligned content — badges, timestamps, or action buttons.'},+ {name: 'Trailing', required: false, description: 'End-aligned content: badges, timestamps, or action buttons.'},],},};@@ -79,9 +79,9 @@ export const docsZh = {description: '通用项目原语,统一 "媒体 + 标签 + 描述 + 尾部内容" 布局模式。用作列表项、菜单项、联系人行、通知等的构建块。',propDescriptions: {label: '标识此项目的主要文本。接受字符串(自动截断)或 ReactNode(用于富内容)。',- media: '前导视觉 — 头像、图标、图片或任何 ReactNode。',- description: '次要文本 — 副标题、描述或辅助信息。',- trailing: '尾部内容 — 徽章、元数据、时间戳、操作按钮。定位在末端。',+ media: '前导视觉:头像、图标、图片或任何 ReactNode。',+ description: '次要文本:副标题、描述或辅助信息。',+ trailing: '尾部内容:徽章、元数据、时间戳、操作按钮。定位在末端。',as: '根元素的 HTML 元素。',startAdornment: '在媒体插槽之前渲染的内容,作为直接 flex 子元素,无包装元素。',align: '媒体和尾部插槽的垂直对齐方式。',@@ -110,14 +110,14 @@ export const docsZh = {{guidance: true, description: '设置 labelLines 和 descriptionLines 控制内容长度不定时的截断。'},{guidance: true, description: '当媒体或尾部内容高于单行文本时使用 align="start"。'},{guidance: false, description: '不要在交互式 XDSItem 内嵌套交互元素(按钮、链接)。'},- {guidance: false, description: '不要使用 XDSItem 进行视图间导航 — 使用适当的导航组件。'},- {guidance: false, description: '不要直接添加已读/未读行为 — 组合一个薄包装器如 XDSPreviewItem。'},+ {guidance: false, description: '不要使用 XDSItem 进行视图间导航:使用适当的导航组件。'},+ {guidance: false, description: '不要直接添加已读/未读行为:组合一个薄包装器如 XDSPreviewItem。'},],anatomy: [- {name: '媒体', required: false, description: '前导视觉 — 头像、图标、图片或状态指示器。'},+ {name: '媒体', required: false, description: '前导视觉:头像、图标、图片或状态指示器。'},{name: '标签', required: true, description: '标识项目的主要文本。'},{name: '描述', required: false, description: '标签下方的次要辅助文本。'},- {name: '尾部', required: false, description: '末端对齐内容 — 徽章、时间戳或操作按钮。'},+ {name: '尾部', required: false, description: '末端对齐内容:徽章、时间戳或操作按钮。'},],},};@@ -134,8 +134,8 @@ export const docsDense = {{guidance: true, description: 'labelLines/descriptionLines for truncation control.'},{guidance: true, description: 'align="start" when media/trailing is taller than one text line.'},{guidance: false, description: "Don't nest interactive elements inside interactive XDSItem."},- {guidance: false, description: "Don't use for view navigation — use nav components."},- {guidance: false, description: "Don't add inbox-specific behavior — compose a wrapper."},+ {guidance: false, description: "Don't use for view navigation; use nav components."},+ {guidance: false, description: "Don't add inbox-specific behavior; compose a wrapper."},],},components: [@@ -145,9 +145,9 @@ export const docsDense = {description: 'universal item primitive w/ media+label+description+trailing layout',propDescriptions: {label: 'Primary text. String auto-truncates; ReactNode for rich content.',- media: 'Leading visual — avatar, icon, image, ReactNode.',+ media: 'Leading visual: avatar, icon, image, ReactNode.',description: 'Secondary text below label.',- trailing: 'End-aligned content — badges, timestamps, actions.',+ trailing: 'End-aligned content: badges, timestamps, actions.',as: 'Root HTML element.',startAdornment: 'Content before media slot as direct flex child, no wrapper.',align: 'Vertical alignment of media/trailing slots.',diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsindex d66425b77e..c886d4d3a9 100644--- a/packages/core/src/Layout/Layout.doc.mjs+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -12,7 +12,7 @@ export const docs = {defaults: {header: {__element: 'XDSLayoutHeader', props: {}, children: {__element: 'XDSHeading', props: {level: 3}, children: 'Page Title'}},content: {__element: 'XDSLayoutContent', props: {}, children: {__element: 'XDSText', props: {type: 'body', color: 'secondary'}, children: 'Main content area. This is the scrollable center section of the layout.'}},- footer: {__element: 'XDSLayoutFooter', props: {}, children: {__element: 'XDSText', props: {type: 'supporting', color: 'secondary'}, children: 'Footer — status bar or actions'}},+ footer: {__element: 'XDSLayoutFooter', props: {}, children: {__element: 'XDSText', props: {type: 'supporting', color: 'secondary'}, children: 'Footer: status bar or actions'}},},},theming: {@@ -65,7 +65,7 @@ export const docs = {name: 'height',type: "'fill' | 'auto'",description:- 'Height behavior — fill the container or grow with content.',+ 'Height behavior: fill the container or grow with content.',default: "'fill'",},], },@@ -244,8 +244,8 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },{ guidance: true, description: 'Use XDSHStack and XDSVStack for simple directional stacking within a content area.' },- { guidance: false, description: 'Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead.' },- { guidance: false, description: 'Nest multiple XDSLayout components — use one per page shell and compose content within its slots.' },+ { guidance: false, description: 'Use XDSLayout for simple stacking layouts; use XDSHStack or XDSVStack instead.' },+ { guidance: false, description: 'Nest multiple XDSLayout components; use one per page shell and compose content within its slots.' },],},};@@ -479,8 +479,8 @@ export const docsZh = {bestPractices: [{ guidance: true, description: 'Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },{ guidance: true, description: 'Use XDSHStack and XDSVStack for simple directional stacking within a content area.' },- { guidance: false, description: 'Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead.' },- { guidance: false, description: 'Nest multiple XDSLayout components — use one per page shell and compose content within its slots.' },+ { guidance: false, description: 'Use XDSLayout for simple stacking layouts; use XDSHStack or XDSVStack instead.' },+ { guidance: false, description: 'Nest multiple XDSLayout components; use one per page shell and compose content within its slots.' },],},};@@ -495,8 +495,8 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },{ guidance: true, description: 'Use XDSHStack and XDSVStack for simple directional stacking within a content area.' },- { guidance: false, description: 'Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead.' },- { guidance: false, description: 'Nest multiple XDSLayout components — use one per page shell and compose content within its slots.' },+ { guidance: false, description: 'Use XDSLayout for simple stacking layouts; use XDSHStack or XDSVStack instead.' },+ { guidance: false, description: 'Nest multiple XDSLayout components; use one per page shell and compose content within its slots.' },],},components: [diff --git a/packages/core/src/Lightbox/Lightbox.doc.mjs b/packages/core/src/Lightbox/Lightbox.doc.mjsindex 49743dfadf..b69d59a0f2 100644--- a/packages/core/src/Lightbox/Lightbox.doc.mjs+++ b/packages/core/src/Lightbox/Lightbox.doc.mjs@@ -61,8 +61,8 @@ export const docs = {{ guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },{ guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },{ guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },- { guidance: false, description: 'Use the lightbox for non-image content — it is specialized for images.' },- { guidance: false, description: 'Nest interactive content inside captions — keep them plain text.' },+ { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },+ { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },],},};@@ -125,8 +125,8 @@ export const docsZh = {{ guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },{ guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },{ guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },- { guidance: false, description: 'Use the lightbox for non-image content — it is specialized for images.' },- { guidance: false, description: 'Nest interactive content inside captions — keep them plain text.' },+ { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },+ { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },],},};@@ -141,8 +141,8 @@ export const docsDense = {{ guidance: true, description: 'Always provide alt text for every image.' },{ guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },{ guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },- { guidance: false, description: 'Use for non-image content — specialized for images.' },- { guidance: false, description: 'Nest interactive content inside captions — keep them plain text.' },+ { guidance: false, description: 'Use for non-image content; specialized for images.' },+ { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },],},propDescriptions: {diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjsindex 539700e2da..8009064bd5 100644--- a/packages/core/src/Link/Link.doc.mjs+++ b/packages/core/src/Link/Link.doc.mjs@@ -33,7 +33,7 @@ export const docs = {{name: 'label',type: 'string',- description: 'Accessible label (aria-label). Only use when children are not self-descriptive (e.g. icon-only links). Omit for text links — the link text is the accessible name.',+ description: 'Accessible label (aria-label). Only use when children are not self-descriptive (e.g. icon-only links). Omit for text links; the link text is the accessible name.',},{name: 'href',@@ -123,10 +123,10 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination.' },{ guidance: true, description: 'Set `isStandalone` when the link appears outside of inline text, so it receives proper base font sizing.' },- { guidance: true, description: 'Only set `label` when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name — adding `label` overrides it for screen readers, which is harmful.' },- { guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },- { guidance: false, description: 'Use generic text like "click here" or "read more" — describe the destination.' },- { guidance: false, description: 'Set `label` on text links — `aria-label` prevents assistive technology from reading the actual link content.' },+ { guidance: true, description: 'Only set `label` when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name; adding `label` overrides it for screen readers, which is harmful.' },+ { guidance: false, description: 'Use Link for actions that do not navigate; use a Button instead.' },+ { guidance: false, description: 'Use generic text like "click here" or "read more"; describe the destination.' },+ { guidance: false, description: 'Set `label` on text links; `aria-label` prevents assistive technology from reading the actual link content.' },],anatomy: [{name: 'Label', required: true, description: 'The visible text of the link.'},@@ -249,10 +249,10 @@ export const docsZh = {bestPractices: [{ guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination.' },{ guidance: true, description: 'Set `isStandalone` when the link appears outside of inline text, so it receives proper base font sizing.' },- { guidance: true, description: 'Only set `label` when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name — adding `label` overrides it for screen readers, which is harmful.' },- { guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },- { guidance: false, description: 'Use generic text like "click here" or "read more" — describe the destination.' },- { guidance: false, description: 'Set `label` on text links — `aria-label` prevents assistive technology from reading the actual link content.' },+ { guidance: true, description: 'Only set `label` when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name; adding `label` overrides it for screen readers, which is harmful.' },+ { guidance: false, description: 'Use Link for actions that do not navigate; use a Button instead.' },+ { guidance: false, description: 'Use generic text like "click here" or "read more"; describe the destination.' },+ { guidance: false, description: 'Set `label` on text links; `aria-label` prevents assistive technology from reading the actual link content.' },],anatomy: [{name: 'Label', required: true, description: 'The visible text of the link.'},@@ -272,10 +272,10 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination.' },{ guidance: true, description: 'Set `isStandalone` when the link appears outside of inline text, so it receives proper base font sizing.' },- { guidance: true, description: 'Only set `label` when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name — adding `label` overrides it for screen readers, which is harmful.' },- { guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },- { guidance: false, description: 'Use generic text like "click here" or "read more" — describe the destination.' },- { guidance: false, description: 'Set `label` on text links — `aria-label` prevents assistive technology from reading the actual link content.' },+ { guidance: true, description: 'Only set `label` when the link content is not descriptive text (e.g. an icon-only link). For text links, the visible text is already the accessible name; adding `label` overrides it for screen readers, which is harmful.' },+ { guidance: false, description: 'Use Link for actions that do not navigate; use a Button instead.' },+ { guidance: false, description: 'Use generic text like "click here" or "read more"; describe the destination.' },+ { guidance: false, description: 'Set `label` on text links; `aria-label` prevents assistive technology from reading the actual link content.' },],anatomy: [{name: 'Label', required: true, description: 'The visible text of the link.'},