Skip to content

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

TypeScript

docs(core): backfill + repair docsDense translations across core (#2605)

Joey5977f8febe79
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index 3ff55a5fe6..eef7822f0b 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -71,3 +71,46 @@ export const docs = {
},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
+ usage: {
+ description:
+ 'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). To show w/o managing open state, use useXDSImperativeAlertDialog hook — call alert.show(options) + render alert.element in tree.',
+ bestPractices: [
+ {guidance: true, description: 'Make action button label specific — "Delete project" > "OK"/"Confirm".'},
+ {guidance: true, description: 'Describe consequences in description so user knows outcome before confirming.'},
+ {guidance: false, description: 'Use AlertDialog for non-destructive actions — use standard Dialog instead.'},
+ ],
+ },
+ components: [
+ {
+ name: 'XDSAlertDialog',
+ description: 'Modal dialog confirming destructive action.',
+ propDescriptions: {
+ isOpen: 'dialog open? **(required)**',
+ onOpenChange: 'visibility change callback **(required)**',
+ title: 'dialog title; linked via aria-labelledby **(required)**',
+ description: 'consequence description; linked via aria-describedby **(required)**',
+ actionLabel: 'action button label **(required)**',
+ onAction: 'fires on action click; does NOT auto-close **(required)**',
+ cancelLabel: 'cancel button label',
+ actionVariant: 'action button variant',
+ isActionLoading: 'shows loading spinner on action button',
+ width: 'dialog width',
+ isInline: 'renders content inline w/o modal behavior; docs previews/showcases only',
+ },
+ },
+ {
+ name: 'useXDSImperativeAlertDialog',
+ description: 'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.',
+ propDescriptions: {
+ show: 'show dialog w/ options; same as XDSAlertDialog props minus isOpen/onOpenChange',
+ hide: 'hide dialog',
+ isOpen: 'dialog currently open?',
+ element: 'dialog element — render in JSX tree',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
index 736d78172a..149f2fd6a4 100644
--- a/packages/core/src/Badge/Badge.doc.mjs
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -117,7 +117,8 @@ export const docsDense = {
{guidance: true, description: 'Every badge steals attention. Only badge states where the user needs to act. If no follow-up is needed, use plain text.'},
{guidance: true, description: 'Use success/warning/error ONLY for system status requiring attention (Failed, Degraded, Action Required). These are visually loud — solid colored backgrounds.'},
{guidance: true, description: 'Use color variants (blue, purple, teal) for category tags that classify items — team names, content types, priority levels.'},
- {guidance: true, description: 'Keep labels to one or two words. Add an icon only when it helps identify the badge type.'},
+ {guidance: true, description: 'Keep labels to one or two words. If more detail is needed, put it in surrounding text instead of the badge.'},
+ {guidance: true, description: 'Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.'},
{guidance: false, description: 'Apply "success" badges to every healthy/normal item. If most rows are green "Active", none stand out. Skip the badge for the default state — only highlight exceptions that need attention.'},
{guidance: false, description: 'Use badges for metadata. Durations, counts, dates, descriptions → use XDSText with type="supporting" instead.'},
{guidance: false, description: 'Use status variants for non-status info. "6h window", "12 types", category names are NOT statuses.'},
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index e5aa920a22..75f5c8b878 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -194,9 +194,10 @@ export const docsDense = {
description:
'Breadcrumbs show a trail of links from root to current page. Use at the top of detail pages, settings, or nested content.',
bestPractices: [
- {guidance: true, description: 'Place above the page heading. Keep labels short and matching page titles.'},
+ {guidance: true, description: 'Place above the page heading so user sees location before reading content.'},
+ {guidance: true, description: 'Keep labels short + matching page titles they link to — "Settings" not "Application Settings Page".'},
{guidance: true, description: 'Use supporting variant in dense UIs where the breadcrumb should be subtle.'},
- {guidance: true, description: 'Last item should be plain text (isCurrent), not a link.'},
+ {guidance: true, description: 'Last item plain text, not a link — represents current page; done automatically when you set isCurrent.'},
{guidance: false, description: 'Use as primary navigation — breadcrumbs supplement, not replace, a main nav.'},
{guidance: false, description: 'Show on top-level pages with no parent.'},
{guidance: false, description: 'Let the trail exceed 5 levels — simplify the hierarchy instead.'},
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 651833fbe4..412ec8dfaf 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -177,8 +177,10 @@ export const docsDense = {
description:
'Calendar lets the user pick a date or date range from a month grid. Use in booking, scheduling, date filters.',
bestPractices: [
- {guidance: true, description: 'Set min/max to limit selection. Use range mode for start + end dates.'},
- {guidance: true, description: 'Use dateConstraints to disable weekends/holidays. Show two months for cross-month selections.'},
+ {guidance: true, description: 'Set min/max to limit selection to a valid window — only future dates for booking, current quarter for a report.'},
+ {guidance: true, description: 'Use range mode when user picks start + end dates — trip, time-off request.'},
+ {guidance: true, description: 'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.'},
+ {guidance: true, description: 'Show two months side by side when user frequently selects dates spanning a month boundary.'},
{guidance: false, description: 'Use for dates far in the past/future — text input is faster.'},
{guidance: false, description: 'Disable dates without explaining why.'},
],
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index cec88aaa49..7eddb73dab 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -150,13 +150,16 @@ export const docsDense = {
description:
'Card is for discrete items with clear interaction boundaries (one profile, one notification, one product). Cards are NOT the default. Spacing and alignment create visual grouping without borders. Ask: "could I reorder or remove this independently?" — if no, don\'t use a card.',
bestPractices: [
- {guidance: true, description: 'Use cards ONLY for discrete items you could reorder/remove independently. Not every group of content needs a container.'},
- {guidance: true, description: 'Try spacing + headings first. If the grouping is clear from whitespace and typography alone, you don\'t need a card.'},
- {guidance: true, description: 'For page sections (settings, forms, sidebars), use heading + XDSStack or XDSSection — not a card.'},
- {guidance: false, description: 'Default to wrapping content in cards. Cards should be the exception, not the reflex. Borders everywhere = visual noise.'},
- {guidance: false, description: 'Wrap page sections in cards. "General Settings" or "Preferences" are not cards.'},
- {guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). This is the lazy default — vary layout or skip cards entirely.'},
- {guidance: false, description: 'Nest cards. Use color variants for status — use Banner or Badge instead.'},
+ {guidance: true, description: 'Ask "could I reorder/remove this independently?" If yes, it\'s a card. If no, it\'s just a page section — use heading + XDSStack or XDSSection.'},
+ {guidance: true, description: 'Use cards for discrete items: one profile, one notification, one metric, one product in a grid. Each card = one "thing" w/ clear interaction boundaries.'},
+ {guidance: true, description: 'Spacing + alignment alone create visual grouping. Not everything needs a container — try removing the card; if grouping still reads from whitespace + typography, skip it.'},
+ {guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
+ {guidance: true, description: 'Pair a card w/ XDSLayout when you need a structured header, scrollable content, and footer with actions.'},
+ {guidance: false, description: 'Default to cards for grouping. Heading + XDSStack w/ proper spacing creates hierarchy w/o borders everywhere. Cards are the exception, not the default.'},
+ {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups are page regions — use XDSSection or heading + stack.'},
+ {guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
+ {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use spacing + dividers instead.'},
+ {guidance: false, description: 'Use color variants for status — use Banner or Badge for that instead. Color cards are for categorization.'},
],
},
propDescriptions: {
@@ -166,5 +169,6 @@ export const docsDense = {
minHeight: 'min card height',
children: 'content inside card',
padding: 'internal padding via spacing scale',
+ variant: 'background color variant; `default` = standard card bg, `muted` = muted bg for de-emphasised cards; non-semantic variants use the corresponding `--color-<name>-background` token',
},
};
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 8fe58aa306..7c549e86cb 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -83,8 +83,12 @@ export const docsDense = {
description:
'Carousel scrolls items horizontally when they overflow. Use for card grids, galleries, product lists.',
bestPractices: [
- {guidance: true, description: 'Scroll-snap for precise alignment. Always set aria-label. Consistent gap and item width.'},
- {guidance: false, description: 'Critical content in carousels. Auto-advance. Nested carousels.'},
+ {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge — gallery, product list.'},
+ {guidance: true, description: 'Always provide an aria-label describing what the carousel contains — "Featured products", "Team members".'},
+ {guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
+ {guidance: false, description: 'Use a carousel for content every user must see — not everyone scrolls horizontally. Put critical content above the fold.'},
+ {guidance: false, description: 'Auto-advance items — let the user scroll at their own pace.'},
+ {guidance: false, description: 'Nest carousels — a carousel inside a carousel is confusing and breaks keyboard navigation.'},
],
},
propDescriptions: {
@@ -93,5 +97,6 @@ export const docsDense = {
hasButtons: 'prev/next buttons on hover (desktop)',
hasSnap: 'scroll-snap; children snap to start edge',
'aria-label': 'accessible label for carousel region',
+ 'data-testid': 'test selector for automated testing frameworks',
},
};
diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjs
index d944a7acc6..e6d1a7e9b9 100644
--- a/packages/core/src/Center/Center.doc.mjs
+++ b/packages/core/src/Center/Center.doc.mjs
@@ -113,8 +113,11 @@ export const docsDense = {
description:
'Center aligns content to the middle of its container. Use for empty states, loading screens, login forms.',
bestPractices: [
- {guidance: true, description: 'Set axis when you only need one direction. Set height for vertical centering. Use isInline for icons in text.'},
- {guidance: false, description: 'Wrap page sections — use XDSLayout. Use for horizontal lists — use XDSStack with hAlign="center".'},
+ {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction — both axes is the default but not always needed.'},
+ {guidance: true, description: 'Set a height when centering vertically — Center needs a defined height to know what space to center within.'},
+ {guidance: true, description: 'Use isInline to center small elements (icons, badges) within a line of text without breaking text flow.'},
+ {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout or XDSAppShell for page-level structure.'},
+ {guidance: false, description: 'Use Center for horizontal lists of items — use XDSStack with hAlign="center" instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 63599517b5..63a5fecb2d 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -187,8 +187,11 @@ export const docsDense = {
usage: {
description: 'CheckboxInput toggles a single on/off value. Use for settings, terms acceptance, opt-in choices. Use CheckboxList for groups.',
bestPractices: [
- { guidance: true, description: 'Always provide a visible label. Add description for context. Use indeterminate for partial "select all".' },
- { guidance: false, description: 'Use for mutually exclusive choices (use RadioList). Use for immediate actions (use toggle/button).' },
+ { guidance: true, description: 'Always provide a visible label so user knows what they\'re toggling. Use isLabelHidden only when surrounding context makes it obvious.' },
+ { guidance: true, description: 'Add a description for choices that need extra context — e.g. what "Share usage data" actually shares.' },
+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },
+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjs
index 9a4a2429e6..08a138b84d 100644
--- a/packages/core/src/Citation/Citation.doc.mjs
+++ b/packages/core/src/Citation/Citation.doc.mjs
@@ -14,3 +14,11 @@ export const docs = {
props: [],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: '',
+ usage: {
+ description: '',
+ },
+};
diff --git a/packages/core/src/ClickableCard/ClickableCard.doc.mjs b/packages/core/src/ClickableCard/ClickableCard.doc.mjs
index d1dac41534..7ec8c21629 100644
--- a/packages/core/src/ClickableCard/ClickableCard.doc.mjs
+++ b/packages/core/src/ClickableCard/ClickableCard.doc.mjs
@@ -38,3 +38,28 @@ export const docs = {
targets: [{className: 'xds-clickable-card', visualProps: ['variant']}],
},
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Interactive card for navigation/action targets. Nested interactive elements work independently.',
+ usage: {
+ description: 'Interactive card for navigation/action targets. Nested interactive elements work independently.',
+ bestPractices: [
+ {guidance: true, description: 'Use for cards navigating to detail page or triggering single action.'},
+ {guidance: true, description: 'Nest buttons/links freely inside — they handle own events.'},
+ {guidance: false, description: 'Use for toggling selection — use SelectableCard instead.'},
+ ],
+ },
+ propDescriptions: {
+ label: 'accessibility label **(required)**',
+ onClick: 'click handler — fires on card surface only',
+ href: 'navigation URL',
+ target: 'link target',
+ isDisabled: 'disables card',
+ padding: 'inner padding',
+ variant: 'background color variant',
+ width: 'card width',
+ height: 'card height',
+ maxWidth: 'max card width',
+ },
+};
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 8b43329c81..b6c97b3639 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -179,11 +179,13 @@ export const docsDense = {
usage: {
description: 'Collapsible hides and reveals content behind a trigger button. Use in settings, FAQs, or detail views. Wrap in XDSCollapsibleGroup for accordion behavior.',
bestPractices: [
- { guidance: true, description: 'Wrap in XDSCard for visual separation. Use type="single" for settings/FAQs.' },
+ { guidance: true, description: 'Wrap each XDSCollapsible in an XDSCard for visual separation in accordion layouts.' },
+ { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
{ guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },
{ guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },
{ guidance: false, description: 'Hide critical content behind a collapsible — users may not discover it.' },
- { guidance: false, description: 'Nest more than two levels deep. Avoid for single short paragraphs.' },
+ { guidance: false, description: 'Nest collapsibles more than two levels deep — makes content hard to find and navigate.' },
+ { guidance: false, description: 'Use a collapsible for a single short paragraph — just show the text directly instead.' },
],
},
components: [
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index e7a1da8748..890a0bfe30 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -217,10 +217,13 @@ export const docsDense = {
usage: {
description: 'DateInput lets the user type or pick a date from a calendar popover. Use for scheduling, deadlines, booking dates, or any form field needing a calendar date.',
bestPractices: [
- { guidance: true, description: 'Clear labels + descriptions. Use min/max/dateConstraints for valid ranges.' },
- { guidance: true, description: 'Use hasClear for optional dates. Use changeAction for server-side saves.' },
- { guidance: false, description: 'Use for free-form text that is not a calendar date.' },
- { guidance: false, description: 'Hide the label without surrounding context. Don\'t ignore the text input — users can type dates directly.' },
+ { guidance: true, description: 'Provide clear labels + descriptions so users understand what date is expected.' },
+ { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
+ { guidance: true, description: 'Use hasClear when the date is optional so the user can easily reset it.' },
+ { guidance: true, description: 'Show a loading state with changeAction when the date triggers a server-side save.' },
+ { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },
+ { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
+ { guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
index 1dc25b5f54..3099e7abad 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
@@ -64,9 +64,12 @@ export const docsDense = {
usage: {
description: 'DateRangeInput lets users select start+end dates from a dual-month calendar. Use for filtering, reports, analytics, and booking.',
bestPractices: [
- { guidance: true, description: 'Use presets for common ranges. Use min/max for constraints.' },
- { guidance: true, description: 'Keep hasClear enabled. Provide clear labels.' },
- { guidance: false, description: 'Use for single dates (use DateInput). Hide label without context.' },
+ { guidance: true, description: 'Use presets for common ranges like "Last 7 days" to speed up selection.' },
+ { guidance: true, description: 'Use min/max to constrain selectable dates to valid ranges.' },
+ { guidance: true, description: 'Keep hasClear enabled (default) so users can reset the filter.' },
+ { guidance: true, description: 'Provide clear labels + descriptions so users understand what the range controls.' },
+ { guidance: false, description: 'Use DateRangeInput when only a single date is needed — use DateInput instead.' },
+ { guidance: false, description: 'Hide the label without surrounding context that makes the purpose obvious.' },
],
},
propDescriptions: {
@@ -88,6 +91,8 @@ export const docsDense = {
status: 'error/warning/success status',
labelTooltip: 'tooltip via info icon at label end',
numberOfMonths: 'months in calendar (default 2)',
+ changeAction: 'async action fired after onChange; drives optimistic UI updates via useTransition',
+ isLoading: 'loading state; disables interaction + shows a spinner',
xstyle: 'StyleX styles for layout',
},
};
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
index 0398ca4407..dbef413ea9 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
@@ -222,10 +222,13 @@ export const docsDense = {
usage: {
description: 'DateTimeInput combines a calendar popover with a time input for selecting both a date and time. Use for scheduling, events, deadlines, or any form field needing a datetime.',
bestPractices: [
- { guidance: true, description: 'Clear labels + descriptions. Use min/max for valid datetime ranges.' },
- { guidance: true, description: 'Use hasClear for optional datetimes. Choose hour format matching locale.' },
- { guidance: false, description: 'Use for date-only (use DateInput) or time-only (use TimeInput).' },
- { guidance: false, description: 'Hide the label without surrounding context.' },
+ { guidance: true, description: 'Provide clear labels + descriptions so users understand what datetime is expected.' },
+ { guidance: true, description: 'Use min and max to restrict selectable datetimes to valid ranges.' },
+ { guidance: true, description: 'Use hasClear when the datetime is optional so the user can easily reset it.' },
+ { guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale.' },
+ { guidance: false, description: 'Use DateTimeInput when only a date is needed — use DateInput instead.' },
+ { guidance: false, description: 'Use DateTimeInput when only a time is needed — use TimeInput instead.' },
+ { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index b0f114f274..94b90fe750 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -324,10 +324,13 @@ export const docsDense = {
usage: {
description: 'Dialog displays a modal overlay that blocks page interaction. Use for delete confirmations, edit forms, terms acceptance.',
bestPractices: [
- { guidance: true, description: 'Pick the right purpose: info=dismissable, form=no backdrop dismiss, required=must respond.' },
- { guidance: true, description: 'Clear title in header. Use purpose="form" for dialogs with inputs.' },
- { guidance: false, description: 'Use for simple messages — use inline or toast instead. Don\'t nest dialogs.' },
- { guidance: false, description: 'Fullscreen for simple confirmations — it\'s for complex content like editors.' },
+ { guidance: true, description: 'Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when user must respond.' },
+ { guidance: true, description: 'Include a clear title in the header so users immediately understand what the dialog is asking.' },
+ { guidance: true, description: 'Use purpose="form" for dialogs with inputs so user can\'t accidentally lose data by clicking the backdrop.' },
+ { guidance: true, description: 'Keep dialogs focused on a single task — if content grows beyond what fits, consider a full page instead.' },
+ { guidance: false, description: 'Use a dialog for simple messages that could be shown inline or as a toast notification.' },
+ { guidance: false, description: 'Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead.' },
+ { guidance: false, description: 'Use the fullscreen variant for simple confirmations — it\'s meant for complex content like editors or long forms.' },
],
},
components: [
@@ -360,5 +363,15 @@ export const docsDense = {
hasDivider: 'bottom border',
},
},
+ {
+ name: 'useXDSImperativeDialog',
+ description: 'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree',
+ propDescriptions: {
+ show: 'show the dialog with given content; options = XDSDialog props minus isOpen/onOpenChange/children',
+ hide: 'hide the dialog',
+ isOpen: 'whether the dialog is currently open',
+ element: 'the dialog element — render this in your JSX tree',
+ },
+ },
],
};
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index d65fdc3552..e205689500 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -163,8 +163,12 @@ export const docsDense = {
usage: {
description: 'EmptyState shows a placeholder for empty lists, zero search results, first-time setups. Always include a title and next step.',
bestPractices: [
- { guidance: true, description: 'Clear title + CTA button. Icon for context. Compact variant in tight spaces.' },
- { guidance: false, description: 'No generic "No data" — be specific. Not for errors — use Banner.' },
+ { guidance: true, description: 'Include a clear title + call-to-action button so users know how to proceed.' },
+ { guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
+ { guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },
+ { guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what user can do next.' },
+ { guidance: false, description: 'Use a generic message like "No data" — be specific about what is empty and why.' },
+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use a Banner instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 173aea7e23..294f0e7208 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -494,8 +494,12 @@ export const docsDense = {
usage: {
description: 'Field wraps input controls with label, description, and validation. Use for accessible forms with consistent labeling and inline feedback.',
bestPractices: [
- { guidance: true, description: 'Always provide a label. Use status with clear messages. Add description for format hints.' },
- { guidance: false, description: 'Don\'t set both isOptional and isRequired. Don\'t use detached status on bordered inputs.' },
+ { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
+ { guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
+ { guidance: true, description: 'Add a description when the label alone does not explain what the field expects — format hints or constraints.' },
+ { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
+ { guidance: false, description: 'Use the detached status variant on bordered inputs — reserve it for checkboxes, switches, and sliders.' },
+ { guidance: false, description: 'Hide the label without providing an alternative way for user to understand the field purpose.' },
],
},
components: [
diff --git a/packages/core/src/FileInput/FileInput.doc.mjs b/packages/core/src/FileInput/FileInput.doc.mjs
index 7100e53c53..fe443a8559 100644
--- a/packages/core/src/FileInput/FileInput.doc.mjs
+++ b/packages/core/src/FileInput/FileInput.doc.mjs
@@ -269,6 +269,7 @@ export const docsDense = {
{guidance: true, description: 'Always specify an accept prop to guide users toward valid file types.'},
{guidance: true, description: 'Use maxSize and maxFiles to prevent oversized uploads.'},
{guidance: true, description: 'Add a description to communicate constraints.'},
+ {guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},
{guidance: false, description: "Don't use FileInput for directory uploads."},
{guidance: false, description: "Don't use mode='input' unless space is very constrained — dropzone mode provides a better experience."},
],
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index 78bff55c90..28e00e7b09 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -227,8 +227,12 @@ export const docsDense = {
usage: {
description: 'HoverCard shows additional info on hover/focus. Use for profile cards, link summaries, inline definitions.',
bestPractices: [
- { guidance: true, description: 'Supplementary content only. Dashed underline on text triggers. Hook API for custom control.' },
- { guidance: false, description: 'No critical actions — content disappears on cursor leave. Use Tooltip/Popover when simpler.' },
+ { guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },
+ { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
+ { guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },
+ { guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },
+ { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
+ { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },
],
},
components: [
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index bd76d87591..2ca0552213 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -76,3 +76,29 @@ export const docs = {
],
},
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+ usage: {
+ description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+ bestPractices: [
+ { guidance: true, description: 'Make aria-label specific — trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },
+ { guidance: true, description: 'Add tooltip — even gear icon can mean Settings/Preferences/Configure.' },
+ { guidance: true, description: 'Use ghost in toolbars + dense areas to reduce visual clutter.' },
+ { guidance: false, description: "Use IconButton if action isn't obvious from icon alone — use Button w/ text instead." },
+ { guidance: false, description: 'Skip tooltip — label only reaches screen readers; sighted users need hover hint.' },
+ ],
+ },
+ propDescriptions: {
+ label: 'accessible label; used as aria-label (not rendered as visible text) **(required)**',
+ icon: 'icon element rendered inside button **(required)**',
+ variant: 'visual style variant',
+ size: 'size variant',
+ isLoading: 'shows loading spinner + disables interaction',
+ isDisabled: 'disables button',
+ tooltip: 'tooltip text shown on hover',
+ onClick: 'standard click handler',
+ clickAction: 'async click handler w/ automatic loading state',
+ },
+};
diff --git a/packages/core/src/InputGroup/InputGroup.doc.mjs b/packages/core/src/InputGroup/InputGroup.doc.mjs
index 7b3a606de4..09fb5dd9ce 100644
--- a/packages/core/src/InputGroup/InputGroup.doc.mjs
+++ b/packages/core/src/InputGroup/InputGroup.doc.mjs
@@ -72,9 +72,11 @@ export const docsDense = {
usage: {
description: 'InputGroup connects an input with addons. Use for URL fields, currency inputs, search with actions.',
bestPractices: [
- {guidance: true, description: 'Text addons for units/prefixes. isInteractive for buttons/selectors.'},
- {guidance: true, description: 'isLabelHidden on inner input, group label visible.'},
- {guidance: false, description: 'Don\'t put multiple inputs in one group. Don\'t group unrelated inputs.'},
+ {guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify input format (e.g. "$", "kg", "https://").'},
+ {guidance: true, description: 'Use XDSInputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},
+ {guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},
+ {guidance: false, description: 'Don\'t put multiple text inputs in one group — use separate fields instead.'},
+ {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs — it\'s for a single input with decorations.'},
],
},
components: [
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index 5f01de0f56..9b28510c3f 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -42,3 +42,22 @@ export const docs = {
],
},
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Core positioning hook rendering overlay content via CSS Anchor Positioning + Popover API. Foundation for popovers/hover cards/tooltips w/o React portals.',
+ usage: {
+ description:
+ 'Layer is core positioning hook for overlay content via CSS Anchor Positioning + Popover API. Use as foundation for popovers, hover cards, tooltips w/o React portals.',
+ bestPractices: [
+ { guidance: true, description: 'Use context mode for anchor-positioned overlays relative to trigger element; fixed mode for manually positioned overlays at specific coordinates.' },
+ { guidance: true, description: 'Build on higher-level components (Popover, HoverCard, Tooltip) instead of using Layer directly for common overlay patterns.' },
+ { guidance: false, description: 'Implement ARIA patterns directly in Layer — leave accessibility semantics to higher-level components that build on it.' },
+ ],
+ },
+ propDescriptions: {
+ mode: 'positioning strategy: context = CSS anchor positioning relative to trigger ref; fixed = explicit x/y coords **(required)**',
+ onShow: 'fires when layer becomes visible',
+ onHide: 'fires when layer hidden',
+ },
+};
diff --git a/packages/core/src/Lightbox/Lightbox.doc.mjs b/packages/core/src/Lightbox/Lightbox.doc.mjs
index 154204ce50..49743dfadf 100644
--- a/packages/core/src/Lightbox/Lightbox.doc.mjs
+++ b/packages/core/src/Lightbox/Lightbox.doc.mjs
@@ -140,7 +140,9 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Always provide alt text for every image.' },
{ guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
+ { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
{ guidance: false, description: 'Use for non-image content — specialized for images.' },
+ { guidance: false, description: 'Nest interactive content inside captions — keep them plain text.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Link/LinkProvider.doc.mjs b/packages/core/src/Link/LinkProvider.doc.mjs
index d23e319d3f..7f976324fe 100644
--- a/packages/core/src/Link/LinkProvider.doc.mjs
+++ b/packages/core/src/Link/LinkProvider.doc.mjs
@@ -17,3 +17,14 @@ export const docs = {
{name: 'children', type: 'ReactNode', required: true, description: 'Content to render with the link provider.'},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+ usage: {
+ description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+ },
+ propDescriptions: {
+ component: 'link component for all link elements in subtree (e.g. Next.js Link) **(required)**',
+ },
+};
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index 1c9bcb248f..87ac98085d 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -258,20 +258,20 @@ export const docsZh = {
};
export const docsDense = {
- n: 'Markdown',
- d: 'Renders markdown string as XDS-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
- kw: ['markdown', 'rich text', 'prose', 'renderer', 'streaming', 'markup', 'md'],
+ description:
+ 'Renders markdown string as XDS-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
usage: {
description:
'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation — it handles headings, lists, tables, code blocks, and citations with consistent styling.',
bestPractices: [
{ guidance: true, description: 'Set headingLevelStart to match the page hierarchy — e.g. start at 3 if the markdown sits inside an h2 section.' },
{ guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
+ { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },
{ guidance: false, description: 'Use Markdown for hand-authored layouts — use XDSText and XDSHeading directly when you control the content.' },
],
},
- p: {
- children: 'Markdown string. Required.',
+ propDescriptions: {
+ children: 'Markdown string. **(required)**',
density: "Block spacing. 'default'|'compact'. Default: 'default'.",
headingLevelStart: 'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',
isStreaming: 'Incremental parse + fade-in for streamed chunks. Default: false.',
@@ -286,9 +286,4 @@ export const docsDense = {
style: 'Inline styles. Prefer xstyle.',
'data-testid': 'Test selector.',
},
- ex: [
- '<XDSMarkdown>{\'# Hello\\\\n\\\\nThis is **bold** text.\'}</XDSMarkdown>',
- '<XDSMarkdown isStreaming={isStreaming}>{streamedText}</XDSMarkdown>',
- '<XDSMarkdown inlinePlugins={issuePlugins}>{\'Fixed PROJ-123; `PROJ-999` stays plain.\'}</XDSMarkdown>',
- ],
};
diff --git a/packages/core/src/NavMenu/NavMenu.doc.mjs b/packages/core/src/NavMenu/NavMenu.doc.mjs
index 96fbf1530a..67aa9b25b0 100644
--- a/packages/core/src/NavMenu/NavMenu.doc.mjs
+++ b/packages/core/src/NavMenu/NavMenu.doc.mjs
@@ -24,3 +24,16 @@ export const docs = {
{name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.'},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Accessible menu container + items for nav heading popovers. XDSNavHeadingMenu = role="menu" w/ keyboard nav; XDSNavHeadingMenuItem renders selectable items.',
+ usage: {
+ description:
+ 'Accessible menu container + items for nav heading popovers. XDSNavHeadingMenu provides role="menu" w/ keyboard navigation; XDSNavHeadingMenuItem renders individual selectable items. Pass as menu prop of XDSSideNavHeading or XDSTopNavHeading.',
+ },
+ propDescriptions: {
+ size: 'controls min-width + item padding',
+ minWidth: 'minimum width override',
+ },
+};
diff --git a/packages/core/src/Overlay/Overlay.doc.mjs b/packages/core/src/Overlay/Overlay.doc.mjs
index 9e4907e0aa..615d8a2c85 100644
--- a/packages/core/src/Overlay/Overlay.doc.mjs
+++ b/packages/core/src/Overlay/Overlay.doc.mjs
@@ -14,3 +14,11 @@ export const docs = {
props: [],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: '',
+ usage: {
+ description: '',
+ },
+};
diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjs
index a2b48eb321..7a3ebf0bcd 100644
--- a/packages/core/src/Resizable/Resizable.doc.mjs
+++ b/packages/core/src/Resizable/Resizable.doc.mjs
@@ -187,3 +187,47 @@ export const docs = {
},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Hook-based resizable panel system. useXDSResizable() manages size state; XDSResizeHandle provides interactive pill-grip separator.',
+ usage: {
+ description:
+ 'Hook-based resizable panel system. useXDSResizable() manages size state; XDSResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',
+ bestPractices: [
+ {guidance: true, description: 'Use useXDSResizable() w/ existing XDS layout components. Pass returned props to resizable prop on XDSLayoutPanel or XDSSideNav.'},
+ {guidance: true, description: 'Provide accessible label on each XDSResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
+ {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM — use it directly on existing components.'},
+ ],
+ },
+ components: [
+ {
+ name: 'useXDSResizable',
+ description: 'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',
+ propDescriptions: {
+ defaultSize: 'initial size in px or % string (e.g. "20%")',
+ minSizePx: 'minimum size in px',
+ maxSizePx: 'maximum size in px',
+ collapsible: 'region can collapse to size 0?',
+ collapsedSize: 'px threshold triggering collapse during drag',
+ snaps: 'px values to snap to during resize',
+ shrinkOrder: 'cascade priority — lower number shrinks first',
+ autoSaveId: 'key for persisting sizes to localStorage',
+ },
+ },
+ {
+ name: 'XDSResizeHandle',
+ description: 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',
+ propDescriptions: {
+ direction: 'layout direction — determines cursor + indicator orientation',
+ isReversed: 'reverse drag direction. Use when handle controls panel on end/right/bottom side',
+ isDisabled: 'handle interactive?',
+ hasDivider: 'show full-length 1px divider line through handle. Use when adjacent panels share same background',
+ isAlwaysVisible: 'show pill grip at rest instead of only on hover. Use when discoverability important',
+ pillPlacement: 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',
+ label: 'accessible label for separator',
+ resizable: 'resize props from useXDSResizable — connects handle to panel **(required)**',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index d4c9fd58c6..9087aa5f29 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -166,9 +166,11 @@ export const docsDense = {
description:
'Section creates page regions. Use for settings groups, form sections, sidebar areas. If you want to visually separate a part of a page, use Section — not Card. Cards are for discrete items (one profile, one notification).',
bestPractices: [
- { guidance: true, description: 'Use Section for page-level grouping (settings, forms, sidebars). Use heading + XDSStack inside for content.' },
- { guidance: true, description: 'Default variant = white surface. Muted = gray for emphasis. Add dividers for separation.' },
- { guidance: false, description: 'Use Card for page sections. Cards = discrete items. Sections = page regions.' },
+ { guidance: true, description: 'Use Section for page-level grouping: settings panels, form groups, sidebar regions. Page sections, not discrete items.' },
+ { guidance: true, description: 'Start w/ default variant. Use muted only to call attention to a specific region.' },
+ { guidance: true, description: 'Add dividers between same-background sections that need separation.' },
+ { guidance: true, description: 'Combine w/ heading + XDSStack for typical page section pattern.' },
+ { guidance: false, description: 'Use Card when you mean Section. Cards = discrete items (one notification, one profile). Sections = page regions.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/SelectableCard/SelectableCard.doc.mjs b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
index 503e888ebe..00e93fc652 100644
--- a/packages/core/src/SelectableCard/SelectableCard.doc.mjs
+++ b/packages/core/src/SelectableCard/SelectableCard.doc.mjs
@@ -37,3 +37,27 @@ export const docs = {
targets: [{className: 'xds-selectable-card', visualProps: ['selected']}],
},
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'Card toggling between selected/unselected states w/ accent border. For navigation use ClickableCard instead.',
+ usage: {
+ description: 'Card toggling between selected/unselected states w/ accent border. For navigation use ClickableCard instead.',
+ bestPractices: [
+ {guidance: true, description: 'Use for plan pickers, filter chips, option grids.'},
+ {guidance: true, description: 'For single-select track one ID; for multi-select use a Set.'},
+ {guidance: false, description: 'Use for navigation — use ClickableCard instead.'},
+ ],
+ },
+ propDescriptions: {
+ label: 'accessibility label **(required)**',
+ isSelected: 'controlled selection state **(required)**',
+ onChange: 'called when toggled **(required)**',
+ isDisabled: 'disables card',
+ padding: 'inner padding',
+ variant: 'background color variant',
+ width: 'card width',
+ height: 'card height',
+ maxWidth: 'max card width',
+ },
+};
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 5b3a933559..42bf758572 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -915,8 +915,10 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
{ guidance: true, description: 'Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell.' },
+ { guidance: true, description: 'Set explicit width on every column via proportional() or pixel(). proportional(1) = equal flex w/ 120px min preventing collapse on narrow viewports. Omitting width skips the minimum.' },
{ guidance: false, description: 'Use a table for data without consistent columns — use a list or card layout for heterogeneous content.' },
{ guidance: false, description: 'Enable every plugin at once — add only the features your use case requires to keep the interface focused.' },
+ { guidance: false, description: 'Omit width on text-heavy columns — w/o explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
],
anatomy: [
{name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
@@ -1001,6 +1003,19 @@ export const docsDense = {
getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
},
},
+ {
+ name: 'useXDSTableSelectionState',
+ displayName: 'useXDSTableSelectionState',
+ description: 'State companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows frozen (state preserved across select-all/deselect-all), non-selectable rows excluded.',
+ propDescriptions: {
+ data: 'Full data array rendered in table. **(required)**',
+ idKey: 'Key extractor — property name or fn returning unique string ID. **(required)**',
+ selectedKeys: 'Controlled set of selected item IDs. **(required)**',
+ setSelectedKeys: 'Setter for controlled selected keys. **(required)**',
+ getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows excluded from select-all. Defaults to () => true.',
+ getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows frozen — select-all preserves their state. Defaults to () => true.',
+ },
+ },
{
name: 'useXDSTableSortable',
displayName: 'useXDSTableSortable',
diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
index eb334b58fa..ec7b818dc1 100644
--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs
+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
@@ -120,9 +120,8 @@ export const docsZh = {
};
export const docsDense = {
- n: 'Thumbnail',
- d: 'Square preview card for image attachments. Skeleton shimmer on upload, image on success, placeholder when no src.',
- kw: ['thumbnail', 'attachment', 'preview', 'image', 'upload', 'dismiss', 'remove', 'loading'],
+ description:
+ 'Square preview card for image attachments. Skeleton shimmer on upload, image on success, placeholder when no src.',
usage: {
description:
'Compact square image preview. Shimmer while uploading, image on success, placeholder when empty. Use in chat composers, file lists, or small media previews.',
@@ -134,7 +133,7 @@ export const docsDense = {
{guidance: false, description: "Don't omit alt when src present \u2014 screen readers need image content description, not just label."},
],
},
- p: {
+ propDescriptions: {
src: 'Image source URL.',
alt: 'Alt text for image.',
label: 'Accessible label (file name). Tooltip on hover, aria-label.',
@@ -147,8 +146,4 @@ export const docsDense = {
style: 'Inline styles. Prefer xstyle.',
'data-testid': 'Test selector.',
},
- ex: [
- '<XDSThumbnail src="/photo.jpg" alt="Vacation" label="vacation.jpg" onRemove={() => {}} />',
- '<XDSThumbnail src="/preview.png" alt="Preview" onClick={openLightbox} />',
- ],
};
diff --git a/packages/core/src/theme/MediaTheme.doc.mjs b/packages/core/src/theme/MediaTheme.doc.mjs
index 4e1177fe76..50fb36490d 100644
--- a/packages/core/src/theme/MediaTheme.doc.mjs
+++ b/packages/core/src/theme/MediaTheme.doc.mjs
@@ -24,3 +24,20 @@ export const docs = {
{name: 'children', type: 'ReactNode', required: true, description: 'Content to render with inverted token context. Components inherit the correct colors automatically.'},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ usage: {
+ description:
+ 'Token overrides for content on inverted surfaces — media overlays, scrims, toasts, tooltips. Base behavior flips color-scheme so all light-dark() tokens resolve to correct side; only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), w/ token overrides (e.g. "--color-accent": "#90CAF9") + component overrides (e.g. ghost buttons get border on dark surfaces).',
+ bestPractices: [
+ {guidance: true, description: 'Use for any content over dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts/tooltips.'},
+ {guidance: true, description: 'Pair w/ background color — MediaTheme flips token context but does NOT add background. Set backgroundColor on parent element.'},
+ {guidance: true, description: 'Themes can customize components on media surfaces via onDark.components + onLight.components in defineTheme(). E.g. add border to ghost buttons on dark surfaces.'},
+ {guidance: false, description: 'Use MediaTheme for app-level dark mode — use XDSTheme w/ mode="dark"/mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.'},
+ ],
+ },
+ propDescriptions: {
+ mode: 'surface luminance context — dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions). **(required)**',
+ },
+};
diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjs
index 4555e745ce..1092dd19a6 100644
--- a/packages/core/src/theme/SyntaxTheme.doc.mjs
+++ b/packages/core/src/theme/SyntaxTheme.doc.mjs
@@ -24,3 +24,20 @@ export const docs = {
{name: 'children', type: 'ReactNode', required: true, description: 'Content subtree. All XDSCodeBlock components within will use this syntax theme.'},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ usage: {
+ description:
+ 'Applies syntax highlighting colors to XDSCodeBlock + any code component in subtree. By default code components use theme-level syntax colors (set via defineTheme({ syntax: ... })), which derive from palette (--color-text-accent for keywords, --color-text-green for strings, etc.); XDSSyntaxTheme overrides those per-region. 14 semantic tokens (keyword, string, comment, number, function, type, variable, operator, constant, tag, attribute, property, punctuation, background) validated against 11 community themes. Custom themes created w/ defineSyntaxTheme(), can use [light, dark] tuples for automatic color-scheme adaptation. Built-in presets: oneDarkPro, dracula, monokai, nord, tokyoNight, catppuccinMocha, githubLight, githubDark, solarizedLight, oneLight (import from @xds/core/theme/syntax).',
+ bestPractices: [
+ {guidance: true, description: 'Use syntax field in defineTheme() for app-wide code styling. Use XDSSyntaxTheme only when a specific section needs different look.'},
+ {guidance: true, description: 'Pick from built-in presets or create custom theme w/ defineSyntaxTheme() for brand-specific colors.'},
+ {guidance: true, description: 'Syntax themes support light-dark() tuples — each token can have different values for light/dark mode, resolved automatically by color scheme.'},
+ {guidance: false, description: 'Wrap individual CodeBlock instances w/ XDSSyntaxTheme — use syntaxTheme prop on XDSCodeBlock directly for per-instance overrides instead.'},
+ ],
+ },
+ propDescriptions: {
+ theme: 'syntax highlighting theme — preset from @xds/core/theme/syntax or custom theme created w/ defineSyntaxTheme(). **(required)**',
+ },
+};
diff --git a/packages/core/src/theme/XDSTheme.doc.mjs b/packages/core/src/theme/XDSTheme.doc.mjs
index e17e5d3fd8..89d90743d0 100644
--- a/packages/core/src/theme/XDSTheme.doc.mjs
+++ b/packages/core/src/theme/XDSTheme.doc.mjs
@@ -18,3 +18,15 @@ export const docs = {
{name: 'children', type: 'ReactNode', required: true, description: 'Content to render with the theme.'},
],
};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ usage: {
+ description:
+ 'Wraps subtree w/ a specific XDS theme. Use at app root or around sections that need different visual treatment.',
+ },
+ propDescriptions: {
+ theme: 'theme created by defineTheme(). **(required)**',
+ mode: 'color mode — system follows OS preference. defaults to "system"',
+ },
+};