An open source design system that's fully customizable and agent ready
TypeScript
Improve Breadcrumbs docs page and block examples (#1553)
rubyycheung8d96e1d501f3
diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.doc.mjs b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.doc.mjsindex c9d9c58f68..88bd528bdc 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.doc.mjs+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.doc.mjs@@ -1,10 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Breadcrumbs — Custom Separator',- description:- 'Breadcrumbs trail using a custom separator character between items.',+ name: 'Breadcrumbs — Separators',+ description: 'Swap the default "/" for a different character like chevrons, arrows, or dots. Use when the visual style of the page calls for a different separator.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Breadcrumbs'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Breadcrumbs', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.tsx b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.tsxindex 7dc9c3edbe..07875ff2a8 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.tsx+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsCustomSeparator.tsx@@ -1,13 +1,30 @@'use client';import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++const SEPARATORS = [+ {char: '›', label: 'Chevron'},+ {char: '→', label: 'Arrow'},+ {char: '·', label: 'Dot'},+];export default function BreadcrumbsCustomSeparator() {return (- <XDSBreadcrumbs separator="›">- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>- <XDSBreadcrumbItem href="/docs">Docs</XDSBreadcrumbItem>- <XDSBreadcrumbItem isCurrent>API Reference</XDSBreadcrumbItem>- </XDSBreadcrumbs>+ <XDSStack direction="vertical" gap={4}>+ {SEPARATORS.map(({char, label}) => (+ <XDSStack key={label} direction="vertical" gap={1}>+ <XDSText type="supporting" color="secondary">+ {label}+ </XDSText>+ <XDSBreadcrumbs separator={char}>+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem href="/docs">Docs</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>API Reference</XDSBreadcrumbItem>+ </XDSBreadcrumbs>+ </XDSStack>+ ))}+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.doc.mjs b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.doc.mjsindex 5cdc17ec76..8c5c6f224f 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.doc.mjs+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.doc.mjs@@ -1,10 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Breadcrumbs — Deep Hierarchy',- description:- 'Breadcrumbs trail with five levels showing a deep navigation path.',+ name: 'Breadcrumbs — Deep Path',+ description: 'A 5-level breadcrumb trail for deeply nested content. Use in e-commerce, file browsers, or any UI with several levels of hierarchy.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Breadcrumbs'],+ aspectRatio: 16 / 4,+ componentsUsed: ['Breadcrumbs', 'Icon'],};diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.tsx b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.tsxindex 907fabd7cd..cc86b6ec1e 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.tsx+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsDeepHierarchy.tsx@@ -1,11 +1,17 @@'use client';import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';+import {XDSIcon} from '@xds/core/Icon';+import {HomeIcon} from '@heroicons/react/24/outline';export default function BreadcrumbsDeepHierarchy() {return (<XDSBreadcrumbs>- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem+ href="/"+ startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>+ Home+ </XDSBreadcrumbItem><XDSBreadcrumbItem href="/products">Products</XDSBreadcrumbItem><XDSBreadcrumbItem href="/products/electronics">Electronicsdiff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.doc.mjs b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.doc.mjsindex d6c5faece7..30f1558467 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.doc.mjs+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.doc.mjs@@ -1,10 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Breadcrumbs — Supporting Variant',- description:- 'Breadcrumbs using the supporting variant with smaller, muted text.',+ name: 'Breadcrumbs — Variants',+ description: 'Compare the default and supporting variants side by side. Use the supporting variant in dense UIs like admin panels where the breadcrumb should be subtle.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Breadcrumbs'],+ aspectRatio: 16 / 9,+ componentsUsed: ['Breadcrumbs', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.tsx b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.tsxindex 337f79273d..89a67cb2be 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.tsx+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsSupportingVariant.tsx@@ -1,13 +1,32 @@'use client';import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';export default function BreadcrumbsSupportingVariant() {return (- <XDSBreadcrumbs variant="supporting">- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>- <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>- <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>- </XDSBreadcrumbs>+ <XDSStack direction="vertical" gap={4}>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="supporting" color="secondary">+ Default+ </XDSText>+ <XDSBreadcrumbs>+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>+ </XDSBreadcrumbs>+ </XDSStack>+ <XDSStack direction="vertical" gap={1}>+ <XDSText type="supporting" color="secondary">+ Supporting+ </XDSText>+ <XDSBreadcrumbs variant="supporting">+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>+ </XDSBreadcrumbs>+ </XDSStack>+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.doc.mjs b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.doc.mjsindex 07887566d5..300dbf42b3 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.doc.mjs+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.doc.mjs@@ -1,9 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'Breadcrumbs — With Icons',- description: 'Breadcrumbs with leading icons on each navigation item.',+ name: 'Breadcrumbs — Icons',+ description: 'Add icons before breadcrumb labels for quick recognition. Use a home icon on the root item and contextual icons on key sections.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Breadcrumbs'],+ aspectRatio: 16 / 4,+ componentsUsed: ['Breadcrumbs', 'Icon'],};diff --git a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.tsx b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.tsxindex 26faec812f..40806411e8 100644--- a/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.tsx+++ b/packages/cli/templates/blocks/components/Breadcrumbs/BreadcrumbsWithIcons.tsx@@ -1,52 +1,20 @@'use client';import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';--function HomeIcon() {- return (- <svg- width={16}- height={16}- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={1.5}- aria-hidden="true">- <path- strokeLinecap="round"- strokeLinejoin="round"- d="m2.25 12 8.954-8.955a1.126 1.126 0 0 1 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25"- />- </svg>- );-}--function SettingsIcon() {- return (- <svg- width={16}- height={16}- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={1.5}- aria-hidden="true">- <path- strokeLinecap="round"- strokeLinejoin="round"- d="M10.343 3.94c.09-.542.56-.94 1.11-.94h1.093c.55 0 1.02.398 1.11.94l.149.894c.07.424.384.764.78.93s.844.141 1.2-.058l.758-.454a1.125 1.125 0 0 1 1.37.17l.773.773c.4.4.48 1.01.17 1.37l-.454.758c-.2.356-.223.808-.058 1.2s.506.71.93.78l.894.149c.542.09.94.56.94 1.11v1.093c0 .55-.398 1.02-.94 1.11l-.894.149c-.424.07-.764.384-.93.78s-.141.844.058 1.2l.454.758a1.125 1.125 0 0 1-.17 1.37l-.773.773a1.125 1.125 0 0 1-1.37.17l-.758-.454c-.356-.2-.808-.223-1.2-.058s-.71.506-.78.93l-.149.894c-.09.542-.56.94-1.11.94h-1.093c-.55 0-1.02-.398-1.11-.94l-.149-.894a1.62 1.62 0 0 0-.78-.93 1.62 1.62 0 0 0-1.2.058l-.758.454a1.125 1.125 0 0 1-1.37-.17l-.773-.773a1.125 1.125 0 0 1-.17-1.37l.454-.758c.2-.356.223-.808.058-1.2a1.62 1.62 0 0 0-.93-.78l-.894-.149c-.542-.09-.94-.56-.94-1.11v-1.093c0-.55.398-1.02.94-1.11l.894-.149c.424-.07.764-.384.93-.78s.141-.844-.058-1.2l-.454-.758a1.125 1.125 0 0 1 .17-1.37l.773-.773a1.125 1.125 0 0 1 1.37-.17l.758.454c.356.2.808.223 1.2.058s.71-.506.78-.93l.149-.894ZM15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"- />- </svg>- );-}+import {XDSIcon} from '@xds/core/Icon';+import {HomeIcon, Cog6ToothIcon} from '@heroicons/react/24/outline';export default function BreadcrumbsWithIcons() {return (<XDSBreadcrumbs>- <XDSBreadcrumbItem href="/" startIcon={<HomeIcon />}>+ <XDSBreadcrumbItem+ href="/"+ startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>Home</XDSBreadcrumbItem>- <XDSBreadcrumbItem href="/settings" startIcon={<SettingsIcon />}>+ <XDSBreadcrumbItem+ href="/settings"+ startIcon={<XDSIcon icon={Cog6ToothIcon} size="sm" />}>Settings</XDSBreadcrumbItem><XDSBreadcrumbItem isCurrent>Profile</XDSBreadcrumbItem>diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjsindex bad6796cd4..037c0d9a54 100644--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs@@ -5,11 +5,21 @@ export const docs = {keywords: ["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],usage: {description:- 'Breadcrumbs display a secondary navigation trail that shows the user\'s position within a content hierarchy. Use to orient users and enable quick back-and-forth navigation across nested pages.',+ 'Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.',bestPractices: [- {guidance: true, description: 'Place breadcrumbs near the top of the page, above the main heading, to establish hierarchy context.'},- {guidance: true, description: 'Keep breadcrumb labels short and match the titles of the pages they link to.'},- {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement, not replace, a main nav.'},+ {guidance: true, description: 'Place breadcrumbs above the page heading so the user sees their location before reading the content.'},+ {guidance: true, description: 'Keep labels short and match the page titles they link to — "Settings" not "Application Settings Page".'},+ {guidance: true, description: 'Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.'},+ {guidance: true, description: 'Make the last item plain text, not a link — it represents the current page. The component does this automatically when you set isCurrent.'},+ {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement a sidebar or top nav, not replace it.'},+ {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent — they add clutter without helping the user.'},+ {guidance: false, description: 'Let the trail grow beyond 5 levels — if you need more, consider simplifying the page hierarchy instead.'},+ ],+ anatomy: [+ {name: 'Trail', required: true, description: 'The ordered list of links from root to current page.'},+ {name: 'Item', required: true, description: 'A single step in the trail. Renders as a link or plain text for the current page.'},+ {name: 'Separator', required: true, description: 'The character between items. Defaults to "/" but can be customized.'},+ {name: 'Icon', required: false, description: 'An optional icon before an item label, like a home icon on the first item.'},],},theming: {@@ -107,11 +117,15 @@ export const docsZh = {name: 'Breadcrumbs',usage: {description:- 'Breadcrumbs display a secondary navigation trail that shows the user\'s position within a content hierarchy. Use to orient users and enable quick back-and-forth navigation across nested pages.',+ 'Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.',bestPractices: [- {guidance: true, description: 'Place breadcrumbs near the top of the page, above the main heading, to establish hierarchy context.'},- {guidance: true, description: 'Keep breadcrumb labels short and match the titles of the pages they link to.'},- {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement, not replace, a main nav.'},+ {guidance: true, description: 'Place breadcrumbs above the page heading so the user sees their location before reading the content.'},+ {guidance: true, description: 'Keep labels short and match the page titles they link to — "Settings" not "Application Settings Page".'},+ {guidance: true, description: 'Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.'},+ {guidance: true, description: 'Make the last item plain text, not a link — it represents the current page. The component does this automatically when you set isCurrent.'},+ {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement a sidebar or top nav, not replace it.'},+ {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent — they add clutter without helping the user.'},+ {guidance: false, description: 'Let the trail grow beyond 5 levels — if you need more, consider simplifying the page hierarchy instead.'},],},theming: {@@ -159,14 +173,17 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'navigation breadcrumb trail w/ semantic HTML',+ description: 'link trail from root to current page for wayfinding',usage: {description:- 'Breadcrumbs display a secondary navigation trail that shows the user\'s position within a content hierarchy. Use to orient users and enable quick back-and-forth navigation across nested pages.',+ '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 breadcrumbs near the top of the page, above the main heading, to establish hierarchy context.'},- {guidance: true, description: 'Keep breadcrumb labels short and match the titles of the pages they link to.'},- {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement, not replace, a main nav.'},+ {guidance: true, description: 'Place above the page heading. Keep labels short and matching page titles.'},+ {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: 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.'},],},components: [