Skip to content

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

TypeScript

docs(deslop): batch 4 - replace em dashes with grammatical punctuation (30 files) (#2662)

Joey872ee94beca4
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index f199ababda..39cbd75cc2 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -55,7 +55,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={{}}.',
},
],
},
@@ -138,8 +138,8 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
{ guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
- { guidance: false, description: 'Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.' },
- { guidance: false, description: 'Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.' },
+ { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
+ { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
{ guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
],
anatomy: [
@@ -279,8 +279,8 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
{ guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
- { guidance: false, description: 'Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.' },
- { guidance: false, description: 'Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.' },
+ { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
+ { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
{ guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
],
anatomy: [
@@ -302,8 +302,8 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
{ guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
- { guidance: false, description: 'Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.' },
- { guidance: false, description: 'Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.' },
+ { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
+ { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
{ guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
],
anatomy: [
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index d6e3589f71..0218888e3c 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -100,9 +100,9 @@ export const docs = {
description:
'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
bestPractices: [
- { guidance: true, description: 'Choose label position based on content — "start" for short values, "top" for long or complex values.' },
+ { guidance: true, description: 'Choose label position based on content: "start" for short values, "top" for long or complex values.' },
{ guidance: true, description: 'Collapse long lists with `maxNumOfItems` to keep the page scannable.' },
- { guidance: false, description: 'Use for extensive form input — use a form layout instead.' },
+ { guidance: false, description: 'Use for extensive form input; use a form layout instead.' },
{ guidance: false, description: "Use for data that doesn't have a clear key-value structure." },
],
anatomy: [
@@ -147,9 +147,9 @@ export const docsZh = {
description:
'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
bestPractices: [
- { guidance: true, description: 'Choose label position based on content — "start" for short values, "top" for long or complex values.' },
+ { guidance: true, description: 'Choose label position based on content: "start" for short values, "top" for long or complex values.' },
{ guidance: true, description: 'Collapse long lists with `maxNumOfItems` to keep the page scannable.' },
- { guidance: false, description: 'Use for extensive form input — use a form layout instead.' },
+ { guidance: false, description: 'Use for extensive form input; use a form layout instead.' },
{ guidance: false, description: "Use for data that doesn't have a clear key-value structure." },
],
anatomy: [
@@ -168,9 +168,9 @@ export const docsDense = {
description:
'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
bestPractices: [
- { guidance: true, description: 'Choose label position based on content — "start" for short values, "top" for long or complex values.' },
+ { guidance: true, description: 'Choose label position based on content: "start" for short values, "top" for long or complex values.' },
{ guidance: true, description: 'Collapse long lists with `maxNumOfItems` to keep the page scannable.' },
- { guidance: false, description: 'Use for extensive form input — use a form layout instead.' },
+ { guidance: false, description: 'Use for extensive form input; use a form layout instead.' },
{ guidance: false, description: "Use for data that doesn't have a clear key-value structure." },
],
anatomy: [
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index ab5fa67339..14b2b888e7 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -12,7 +12,7 @@ export const docs = {
name: 'items',
type: 'XDSDropdownMenuOption[]',
description:
- 'Menu items — data array of actions, dividers, and sections. Same type as XDSDropdownMenu items prop.',
+ 'Menu items: data array of actions, dividers, and sections. Same type as XDSDropdownMenu items prop.',
required: true,
},
{
@@ -63,7 +63,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: {
@@ -84,9 +84,9 @@ export const docs = {
description:
'MoreMenu is a three-dot button that opens a list of actions. Use it for secondary actions that don\'t need to be always visible, like in table rows, card headers, or toolbars.',
bestPractices: [
- { guidance: true, description: 'Use for overflow or secondary actions — keep primary actions visible outside the menu.' },
+ { guidance: true, description: 'Use for overflow or secondary actions; keep primary actions visible outside the menu.' },
{ guidance: true, description: 'Use dividers or sections to group related actions when the menu has many items.' },
- { guidance: false, description: 'Hide primary actions inside a MoreMenu — they should be directly visible.' },
+ { guidance: false, description: 'Hide primary actions inside a MoreMenu; they should be directly visible.' },
],
},
};
@@ -161,9 +161,9 @@ export const docsZh = {
description:
'MoreMenu is a three-dot button that opens a list of actions. Use it for secondary actions that don\'t need to be always visible, like in table rows, card headers, or toolbars.',
bestPractices: [
- { guidance: true, description: 'Use for overflow or secondary actions — keep primary actions visible outside the menu.' },
+ { guidance: true, description: 'Use for overflow or secondary actions; keep primary actions visible outside the menu.' },
{ guidance: true, description: 'Use dividers or sections to group related actions when the menu has many items.' },
- { guidance: false, description: 'Hide primary actions inside a MoreMenu — they should be directly visible.' },
+ { guidance: false, description: 'Hide primary actions inside a MoreMenu; they should be directly visible.' },
],
},
};
@@ -176,9 +176,9 @@ export const docsDense = {
description:
'MoreMenu is a three-dot button that opens a list of actions. Use it for secondary actions that don\'t need to be always visible, like in table rows, card headers, or toolbars.',
bestPractices: [
- { guidance: true, description: 'Use for overflow or secondary actions — keep primary actions visible outside the menu.' },
+ { guidance: true, description: 'Use for overflow or secondary actions; keep primary actions visible outside the menu.' },
{ guidance: true, description: 'Use dividers or sections to group related actions when the menu has many items.' },
- { guidance: false, description: 'Hide primary actions inside a MoreMenu — they should be directly visible.' },
+ { guidance: false, description: 'Hide primary actions inside a MoreMenu; they should be directly visible.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 34514281e7..c7c105b90f 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -30,7 +30,7 @@ export const docs = {
name: 'options',
type: 'XDSMultiSelectorOptionType[]',
description:
- 'Array of items — strings, objects with value/label/icon/disabled, dividers, or sections.',
+ 'Array of items: strings, objects with value/label/icon/disabled, dividers, or sections.',
required: true,
},
{
@@ -152,7 +152,7 @@ export const docs = {
{ guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },
{ guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },
{ guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },
- { guidance: false, description: 'Use for single-value selection — use Selector instead.' },
+ { guidance: false, description: 'Use for single-value selection; use Selector instead.' },
{ guidance: false, description: 'Show more than ~20 options without enabling search.' },
],
},
@@ -198,7 +198,7 @@ export const docsZh = {
{ guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },
{ guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },
{ guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },
- { guidance: false, description: 'Use for single-value selection — use Selector instead.' },
+ { guidance: false, description: 'Use for single-value selection; use Selector instead.' },
{ guidance: false, description: 'Show more than ~20 options without enabling search.' },
],
},
@@ -214,7 +214,7 @@ export const docsDense = {
{ guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },
{ guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },
{ guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },
- { guidance: false, description: 'Use for single-value selection — use Selector instead.' },
+ { guidance: false, description: 'Use for single-value selection; use Selector instead.' },
{ guidance: false, description: 'Show more than ~20 options without enabling search.' },
],
},
diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjs
index 40af44d0ce..8f4eeecb08 100644
--- a/packages/core/src/NavIcon/NavIcon.doc.mjs
+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs
@@ -31,7 +31,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },
{ guidance: true, description: 'Pass an XDSIcon or similarly sized icon component to ensure proper proportions.' },
- { guidance: false, description: 'Use NavIcon for interactive purposes — it is a display-only container, not a button.' },
+ { guidance: false, description: 'Use NavIcon for interactive purposes; it is a display-only container, not a button.' },
],
},
};
@@ -60,7 +60,7 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },
{ guidance: true, description: 'Pass an XDSIcon or similarly sized icon component to ensure proper proportions.' },
- { guidance: false, description: 'Use NavIcon for interactive purposes — it is a display-only container, not a button.' },
+ { guidance: false, description: 'Use NavIcon for interactive purposes; it is a display-only container, not a button.' },
],
},
};
@@ -75,7 +75,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },
{ guidance: true, description: 'Pass an XDSIcon or similarly sized icon component to ensure proper proportions.' },
- { guidance: false, description: 'Use NavIcon for interactive purposes — it is a display-only container, not a button.' },
+ { guidance: false, description: 'Use NavIcon for interactive purposes; it is a display-only container, not a button.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/NavMenu/NavMenu.doc.mjs b/packages/core/src/NavMenu/NavMenu.doc.mjs
index 67aa9b25b0..36866a42c0 100644
--- a/packages/core/src/NavMenu/NavMenu.doc.mjs
+++ b/packages/core/src/NavMenu/NavMenu.doc.mjs
@@ -21,7 +21,7 @@ export const docs = {
{name: 'children', type: 'ReactNode', required: true, description: 'Menu items.'},
{name: 'size', type: "'sm' | 'md' | 'lg'", default: "'md'", description: 'Controls min-width and item padding.'},
{name: 'minWidth', type: 'number | string', description: 'Minimum width override.'},
- {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={{}}.'},
],
};
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index 904cfa5324..177ec85693 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -164,7 +164,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Set min, max, and step to guide users toward valid values.' },
{ guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
- { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.' },
+ { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
],
anatomy: [
@@ -337,7 +337,7 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Set min, max, and step to guide users toward valid values.' },
{ guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
- { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.' },
+ { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
],
anatomy: [
@@ -359,7 +359,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Set min, max, and step to guide users toward valid values.' },
{ guidance: true, description: 'Show units (e.g. "%" or "GB") so users know what the number represents.' },
- { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.' },
+ { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers; use TextInput instead.' },
{ guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
],
anatomy: [
diff --git a/packages/core/src/OverflowList/OverflowList.doc.mjs b/packages/core/src/OverflowList/OverflowList.doc.mjs
index 885f6d6517..36d40508f7 100644
--- a/packages/core/src/OverflowList/OverflowList.doc.mjs
+++ b/packages/core/src/OverflowList/OverflowList.doc.mjs
@@ -54,14 +54,14 @@ export const docs = {
name: 'behavior',
type: "'observeSelf' | 'observeParent'",
description:
- "Controls which element is measured for available width. 'observeSelf' uses the container's own width. 'observeParent' observes the parent element — useful when the list should stay content-sized while still detecting available space.",
+ "Controls which element is measured for available width. 'observeSelf' uses the container's own width. 'observeParent' observes the parent element, useful when the list should stay content-sized while still detecting available space.",
default: "'observeSelf'",
},
{
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object.',
},
],
theming: {
@@ -73,9 +73,9 @@ export const docs = {
description:
'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
bestPractices: [
- { guidance: true, description: 'Provide a meaningful overflowRenderer — a "+N more" badge, a dropdown, or a count indicator.' },
+ { guidance: true, description: 'Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.' },
{ guidance: true, description: 'Set minVisibleItems to keep key items visible regardless of container size.' },
- { guidance: false, description: 'Use OverflowList for vertical layouts — it only works with horizontal rows.' },
+ { guidance: false, description: 'Use OverflowList for vertical layouts; it only works with horizontal rows.' },
],
},
};
@@ -134,23 +134,23 @@ export const docsZh = {
description:
'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
bestPractices: [
- { guidance: true, description: 'Provide a meaningful overflowRenderer — a "+N more" badge, a dropdown, or a count indicator.' },
+ { guidance: true, description: 'Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.' },
{ guidance: true, description: 'Set minVisibleItems to keep key items visible regardless of container size.' },
- { guidance: false, description: 'Use OverflowList for vertical layouts — it only works with horizontal rows.' },
+ { guidance: false, description: 'Use OverflowList for vertical layouts; it only works with horizontal rows.' },
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'horizontal list w/ overflow indicator — hides items beyond container width',
+ description: 'horizontal list w/ overflow indicator: hides items beyond container width',
usage: {
description:
'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
bestPractices: [
- { guidance: true, description: 'Provide a meaningful overflowRenderer — a "+N more" badge, a dropdown, or a count indicator.' },
+ { guidance: true, description: 'Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.' },
{ guidance: true, description: 'Set minVisibleItems to keep key items visible regardless of container size.' },
- { guidance: false, description: 'Use OverflowList for vertical layouts — it only works with horizontal rows.' },
+ { guidance: false, description: 'Use OverflowList for vertical layouts; it only works with horizontal rows.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index 56a2698326..af0a30afb8 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -98,7 +98,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: {
@@ -109,16 +109,16 @@ export const docs = {
},
usage: {
description:
- 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
+ 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context: numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
bestPractices: [
{ guidance: true, description: 'Place pagination below the content it controls so users see results before navigating.' },
{ guidance: true, description: 'Use the pages variant for data tables where users need to jump to a specific page.' },
{ guidance: true, description: 'Use the count variant with a page size selector when users need to control how many items they see at once.' },
{ guidance: true, description: 'Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.' },
{ guidance: true, description: 'Pass totalItems when the total is known so users can see how much content remains.' },
- { guidance: false, description: 'Show pagination when all items fit on a single page — there is nothing to paginate.' },
- { guidance: false, description: 'Use the dots variant for more than about 10 pages — the dots become too small to be useful.' },
- { guidance: false, description: 'Place pagination above the content — users expect it at the bottom.' },
+ { guidance: false, description: 'Show pagination when all items fit on a single page; there is nothing to paginate.' },
+ { guidance: false, description: 'Use the dots variant for more than about 10 pages; the dots become too small to be useful.' },
+ { guidance: false, description: 'Place pagination above the content; users expect it at the bottom.' },
],
},
};
@@ -229,16 +229,16 @@ export const docsZh = {
},
usage: {
description:
- 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
+ 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context: numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
bestPractices: [
{ guidance: true, description: 'Place pagination below the content it controls so users see results before navigating.' },
{ guidance: true, description: 'Use the pages variant for data tables where users need to jump to a specific page.' },
{ guidance: true, description: 'Use the count variant with a page size selector when users need to control how many items they see at once.' },
{ guidance: true, description: 'Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.' },
{ guidance: true, description: 'Pass totalItems when the total is known so users can see how much content remains.' },
- { guidance: false, description: 'Show pagination when all items fit on a single page — there is nothing to paginate.' },
- { guidance: false, description: 'Use the dots variant for more than about 10 pages — the dots become too small to be useful.' },
- { guidance: false, description: 'Place pagination above the content — users expect it at the bottom.' },
+ { guidance: false, description: 'Show pagination when all items fit on a single page; there is nothing to paginate.' },
+ { guidance: false, description: 'Use the dots variant for more than about 10 pages; the dots become too small to be useful.' },
+ { guidance: false, description: 'Place pagination above the content; users expect it at the bottom.' },
],
},
};
@@ -249,16 +249,16 @@ export const docsDense = {
'Standalone pagination controls for navigating content pages. Supports multiple display variants + works w/ known totals or cursor-based pagination.',
usage: {
description:
- 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context — numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
+ 'Pagination lets users step through pages of content. Place it below a table, list, or card grid so users can move forward and backward through results. Pick a variant to match the context: numbered pages for data tables, a count for large lists, compact for tight spaces, or dots for carousels.',
bestPractices: [
{ guidance: true, description: 'Place pagination below the content it controls so users see results before navigating.' },
{ guidance: true, description: 'Use the pages variant for data tables where users need to jump to a specific page.' },
{ guidance: true, description: 'Use the count variant with a page size selector when users need to control how many items they see at once.' },
{ guidance: true, description: 'Use the dots variant for carousels and walkthroughs where the total is small and position matters more than a number.' },
{ guidance: true, description: 'Pass totalItems when the total is known so users can see how much content remains.' },
- { guidance: false, description: 'Show pagination when all items fit on a single page — there is nothing to paginate.' },
- { guidance: false, description: 'Use the dots variant for more than about 10 pages — the dots become too small to be useful.' },
- { guidance: false, description: 'Place pagination above the content — users expect it at the bottom.' },
+ { guidance: false, description: 'Show pagination when all items fit on a single page; there is nothing to paginate.' },
+ { guidance: false, description: 'Use the dots variant for more than about 10 pages; the dots become too small to be useful.' },
+ { guidance: false, description: 'Place pagination above the content; users expect it at the bottom.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index fc8424c92f..189f499192 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -93,7 +93,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={{}}.',
},
],
},
@@ -120,10 +120,10 @@ export const docs = {
'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.',
bestPractices: [
{ guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
- { guidance: true, description: 'Provide a clear way to close — either by clicking outside or with an explicit close button.' },
- { guidance: false, description: 'Nest popovers inside other popovers — it creates confusing focus and navigation.' },
- { guidance: false, description: 'Use a popover for content that requires heavy user input — use a Dialog instead.' },
- { guidance: false, description: 'Put too much content in a popover — if it needs scrolling, use a Dialog instead.' },
+ { guidance: true, description: 'Provide a clear way to close: either by clicking outside or with an explicit close button.' },
+ { guidance: false, description: 'Nest popovers inside other popovers; it creates confusing focus and navigation.' },
+ { guidance: false, description: 'Use a popover for content that requires heavy user input; use a Dialog instead.' },
+ { guidance: false, description: 'Put too much content in a popover; if it needs scrolling, use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -238,10 +238,10 @@ export const docsZh = {
'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.',
bestPractices: [
{ guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
- { guidance: true, description: 'Provide a clear way to close — either by clicking outside or with an explicit close button.' },
- { guidance: false, description: 'Nest popovers inside other popovers — it creates confusing focus and navigation.' },
- { guidance: false, description: 'Use a popover for content that requires heavy user input — use a Dialog instead.' },
- { guidance: false, description: 'Put too much content in a popover — if it needs scrolling, use a Dialog instead.' },
+ { guidance: true, description: 'Provide a clear way to close: either by clicking outside or with an explicit close button.' },
+ { guidance: false, description: 'Nest popovers inside other popovers; it creates confusing focus and navigation.' },
+ { guidance: false, description: 'Use a popover for content that requires heavy user input; use a Dialog instead.' },
+ { guidance: false, description: 'Put too much content in a popover; if it needs scrolling, use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -260,10 +260,10 @@ export const docsDense = {
'A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.',
bestPractices: [
{ guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
- { guidance: true, description: 'Provide a clear way to close — either by clicking outside or with an explicit close button.' },
- { guidance: false, description: 'Nest popovers inside other popovers — it creates confusing focus and navigation.' },
- { guidance: false, description: 'Use a popover for content that requires heavy user input — use a Dialog instead.' },
- { guidance: false, description: 'Put too much content in a popover — if it needs scrolling, use a Dialog instead.' },
+ { guidance: true, description: 'Provide a clear way to close: either by clicking outside or with an explicit close button.' },
+ { guidance: false, description: 'Nest popovers inside other popovers; it creates confusing focus and navigation.' },
+ { guidance: false, description: 'Use a popover for content that requires heavy user input; use a Dialog instead.' },
+ { guidance: false, description: 'Put too much content in a popover; if it needs scrolling, use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 3766e972af..7c614d506f 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -135,7 +135,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
{ guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
- { guidance: false, description: 'Use PowerSearch for simple keyword searches — a standard text input is more appropriate for single-field lookups.' },
+ { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
],
},
};
@@ -268,7 +268,7 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
{ guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
- { guidance: false, description: 'Use PowerSearch for simple keyword searches — a standard text input is more appropriate for single-field lookups.' },
+ { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
],
},
};
@@ -283,7 +283,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
{ guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
- { guidance: false, description: 'Use PowerSearch for simple keyword searches — a standard text input is more appropriate for single-field lookups.' },
+ { guidance: false, description: 'Use PowerSearch for simple keyword searches; a standard text input is more appropriate for single-field lookups.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index 449c9dc229..7599a13b8f 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -59,14 +59,14 @@ export const docs = {
{
name: 'isDisabled',
type: 'boolean',
- description: 'Visually disabled state — grays out the fill and text. Use for canceled or inactive operations.',
+ description: 'Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.',
default: 'false',
},
{
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: {
@@ -80,11 +80,11 @@ export const docs = {
'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',
bestPractices: [
{ guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },
- { guidance: true, description: 'Choose a color variant that matches the context — accent for general progress, success for completion, warning or error for alerts.' },
- { guidance: true, description: "Always provide a label, even if hidden — screen readers need it to announce what's loading." },
- { guidance: false, description: 'Place icons or labels inside the bar — compose them alongside it using layout components.' },
- { guidance: false, description: "Use a progress bar for instant actions — it's meant for operations that take noticeable time." },
- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation — use one bar with a value label instead.' },
+ { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },
+ { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },
+ { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },
+ { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },
+ { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },
],
},
};
@@ -166,11 +166,11 @@ export const docsZh = {
'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',
bestPractices: [
{ guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },
- { guidance: true, description: 'Choose a color variant that matches the context — accent for general progress, success for completion, warning or error for alerts.' },
- { guidance: true, description: "Always provide a label, even if hidden — screen readers need it to announce what's loading." },
- { guidance: false, description: 'Place icons or labels inside the bar — compose them alongside it using layout components.' },
- { guidance: false, description: "Use a progress bar for instant actions — it's meant for operations that take noticeable time." },
- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation — use one bar with a value label instead.' },
+ { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },
+ { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },
+ { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },
+ { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },
+ { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },
],
},
};
@@ -184,11 +184,11 @@ export const docsDense = {
'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',
bestPractices: [
{ guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },
- { guidance: true, description: 'Choose a color variant that matches the context — accent for general progress, success for completion, warning or error for alerts.' },
- { guidance: true, description: "Always provide a label, even if hidden — screen readers need it to announce what's loading." },
- { guidance: false, description: 'Place icons or labels inside the bar — compose them alongside it using layout components.' },
- { guidance: false, description: "Use a progress bar for instant actions — it's meant for operations that take noticeable time." },
- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation — use one bar with a value label instead.' },
+ { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },
+ { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },
+ { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },
+ { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },
+ { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },
],
},
propDescriptions: {
@@ -200,7 +200,7 @@ export const docsDense = {
formatValueLabel: 'Custom value label formatter; defaults to percentage string.',
variant: 'Semantic color variant.',
isIndeterminate: 'Animated loading indicator for unknown progress.',
- isDisabled: 'Visually disabled — grays out fill and text.',
+ isDisabled: 'Visually disabled: grays out fill and text.',
xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
},
};
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index 7d2a6e3d78..a57d846e73 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -104,7 +104,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={{}}.',
},
],
},
@@ -160,12 +160,12 @@ export const docs = {
description:
'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
bestPractices: [
- { guidance: true, description: 'Keep the number of options small — typically 2 to 7 choices.' },
+ { guidance: true, description: 'Keep the number of options small: typically 2 to 7 choices.' },
{ guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },
- { guidance: true, description: "Pre-select a default option when there's a sensible default — don't leave the group empty unless the choice is truly optional." },
- { guidance: false, description: 'Use when multiple selections are needed — use CheckboxList instead.' },
- { guidance: false, description: 'Use for long lists — use Selector for better discoverability.' },
- { guidance: false, description: 'Use horizontal layout with more than 4 options — it wraps awkwardly.' },
+ { guidance: true, description: "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is truly optional." },
+ { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
+ { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
+ { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -326,12 +326,12 @@ export const docsZh = {
description:
'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
bestPractices: [
- { guidance: true, description: 'Keep the number of options small — typically 2 to 7 choices.' },
+ { guidance: true, description: 'Keep the number of options small: typically 2 to 7 choices.' },
{ guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },
- { guidance: true, description: "Pre-select a default option when there's a sensible default — don't leave the group empty unless the choice is truly optional." },
- { guidance: false, description: 'Use when multiple selections are needed — use CheckboxList instead.' },
- { guidance: false, description: 'Use for long lists — use Selector for better discoverability.' },
- { guidance: false, description: 'Use horizontal layout with more than 4 options — it wraps awkwardly.' },
+ { guidance: true, description: "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is truly optional." },
+ { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
+ { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
+ { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -349,12 +349,12 @@ export const docsDense = {
description:
'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
bestPractices: [
- { guidance: true, description: 'Keep the number of options small — typically 2 to 7 choices.' },
+ { guidance: true, description: 'Keep the number of options small: typically 2 to 7 choices.' },
{ guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },
- { guidance: true, description: "Pre-select a default option when there's a sensible default — don't leave the group empty unless the choice is truly optional." },
- { guidance: false, description: 'Use when multiple selections are needed — use CheckboxList instead.' },
- { guidance: false, description: 'Use for long lists — use Selector for better discoverability.' },
- { guidance: false, description: 'Use horizontal layout with more than 4 options — it wraps awkwardly.' },
+ { guidance: true, description: "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is truly optional." },
+ { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },
+ { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },
+ { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjs
index 7a3ebf0bcd..875f79e195 100644
--- a/packages/core/src/Resizable/Resizable.doc.mjs
+++ b/packages/core/src/Resizable/Resizable.doc.mjs
@@ -40,7 +40,7 @@ export const docs = {
guidance: false,
description:
'Wrap panels in extra container components for resize. The hook-first ' +
- 'architecture avoids extra DOM — use it directly on existing components.',
+ 'architecture avoids extra DOM; use it directly on existing components.',
},
],
},
@@ -99,7 +99,7 @@ export const docs = {
name: 'shrinkOrder',
type: 'number',
description:
- 'Cascade priority — lower number shrinks first.',
+ 'Cascade priority: lower number shrinks first.',
},
{
name: 'autoSaveId',
@@ -119,7 +119,7 @@ export const docs = {
name: 'direction',
type: "'horizontal' | 'vertical'",
description:
- 'Layout direction — determines cursor and indicator orientation.',
+ 'Layout direction: determines cursor and indicator orientation.',
default: "'horizontal'",
},
{
@@ -168,7 +168,7 @@ export const docs = {
name: 'resizable',
type: 'ResizableProps',
description:
- 'Resize props from useXDSResizable — connects handle to panel.',
+ 'Resize props from useXDSResizable: connects handle to panel.',
required: true,
},
{
@@ -181,7 +181,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={{}}.',
},
],
},
@@ -197,7 +197,7 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use useXDSResizable() w/ existing XDS layout components. Pass returned props to resizable prop on XDSLayoutPanel or XDSSideNav.'},
{guidance: true, description: 'Provide accessible label on each XDSResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
- {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM — use it directly on existing components.'},
+ {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},
],
},
components: [
@@ -211,7 +211,7 @@ export const docsDense = {
collapsible: 'region can collapse to size 0?',
collapsedSize: 'px threshold triggering collapse during drag',
snaps: 'px values to snap to during resize',
- shrinkOrder: 'cascade priority — lower number shrinks first',
+ shrinkOrder: 'cascade priority: lower number shrinks first',
autoSaveId: 'key for persisting sizes to localStorage',
},
},
@@ -219,14 +219,14 @@ export const docsDense = {
name: 'XDSResizeHandle',
description: 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',
propDescriptions: {
- direction: 'layout direction — determines cursor + indicator orientation',
+ direction: 'layout direction: determines cursor + indicator orientation',
isReversed: 'reverse drag direction. Use when handle controls panel on end/right/bottom side',
isDisabled: 'handle interactive?',
hasDivider: 'show full-length 1px divider line through handle. Use when adjacent panels share same background',
isAlwaysVisible: 'show pill grip at rest instead of only on hover. Use when discoverability important',
pillPlacement: 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',
label: 'accessible label for separator',
- resizable: 'resize props from useXDSResizable — connects handle to panel **(required)**',
+ resizable: 'resize props from useXDSResizable: connects handle to panel **(required)**',
},
},
],
diff --git a/packages/core/src/Resizable/useXDSResizable.doc.mjs b/packages/core/src/Resizable/useXDSResizable.doc.mjs
index c1c1bb5684..dbd6c66ddc 100644
--- a/packages/core/src/Resizable/useXDSResizable.doc.mjs
+++ b/packages/core/src/Resizable/useXDSResizable.doc.mjs
@@ -78,7 +78,7 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use with XDSLayout or XDSAppShell sidebar for resizable navigation panels.'},
{guidance: true, description: 'Set autoSaveId to persist user-chosen sizes across page reloads.'},
- {guidance: false, description: 'Set minSizePx too small — content becomes unreadable. Prefer collapsible for panels that can hide entirely.'},
+ {guidance: false, description: 'Set minSizePx too small; content becomes unreadable. Prefer collapsible for panels that can hide entirely.'},
],
},
relatedComponents: ['Resizable', 'AppShell', 'Layout', 'SideNav'],
@@ -111,7 +111,7 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use w/ XDSLayout / XDSAppShell sidebar for resizable navigation panels.'},
{guidance: true, description: 'Set autoSaveId to persist user-chosen sizes across page reloads.'},
- {guidance: false, description: 'Set minSizePx too small — content becomes unreadable. Prefer collapsible for panels that can hide entirely.'},
+ {guidance: false, description: 'Set minSizePx too small; content becomes unreadable. Prefer collapsible for panels that can hide entirely.'},
],
},
};
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index 9087aa5f29..04cb467176 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -70,7 +70,7 @@ export const docs = {
},
usage: {
description:
- 'Section is the correct way to create page regions and group related content on a page. Use it for settings groups, form sections, sidebar areas, or any time you need visual separation between parts of a page. If you are tempted to use a Card for a page section — use XDSSection instead.',
+ 'Section is the correct way to create page regions and group related content on a page. Use it for settings groups, form sections, sidebar areas, or any time you need visual separation between parts of a page. If you are tempted to use a Card for a page section, use XDSSection instead.',
bestPractices: [
{ guidance: true, description: 'Use Section for page-level grouping: settings panels, form groups, sidebar regions. These are sections of a page, not discrete items.' },
{ guidance: true, description: 'Start with the default variant. Use muted only to call attention to a specific region.' },
@@ -147,7 +147,7 @@ export const docsZh = {
},
usage: {
description:
- 'Section is the correct way to create page regions and group related content on a page. Use it for settings groups, form sections, sidebar areas, or any time you need visual separation between parts of a page. If you are tempted to use a Card for a page section — use XDSSection instead.',
+ 'Section is the correct way to create page regions and group related content on a page. Use it for settings groups, form sections, sidebar areas, or any time you need visual separation between parts of a page. If you are tempted to use a Card for a page section, use XDSSection instead.',
bestPractices: [
{ guidance: true, description: 'Use Section for page-level grouping: settings panels, form groups, sidebar regions. These are sections of a page, not discrete items.' },
{ guidance: true, description: 'Start with the default variant. Use muted only to call attention to a specific region.' },
@@ -164,7 +164,7 @@ export const docsDense = {
'Page-level container for grouping content into regions. Use INSTEAD of Card for settings panels, form groups, and page sections.',
usage: {
description:
- 'Section creates page regions. Use for settings groups, form sections, sidebar areas. If you want to visually separate a part of a page, use Section — not Card. Cards are for discrete items (one profile, one notification).',
+ 'Section creates page regions. Use for settings groups, form sections, sidebar areas. If you want to visually separate a part of a page, use Section, not Card. Cards are for discrete items (one profile, one notification).',
bestPractices: [
{ guidance: true, description: 'Use Section for page-level grouping: settings panels, form groups, sidebar regions. Page sections, not discrete items.' },
{ guidance: true, description: 'Start w/ default variant. Use muted only to call attention to a specific region.' },
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 867a3f3d5b..6c345175d0 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -81,7 +81,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={{}}.',
},
], },
{
@@ -133,8 +133,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
- {guidance: false, description: 'Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
- {guidance: false, description: 'Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+ {guidance: false, description: 'Use for page-level navigation; use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
+ {guidance: false, description: 'Use for simple on/off states; use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
],
},
};
@@ -179,8 +179,8 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
- {guidance: false, description: 'Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
- {guidance: false, description: 'Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+ {guidance: false, description: 'Use for page-level navigation; use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
+ {guidance: false, description: 'Use for simple on/off states; use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
],
},
};
@@ -193,8 +193,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
- {guidance: false, description: 'Use for page-level navigation — use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
- {guidance: false, description: 'Use for simple on/off states — use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
+ {guidance: false, description: 'Use for page-level navigation; use XDSTabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
+ {guidance: false, description: 'Use for simple on/off states; use XDSToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/SelectableCard/SelectableCard.doc.mjs b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
index 00e93fc652..cdf1247fa4 100644
--- a/packages/core/src/SelectableCard/SelectableCard.doc.mjs
+++ b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
@@ -12,7 +12,7 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for plan pickers, filter chips, or option grids.'},
{guidance: true, description: 'For single-select track one ID; for multi-select use a Set.'},
- {guidance: false, description: 'Use for navigation — use ClickableCard for that.'},
+ {guidance: false, description: 'Use for navigation; use ClickableCard for that.'},
],
anatomy: [
{name: 'Container', required: true, description: 'Interactive div with accent border on selection.'},
@@ -30,7 +30,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,7 +46,7 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for plan pickers, filter chips, option grids.'},
{guidance: true, description: 'For single-select track one ID; for multi-select use a Set.'},
- {guidance: false, description: 'Use for navigation — use ClickableCard instead.'},
+ {guidance: false, description: 'Use for navigation; use ClickableCard instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index fed560f769..b87cfaa45f 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -30,7 +30,7 @@ export const docs = {
name: 'options',
type: 'XDSSelectorOption[]',
description:
- 'Array of items — strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
+ 'Array of items: strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
required: true,
},
{
@@ -119,7 +119,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={{}}.',
},
],
},
@@ -156,11 +156,11 @@ export const docs = {
{guidance: true, description: 'Provide a visible label so users understand what they are selecting.'},
{guidance: true, description: 'Use sections and dividers to organize options when the list exceeds ~8 items.'},
{guidance: true, description: 'Set a meaningful placeholder that hints at the expected selection (e.g. "Choose a country" not "Select...").'},
- {guidance: false, description: 'Use for action menus — use Dropdown Menu for triggering commands or navigation.'},
- {guidance: false, description: 'Use when there are only two options — use a SegmentedControl or radio buttons instead.'},
- {guidance: false, description: 'Use Selector for navigation — links should be links, not dropdown options.'},
- {guidance: false, description: 'Use for yes/no or on/off choices — use Switch or CheckboxInput instead.'},
- {guidance: false, description: 'Put more than ~20 options without sections — consider Typeahead for large lists.'},
+ {guidance: false, description: 'Use for action menus; use Dropdown Menu for triggering commands or navigation.'},
+ {guidance: false, description: 'Use when there are only two options; use a SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Use Selector for navigation; links should be links, not dropdown options.'},
+ {guidance: false, description: 'Use for yes/no or on/off choices; use Switch or CheckboxInput instead.'},
+ {guidance: false, description: 'Put more than ~20 options without sections; consider Typeahead for large lists.'},
],
anatomy: [
{name: 'Label', required: false, description: 'Text label displayed above the selector.'},
@@ -324,11 +324,11 @@ export const docsZh = {
{guidance: true, description: 'Provide a visible label so users understand what they are selecting.'},
{guidance: true, description: 'Use sections and dividers to organize options when the list exceeds ~8 items.'},
{guidance: true, description: 'Set a meaningful placeholder that hints at the expected selection (e.g. "Choose a country" not "Select...").'},
- {guidance: false, description: 'Use for action menus — use Dropdown Menu for triggering commands or navigation.'},
- {guidance: false, description: 'Use when there are only two options — use a SegmentedControl or radio buttons instead.'},
- {guidance: false, description: 'Use Selector for navigation — links should be links, not dropdown options.'},
- {guidance: false, description: 'Use for yes/no or on/off choices — use Switch or CheckboxInput instead.'},
- {guidance: false, description: 'Put more than ~20 options without sections — consider Typeahead for large lists.'},
+ {guidance: false, description: 'Use for action menus; use Dropdown Menu for triggering commands or navigation.'},
+ {guidance: false, description: 'Use when there are only two options; use a SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Use Selector for navigation; links should be links, not dropdown options.'},
+ {guidance: false, description: 'Use for yes/no or on/off choices; use Switch or CheckboxInput instead.'},
+ {guidance: false, description: 'Put more than ~20 options without sections; consider Typeahead for large lists.'},
],
anatomy: [
{name: 'Label', required: false, description: 'Text label displayed above the selector.'},
@@ -350,11 +350,11 @@ export const docsDense = {
{guidance: true, description: 'Provide a visible label so users understand what they are selecting.'},
{guidance: true, description: 'Use sections and dividers to organize options when the list exceeds ~8 items.'},
{guidance: true, description: 'Set a meaningful placeholder that hints at the expected selection (e.g. "Choose a country" not "Select...").'},
- {guidance: false, description: 'Use for action menus — use Dropdown Menu for triggering commands or navigation.'},
- {guidance: false, description: 'Use when there are only two options — use a SegmentedControl or radio buttons instead.'},
- {guidance: false, description: 'Use Selector for navigation — links should be links, not dropdown options.'},
- {guidance: false, description: 'Use for yes/no or on/off choices — use Switch or CheckboxInput instead.'},
- {guidance: false, description: 'Put more than ~20 options without sections — consider Typeahead for large lists.'},
+ {guidance: false, description: 'Use for action menus; use Dropdown Menu for triggering commands or navigation.'},
+ {guidance: false, description: 'Use when there are only two options; use a SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Use Selector for navigation; links should be links, not dropdown options.'},
+ {guidance: false, description: 'Use for yes/no or on/off choices; use Switch or CheckboxInput instead.'},
+ {guidance: false, description: 'Put more than ~20 options without sections; consider Typeahead for large lists.'},
],
anatomy: [
{name: 'Label', required: false, description: 'Text label displayed above the selector.'},
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 2e36c1829a..6edb31a5d2 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -79,7 +79,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={{}}.',
},
], },
{
@@ -258,7 +258,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={{}}.',
},
],
},
@@ -296,8 +296,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
{guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
- {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.'},
- {guidance: false, description: 'Use for filtering content — use tabs or filter buttons instead.'},
+ {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
+ {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
],
anatomy: [
{name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
@@ -567,8 +567,8 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
{guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
- {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.'},
- {guidance: false, description: 'Use for filtering content — use tabs or filter buttons instead.'},
+ {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
+ {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
],
anatomy: [
{name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
@@ -586,8 +586,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
{guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
- {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.'},
- {guidance: false, description: 'Use for filtering content — use tabs or filter buttons instead.'},
+ {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
+ {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
],
anatomy: [
{name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjs
index e454a2483e..48a6a25060 100644
--- a/packages/core/src/Skeleton/Skeleton.doc.mjs
+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs
@@ -44,9 +44,9 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Match the size and shape of the content being loaded to create a realistic placeholder.'},
{guidance: true, description: 'Stagger multiple skeletons with the `index` prop for a natural wave animation.'},
- {guidance: false, description: 'Use when the content dimensions are unknown — use Spinner instead.'},
- {guidance: false, description: 'Combine with a Spinner on the same content area — pick one loading pattern.'},
- {guidance: false, description: 'Show skeletons indefinitely — if loading takes too long, show an error or empty state instead.'},
+ {guidance: false, description: 'Use when the content dimensions are unknown; use Spinner instead.'},
+ {guidance: false, description: 'Combine with a Spinner on the same content area; pick one loading pattern.'},
+ {guidance: false, description: 'Show skeletons indefinitely; if loading takes too long, show an error or empty state instead.'},
],
},
};
@@ -93,9 +93,9 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Match the size and shape of the content being loaded to create a realistic placeholder.'},
{guidance: true, description: 'Stagger multiple skeletons with the `index` prop for a natural wave animation.'},
- {guidance: false, description: 'Use when the content dimensions are unknown — use Spinner instead.'},
- {guidance: false, description: 'Combine with a Spinner on the same content area — pick one loading pattern.'},
- {guidance: false, description: 'Show skeletons indefinitely — if loading takes too long, show an error or empty state instead.'},
+ {guidance: false, description: 'Use when the content dimensions are unknown; use Spinner instead.'},
+ {guidance: false, description: 'Combine with a Spinner on the same content area; pick one loading pattern.'},
+ {guidance: false, description: 'Show skeletons indefinitely; if loading takes too long, show an error or empty state instead.'},
],
},
};
@@ -108,9 +108,9 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Match the size and shape of the content being loaded to create a realistic placeholder.'},
{guidance: true, description: 'Stagger multiple skeletons with the `index` prop for a natural wave animation.'},
- {guidance: false, description: 'Use when the content dimensions are unknown — use Spinner instead.'},
- {guidance: false, description: 'Combine with a Spinner on the same content area — pick one loading pattern.'},
- {guidance: false, description: 'Show skeletons indefinitely — if loading takes too long, show an error or empty state instead.'},
+ {guidance: false, description: 'Use when the content dimensions are unknown; use Spinner instead.'},
+ {guidance: false, description: 'Combine with a Spinner on the same content area; pick one loading pattern.'},
+ {guidance: false, description: 'Show skeletons indefinitely; if loading takes too long, show an error or empty state instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index 41c7127db4..a9eb17858f 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -24,7 +24,7 @@ export const docs = {
name: 'value',
type: 'number | [number, number]',
description:
- 'Current value — a `number` for single thumb mode or `[number, number]` for range mode.',
+ 'Current value: a `number` for single thumb mode or `[number, number]` for range mode.',
required: true,
},
{
@@ -129,7 +129,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: {
@@ -145,8 +145,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
{guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
- {guidance: false, description: 'Use for precise numeric entry — pair with a text input or use NumberInput instead.'},
- {guidance: false, description: 'Set a step size so large that only a few positions are possible — use SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
+ {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
],
},
};
@@ -287,8 +287,8 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
{guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
- {guidance: false, description: 'Use for precise numeric entry — pair with a text input or use NumberInput instead.'},
- {guidance: false, description: 'Set a step size so large that only a few positions are possible — use SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
+ {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
],
},
};
@@ -301,8 +301,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
{guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
- {guidance: false, description: 'Use for precise numeric entry — pair with a text input or use NumberInput instead.'},
- {guidance: false, description: 'Set a step size so large that only a few positions are possible — use SegmentedControl or radio buttons instead.'},
+ {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
+ {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
index c6cff6c5a7..e02b15ebeb 100644
--- a/packages/core/src/Spinner/Spinner.doc.mjs
+++ b/packages/core/src/Spinner/Spinner.doc.mjs
@@ -37,7 +37,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
], theming: {
targets: [
@@ -50,8 +50,8 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
{guidance: true, description: 'Use the "onMedia" shade when placed on dark or accent-colored backgrounds.'},
- {guidance: false, description: 'Use for content areas with known dimensions — use Skeleton to preserve layout instead.'},
- {guidance: false, description: 'Stack multiple spinners in the same view — use one to represent the overall loading state.'},
+ {guidance: false, description: 'Use for content areas with known dimensions; use Skeleton to preserve layout instead.'},
+ {guidance: false, description: 'Stack multiple spinners in the same view; use one to represent the overall loading state.'},
],
},
};
@@ -102,8 +102,8 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
{guidance: true, description: 'Use the "onMedia" shade when placed on dark or accent-colored backgrounds.'},
- {guidance: false, description: 'Use for content areas with known dimensions — use Skeleton to preserve layout instead.'},
- {guidance: false, description: 'Stack multiple spinners in the same view — use one to represent the overall loading state.'},
+ {guidance: false, description: 'Use for content areas with known dimensions; use Skeleton to preserve layout instead.'},
+ {guidance: false, description: 'Stack multiple spinners in the same view; use one to represent the overall loading state.'},
],
},
};
@@ -116,8 +116,8 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
{guidance: true, description: 'Use the "onMedia" shade when placed on dark or accent-colored backgrounds.'},
- {guidance: false, description: 'Use for content areas with known dimensions — use Skeleton to preserve layout instead.'},
- {guidance: false, description: 'Stack multiple spinners in the same view — use one to represent the overall loading state.'},
+ {guidance: false, description: 'Use for content areas with known dimensions; use Skeleton to preserve layout instead.'},
+ {guidance: false, description: 'Stack multiple spinners in the same view; use one to represent the overall loading state.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index cd226ded5d..ee61421426 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -80,7 +80,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={{}}.',
},
], },
{
@@ -184,9 +184,9 @@ export const docs = {
description:
'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
bestPractices: [
- { guidance: true, description: 'Use the gap prop for spacing between items — don\'t add margins manually.' },
+ { guidance: true, description: 'Use the gap prop for spacing between items; don\'t add margins manually.' },
{ guidance: true, description: 'Use XDSStackItem with size="fill" to make one item stretch and fill the leftover space.' },
- { guidance: false, description: 'Nest stacks inside stacks — try wrap="wrap" first to let items flow to the next line.' },
+ { guidance: false, description: 'Nest stacks inside stacks; try wrap="wrap" first to let items flow to the next line.' },
],
},
};
@@ -373,9 +373,9 @@ export const docsZh = {
description:
'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
bestPractices: [
- { guidance: true, description: 'Use the gap prop for spacing between items — don\'t add margins manually.' },
+ { guidance: true, description: 'Use the gap prop for spacing between items; don\'t add margins manually.' },
{ guidance: true, description: 'Use XDSStackItem with size="fill" to make one item stretch and fill the leftover space.' },
- { guidance: false, description: 'Nest stacks inside stacks — try wrap="wrap" first to let items flow to the next line.' },
+ { guidance: false, description: 'Nest stacks inside stacks; try wrap="wrap" first to let items flow to the next line.' },
],
},
};
@@ -387,9 +387,9 @@ export const docsDense = {
description:
'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
bestPractices: [
- { guidance: true, description: 'Use the gap prop for spacing between items — don\'t add margins manually.' },
+ { guidance: true, description: 'Use the gap prop for spacing between items; don\'t add margins manually.' },
{ guidance: true, description: 'Use XDSStackItem with size="fill" to make one item stretch and fill the leftover space.' },
- { guidance: false, description: 'Nest stacks inside stacks — try wrap="wrap" first to let items flow to the next line.' },
+ { guidance: false, description: 'Nest stacks inside stacks; try wrap="wrap" first to let items flow to the next line.' },
],
},
components: [
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
index 300de85099..ab06e8c5fb 100644
--- a/packages/core/src/StatusDot/StatusDot.doc.mjs
+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs
@@ -37,7 +37,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,8 +51,8 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
{ guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
- { guidance: false, description: 'Use the pulse animation for purely decorative purposes — reserve it for states that require immediate attention.' },
- { guidance: false, description: 'Rely on color alone to communicate status — always include text.' },
+ { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
+ { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
],
},
};
@@ -99,8 +99,8 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
{ guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
- { guidance: false, description: 'Use the pulse animation for purely decorative purposes — reserve it for states that require immediate attention.' },
- { guidance: false, description: 'Rely on color alone to communicate status — always include text.' },
+ { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
+ { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
],
},
};
@@ -114,8 +114,8 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
{ guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
- { guidance: false, description: 'Use the pulse animation for purely decorative purposes — reserve it for states that require immediate attention.' },
- { guidance: false, description: 'Rely on color alone to communicate status — always include text.' },
+ { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
+ { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index 8b7a583e2b..b7d05933e7 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -129,10 +129,10 @@ export const docs = {
description:
'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
bestPractices: [
- { guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
+ { guidance: true, description: 'Use for settings that apply immediately; the toggle should take effect without a separate save action.' },
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
- { guidance: false, description: 'Use for options that require a form submission to take effect — use a checkbox instead.' },
- { guidance: false, description: 'Use a switch for multi-state values — it\'s strictly on/off.' },
+ { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
+ { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
],
},
};
@@ -263,10 +263,10 @@ export const docsZh = {
description:
'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
bestPractices: [
- { guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
+ { guidance: true, description: 'Use for settings that apply immediately; the toggle should take effect without a separate save action.' },
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
- { guidance: false, description: 'Use for options that require a form submission to take effect — use a checkbox instead.' },
- { guidance: false, description: 'Use a switch for multi-state values — it\'s strictly on/off.' },
+ { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
+ { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
],
},
};
@@ -278,10 +278,10 @@ export const docsDense = {
description:
'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
bestPractices: [
- { guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
+ { guidance: true, description: 'Use for settings that apply immediately; the toggle should take effect without a separate save action.' },
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
- { guidance: false, description: 'Use for options that require a form submission to take effect — use a checkbox instead.' },
- { guidance: false, description: 'Use a switch for multi-state values — it\'s strictly on/off.' },
+ { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
+ { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 794ad2c3b9..27b8912fd0 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -66,7 +66,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={{}}.',
},
], },
{
@@ -128,7 +128,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={{}}.',
},
],
},
@@ -162,9 +162,9 @@ export const docs = {
{ guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
{ guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
{ guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
- { guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
- { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
- { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
+ { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
+ { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
+ { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
@@ -322,9 +322,9 @@ export const docsZh = {
{ guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
{ guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
{ guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
- { guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
- { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
- { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
+ { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
+ { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
+ { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
@@ -344,9 +344,9 @@ export const docsDense = {
{ guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
{ guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
{ guidance: true, description: 'When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don\u2019t overpower the tab row.' },
- { guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
- { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
- { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
+ { guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },
+ { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },
+ { guidance: false, description: 'Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 51333f75c9..24e3f1f811 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.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={{}}.',
},
],
},