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.mjsindex 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 statementif (importHint) {sections.push('## Import\n');diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.tsindex 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 */