Skip to content

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

TypeScript

docs: replace em/en dashes with standard punctuation in doc prose (#2857)

Joey245009ae0250
diff --git a/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs b/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs
index 1c3a0baecd..ff3f421139 100644
--- a/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs
@@ -26,7 +26,7 @@ export const docs = {
{
name: 'element',
type: 'ReactNode',
- description: 'The dialog element — render this in your JSX tree.',
+ description: 'The dialog element: render this in your JSX tree.',
},
],
};
@@ -38,6 +38,6 @@ export const docsDense = {
show: 'show dialog w/ options; same as XDSAlertDialog props minus isOpen/onOpenChange',
hide: 'hide dialog',
isOpen: 'dialog currently open?',
- element: 'dialog element — render in JSX tree',
+ element: 'dialog element: render in JSX tree',
},
};
diff --git a/packages/core/src/AppShell/useXDSAppShellMobile.doc.mjs b/packages/core/src/AppShell/useXDSAppShellMobile.doc.mjs
index 4116179000..1e1406bc4b 100644
--- a/packages/core/src/AppShell/useXDSAppShellMobile.doc.mjs
+++ b/packages/core/src/AppShell/useXDSAppShellMobile.doc.mjs
@@ -73,7 +73,7 @@ export const docs = {
{
guidance: true,
description:
- 'Prefer XDSMobileNavToggle for the standard hamburger trigger — use this hook when you need custom placement, styling, or extra behavior.',
+ 'Prefer XDSMobileNavToggle for the standard hamburger trigger: use this hook when you need custom placement, styling, or extra behavior.',
},
{
guidance: true,
@@ -83,7 +83,7 @@ export const docs = {
{
guidance: false,
description:
- 'Use as a general responsive primitive when the UI is not inside AppShell or does not need to align with AppShell mobile nav — use useMediaQuery instead.',
+ 'Use as a general responsive primitive when the UI is not inside AppShell or does not need to align with AppShell mobile nav: use useMediaQuery instead.',
},
{
guidance: false,
@@ -141,7 +141,7 @@ export const docsDense = {
{
guidance: false,
description:
- 'Use as general responsive primitive when not inside AppShell / not aligning to AppShell mobile nav — use useMediaQuery instead.',
+ 'Use as general responsive primitive when not inside AppShell / not aligning to AppShell mobile nav: use useMediaQuery instead.',
},
{
guidance: false,
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index 2128ede71c..3b6be4d7dc 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -68,7 +68,7 @@ export const docs = {
{
name: 'variant',
type: "'default' | 'supporting'",
- description: 'Visual variant — supporting is smaller with secondary text styling.',
+ description: 'Visual variant: supporting is smaller with secondary text styling.',
default: "'default'",
},
{
@@ -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={{}}.',
+ description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
},
],
components: [
diff --git a/packages/core/src/Chat/ChatComposer.doc.mjs b/packages/core/src/Chat/ChatComposer.doc.mjs
index 1d3b9cafee..a68894f020 100644
--- a/packages/core/src/Chat/ChatComposer.doc.mjs
+++ b/packages/core/src/Chat/ChatComposer.doc.mjs
@@ -56,7 +56,7 @@ export const docs = {
{
name: 'drawer',
type: 'ReactNode',
- description: 'Slot: collapsible drawer above the input — attachments, context chips, etc. Use XDSChatComposerDrawer.',
+ description: 'Slot: collapsible drawer above the input: attachments, context chips, etc. Use XDSChatComposerDrawer.',
slotElements: [
{
__element: 'XDSText',
@@ -207,7 +207,7 @@ export const docsDense = {
placeholder: 'placeholder when empty',
isDisabled: 'disabled; use during streaming or unmet prereqs',
density: 'visual density',
- drawer: 'slot: collapsible drawer above input — attachments, context chips, etc.; use XDSChatComposerDrawer',
+ drawer: 'slot: collapsible drawer above input: attachments, context chips, etc.; use XDSChatComposerDrawer',
headerActions: 'slot: left header actions (attach, mention); icon-only sm buttons',
headerContext: 'slot: right header context info (window usage, XDSProgressBar, text)',
input: 'slot: custom input; replaces default textarea; use XDSChatComposerInput for triggers',
diff --git a/packages/core/src/Chat/ChatComposerDrawer.doc.mjs b/packages/core/src/Chat/ChatComposerDrawer.doc.mjs
index 5c7e969090..ecdd36e2ae 100644
--- a/packages/core/src/Chat/ChatComposerDrawer.doc.mjs
+++ b/packages/core/src/Chat/ChatComposerDrawer.doc.mjs
@@ -7,12 +7,12 @@ export const docs = {
subComponentOf: 'Chat',
displayName: 'Chat Composer Drawer',
isHiddenFromOverview: true,
- description: "Collapsible drawer panel that sits above the chat input inside XDSChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle — collapsed state shows a badge and label, expanded state shows all children.",
+ description: "Collapsible drawer panel that sits above the chat input inside XDSChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a badge and label, expanded state shows all children.",
props: [
{
name: 'children',
type: 'ReactNode',
- description: 'Content to render inside the drawer — tokens, chips, previews, or any React elements.',
+ description: 'Content to render inside the drawer: tokens, chips, previews, or any React elements.',
required: true,
},
{
@@ -66,7 +66,7 @@ export const docsDense = {
displayName: 'Chat Composer Drawer',
description: 'collapsible drawer above chat input; pass to composer `drawer` slot for attachments, context chips, previews. `count` enables collapse toggle',
propDescriptions: {
- children: 'drawer content — tokens, chips, previews, any React elements',
+ children: 'drawer content: tokens, chips, previews, any React elements',
count: 'total count for collapsed badge; enables collapse/expand toggle',
label: 'collapsed label next to count badge',
isCollapsed: 'controlled collapsed state',
diff --git a/packages/core/src/Chat/ChatComposerInput.doc.mjs b/packages/core/src/Chat/ChatComposerInput.doc.mjs
index 35ab688ac6..dd6e45f696 100644
--- a/packages/core/src/Chat/ChatComposerInput.doc.mjs
+++ b/packages/core/src/Chat/ChatComposerInput.doc.mjs
@@ -12,7 +12,7 @@ export const docs = {
{
name: 'handleRef',
type: 'React.Ref<XDSChatComposerInputHandle>',
- description: 'Imperative handle for programmatic control — insertToken, insertText, focus, and getValue.',
+ description: 'Imperative handle for programmatic control: insertToken, insertText, focus, and getValue.',
},
{
name: 'value',
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index 49d79f1cdb..44cc1f1e70 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -11,13 +11,13 @@ export const docs = {
{
name: 'children',
type: 'ReactNode',
- description: 'Message content — typically XDSChatMessageList. Flows naturally in the page and scrolls with the container.',
+ description: 'Message content: typically XDSChatMessageList. Flows naturally in the page and scrolls with the container.',
required: true,
},
{
name: 'composer',
type: 'ReactNode',
- description: 'Composer element — typically XDSChatComposer. Fixed to the bottom with a frosted glass dock.',
+ description: 'Composer element: typically XDSChatComposer. Fixed to the bottom with a frosted glass dock.',
required: true,
slotElements: [
{
@@ -71,11 +71,11 @@ export const docs = {
},
{
guidance: false,
- description: "Don't apply a fixed height on the layout — let it fill its container with flex: 1.",
+ description: "Don't apply a fixed height on the layout; let it fill its container with flex: 1.",
},
{
guidance: false,
- description: "Don't render multiple ChatLayout instances in the same scroll container — each expects to own its scroll context.",
+ description: "Don't render multiple ChatLayout instances in the same scroll container; each expects to own its scroll context.",
},
],
anatomy: [
diff --git a/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs b/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs
index 02b6a2238a..054e8105e9 100644
--- a/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs
+++ b/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'Chat',
displayName: 'Chat Layout Scroll Button',
isHiddenFromOverview: true,
- description: 'Floating scroll-to-bottom button that appears when the user scrolls away from the latest messages. It fades in as a compact icon button and expands to show a label when new messages arrive. XDSChatLayout renders this by default — pass a custom element to the scrollButton prop to override, or null to hide it entirely.',
+ description: 'Floating scroll-to-bottom button that appears when the user scrolls away from the latest messages. It fades in as a compact icon button and expands to show a label when new messages arrive. XDSChatLayout renders this by default: pass a custom element to the scrollButton prop to override, or null to hide it entirely.',
props: [
{
name: 'isVisible',
@@ -23,7 +23,7 @@ export const docs = {
{
name: 'onClick',
type: '() => void',
- description: 'Click handler — typically scrolls to bottom and dismisses the new message indicator.',
+ description: 'Click handler: typically scrolls to bottom and dismisses the new message indicator.',
required: true,
},
],
@@ -47,7 +47,7 @@ export const docsDense = {
displayName: 'Chat Layout Scroll Button',
description: 'floating scroll-to-bottom btn; fades in when scrolled up, expands w/ label for new msgs. Default in XDSChatLayout; override via scrollButton prop.',
propDescriptions: {
- isVisible: 'btn visibility — bind to scroll-position check',
+ isVisible: 'btn visibility: bind to scroll-position check',
label: 'optional label; expands btn (e.g. "New messages")',
onClick: 'click handler',
},
diff --git a/packages/core/src/Chat/ChatMessage.doc.mjs b/packages/core/src/Chat/ChatMessage.doc.mjs
index ea045b324a..8e8863d420 100644
--- a/packages/core/src/Chat/ChatMessage.doc.mjs
+++ b/packages/core/src/Chat/ChatMessage.doc.mjs
@@ -6,12 +6,12 @@ export const docs = {
name: 'ChatMessage',
subComponentOf: 'Chat',
displayName: 'Chat Message',
- description: 'Sender context wrapper — handles avatar, name, metadata, and alignment based on sender role.',
+ description: 'Sender context wrapper: handles avatar, name, metadata, and alignment based on sender role.',
props: [
{
name: 'sender',
type: "'user' | 'assistant' | 'system'",
- description: 'Who sent this message — controls alignment and layout.',
+ description: 'Who sent this message: controls alignment and layout.',
required: true,
},
{
diff --git a/packages/core/src/Chat/ChatMessageList.doc.mjs b/packages/core/src/Chat/ChatMessageList.doc.mjs
index 00ca9a8c7c..b7a4a2d534 100644
--- a/packages/core/src/Chat/ChatMessageList.doc.mjs
+++ b/packages/core/src/Chat/ChatMessageList.doc.mjs
@@ -12,7 +12,7 @@ export const docs = {
{
name: 'children',
type: 'ReactNode',
- description: 'Message elements — typically XDSChatMessage or XDSChatSystemMessage.',
+ description: 'Message elements: typically XDSChatMessage or XDSChatSystemMessage.',
required: true,
},
{
@@ -32,12 +32,12 @@ export const docs = {
{
name: 'scrollToTopAction',
type: '() => Promise<void>',
- description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.',
+ description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition: shows a spinner at the top while pending.',
},
{
name: 'density',
type: "'compact' | 'balanced' | 'spacious'",
- description: 'Visual density — flows to child messages via context.',
+ description: 'Visual density: flows to child messages via context.',
default: "'balanced'",
},
{
diff --git a/packages/core/src/Chat/ChatMessageMetadata.doc.mjs b/packages/core/src/Chat/ChatMessageMetadata.doc.mjs
index 98fdfc7887..be6b394254 100644
--- a/packages/core/src/Chat/ChatMessageMetadata.doc.mjs
+++ b/packages/core/src/Chat/ChatMessageMetadata.doc.mjs
@@ -11,7 +11,7 @@ export const docs = {
{
name: 'timestamp',
type: 'ReactNode',
- description: 'Timestamp content — a string or XDSTimestamp component.',
+ description: 'Timestamp content: a string or XDSTimestamp component.',
slotElements: [
{
__element: 'XDSText',
@@ -25,7 +25,7 @@ export const docs = {
{
name: 'footer',
type: 'ReactNode',
- description: 'Footer content — model info, reaction buttons, copy button.',
+ description: 'Footer content: model info, reaction buttons, copy button.',
slotElements: [
{
__element: 'XDSText',
diff --git a/packages/core/src/Chat/ChatSendButton.doc.mjs b/packages/core/src/Chat/ChatSendButton.doc.mjs
index 35b33dfe4d..c64adf9e37 100644
--- a/packages/core/src/Chat/ChatSendButton.doc.mjs
+++ b/packages/core/src/Chat/ChatSendButton.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'Chat',
displayName: 'Chat Send Button',
isHiddenFromOverview: true,
- description: 'Circular send/stop toggle button for the chat composer. Place it inside XDSChatComposer where it reads context automatically — no wiring needed. When streaming starts, the button switches from a primary send icon to a secondary stop icon. Override any context value via props for standalone or custom usage.',
+ description: 'Circular send/stop toggle button for the chat composer. Place it inside XDSChatComposer where it reads context automatically: no wiring needed. When streaming starts, the button switches from a primary send icon to a secondary stop icon. Override any context value via props for standalone or custom usage.',
props: [
{
name: 'isStopShown',
@@ -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={{}}.',
+ 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/Chat/ChatSystemMessage.doc.mjs b/packages/core/src/Chat/ChatSystemMessage.doc.mjs
index 6cfbfbb656..fa5b8e459f 100644
--- a/packages/core/src/Chat/ChatSystemMessage.doc.mjs
+++ b/packages/core/src/Chat/ChatSystemMessage.doc.mjs
@@ -6,18 +6,18 @@ export const docs = {
name: 'ChatSystemMessage',
subComponentOf: 'Chat',
displayName: 'Chat System Message',
- description: 'Centered system message for non-sender content like date separators, membership changes, and status notices. It is not a chat bubble — it has no avatar, no alignment, and no sender context. Use the divider variant for temporal breaks and default for inline status updates.',
+ description: 'Centered system message for non-sender content like date separators, membership changes, and status notices. It is not a chat bubble; it has no avatar, no alignment, and no sender context. Use the divider variant for temporal breaks and default for inline status updates.',
props: [
{
name: 'children',
type: 'ReactNode',
- description: 'System message content — a short, factual string like a date, a join/leave notice, or a status change.',
+ description: 'System message content: a short, factual string like a date, a join/leave notice, or a status change.',
required: true,
},
{
name: 'variant',
type: "'default' | 'divider'",
- description: "Visual variant. 'default' renders centered text. 'divider' adds horizontal lines on each side via XDSDivider — use for date separators and section breaks.",
+ description: "Visual variant. 'default' renders centered text. 'divider' adds horizontal lines on each side via XDSDivider: use for date separators and section breaks.",
default: "'default'",
},
{
diff --git a/packages/core/src/Chat/ChatTokenizedText.doc.mjs b/packages/core/src/Chat/ChatTokenizedText.doc.mjs
index b1d4be37ee..a14d660227 100644
--- a/packages/core/src/Chat/ChatTokenizedText.doc.mjs
+++ b/packages/core/src/Chat/ChatTokenizedText.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'Chat',
displayName: 'Chat Tokenized Text',
isHiddenFromOverview: true,
- description: 'Renders a text string with token patterns replaced by inline XDSBadge components. Wrap any message body inside XDSChatMessageBubble to turn raw @mentions, #tags, or /commands into styled badges. When no tokens match or none are provided, the text renders as-is — so you can use ChatTokenizedText unconditionally on every message.',
+ description: 'Renders a text string with token patterns replaced by inline XDSBadge components. Wrap any message body inside XDSChatMessageBubble to turn raw @mentions, #tags, or /commands into styled badges. When no tokens match or none are provided, the text renders as-is: so you can use ChatTokenizedText unconditionally on every message.',
props: [
{
name: 'children',
@@ -18,7 +18,7 @@ export const docs = {
{
name: 'tokens',
type: 'XDSChatComposerToken[]',
- description: 'Token definitions — same type returned by trigger onSelect. Each token has a value (the string to match), label (display text), and optional variant and icon. Uses the same type as the composer input, so token definitions work for both input and display.',
+ description: 'Token definitions: same type returned by trigger onSelect. Each token has a value (the string to match), label (display text), and optional variant and icon. Uses the same type as the composer input, so token definitions work for both input and display.',
},
],
};
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index efaae99f5c..4e635ac591 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -19,7 +19,7 @@ export const docs = {
{className: 'xds-collapsible'},
],
},
- description: 'A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',
+ description: 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',
props: [
{
name: 'trigger',
diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs
index c3ed3071b3..ae206d5250 100644
--- a/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs
@@ -18,7 +18,7 @@ export const docs = {
{
name: 'children',
type: 'ReactNode',
- description: 'Item content — render icons, descriptions, keyboard shortcuts, etc.',
+ description: 'Item content: render icons, descriptions, keyboard shortcuts, etc.',
required: true,
},
{
@@ -75,7 +75,7 @@ export const docsDense = {
description: 'selectable item; arbitrary children; registers w/ context for kbd nav',
propDescriptions: {
value: 'unique id for selection',
- children: 'item content — icons, descriptions, shortcuts',
+ children: 'item content: icons, descriptions, shortcuts',
onSelect: 'called on click or Enter',
isHighlighted: 'keyboard focus; derived from context inside palette',
isSelected: 'selected in picker mode',
diff --git a/packages/core/src/ContextMenu/ContextMenu.doc.mjs b/packages/core/src/ContextMenu/ContextMenu.doc.mjs
index 1e4b34315e..8aaac0762f 100644
--- a/packages/core/src/ContextMenu/ContextMenu.doc.mjs
+++ b/packages/core/src/ContextMenu/ContextMenu.doc.mjs
@@ -26,7 +26,7 @@ export const docs = {
{
name: 'children',
type: 'ReactNode',
- description: 'The trigger area — right-click on this content to open the menu.',
+ description: 'The trigger area: right-click on this content to open the menu.',
required: true,
},
{
@@ -49,7 +49,7 @@ export const docs = {
{
name: 'size',
type: "'sm' | 'md' | 'lg'",
- description: 'Size of menu items — controls padding density.',
+ description: 'Size of menu items: controls padding density.',
default: "'md'",
},
{
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 32b8bb29aa..2b41c4cf01 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -75,7 +75,7 @@ export const docs = {
{
name: 'variant',
type: "'standard' | 'fullscreen'",
- description: 'Dialog variant — fullscreen expands to fill the entire viewport.',
+ description: 'Dialog variant: fullscreen expands to fill the entire viewport.',
default: "'standard'",
},
{
diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs b/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs
index 42c852fa51..18e94b757e 100644
--- a/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs
+++ b/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs
@@ -26,7 +26,7 @@ export const docs = {
{
name: 'element',
type: 'ReactNode',
- description: 'The dialog element — render this in your JSX tree.',
+ description: 'The dialog element: render this in your JSX tree.',
},
],
};
@@ -38,6 +38,6 @@ export const docsDense = {
show: 'show the dialog with given content; options = XDSDialog props minus isOpen/onOpenChange/children',
hide: 'hide the dialog',
isOpen: 'whether the dialog is currently open',
- element: 'the dialog element — render this in your JSX tree',
+ element: 'the dialog element: render this in your JSX tree',
},
};
diff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
index 5821a52f1a..94bea4c3c9 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
@@ -32,7 +32,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={{}}.',
},
],
};
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index ebaa617df3..e5da4d0ac0 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -110,7 +110,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={{}}.',
},
{
name: 'className',
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index 0b30ae5138..183666b582 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -35,7 +35,7 @@ export const docs = {
{
name: 'minChildWidth',
type: 'number',
- description: 'Deprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',
+ description: 'Deprecated: use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',
},
{
name: 'width',
@@ -82,7 +82,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
index 9f7d3497f4..8ea53d376f 100644
--- a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
@@ -33,7 +33,7 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for rich content previews such as user profiles, entity summaries, and link previews.'},
{guidance: true, description: 'Prefer the XDSHoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.'},
- {guidance: false, description: 'Use for simple text hints — use XDSTooltip or useXDSTooltip instead.'},
+ {guidance: false, description: 'Use for simple text hints: use XDSTooltip or useXDSTooltip instead.'},
],
},
relatedComponents: ['HoverCard', 'Tooltip', 'Popover'],
@@ -72,7 +72,7 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for rich previews: profiles, entity summaries, link previews.'},
{guidance: true, description: 'Prefer XDSHoverCard for standard trigger-content pairs; use hook for custom trigger patterns.'},
- {guidance: false, description: 'Use for simple text hints — use XDSTooltip / useXDSTooltip instead.'},
+ {guidance: false, description: 'Use for simple text hints: use XDSTooltip / useXDSTooltip instead.'},
],
},
};
diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjs
index a558c5a8e1..30a5e265cb 100644
--- a/packages/core/src/Item/Item.doc.mjs
+++ b/packages/core/src/Item/Item.doc.mjs
@@ -29,7 +29,7 @@ export const docs = {
{name: 'label', type: 'ReactNode', description: 'Primary text identifying this item. Accepts string (auto-truncated) or ReactNode (for rich content).', required: true},
{name: 'marker', type: 'ReactNode', description: 'Marker rendered before startContent as a direct flex child. Use for list bullets/counters that need custom baseline alignment.'},
{name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'XDSAvatar', props: {name: 'Ada Lovelace', size: 'xsmall'}}, {__element: 'XDSIcon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
- {name: 'description', type: 'ReactNode', description: 'Secondary text — subtitle, description, or supporting info.'},
+ {name: 'description', type: 'ReactNode', description: 'Secondary text: subtitle, description, or supporting info.'},
{name: 'endContent', type: 'ReactNode', description: 'Content rendered after the label/description area, such as badges, metadata, timestamps, or action buttons.', slotElements: [{__element: 'XDSBadge', props: {label: 3}}, {__element: 'XDSText', props: {color: 'secondary'}, children: '2h ago'}]},
{name: 'as', type: "'div' | 'li' | 'span'", description: 'HTML element to render as the root.', default: "'div'"},
{name: 'align', type: "'center' | 'start'", description: 'Vertical alignment of start/end content slots.', default: "'center'"},
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index 0135ff44ac..8a5351cdc9 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -35,7 +35,7 @@ export const docs = {
{
guidance: false,
description:
- 'Add nested XDSLayerProvider instances — nested providers are ignored and add unnecessary tree depth.',
+ 'Add nested XDSLayerProvider instances: nested providers are ignored and add unnecessary tree depth.',
},
],
},
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index 6ef8294340..c8310e7ad6 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -89,7 +89,7 @@ export const docs = {
{
name: 'height',
type: "'fill' | 'auto'",
- description: 'Height behavior — fill the container or grow with content.',
+ description: 'Height behavior: fill the container or grow with content.',
default: "'fill'",
},
],
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 14533cfb4f..3f0541d872 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -64,7 +64,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index 6ddb3883f3..ef810aee9f 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -30,7 +30,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description:
- 'Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.',
+ 'Drawer content: typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.',
required: true,
},
{
@@ -57,7 +57,7 @@ export const docs = {
{
name: 'XDSMobileNavToggle',
displayName: 'Mobile Nav Toggle',
- description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from XDSAppShell context automatically — does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
+ description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from XDSAppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
props: [
{
name: 'children',
@@ -80,12 +80,12 @@ export const docs = {
},
usage: {
description:
- 'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical. Inside XDSAppShell, use XDSMobileNavToggle as the trigger — it reads state from context automatically.',
+ 'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical. Inside XDSAppShell, use XDSMobileNavToggle as the trigger; it reads state from context automatically.',
bestPractices: [
{ guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
{ guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
- { guidance: true, description: 'Inside XDSAppShell, use XDSMobileNavToggle to open the drawer — it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
- { guidance: false, description: 'Use MobileNav on desktop — use a persistent SideNav instead.' },
+ { guidance: true, description: 'Inside XDSAppShell, use XDSMobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
+ { guidance: false, description: 'Use MobileNav on desktop: use a persistent SideNav instead.' },
],
},
};
@@ -145,8 +145,8 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
{ guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
- { guidance: true, description: 'Inside XDSAppShell, use XDSMobileNavToggle to open the drawer — it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
- { guidance: false, description: 'Use MobileNav on desktop — use a persistent SideNav instead.' },
+ { guidance: true, description: 'Inside XDSAppShell, use XDSMobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
+ { guidance: false, description: 'Use MobileNav on desktop: use a persistent SideNav instead.' },
],
},
};
diff --git a/packages/core/src/Popover/useXDSPopover.doc.mjs b/packages/core/src/Popover/useXDSPopover.doc.mjs
index d3d2c1dd49..434aa13321 100644
--- a/packages/core/src/Popover/useXDSPopover.doc.mjs
+++ b/packages/core/src/Popover/useXDSPopover.doc.mjs
@@ -34,7 +34,7 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for interactive content such as menus, pickers, forms, and command panels that need focus management.'},
{guidance: true, description: 'Prefer the XDSPopover component for standard trigger-content pairs; use the hook for custom trigger patterns.'},
- {guidance: false, description: 'Use for non-interactive hover previews — use useXDSHoverCard or useXDSTooltip instead.'},
+ {guidance: false, description: 'Use for non-interactive hover previews: use useXDSHoverCard or useXDSTooltip instead.'},
],
},
relatedComponents: ['Popover', 'DropdownMenu', 'HoverCard'],
@@ -74,7 +74,7 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for menus, pickers, forms, command panels needing focus management.'},
{guidance: true, description: 'Prefer XDSPopover for standard trigger-content pairs; use hook for custom trigger patterns.'},
- {guidance: false, description: 'Use for non-interactive hover previews — use useXDSHoverCard / useXDSTooltip instead.'},
+ {guidance: false, description: 'Use for non-interactive hover previews: use useXDSHoverCard / useXDSTooltip instead.'},
],
},
};
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index cd514f2e7f..9e732140dd 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -105,7 +105,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 242dd511b6..2fad76a85c 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -83,7 +83,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index 62b545a629..1420cf1135 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -25,7 +25,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}).',
+ description: 'Array of items: strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
required: true,
},
{
@@ -106,7 +106,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 8c96463d3d..c9665a5d17 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -110,7 +110,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/SideNav/SideNavSection.doc.mjs b/packages/core/src/SideNav/SideNavSection.doc.mjs
index d9100590f2..95398f0e9d 100644
--- a/packages/core/src/SideNav/SideNavSection.doc.mjs
+++ b/packages/core/src/SideNav/SideNavSection.doc.mjs
@@ -62,7 +62,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={{}}.',
},
],
};
diff --git a/packages/core/src/TabList/Tab.doc.mjs b/packages/core/src/TabList/Tab.doc.mjs
index 002ea8c945..24e926d665 100644
--- a/packages/core/src/TabList/Tab.doc.mjs
+++ b/packages/core/src/TabList/Tab.doc.mjs
@@ -97,7 +97,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={{}}.',
},
],
};
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 63d9067111..ac6f1be87d 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -67,7 +67,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 8b3b07591f..bf3805f338 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -40,7 +40,7 @@ export const docs = {
{
name: 'columns',
type: 'XDSTableColumn<T>[]',
- description: 'Column definitions — each column has {key, header, width?, align?, renderCell?}. The `header` field sets the column heading text. If omitted, columns are auto-generated from data object keys.',
+ description: 'Column definitions: each column has {key, header, width?, align?, renderCell?}. The `header` field sets the column heading text. If omitted, columns are auto-generated from data object keys.',
},
{
name: 'idKey',
@@ -79,12 +79,12 @@ export const docs = {
{
name: 'children',
type: 'ReactNode',
- description: 'Children mode — render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.',
+ description: 'Children mode: render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.',
},
{
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={{}}.',
},
],
components: [
diff --git a/packages/core/src/Table/useXDSTableFiltering.doc.mjs b/packages/core/src/Table/useXDSTableFiltering.doc.mjs
index b5d859a760..b47a254bcb 100644
--- a/packages/core/src/Table/useXDSTableFiltering.doc.mjs
+++ b/packages/core/src/Table/useXDSTableFiltering.doc.mjs
@@ -12,7 +12,7 @@ export const docs = {
{
name: 'filters',
type: 'XDSTableFilterState',
- description: 'Current filter state — map from column key to filter value.',
+ description: 'Current filter state: map from column key to filter value.',
required: true,
},
{
@@ -61,7 +61,7 @@ export const docsDense = {
name: 'useXDSTableFiltering',
isHiddenFromOverview: true,
displayName: 'useXDSTableFiltering',
- description: 'Table filtering plugin — inline column filters (popover/inline). Pairs w/ useXDSTableFilterState.',
+ description: 'Table filtering plugin: inline column filters (popover/inline). Pairs w/ useXDSTableFilterState.',
propDescriptions: {
filters: 'Current filter state map (columnKey → value).',
onFilterChange: 'Called on filter change. null clears.',
diff --git a/packages/core/src/Table/useXDSTableSelectionState.doc.mjs b/packages/core/src/Table/useXDSTableSelectionState.doc.mjs
index 2b690ae180..e3396d4d16 100644
--- a/packages/core/src/Table/useXDSTableSelectionState.doc.mjs
+++ b/packages/core/src/Table/useXDSTableSelectionState.doc.mjs
@@ -6,7 +6,7 @@ export const docs = {
name: 'useXDSTableSelectionState',
subComponentOf: 'Table',
displayName: 'useXDSTableSelectionState',
- description: 'State management companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.',
+ description: 'State management companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically: disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.',
props: [
{
name: 'data',
@@ -17,7 +17,7 @@ export const docs = {
{
name: 'idKey',
type: '(keyof T & string) | ((item: T) => string)',
- description: 'Key extractor — property name or function returning a unique string ID.',
+ description: 'Key extractor: property name or function returning a unique string ID.',
required: true,
},
{
@@ -41,7 +41,7 @@ export const docs = {
{
name: 'getIsItemEnabled',
type: '(item: T) => boolean',
- description: 'Is this row checkbox interactive? Disabled rows are frozen — select-all preserves their state.',
+ description: 'Is this row checkbox interactive? Disabled rows are frozen: select-all preserves their state.',
default: '() => true',
},
],
@@ -50,13 +50,13 @@ export const docs = {
export const docsDense = {
name: 'useXDSTableSelectionState',
displayName: 'useXDSTableSelectionState',
- description: 'State companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows frozen (state preserved across select-all/deselect-all), non-selectable rows excluded.',
+ description: 'State companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically: disabled rows frozen (state preserved across select-all/deselect-all), non-selectable rows excluded.',
propDescriptions: {
data: 'Full data array rendered in table. **(required)**',
- idKey: 'Key extractor — property name or fn returning unique string ID. **(required)**',
+ idKey: 'Key extractor: property name or fn returning unique string ID. **(required)**',
selectedKeys: 'Controlled set of selected item IDs. **(required)**',
setSelectedKeys: 'Setter for controlled selected keys. **(required)**',
getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows excluded from select-all. Defaults to () => true.',
- getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows frozen — select-all preserves their state. Defaults to () => true.',
+ getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows frozen: select-all preserves their state. Defaults to () => true.',
},
};
diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjs
index abf9cfedb7..ae87574766 100644
--- a/packages/core/src/Text/Heading.doc.mjs
+++ b/packages/core/src/Text/Heading.doc.mjs
@@ -6,12 +6,12 @@ export const docs = {
name: 'Heading',
subComponentOf: 'Text',
displayName: 'Heading',
- description: 'Semantic heading component that renders h1–h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.',
+ description: 'Semantic heading component that renders h1-h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.',
props: [
{
name: 'level',
type: '1 | 2 | 3 | 4 | 5 | 6',
- description: 'Heading level. Determines the semantic HTML element (h1–h6) and the visual styling from the theme (unless `type` is set).',
+ description: 'Heading level. Determines the semantic HTML element (h1-h6) and the visual styling from the theme (unless `type` is set).',
required: true,
},
{
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 6a97c3f801..9446ea2424 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -108,7 +108,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
index a1aa15715a..4058208b24 100644
--- a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
+++ b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
@@ -31,7 +31,7 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.'},
{guidance: true, description: 'Prefer the XDSTooltip component for standard wrapping; use the hook when the trigger is not a simple child.'},
- {guidance: false, description: 'Put interactive content inside tooltips — use Popover or HoverCard instead.'},
+ {guidance: false, description: 'Put interactive content inside tooltips: use Popover or HoverCard instead.'},
],
},
relatedComponents: ['Tooltip', 'HoverCard', 'Popover'],
@@ -68,7 +68,7 @@ export const docsDense = {
bestPractices: [
{guidance: true, description: 'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.'},
{guidance: true, description: 'Prefer XDSTooltip for standard wrapping; use hook when trigger is not simple child.'},
- {guidance: false, description: 'Put interactive content in tooltips — use Popover / HoverCard instead.'},
+ {guidance: false, description: 'Put interactive content in tooltips: use Popover / HoverCard instead.'},
],
},
};
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index f9cbba85ab..7eb323f231 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -30,7 +30,7 @@ export const docs = {
{
name: 'heading',
type: 'ReactNode',
- description: 'Heading slot content (logo, brand) — positioned at the left edge of the nav bar.',
+ description: 'Heading slot content (logo, brand): positioned at the left edge of the nav bar.',
slotElements: [
{
__element: 'XDSText',
@@ -45,7 +45,7 @@ export const docs = {
{
name: 'startContent',
type: 'ReactNode',
- description: 'Start content slot for navigation items or breadcrumbs — positioned after the heading, left-aligned.',
+ description: 'Start content slot for navigation items or breadcrumbs: positioned after the heading, left-aligned.',
slotElements: [
{
__element: 'XDSIcon',
@@ -73,7 +73,7 @@ export const docs = {
{
name: 'centerContent',
type: 'ReactNode',
- description: 'Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering.',
+ description: 'Center content slot (tabs, search bar, primary navigation): when provided, switches the layout to a three-column CSS grid for true horizontal centering.',
slotElements: [
{
__element: 'XDSText',
@@ -88,7 +88,7 @@ export const docs = {
{
name: 'endContent',
type: 'ReactNode',
- description: 'End content slot for search, icons, or user profile — positioned at the right edge.',
+ description: 'End content slot for search, icons, or user profile: positioned at the right edge.',
slotElements: [
{
__element: 'XDSIcon',
@@ -113,7 +113,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/TopNav/TopNavHeading.doc.mjs b/packages/core/src/TopNav/TopNavHeading.doc.mjs
index 0ea537587e..b80ae2cfd6 100644
--- a/packages/core/src/TopNav/TopNavHeading.doc.mjs
+++ b/packages/core/src/TopNav/TopNavHeading.doc.mjs
@@ -36,7 +36,7 @@ export const docs = {
{
name: 'href',
type: 'string',
- description: 'Deprecated — use headingHref instead. URL to navigate to when clicked.',
+ description: 'Deprecated: use headingHref instead. URL to navigate to when clicked.',
},
{
name: 'superheading',
@@ -179,7 +179,7 @@ export const docsDense = {
logo: 'Logo before heading text. Image, XDSNavIcon, or ReactNode.',
heading: 'Product/app name.',
headingHref: 'Link for heading (product home). Only href + no menu → whole heading is link.',
- href: 'Deprecated — use headingHref.',
+ href: 'Deprecated: use headingHref.',
superheading: 'Text above heading (suite name). Smaller secondary style.',
superheadingHref: 'Link for superheading. Independent inline link when menu present.',
subheading: 'Text below heading (account context). Smaller secondary style.',
diff --git a/packages/core/src/TopNav/TopNavItem.doc.mjs b/packages/core/src/TopNav/TopNavItem.doc.mjs
index 4691e7836a..43f636c1cf 100644
--- a/packages/core/src/TopNav/TopNavItem.doc.mjs
+++ b/packages/core/src/TopNav/TopNavItem.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
subComponentOf: 'TopNav',
displayName: 'Top Nav Item',
isHiddenFromOverview: true,
- description: 'Navigation link item for use in XDSTopNav startContent — renders as an anchor with hover and selected states.',
+ description: 'Navigation link item for use in XDSTopNav startContent: renders as an anchor with hover and selected states.',
props: [
{
name: 'label',
diff --git a/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs b/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs
index e0130fbf85..e9b83c16cb 100644
--- a/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs
+++ b/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs
@@ -17,7 +17,7 @@ export const docs = {
{
name: 'items',
type: 'ReactNode',
- description: 'Menu items slot — typically XDSTopNavMegaMenuItem components, but accepts any ReactNode.',
+ description: 'Menu items slot: typically XDSTopNavMegaMenuItem components, but accepts any ReactNode.',
slotElements: [
{
__element: 'XDSTopNavItem',
@@ -31,7 +31,7 @@ export const docs = {
{
name: 'featured',
type: 'ReactNode',
- description: 'Featured content slot — rendered in the right panel on desktop, below items in the mobile drawer.',
+ description: 'Featured content slot: rendered in the right panel on desktop, below items in the mobile drawer.',
slotElements: [
{
__element: 'XDSCard',
@@ -109,8 +109,8 @@ export const docsDense = {
description: 'Nav item w/ full-width mega menu panel on hover. Slots API w/ items+featured ReactNode props. Mobile drawer inline collapsible.',
propDescriptions: {
label: 'Trigger button visible label.',
- items: 'Menu items slot — typically XDSTopNavMegaMenuItem, accepts any ReactNode.',
- featured: 'Featured content slot — right panel desktop, below items in drawer.',
+ items: 'Menu items slot: typically XDSTopNavMegaMenuItem, accepts any ReactNode.',
+ featured: 'Featured content slot: right panel desktop, below items in drawer.',
delay: 'Show delay ms on hover.',
hideDelay: 'Hide delay ms after mouse leaves.',
onOpenChange: 'Fired on open/close. For coordinating wrapper styles.',
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 78c9a3d883..b55f76a7ae 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -138,7 +138,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={{}}.',
},
],
components: [
diff --git a/packages/core/src/theme/MediaTheme.doc.mjs b/packages/core/src/theme/MediaTheme.doc.mjs
index 0bb82410ab..3258725398 100644
--- a/packages/core/src/theme/MediaTheme.doc.mjs
+++ b/packages/core/src/theme/MediaTheme.doc.mjs
@@ -68,7 +68,7 @@ export const docs = {
{
guidance: true,
description:
- 'Pair with a background color — MediaTheme flips the token context but does not add a background. Set backgroundColor on the parent element.',
+ 'Pair with a background color: MediaTheme flips the token context but does not add a background. Set backgroundColor on the parent element.',
},
{
guidance: true,
@@ -78,7 +78,7 @@ export const docs = {
{
guidance: false,
description:
- 'Use MediaTheme for app-level dark mode — use XDSTheme with mode="dark" or mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.',
+ 'Use MediaTheme for app-level dark mode: use XDSTheme with mode="dark" or mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.',
},
],
},
@@ -88,7 +88,7 @@ export const docs = {
type: "'dark' | 'light'",
required: true,
description:
- 'Surface luminance context — dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions).',
+ 'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions).',
},
{
name: 'children',
@@ -114,7 +114,7 @@ export const docsDense = {
{
guidance: true,
description:
- 'Pair w/ background color — MediaTheme flips token context but does NOT add background. Set backgroundColor on parent element.',
+ 'Pair w/ background color: MediaTheme flips token context but does NOT add background. Set backgroundColor on parent element.',
},
{
guidance: true,
@@ -124,7 +124,7 @@ export const docsDense = {
{
guidance: false,
description:
- 'Use MediaTheme for app-level dark mode — use XDSTheme w/ mode="dark"/mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.',
+ 'Use MediaTheme for app-level dark mode: use XDSTheme w/ mode="dark"/mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.',
},
],
},
diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjs
index 40e8502eb7..3b3fd1caad 100644
--- a/packages/core/src/theme/SyntaxTheme.doc.mjs
+++ b/packages/core/src/theme/SyntaxTheme.doc.mjs
@@ -47,12 +47,12 @@ export const docs = {
{
guidance: true,
description:
- 'Syntax themes support light-dark() tuples — each token can have different values for light and dark mode, resolved automatically by the color scheme.',
+ 'Syntax themes support light-dark() tuples: each token can have different values for light and dark mode, resolved automatically by the color scheme.',
},
{
guidance: false,
description:
- 'Wrap individual CodeBlock instances with XDSSyntaxTheme — use the syntaxTheme prop on XDSCodeBlock directly for per-instance overrides.',
+ 'Wrap individual CodeBlock instances with XDSSyntaxTheme: use the syntaxTheme prop on XDSCodeBlock directly for per-instance overrides.',
},
],
},
@@ -62,7 +62,7 @@ export const docs = {
type: 'SyntaxTheme',
required: true,
description:
- 'Syntax highlighting theme — a preset from @xds/core/theme/syntax or a custom theme created with defineSyntaxTheme().',
+ 'Syntax highlighting theme: a preset from @xds/core/theme/syntax or a custom theme created with defineSyntaxTheme().',
},
{
name: 'children',
@@ -93,17 +93,17 @@ export const docsDense = {
{
guidance: true,
description:
- 'Syntax themes support light-dark() tuples — each token can have different values for light/dark mode, resolved automatically by color scheme.',
+ 'Syntax themes support light-dark() tuples: each token can have different values for light/dark mode, resolved automatically by color scheme.',
},
{
guidance: false,
description:
- 'Wrap individual CodeBlock instances w/ XDSSyntaxTheme — use syntaxTheme prop on XDSCodeBlock directly for per-instance overrides instead.',
+ 'Wrap individual CodeBlock instances w/ XDSSyntaxTheme: use syntaxTheme prop on XDSCodeBlock directly for per-instance overrides instead.',
},
],
},
propDescriptions: {
theme:
- 'syntax highlighting theme — preset from @xds/core/theme/syntax or custom theme created w/ defineSyntaxTheme(). **(required)**',
+ 'syntax highlighting theme: preset from @xds/core/theme/syntax or custom theme created w/ defineSyntaxTheme(). **(required)**',
},
};
diff --git a/packages/core/src/theme/useXDSTheme.doc.mjs b/packages/core/src/theme/useXDSTheme.doc.mjs
index 1d63b84a97..78c646393d 100644
--- a/packages/core/src/theme/useXDSTheme.doc.mjs
+++ b/packages/core/src/theme/useXDSTheme.doc.mjs
@@ -73,7 +73,7 @@ export const docs = {
{
guidance: false,
description:
- 'Hardcode light/dark colors in data visualizations — resolve them through the current theme instead.',
+ 'Hardcode light/dark colors in data visualizations: resolve them through the current theme instead.',
},
{
guidance: false,
@@ -122,7 +122,7 @@ export const docsDense = {
},
{
guidance: false,
- description: 'Hardcode light/dark chart colors — resolve from current theme.',
+ description: 'Hardcode light/dark chart colors: resolve from current theme.',
},
{
guidance: false,