Skip to content

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

TypeScript

feat(docs-types): add UsageDoc and AnatomyElement types (#1231)

Joey7232143e795c
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index 141567491f..a140e1631f 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -108,6 +108,26 @@ export function formatFull(docs, options = {}) {
sections.push(`# ${docs.name}\n`);
sections.push(docs.description + '\n');
+ if (docs.usage) {
+ sections.push('## Usage\n');
+ if (docs.usage.summary) {
+ sections.push(docs.usage.summary + '\n');
+ }
+ if (docs.usage.content) {
+ sections.push(docs.usage.content + '\n');
+ }
+ if (docs.usage.anatomy?.length) {
+ sections.push('### Anatomy\n');
+ sections.push('| Element | Required | Description |');
+ sections.push('|---------|----------|-------------|');
+ for (const el of docs.usage.anatomy) {
+ const req = el.required ? 'Yes' : 'No';
+ sections.push(`| ${el.name} | ${req} | ${el.description} |`);
+ }
+ sections.push('');
+ }
+ }
+
if (docs.features?.length) {
sections.push('## Features\n');
sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
@@ -263,6 +283,16 @@ export function formatCompact(docs, componentName, importHint) {
sections.push(`# ${docs.name}\n`);
sections.push(docs.description + '\n');
+ if (docs.usage?.summary) {
+ sections.push(docs.usage.summary + '\n');
+ }
+ if (docs.usage?.anatomy?.length) {
+ sections.push('Anatomy: ' + docs.usage.anatomy.map(el => {
+ const req = el.required ? '' : ' (optional)';
+ return `${el.name}${req}`;
+ }).join(', ') + '\n');
+ }
+
// Import statement
if (importHint) {
sections.push('## Import\n');
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index d359de4aec..a58191d79c 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -280,6 +280,9 @@ const isMobile = useMediaQuery('(max-width: 768px)');
'In "auto" height mode, TopNav gets position: sticky; top: 0 and SideNav gets position: sticky; top: <header-height>.',
'In "fill" height mode, the shell fills 100dvh, TopNav is pinned at the top, and both the SideNav and content area have independent scroll containers.',
],
+ usage: {
+ summary: 'Application-level layout shell providing header, side navigation, and main content area.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
index 02caeff26f..c24c58da5a 100644
--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs
+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
@@ -54,6 +54,9 @@ export const docs = {
{className: 'xds-aspect-ratio'},
],
},
+ usage: {
+ summary: 'Maintains a specific aspect ratio for its children, useful for responsive media containers.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index d33706c6d1..d6d080ce8f 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -150,6 +150,14 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Displays a user profile picture with automatic fallback to initials when no image is available.',
+ content: `## When to use
+
+- Representing a user or entity visually.
+- Showing a profile image alongside user information.
+- Displaying a fallback when no image is provided.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
index b43c1b6aeb..648e13f118 100644
--- a/packages/core/src/Badge/Badge.doc.mjs
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -52,6 +52,51 @@ export const docs = {
{className: 'xds-badge', visualProps: ['variant']},
],
},
+ usage: {
+ summary: 'Badges display system or categorical information, helping users quickly identify the state of a system, process, or entity, or group items into meaningful categories.',
+ content: `## When to use
+
+Badges provide users with clear information about the current or upcoming state of a system, process, or categorization, enabling users to take necessary actions.
+
+There are two types of badges:
+
+- **System status**: Indicate the current, dynamic state of a system, process, or entity. Use semantic colors to convey critical information (e.g., error, warning, success, or active states).
+- **Categorical**: Group objects, processes, or entities into static categories. Use non-semantic colors to provide visual distinction without implying criticality.
+
+## When NOT to use
+
+- Don't use badges as filters. Use interactive filters or tabs instead.
+- Don't use badges to highlight or draw attention to text. Use plain text for information that doesn't require scanning.
+
+## Best practices
+
+### Color usage
+
+- Do: Use semantic (system status) colors to convey statuses such as active, success, error, or warning.
+- Don't: Use categorical colors for system status, as they may not draw enough attention.
+- Do: Use non-semantic colors to categorize information.
+- Don't: Use system status colors for categorization.
+- Do: Use color to draw attention to badges that require user action. Use the default badge color for non-actionable items.
+- Don't: Overuse color.
+
+### Icons and labels
+
+- Do: Always pair icons with a clear label.
+- Don't: Use icon-only badges, as they can be ambiguous.
+- Do: Use concise labels (fewer than 3 words).
+- Don't: Use more than 3 words in a badge.
+
+## Placement
+
+- **Headers**: Provide additional context in page or section headers.
+- **List items**: Annotate items within lists.
+- **Tables**: Highlight specific rows or cells.
+- **Tabs and menus**: Annotate tabs or menu items.`,
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
+ {name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index 3d7836a9e2..75b6f863fd 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -129,6 +129,30 @@ export const docs = {
'Banner uses `status` as its extensible theming axis. Custom statuses via `defineTheme` components: `status:neutral`.',
'Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',
],
+ usage: {
+ summary: 'Displays a prominent message and related actions to communicate critical or non-critical information.',
+ content: `## When to use
+
+- To communicate critical or non-critical information at the top of a page, below headers, or in card format.
+
+## Best practices
+
+- Do: Display the action on both the banner and the page.
+- Do: Keep titles and descriptions to 1\u20132 lines.
+- Do: Default to the collapsed state.
+- Don't: Replace user actions on the page \u2014 banners are temporary.
+- Don't: Add lengthy content.
+- Don't: Use expanded as the default state.`,
+ anatomy: [
+ {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
+ {name: 'Heading', required: false, description: 'Required if no description is provided.'},
+ {name: 'Description', required: false, description: 'Required if no heading is provided.'},
+ {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},
+ {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},
+ {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},
+ {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index cbc3435a18..f9a87b9cb3 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -174,6 +174,14 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'A secondary form of navigation that orients the user within a hierarchy.',
+ content: `## When to use
+
+- To show the user's position relative to the product architecture.
+- To enable quick back-and-forth navigation.
+- To organize content hierarchy of 2 or more levels.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 56515eac7b..d063e7d894 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -189,6 +189,42 @@ export const docs = {
'type defaults to "button" (not "submit") to prevent accidental form submission.',
'Disabled background gradient is cleared (backgroundImage: none) to prevent hover tint leaking through opacity.',
],
+ usage: {
+ summary: 'Buttons provide visual cues for actions and events, allowing users to commit actions and navigate a page flow.',
+ content: `## When to use
+
+- Submit a form.
+- Start a new task or action.
+- Trigger a new UI element to appear on the page.
+
+## Variants
+
+- **Secondary**: The standard button for most actions.
+- **Ghost**: Use when you need to limit the visual prominence of a button.
+- **Primary**: Use to draw emphasis to the primary action. A layout should only contain a single primary button.
+- **Destructive**: Use when the resulting action is the deletion of an object. Destructive buttons should trigger a confirmation dialog before the action is completed.
+
+## Best practices
+
+Do:
+- Convey clear action hierarchy: each surface should only have one primary button. Most buttons should use the secondary or ghost variant.
+- Use sentence case and no punctuation for labels.
+- Provide the logical next step in a task.
+- Use only one call-to-action per button.
+- Use an informative tone. Don't editorialize in a button.
+
+Don't:
+- Overuse primary buttons. Overusing colored buttons creates visual confusion and undermines page hierarchy.
+- Use all uppercase or all lowercase text.
+- Mix sizes in a single row.
+- Add custom gradients, drop shadows, or custom padding.`,
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A leading icon that visually represents the meaning of the button label.'},
+ {name: 'Label', required: true, description: 'A text label describing the button action. Required for accessibility.'},
+ {name: 'End content', required: false, description: 'Trailing content that provides affordance to the type of action performed. Recommended when the expected action is non-obvious.'},
+ {name: 'Spinner', required: false, description: 'Indicates a loading state when the button action is not immediate.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 98f456391f..f91f8e7115 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -140,6 +140,9 @@ export const docs = {
'Outside days (adjacent month) are rendered with aria-disabled="true" and ignore clicks',
'Day cell transitions are suppressed under @media (prefers-reduced-motion: reduce)',
],
+ usage: {
+ summary: 'A calendar component for date selection supporting single and range selection modes.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 43eff87b5f..027b7b81be 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -123,6 +123,27 @@ export const docs = {
},
],
},
+ usage: {
+ summary: 'Groups similar information inside containers for visual organization.',
+ content: `## When to use
+
+- When explicit grouping of related information is needed.
+- When browsing and scanning content is frequent.
+
+## Best practices
+
+- Do: Use whitespace, type scale, and dividers with cards.
+- Do: Prioritize sections as the default; use cards only for stronger visual distinction.
+- Don't: Exclusively use cards, as it diminishes visual hierarchy.
+- Don't: Use cards for primary content unless stronger visual separation is needed.
+- Start with sections; escalate to cards only when additional distinction is required.
+- Card elevation adapts automatically based on the background surface.`,
+ anatomy: [
+ {name: 'Card Header', required: false, description: 'Displays a title and optional end content.'},
+ {name: 'Card Body', required: true, description: 'Accepts any content.'},
+ {name: 'Card Footer', required: false, description: 'Contains actions.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjs
index cb175a47aa..f793333d91 100644
--- a/packages/core/src/Center/Center.doc.mjs
+++ b/packages/core/src/Center/Center.doc.mjs
@@ -69,6 +69,9 @@ export const docs = {
{className: 'xds-center', visualProps: ['axis']},
],
},
+ usage: {
+ summary: 'Centers children horizontally and/or vertically using flexbox.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index f07ed6e259..66ea465271 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -170,6 +170,9 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Chat components for building AI chat interfaces, including message lists, message bubbles, and a composer.',
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 4e0580e345..197c0c6639 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -199,6 +199,13 @@ export const docs = {
'Focus outline uses the standard XDS focus ring token.',
'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling.',
],
+ usage: {
+ summary: 'A checkbox input for toggling boolean values.',
+ content: `## When to use
+
+- Toggling a single boolean setting.
+- Selecting multiple options from a set (use CheckboxList for groups).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index 565e3c6b29..9f28952777 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -256,6 +256,18 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'A checkbox group for multi-value selection from a list of options.',
+ content: `## When to use
+
+- Users need to select multiple options from a set.
+- All options should be visible at once.
+
+## When NOT to use
+
+- Only one option can be selected (use RadioList instead).
+- The option list is very long (consider MultiSelector instead).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 58852135f4..28f844a78b 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -219,6 +219,13 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Contains information that may need additional space to display.',
+ content: `## When to use
+
+- Presenting additional information for items in a list.
+- Content that can be hidden to save space and revealed on demand.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index e5e0217de7..9a199a5719 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -199,6 +199,12 @@ export const docs = {
{className: 'xds-date-input', visualProps: ['size']},
],
},
+ usage: {
+ summary: 'Field formatted for users to input a date.',
+ content: `## When to use
+
+- User needs to input a date (e.g. scheduling events, form submissions).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 2400214d23..d9553f2a6d 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -257,6 +257,32 @@ function Example() {
],
},
],
+ usage: {
+ summary: 'A top-level dialog that communicates important information and pauses the user\'s workflow.',
+ content: `## When to use
+
+- Pause a user's workflow to communicate top-level information.
+- Guide users through multi-step workflows.
+- Surface information that requires acknowledgement.
+- Present confirmations before destructive actions.
+
+## Best practices
+
+- Do: Include a back arrow for two-view dialogs.
+- Do: Include a step count indicator for dialogs with 3 or more views.
+- Don't: Remove all dismissal behaviors.
+- Use sentence case for dialog content.
+- Match the call-to-action label to the dialog headline.
+- Number steps in multi-step dialogs.
+- Dismissal types: informational (all exit methods), form (disable click-outside), required (only footer buttons).`,
+ anatomy: [
+ {name: 'Body', required: true, description: 'The main content area of the dialog.'},
+ {name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},
+ {name: 'Footer', required: true, description: 'Contains action buttons, links, and page count.'},
+ {name: 'Left Panel', required: false, description: 'Used for navigation or completion stages.'},
+ {name: 'Right Panel', required: false, description: 'Used for supplementary information.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjs
index a15892c2b5..655368ce17 100644
--- a/packages/core/src/Divider/Divider.doc.mjs
+++ b/packages/core/src/Divider/Divider.doc.mjs
@@ -72,6 +72,26 @@ export const docs = {
{className: 'xds-divider', visualProps: ['orientation', 'variant']},
],
},
+ usage: {
+ summary: 'Separates different pieces of content.',
+ content: `## When to use
+
+- Standard level: subtle hairlines to demote sections or regions.
+- Emphasized level: critical visual lines for chart axes or input borders.
+- High contrast level: strong visual separation.
+
+## When NOT to use
+
+- Emphasized dividers for sectional distinction \u2014 use standard instead.
+- Standard dividers for critical content boundaries \u2014 use emphasized instead.
+
+## Best practices
+
+- Do: Use standard dividers for demoting sections and regions.
+- Do: Use emphasized dividers for interactive element boundaries.
+- Don't: Use emphasized dividers for sectional distinction.
+- Don't: Use standard dividers for critical content boundaries.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index e53e3e9cd3..a2224e5668 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -333,6 +333,13 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Shows options for actions in a dropdown list.',
+ content: `## When to use
+
+- To present different action options as a next step in a process.
+- As sub-navigation to guide users to a next destination.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index 50b7e7f0c4..ba7f27a23e 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -101,6 +101,26 @@ export const docs = {
'Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',
'Title renders as a heading element (h1-h6 via headingLevel prop, default h3), keeping it in the document heading outline.',
],
+ usage: {
+ summary: 'Provides guidance and context when there is no data to display.',
+ content: `## When to use
+
+- Null states when no content exists yet.
+- Failed loading states.
+- When search or filter results return nothing.
+
+## Best practices
+
+- Do: Be clear and direct with messaging.
+- Do: Use simple language and provide context.
+- Do: Offer a next step so users know how to proceed.`,
+ anatomy: [
+ {name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
+ {name: 'Title', required: true, description: 'Primary message explaining the empty state.'},
+ {name: 'Subtitle', required: false, description: 'Additional context or explanation.'},
+ {name: 'Call to action', required: false, description: 'Buttons guiding the user to a next step.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 818b672ec8..14a9cc4287 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -311,6 +311,12 @@ const bioDescId = useId();
],
},
],
+ usage: {
+ summary: 'A form field wrapper that provides label, description, and optional/required indicators around an input.',
+ content: `## When to use
+
+- Wrapping input components in forms to provide consistent labels, descriptions, and validation states.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index b5247abbd3..316f1cdd3e 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -89,6 +89,38 @@ export const docs = {
'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',
'Also accepts standard HTML div attributes (id, role, aria-*, etc.) via rest props.',
],
+ usage: {
+ summary: 'Wraps input components to collect structured user input with validation and confirmation.',
+ content: `## When to use
+
+- Sign-in flows.
+- Creating or editing objects.
+- Submitting orders.
+- Changing settings.
+
+## When NOT to use
+
+- One-off confirmations.
+- Quick inline tweaks.
+- Navigation or search.
+
+## Best practices
+
+- Do: Use a single column layout.
+- Don't: Use a multi-column layout.
+- Do: Keep text width between 50\u201380 characters.
+- Don't: Position multiple fields across rows (except related short fields like city/state/zip).
+- Prefer labels over placeholders for input fields.
+- Validate input early to surface errors as soon as possible.
+- Minimize the number of fields to reduce user effort.
+- Use top-aligned labels for step-by-step flows (wizards).
+- Use left-aligned labels for scanning-heavy layouts (settings).`,
+ anatomy: [
+ {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
+ {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
+ {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index b216758ad3..697faa7c71 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -168,6 +168,9 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'CSS Grid-based layout with responsive auto-fit support.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index b4ce576a13..96fa366cb0 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -197,6 +197,33 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Interactive cards providing additional information on hover.',
+ content: `## When to use
+
+- Non-critical supplementary information.
+- Progressive disclosure of details.
+- Non-interruptive education or onboarding.
+- Rich content with media (images, icons, text pairings).
+
+## When NOT to use
+
+- Plain text hints \u2014 use Tooltip instead.
+- Dropdown menus \u2014 use Popover instead.
+- Page content grouping \u2014 use Card instead.
+- Arbitrary or frequently changing content.
+
+## Best practices
+
+- Do: Use thoughtfully and situationally.
+- Don't: Use on arbitrary or frequently changing content.
+- Place hover card 4px from the context element.`,
+ anatomy: [
+ {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
+ {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},
+ {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index bc9c714430..ccfc0cd6c5 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -91,6 +91,9 @@ import {Home} from 'lucide-react';
'Color token mappings — primary: --color-icon-primary (default); secondary: --color-icon-secondary (de-emphasized); tertiary: --color-icon-secondary (subtle/background); disabled: --color-icon-disabled (disabled state); accent: --color-accent (interactive/actionable); positive: --color-success (success/confirmation); negative: --color-error (error/destructive); warning: --color-warning (caution/attention); inherit: currentColor (inherits from parent text color).',
'Size dimensions — xsm: 12x12px (dense UI, badges, indicators); sm: 16x16px (inline with text, compact UI); md: 20x20px (default, buttons, inputs); lg: 24x24px (emphasis, standalone icons).',
],
+ usage: {
+ summary: 'Renders icons with XDS design system colors and sizes.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Kbd/Kbd.doc.mjs b/packages/core/src/Kbd/Kbd.doc.mjs
index c4b84251b2..e244b99ba8 100644
--- a/packages/core/src/Kbd/Kbd.doc.mjs
+++ b/packages/core/src/Kbd/Kbd.doc.mjs
@@ -67,6 +67,12 @@ export const docs = {
'Uses --color-background-body background and --color-text-secondary text color',
'Key display symbols follow macOS conventions (⌘, ⌥, ⇧, ⌃)',
],
+ usage: {
+ summary: 'Displays a keyboard shortcut as styled key elements.',
+ content: `## When to use
+
+- Showing keyboard shortcuts in tooltips, menus, and documentation.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index 76a11dee43..a84736e64c 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -88,6 +88,9 @@ layer.show();
],
},
],
+ usage: {
+ summary: 'Core hook for overlay positioning using CSS Anchor Positioning and the Popover API.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index e80e7a0069..938f36db7e 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -391,6 +391,9 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Composable utilities for building structured layouts with container and content separation.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index 2b7430e689..c32ba2fd0b 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -213,6 +213,29 @@ import {XDSLinkProvider} from '@xds/core/Link';
],
},
],
+ usage: {
+ summary: 'Clickable element that leads to a new destination or performs an action.',
+ content: `## When to use
+
+- To embed actions inline on a page.
+- To provide a path to more information.
+
+## When NOT to use
+
+- Don't use to trigger dropdown menus.
+- Don't use icon-only links without a visible label.
+
+## Best practices
+
+- Do: Write descriptive link text and front-load key information.
+- Do: Keep link text concise.
+- Do: Include context about the destination for "Learn more" links.`,
+ anatomy: [
+ {name: 'Label', required: true, description: 'The visible text of the link.'},
+ {name: 'Right icon', required: false, description: 'Icon placed after the label to indicate an action affordance.'},
+ {name: 'Left icon', required: false, description: 'Icon placed before the label to represent meaning.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 4a4cf40438..e39ad2aa7c 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -194,6 +194,24 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Organizes information or interactive elements.',
+ content: `## When to use
+
+- To organize text, media, charts, or actions.
+- To create subgroups of parallel information.
+- When items need add, edit, delete, or expand operations.
+
+## Best practices
+
+- Do: Place lists within a container such as a card or dialog.`,
+ anatomy: [
+ {name: 'List title', required: true, description: 'Heading that labels the list.'},
+ {name: 'Description', required: false, description: 'Supplementary text below the title.'},
+ {name: 'List items', required: true, description: 'Individual entries, which may include icons or images.'},
+ {name: 'Item description', required: false, description: 'Additional detail for an individual list item.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index ddacd3e1d0..16153ebbf7 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -114,6 +114,9 @@ export const docs = {
'Task list checkboxes are rendered via XDSCheckboxList with isReadOnly.',
'Code blocks use XDSCodeBlock with appropriate ARIA attributes.',
],
+ usage: {
+ summary: 'Renders a markdown string as XDS-styled components.',
+ },
};
export const docsZh = {
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 8f0771265b..537e7a7f4f 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -157,6 +157,28 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'An editable list of key-value pairs providing a comprehensive overview of an object\'s attributes.',
+ content: `## When to use
+
+- Display and edit key-value pairs for object attributes.
+- Use edit mode for inline editing.
+- Use disclosure to collapse/expand sections.
+
+## When NOT to use
+
+- For extensive form input, use forms instead.
+
+## Best practices
+
+- Default to collapsed state showing the top 6 items.`,
+ anatomy: [
+ {name: 'Title', required: false, description: 'Optional title for the metadata list.'},
+ {name: 'Label', required: true, description: 'The key label for each metadata entry.'},
+ {name: 'Metadata', required: true, description: 'The value displayed in various formats.'},
+ {name: 'Disclosure', required: false, description: 'Collapse/expand control for the list.'},
+ ],
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index c2760ee9b3..9a934eade8 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -146,6 +146,12 @@ const navSections = (
{className: 'xds-mobile-nav', visualProps: ['side']},
],
},
+ usage: {
+ summary: 'Slide-out drawer overlay for mobile navigation, the mobile counterpart to SideNav.',
+ content: `## When to use
+
+- Providing navigation on mobile viewports where a persistent side nav is not practical.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index 8d227d8f4f..24e03db1bd 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -157,6 +157,13 @@ export const docs = {
'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',
'Use XDSMoreMenu for icon-only overflow actions in tight spaces (table rows, card headers). Use XDSDropdownMenu for labeled trigger buttons with chevrons.',
],
+ usage: {
+ summary: 'Overflow menu with a three-dot icon trigger for secondary actions.',
+ content: `## When to use
+
+- Presenting secondary or overflow actions in a compact space.
+- Actions that don't warrant their own visible button.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index b78e4572bb..661dcfcefb 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -235,6 +235,13 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Multi-select dropdown with checkboxes for choosing multiple items from a list.',
+ content: `## When to use
+
+- Users need to select multiple values from a dropdown list.
+- For small, finite sets of options use CheckboxList instead.`,
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjs
index 094821557f..0aed868728 100644
--- a/packages/core/src/NavIcon/NavIcon.doc.mjs
+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs
@@ -53,6 +53,9 @@ export const docs = {
{className: 'xds-navicon'},
],
},
+ usage: {
+ summary: 'Circular icon container with accent background for navigation headers.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index c9b5e1bda4..259a38aba7 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -243,6 +243,24 @@ export const docs = {
'Uses internal pending state to allow free-form typing while validating on commit.',
'Units are displayed as a lighter grey suffix after the input value.',
],
+ usage: {
+ summary: 'Enables users to enter or edit numeric values with validation support.',
+ content: `## When to use
+
+- Numeric input within forms.
+
+## Best practices
+
+- Size the input to reflect expected content length.
+- Validation states: error (blocking), warning (non-blocking), success (confirmation).`,
+ anatomy: [
+ {name: 'Label', required: true, description: 'The label for the number input.'},
+ {name: 'Description', required: false, description: 'Additional description text below the label.'},
+ {name: 'Icon', required: false, description: 'An optional icon within the input.'},
+ {name: 'Placeholder', required: false, description: 'Placeholder text shown when the input is empty.'},
+ {name: 'Spinner', required: false, description: 'Increment and decrement controls for the value.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/OverflowList/OverflowList.doc.mjs b/packages/core/src/OverflowList/OverflowList.doc.mjs
index 22886923e6..449f0a232c 100644
--- a/packages/core/src/OverflowList/OverflowList.doc.mjs
+++ b/packages/core/src/OverflowList/OverflowList.doc.mjs
@@ -115,6 +115,9 @@ export const docs = {
"For collapseFrom='start', items are hidden from the beginning and the overflow indicator appears at the start.",
'Use minVisibleItems to guarantee at least N items are always visible regardless of available space.',
],
+ usage: {
+ summary: 'Horizontal list that hides items exceeding the available width and shows an overflow indicator.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index c6b85570a8..739154d39c 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -166,6 +166,14 @@ export const docs = {
'Returns null when totalItems <= 0 or totalPages <= 0.',
'Also exports generatePageRange utility for computing visible page numbers with ellipsis.',
],
+ usage: {
+ summary: 'Communicates the number of elements that can be loaded within a given context.',
+ content: `## When to use
+
+- Showing current position within a paginated set.
+- Accessing previous and next items.
+- Selecting a specific page from a range.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 49612fec49..849687efcb 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -237,6 +237,33 @@ export const docs = {
{name: '--popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)'},
],
},
+ usage: {
+ summary: 'A floating card toggled open on click for secondary actions or supplementary information.',
+ content: `## When to use
+
+- Secondary menu options.
+- Customizable settings panels.
+- Filtering options.
+- Supplementary information that does not warrant a full dialog.
+
+## When NOT to use
+
+- Static content display (use Card instead).
+- Hover-triggered previews (use HoverCard instead).
+- Brief helper text (use Tooltip instead).
+- Complex flows requiring full focus (use Dialog instead).
+
+## Best practices
+
+- Do: Use a clear trigger element such as a button or link.
+- Don't: Confuse with Tooltip \u2014 Popovers are click-triggered and contain richer content.
+- Include a close button in the header for easy dismissal.`,
+ anatomy: [
+ {name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
+ {name: 'Body', required: true, description: 'Main content area of the popover.'},
+ {name: 'Trigger Element', required: true, description: 'The button or link that toggles the popover open.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 02d254a315..abad5a2fed 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -236,6 +236,17 @@ const [filters, setFilters] = useState([]);
],
keyboard:
'Type to search fields; Enter to select; Click token to edit; Backspace on empty input removes last filter; Escape closes popover',
+ usage: {
+ summary: 'Structured filter bar where each token represents a filter with field, operator, and value.',
+ content: `## When to use
+
+- Complex filtering across multiple dimensions.
+- Users need to build and combine filter criteria.
+
+## When NOT to use
+
+- Simple single-field search (use a text input instead).`,
+ },
};
// -------------------------------------------------------
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index bd034d64c7..36eb651865 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -138,6 +138,13 @@ export const docs = {
'aria-valuetext provides human-readable value description (determinate only)',
'Indeterminate animation respects prefers-reduced-motion',
],
+ usage: {
+ summary: 'Displays determinate or indeterminate progress of a process.',
+ content: `## When to use
+
+- Showing completion progress of a known-length operation.
+- Indicating an indeterminate loading state with a known container size.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index 786058f24e..19a58967c3 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -252,6 +252,28 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Allows a user to make a single selection from a list of options.',
+ content: `## When to use
+
+- Presenting a limited set of options where only one can be selected.
+- Making the single-selection constraint visually clear to users.
+
+## When NOT to use
+
+- Multiple selections are needed (use CheckboxList instead).
+- The option list is very long (consider Selector instead).
+
+## Best practices
+
+- Do: Use a vertical list when labels are long or need detailed descriptions.
+- Do: Use a horizontal input group for compact side-by-side comparison of short options.`,
+ anatomy: [
+ {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
+ {name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},
+ {name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index 9966cb650f..5952e825f2 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -110,6 +110,13 @@ export const docs = {
},
],
},
+ usage: {
+ summary: 'Container for creating visually distinct regions on a page.',
+ content: `## When to use
+
+- Chunking information into groups using whitespace, dividers, or type scale.
+- Prefer sections over cards as the default page structure; use cards only when stronger visual distinction is needed.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index c6e641c1a6..d93979ce91 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -183,6 +183,18 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Segmented button group for single selection with radio group semantics.',
+ content: `## When to use
+
+- Switching between a small set of mutually exclusive views or modes.
+- When all options should be visible at once.
+
+## When NOT to use
+
+- For two-state toggles (use ToggleButton instead).
+- For navigation between pages (use Tabs instead).`,
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index 421ca8db13..5499d00bec 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -238,6 +238,33 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Gives users a choice between multiple items within a dropdown list.',
+ content: `## When to use
+
+- Presenting 3\u201320 options in forms or settings.
+- Capturing or assigning a value from a predefined list.
+- For 20+ options, use a searchable Selector variant.
+
+## When NOT to use
+
+- Triggering actions (use Dropdown Menu instead).
+- Selecting with a default action (use Split Button instead).
+
+## Best practices
+
+- Do: Use to capture or assign values in forms, wizards, or settings.
+- Don't: Use for triggering actions \u2014 use Dropdown Menu instead.
+- Supports error, success, warning, and disabled states.`,
+ anatomy: [
+ {name: 'Label', required: false, description: 'Text label displayed above the selector.'},
+ {name: 'Placeholder', required: false, description: 'Hint text shown when no value is selected.'},
+ {name: 'Description', required: false, description: 'Helper text providing additional context.'},
+ {name: 'Left Icon', required: false, description: 'Icon displayed to the left of the selected value.'},
+ {name: 'Value', required: true, description: 'The currently selected item displayed in the selector.'},
+ {name: 'List', required: true, description: 'The dropdown list of selectable options.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 46b043b6e0..87aa6397c9 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -456,6 +456,31 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Navigation system helping users find and browse information. Left nav is the default recommendation.',
+ content: `## When to use
+
+- 5 or more navigation items.
+- Customizable navigation structure.
+- Complex grouping of navigation items.
+- Secondary item actions needed.
+- Collapsible navigation sections.
+
+## When NOT to use
+
+- Filter-primary tools (use tabs or filter buttons instead).
+- Housing wide components that need more horizontal space.
+
+## Best practices
+
+- Do: Use descriptive names for navigation items.
+- Don't: Use navigation to filter content \u2014 use tabs or filter buttons instead.`,
+ anatomy: [
+ {name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
+ {name: 'Navigation items', required: true, description: 'Sections and groups of navigable links.'},
+ {name: 'Collapse/expand toggle', required: false, description: 'Toggle to collapse or expand the side nav.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjs
index ddc3473f40..21c9dd9bb7 100644
--- a/packages/core/src/Skeleton/Skeleton.doc.mjs
+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs
@@ -73,6 +73,17 @@ export const docs = {
'Numeric dimensions are converted to pixels; strings are passed through as-is.',
'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',
],
+ usage: {
+ summary: 'A placeholder loading component that displays an animated pulsing effect while content is loading.',
+ content: `## When to use
+
+- Content of known size is loading.
+- Building skeleton screens that match the layout of the content being loaded.
+
+## When NOT to use
+
+- Content dimensions are unknown (use Spinner instead).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index c220829e26..ee956c4831 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -244,6 +244,12 @@ export const docs = {
'`minStepsBetweenThumbs` enforces a minimum gap between range thumbs.',
'Vertical orientation inverts the Y axis so that bottom = min and top = max.',
],
+ usage: {
+ summary: 'Allows a user to select a single number within a fixed range.',
+ content: `## When to use
+
+- To help users explore and select a number within a constrained range.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
index 7c8374d2ac..e7cdf1fa07 100644
--- a/packages/core/src/Spinner/Spinner.doc.mjs
+++ b/packages/core/src/Spinner/Spinner.doc.mjs
@@ -79,6 +79,17 @@ export const docs = {
'XDSSpinner is intentionally minimal — compose with layout and text components for full loading states.',
'Size reference: sm = 10×10px / 3px border, md = 14×14px / 3px border, lg = 18×18px / 3px border.',
],
+ usage: {
+ summary: 'An animated loading indicator for indeterminate wait states.',
+ content: `## When to use
+
+- Indicating an ongoing process with unknown duration.
+- Inline loading states within buttons or other components.
+
+## When NOT to use
+
+- Content of known size is loading (use Skeleton instead).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index fa9e33bb0b..61fa80d993 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -332,6 +332,9 @@ import * as stylex from '@stylexjs/stylex';
],
},
],
+ usage: {
+ summary: 'Layout primitives for arranging items in horizontal or vertical sequences using flexbox.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
index 6d9d3b0e81..d0e0642cdb 100644
--- a/packages/core/src/StatusDot/StatusDot.doc.mjs
+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs
@@ -65,6 +65,18 @@ export const docs = {
'Not focusable — intended as a decorative indicator only.',
'isPulsing animation respects prefers-reduced-motion: reduce.',
],
+ usage: {
+ summary: 'A small dot indicating status through semantic colors, often paired with a text label.',
+ content: `## When to use
+
+- Indicating status with semantic colors (e.g. active, inactive, warning, error).
+- Pairing with text labels to provide visual status cues.
+
+## Best practices
+
+- Do: Pair with a text label to ensure the status is accessible and clear.
+- Don't: Rely on color alone \u2014 always provide a text label for context.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index 7b75d0a25b..dc1a24558e 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -212,6 +212,16 @@ export const docs = {
'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling',
'Track and thumb transitions respect prefers-reduced-motion (0s duration when reduced motion preferred)',
],
+ usage: {
+ summary: 'Conveys a binary on/off state that takes effect immediately.',
+ content: `## When to use
+
+- Settings that take effect immediately upon toggling.
+
+## When NOT to use
+
+- When changes require a separate submit step \u2014 use a checkbox instead.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 86b7131142..0cc17c99d5 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -242,6 +242,22 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Organizes content into tabbed sections for quick access to categorized information.',
+ content: `## When to use
+
+- To organize large amounts of content into categories accessible above the fold.
+
+## Best practices
+
+- Two styles are available: underlined tabs and header tabs.
+- Tab items overflow into a "more" menu when horizontal space is limited.`,
+ anatomy: [
+ {name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
+ {name: 'Center-Fill Content', required: false, description: 'Stretches to fill available space.'},
+ {name: 'Right Content', required: false, description: 'Hugs content width.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index c92d05d282..a4c9750f25 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -776,6 +776,33 @@ const columnSettings = useXDSTableColumnSettings({
],
},
],
+ usage: {
+ summary: 'Displays information with consistent data dimensionality in a grid format.',
+ content: `## When to use
+
+- Simple tables for read-only data display.
+- Data tables with column controls.
+- Complex tables with control toolbars and detail panes.
+
+## When NOT to use
+
+- Consider lists or card-lists for simpler or inconsistent data.
+
+## Best practices
+
+- Do: Use row activation to show details in a side panel.
+- Don't: Use row expansion for details (breaks column alignment).
+- Layout presets: space-optimized (40px rows), balanced (56px default), content-optimized (dynamic height).
+- Cell types: Content (main with media), Text, Value (right-aligned numbers), Status (dot + label).`,
+ anatomy: [
+ {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
+ {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
+ {name: 'Footer', required: false, description: 'Displays summary or totals.'},
+ {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
+ {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
+ {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index b1191614bf..8aed8354cd 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -282,6 +282,9 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Typography components for body text, headings, and semantic text rendering.',
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index b2fb29439b..f56b2e6fb3 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -218,6 +218,18 @@ export const docs = {
'Interaction is blocked during busy state (loading or pending async action) to prevent double-input.',
'Character counter is connected to the textarea via aria-describedby and uses aria-live="polite" for screen reader announcements.',
],
+ usage: {
+ summary: 'A multi-line text input for collecting longer user input.',
+ content: `## When to use
+
+- Users need to enter multiple lines of text.
+- Comments, descriptions, or longer-form content entry.
+
+## When NOT to use
+
+- Single-line input (use TextInput instead).
+- Rich text with formatting (use a rich text editor instead).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index baba7d90fd..70bfef4711 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -218,6 +218,25 @@ export const docs = {
'The component wraps XDSField for label, description, and optional/required rendering.',
'The size prop supports "sm", "md", and "lg".',
],
+ usage: {
+ summary: 'Enables users to enter or edit text or numeric values.',
+ content: `## When to use
+
+- Short-form and long-form text entries.
+
+## Best practices
+
+- Do: Size the input to reflect the expected content length.
+- Do: Use validation messaging for required fields.
+- Validation states: error (blocking), warning (non-blocking), success (confirmation).`,
+ anatomy: [
+ {name: 'Label', required: true, description: 'Text that identifies the input field.'},
+ {name: 'Description', required: false, description: 'Helper text providing additional context.'},
+ {name: 'Icon', required: false, description: '16px icon displayed inside the input.'},
+ {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty.'},
+ {name: 'Spinner', required: false, description: 'Loading indicator for pending actions.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 59eac240a8..909ce79dc1 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -209,6 +209,12 @@ export const docs = {
{className: 'xds-time-input', visualProps: ['size']},
],
},
+ usage: {
+ summary: 'Field formatted for users to input a time.',
+ content: `## When to use
+
+- When the user needs to input a time, such as in scheduling or form fields.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index 0d5856d81e..342b6bb74f 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -119,6 +119,26 @@ export const docs = {
'Sets aria-label with full absolute time when displaying relative format.',
'Tooltip is keyboard accessible via focus.',
],
+ usage: {
+ summary: 'Displays the absolute or relative date and time of an event or its duration.',
+ content: `## When to use
+
+- Showing an exact date and time (absolute format).
+- Indicating freshness with an "ago" format (relative).
+- Displaying event duration.
+
+## Best practices
+
+- Do: Choose a format that fits the context (absolute for precision, relative for recency).
+- Do: Ensure consistent timestamp formatting within the same view.
+- Do: Use a single time unit for table column displays.
+- Do: Provide tooltips with additional detail such as timezone or full date.`,
+ anatomy: [
+ {name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
+ {name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},
+ {name: 'Hover Card', required: false, description: 'Floating card showing timezone, full date, or additional details on hover.'},
+ ],
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs
index 7e15d5825e..8b5a763ffc 100644
--- a/packages/core/src/Toast/Toast.doc.mjs
+++ b/packages/core/src/Toast/Toast.doc.mjs
@@ -80,4 +80,18 @@ export const docs = {
code: `toast({\n body: "Item deleted",\n isAutoHide: false,\n endContent: <XDSButton label="Undo" variant="secondary" size="sm" onClick={undo} />,\n});`,
},
],
+ usage: {
+ summary: 'Transient notification that appears briefly to confirm an action or surface non-critical information.',
+ content: `## When to use
+
+- Confirming a completed action (e.g., "Saved successfully").
+- Surfacing non-critical, time-sensitive information.
+- Providing undo opportunities for reversible actions.
+
+## When NOT to use
+
+- Critical information that requires user action (use Banner instead).
+- Persistent messages (use Banner instead).
+- Validation errors on form fields (use Field status instead).`,
+ },
};
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index fb47f8514f..b6d62f1cd1 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -124,6 +124,19 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'A button that switches between two persistent states, typically active and inactive.',
+ content: `## When to use
+
+- When an action has two persistent states and can be undone.
+- Use a group of toggle buttons for multiple independent two-state actions.
+- Use a toggle button group for 3 or more mutually exclusive states.
+
+## Best practices
+
+- Do: Convey state through color change, bolded text, or a filled icon.
+- Do: Keep the label the same between states.`,
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
index 6e009d882d..8936b53945 100644
--- a/packages/core/src/Token/Token.doc.mjs
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -129,6 +129,25 @@ export const docs = {
],
keyboard:
'Tab focuses the token (or its inner button when onClick is used). Enter/Space activate a clickable token or the remove button. Remove button is reachable as a separate Tab stop.',
+ usage: {
+ summary: 'Displays entities inline for tags or names.',
+ content: `## When to use
+
+- Concise metadata display.
+- Icon with colored background indicator.
+- Combined icon, text, and number representation.
+
+## When NOT to use
+
+- Static indicators without interaction \u2014 use Badge instead (Badge is 20px, Token is 28px).`,
+ anatomy: [
+ {name: 'Color', required: false, description: 'Background color indicator.'},
+ {name: 'Label', required: true, description: 'Text label for the token.'},
+ {name: 'Icon', required: false, description: '16px icon displayed in the token.'},
+ {name: 'Remove button', required: false, description: 'Shown when onRemove is provided.'},
+ {name: 'Description', required: false, description: 'Additional descriptive text.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index 154ba1fb39..f2f7ba499d 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -253,6 +253,18 @@ export const docs = {
],
keyboard:
'Backspace on empty input removes last token; Arrow keys navigate dropdown; Enter selects highlighted item; Escape closes dropdown',
+ usage: {
+ summary: 'Converts text into tokens, enabling users to filter content and make selections.',
+ content: `## When to use
+
+- Convert plain text into tokens for metadata.
+- Predict entries from a data source.
+- Allow users to create custom entries.
+
+## Best practices
+
+- Don't: Apply colored backgrounds to tokens within a tokenizer.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjs
index f69a712665..3a24637d49 100644
--- a/packages/core/src/Toolbar/Toolbar.doc.mjs
+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -196,6 +196,13 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'General-purpose toolbar with start, center, and end content slots.',
+ content: `## When to use
+
+- Grouping related actions or controls in a horizontal bar.
+- Providing contextual actions above content areas like tables or editors.`,
+ },
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index b1bd9d9e10..c761ba0775 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -198,6 +198,24 @@ export const docs = {
{className: 'xds-tooltip'},
],
},
+ usage: {
+ summary: 'Non-interactive hints that provide additional information in the context of a specific UI element.',
+ content: `## When to use
+
+- Progressive disclosure of non-interactive content.
+- Non-interruptive education.
+- Show full text for truncated labels.
+
+## When NOT to use
+
+- For interactive content, use HoverCard instead.
+
+## Best practices
+
+- Limit tooltip content to approximately 140 characters.
+- Place tooltip 8px from the context element.
+- Supported placements: above, below, left, right.`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index b172e1ab15..f69920ef70 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -579,6 +579,27 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Horizontal navigation bar for product-level navigation.',
+ content: `## When to use
+
+- 5 or fewer nav items that should always be visible.
+- Items don't require icons.
+- Minimal navigation paired with controls or filters.
+- Can combine with side nav for ecosystem tools.
+
+## When NOT to use
+
+- Complex navigation hierarchies.
+- Products without clear ownership.
+- Don't use to filter content \u2014 use tabs or filter buttons instead.`,
+ anatomy: [
+ {name: 'Product icon and name', required: true, description: 'Identifies the product in the navigation bar.'},
+ {name: 'Navigation items', required: true, description: 'Primary links for product-level destinations.'},
+ {name: 'More menu', required: false, description: 'Overflow menu for additional navigation items.'},
+ {name: 'Flex area', required: false, description: 'Flexible region for search, primary action buttons, or other controls.'},
+ ],
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 27df14f0db..a035b354dc 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -118,6 +118,14 @@ export const docs = {
],
},
],
+ usage: {
+ summary: 'Displays hierarchical information with expandable and collapsible nodes.',
+ content: `## When to use
+
+- For file system navigators.
+- For visualizing hierarchical data.
+- When expand/collapse interactions are needed.`,
+ },
};
// -------------------------------------------------------
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 3a3082844c..d592579da9 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -416,6 +416,18 @@ export const docs = {
'XDSBaseTypeahead renders only the <input> and dropdown popover — consumers provide their own wrapper.',
'If item has an element property, XDSTypeaheadItem renders it directly instead of the standard layout.',
],
+ usage: {
+ summary: 'Searchable dropdown for single-item selection with keyboard navigation and async data support.',
+ content: `## When to use
+
+- Selecting a single item from a large or dynamic dataset.
+- Users benefit from search-as-you-type to find options.
+
+## When NOT to use
+
+- A small, fixed list of options (use Selector instead).
+- Multiple selections needed (use Tokenizer instead).`,
+ },
};
/** @type {import('../docs-types').ComponentDoc} */
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index 06a2e5b9d1..e45c432d6e 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -163,6 +163,58 @@ export interface ComponentEntry {
examples: Example[];
}
+/**
+ * Documents one element in a component's anatomy breakdown.
+ * Anatomy describes the visual/structural parts that make up a component
+ * (e.g. a Button has: left icon, label, end content, container).
+ *
+ * @example
+ * ```
+ * {name: 'Label', required: true, description: 'Accessible text for the button. Set isLabelHidden to visually hide it.'}
+ * {name: 'Left icon', required: false, description: 'Visually represents the meaning of the button label. Icon size is typically 16px.'}
+ * ```
+ */
+export interface AnatomyElement {
+ /** Human-readable element name. e.g. `"Label"`, `"Left icon"`, `"Container"` */
+ name: string;
+ /** Whether this element is required for the component to function. */
+ required: boolean;
+ /** What this element is and how it contributes to the component. 1-2 sentences. */
+ description: string;
+}
+
+/**
+ * Usage guidance for a component — when to use it, when not to,
+ * and the visual anatomy of its parts.
+ *
+ * `summary` is a design-oriented overview (vs. the developer-focused `description`).
+ * `content` is freeform markdown for usage guidance — authors can structure it
+ * however they like (when to use, when not to, do/don't, migration notes, etc.).
+ * `anatomy` is a structured breakdown of the component's visual elements.
+ */
+export interface UsageDoc {
+ /** Design-oriented summary of the component's purpose and role in the UI.
+ * More conceptual than `description` — explains *what problem* the component
+ * solves rather than *what API* it exposes.
+ * e.g. `"Buttons communicate calls to action and allow users to interact
+ * with pages in a variety of ways."` */
+ summary?: string;
+ /** Freeform markdown covering usage guidance. Use markdown headers and lists
+ * to organize content. Common sections include "When to use", "When NOT to use",
+ * but authors are free to structure this however makes sense.
+ *
+ * @example
+ * ```
+ * `## When to use\n- To trigger an action\n- To navigate when the action is primary\n\n## When NOT to use\n- For navigation — use Link instead`
+ * ```
+ */
+ content?: string;
+ /** Structural/visual anatomy of the component. Each entry describes one
+ * element that makes up the component (icon slot, label, container, etc.).
+ * Order entries in the visual reading order (leading → trailing, top → bottom). */
+ anatomy?: AnatomyElement[];
+}
+
/**
* Shared fields between single-component and multi-component docs.
* Do not use this interface directly — use `ComponentDoc` (the union type).
@@ -221,6 +273,10 @@ interface BaseDoc {
* self-contained note. Do not duplicate information from `features`,
* `accessibility`, or `keyboard`. */
notes?: string[];
+ /** Design-oriented usage guidance: when to use this component, when not to,
+ * and the visual anatomy of its parts. Complements the developer-focused
+ * fields (`description`, `features`, `props`). */
+ usage?: UsageDoc;
}
/**
@@ -292,6 +348,12 @@ export interface TranslationDoc {
keyboard?: string;
/** Prop descriptions keyed by prop name. Only include props that have descriptions. */
propDescriptions?: Record<string, string>;
+ /** Translated/compressed usage overlay. Only summary and content are translated;
+ * anatomy element names are stable identifiers and stay as-is from the base doc. */
+ usage?: {
+ summary?: string;
+ content?: string;
+ };
/** Sub-component translations. Must match docs.components length and order (if present). */
components?: Array<{
/** Exact name from docs.components[n].name */