Skip to content

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

TypeScript

docs(toolbar): improve block templates and component documentation (#1651)

rubyycheunga9ecd53ed5df
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkActions.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkActions.doc.mjs
new file mode 100644
index 0000000000..521a487a27
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkActions.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toolbar — Bulk Actions',
+ description:
+ 'A compact toolbar with the wash variant for showing bulk selection actions. Use when the user selects multiple items in a list or table and needs quick access to batch operations.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toolbar', 'Button', 'Icon', 'Badge', 'Table'],
+};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkActions.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkActions.tsx
new file mode 100644
index 0000000000..a61e0854b5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkActions.tsx
@@ -0,0 +1,79 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSToolbar} from '@xds/core/Toolbar';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSTable} from '@xds/core/Table';
+import {useXDSTableSelection, useXDSTableSelectionState} from '@xds/core/Table';
+import {TrashIcon, ArchiveBoxIcon} from '@heroicons/react/24/outline';
+
+const DATA = [
+ {id: '1', name: 'Alex Johnson', status: 'Active', role: 'Admin'},
+ {id: '2', name: 'Sam Rivera', status: 'Active', role: 'Editor'},
+ {id: '3', name: 'Jordan Lee', status: 'Invited', role: 'Viewer'},
+ {id: '4', name: 'Taylor Kim', status: 'Active', role: 'Editor'},
+ {id: '5', name: 'Casey Park', status: 'Active', role: 'Viewer'},
+];
+
+export default function ToolbarBulkActions() {
+ const [selectedKeys, setSelectedKeys] = useState<Set<string>>(
+ () => new Set(['1', '3', '5']),
+ );
+
+ const {selectionConfig} = useXDSTableSelectionState({
+ data: DATA,
+ idKey: 'id',
+ selectedKeys,
+ setSelectedKeys,
+ });
+
+ const selectionPlugin = useXDSTableSelection(selectionConfig);
+
+ return (
+ <>
+ {selectedKeys.size > 0 && (
+ <XDSToolbar
+ label="Bulk actions"
+ size="sm"
+ variant="wash"
+ startContent={
+ <>
+ <XDSBadge label={`${selectedKeys.size} selected`} />
+ <XDSButton
+ label="Delete"
+ variant="ghost"
+ icon={<XDSIcon icon={TrashIcon} />}
+ isIconOnly
+ />
+ <XDSButton
+ label="Archive"
+ variant="ghost"
+ icon={<XDSIcon icon={ArchiveBoxIcon} />}
+ isIconOnly
+ />
+ </>
+ }
+ endContent={
+ <XDSButton
+ label="Deselect all"
+ variant="ghost"
+ onClick={() => setSelectedKeys(new Set())}
+ />
+ }
+ />
+ )}
+ <XDSTable
+ idKey="id"
+ columns={[
+ {key: 'name', header: 'Name'},
+ {key: 'status', header: 'Status'},
+ {key: 'role', header: 'Role'},
+ ]}
+ data={DATA}
+ plugins={{selection: selectionPlugin}}
+ />
+ </>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkSelection.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkSelection.doc.mjs
deleted file mode 100644
index 5ea3183eff..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkSelection.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toolbar — Bulk Selection',
- description:
- 'Contextual toolbar for bulk item selection with badge count and actions.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toolbar', 'Badge', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkSelection.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkSelection.tsx
deleted file mode 100644
index bf73107f1d..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarBulkSelection.tsx
+++ /dev/null
@@ -1,59 +0,0 @@
-'use client';
-
-import {XDSToolbar} from '@xds/core/Toolbar';
-import {XDSBadge} from '@xds/core/Badge';
-import {XDSButton} from '@xds/core/Button';
-
-export default function ToolbarBulkSelection() {
- return (
- <XDSToolbar
- label="Bulk actions"
- variant="wash"
- startContent={
- <>
- <XDSBadge label="5 selected" />
- <XDSButton
- label="Delete"
- variant="ghost"
- size="sm"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={1.5}
- strokeLinecap="round"
- strokeLinejoin="round">
- <path d="M3 4h10M5 4V3a1 1 0 011-1h4a1 1 0 011 1v1m2 0v9a1 1 0 01-1 1H4a1 1 0 01-1-1V4h10z" />
- </svg>
- }
- isIconOnly
- />
- <XDSButton
- label="Archive"
- variant="ghost"
- size="sm"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={1.5}
- strokeLinecap="round"
- strokeLinejoin="round">
- <rect x="1" y="2" width="14" height="3" rx="1" />
- <path d="M2 5v8a1 1 0 001 1h10a1 1 0 001-1V5M6.5 8h3" />
- </svg>
- }
- isIconOnly
- />
- </>
- }
- endContent={<XDSButton label="Deselect all" variant="ghost" size="sm" />}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs
index 9e55da0c3c..0cdfc70900 100644
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Toolbar — Card Header',
description:
- 'Compact toolbar as a card header with title, filter, and add actions.',
+ 'A toolbar as a card header with a left-aligned title and icon actions on the right. Use Toolbar instead of LayoutHeader when your card header has interactive actions — Toolbar adds start/end slot layout, keyboard navigation, and automatic size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toolbar', 'Card', 'Section', 'Button', 'Text'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toolbar', 'Button', 'Icon', 'Text', 'Card', 'Section'],
};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.tsx
index d1aabfaa10..2583e42304 100644
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.tsx
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarCardHeader.tsx
@@ -1,63 +1,47 @@
'use client';
import {XDSToolbar} from '@xds/core/Toolbar';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSHeading} from '@xds/core/Text';
import {XDSCard} from '@xds/core/Card';
import {XDSSection} from '@xds/core/Section';
-import {XDSText, XDSHeading} from '@xds/core/Text';
-import {XDSButton} from '@xds/core/Button';
+import {FunnelIcon, PlusIcon} from '@heroicons/react/24/outline';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ card: {
+ width: 600,
+ height: '100%',
+ marginTop: 260,
+ },
+});
export default function ToolbarCardHeader() {
return (
- <XDSCard width={600}>
+ <XDSCard xstyle={styles.card}>
<XDSToolbar
label="User list actions"
size="sm"
dividers={['bottom']}
- startContent={<XDSHeading level={4}>Users</XDSHeading>}
+ startContent={<XDSHeading level={4}>Card title</XDSHeading>}
endContent={
<>
<XDSButton
label="Filter"
variant="ghost"
- size="sm"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={1.5}
- strokeLinecap="round"
- strokeLinejoin="round">
- <path d="M1.5 3h13L9.5 9v4l-3 1.5V9L1.5 3z" />
- </svg>
- }
+ icon={<XDSIcon icon={FunnelIcon} />}
isIconOnly
/>
<XDSButton
label="Add user"
- size="sm"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={2}
- strokeLinecap="round">
- <path d="M8 3v10M3 8h10" />
- </svg>
- }
+ icon={<XDSIcon icon={PlusIcon} />}
isIconOnly
/>
</>
}
/>
- <XDSSection>
- <XDSText type="body">Table rows go here...</XDSText>
- </XDSSection>
+ <XDSSection />
</XDSCard>
);
}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarPageHeader.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarPageHeader.doc.mjs
deleted file mode 100644
index 29ebcc3ca0..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarPageHeader.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toolbar — Page Header',
- description:
- 'Page-level toolbar with back navigation, centered title, and save actions.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toolbar', 'Card', 'Section', 'Button', 'Text'],
-};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarPageHeader.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarPageHeader.tsx
deleted file mode 100644
index f1d8a6f09e..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarPageHeader.tsx
+++ /dev/null
@@ -1,48 +0,0 @@
-'use client';
-
-import {XDSToolbar} from '@xds/core/Toolbar';
-import {XDSCard} from '@xds/core/Card';
-import {XDSSection} from '@xds/core/Section';
-import {XDSText, XDSHeading} from '@xds/core/Text';
-import {XDSButton} from '@xds/core/Button';
-
-export default function ToolbarPageHeader() {
- return (
- <XDSCard>
- <XDSToolbar
- label="Page navigation"
- dividers={['bottom']}
- startContent={
- <XDSButton
- label="Back to projects"
- variant="ghost"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={1.5}
- strokeLinecap="round"
- strokeLinejoin="round">
- <path d="M10 3L5 8l5 5" />
- </svg>
- }
- isIconOnly
- />
- }
- centerContent={<XDSHeading level={3}>Project Settings</XDSHeading>}
- endContent={
- <>
- <XDSButton label="Reset" variant="ghost" />
- <XDSButton label="Save changes" />
- </>
- }
- />
- <XDSSection>
- <XDSText type="body">Settings form content...</XDSText>
- </XDSSection>
- </XDSCard>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarShowcase.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarShowcase.doc.mjs
deleted file mode 100644
index 522c11da7c..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarShowcase.doc.mjs
+++ /dev/null
@@ -1,8 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toolbar',
- isReady: true,
- aspectRatio: 4 / 3,
- isShowcase: true,
-};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarShowcase.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarShowcase.tsx
deleted file mode 100644
index 9fa002b083..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarShowcase.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-'use client';
-
-import {XDSToolbar} from '@xds/core/Toolbar';
-import {XDSButton} from '@xds/core/Button';
-
-export default function ToolbarShowcase() {
- return (
- <XDSToolbar
- label="Actions"
- startContent={
- <>
- <XDSButton label="Cut" variant="ghost" />
- <XDSButton label="Copy" variant="ghost" />
- <XDSButton label="Paste" variant="ghost" />
- </>
- }
- endContent={
- <XDSButton
- label="Settings"
- variant="ghost"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={1.5}>
- <circle cx="8" cy="8" r="2" />
- <path d="M8 1v2M8 13v2M1 8h2M13 8h2M3.05 3.05l1.41 1.41M11.54 11.54l1.41 1.41M3.05 12.95l1.41-1.41M11.54 4.46l1.41-1.41" />
- </svg>
- }
- isIconOnly
- />
- }
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarSizes.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarSizes.doc.mjs
new file mode 100644
index 0000000000..96289481ea
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarSizes.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toolbar — Sizes',
+ description:
+ 'Small, medium, and large toolbars side by side. The size prop cascades to child buttons and inputs automatically. Use small in dense UIs like cards, medium for most cases, and large for spacious layouts.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toolbar', 'Button', 'Icon', 'Text', 'Layout', 'Card'],
+};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarSizes.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarSizes.tsx
new file mode 100644
index 0000000000..26a9a47153
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarSizes.tsx
@@ -0,0 +1,50 @@
+'use client';
+
+import {XDSToolbar} from '@xds/core/Toolbar';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSHeading} from '@xds/core/Text';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSCard} from '@xds/core/Card';
+import {FunnelIcon, PlusIcon} from '@heroicons/react/24/outline';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ container: {
+ width: 600,
+ },
+});
+
+const SIZES = [
+ {size: 'sm' as const, label: 'Small'},
+ {size: 'md' as const, label: 'Medium'},
+ {size: 'lg' as const, label: 'Large'},
+];
+
+export default function ToolbarSizes() {
+ return (
+ <XDSStack direction="vertical" gap={4} xstyle={styles.container}>
+ {SIZES.map(({size, label}) => (
+ <XDSCard key={size}>
+ <XDSToolbar
+ label={`${label} toolbar`}
+ size={size}
+ dividers={['bottom']}
+ startContent={<XDSHeading level={4}>{label}</XDSHeading>}
+ endContent={
+ <>
+ <XDSButton
+ label="Filter"
+ variant="ghost"
+ icon={<XDSIcon icon={FunnelIcon} />}
+ isIconOnly
+ />
+ <XDSButton label="Add" icon={<XDSIcon icon={PlusIcon} />} />
+ </>
+ }
+ />
+ </XDSCard>
+ ))}
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarTableFilter.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarTableFilter.doc.mjs
new file mode 100644
index 0000000000..4c92926519
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarTableFilter.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toolbar — Table Filter',
+ description:
+ 'A compact toolbar with a search input, filter buttons, and an overflow menu. Use above a data table to let users search, filter, and access view options.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toolbar', 'Button', 'Icon', 'TextInput', 'MoreMenu', 'Layout', 'Table'],
+};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx
new file mode 100644
index 0000000000..7ced5d81d8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx
@@ -0,0 +1,81 @@
+'use client';
+
+import {XDSToolbar} from '@xds/core/Toolbar';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSMoreMenu} from '@xds/core/MoreMenu';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSTable} from '@xds/core/Table';
+import * as stylex from '@stylexjs/stylex';
+import {
+ MagnifyingGlassIcon,
+ ChevronDownIcon,
+} from '@heroicons/react/24/outline';
+
+const styles = stylex.create({
+ container: {
+ width: 600,
+ },
+});
+
+export default function ToolbarTableFilter() {
+ return (
+ <XDSStack direction="vertical" xstyle={styles.container}>
+ <XDSToolbar
+ label="Table filters"
+ size="sm"
+ dividers={['bottom']}
+ startContent={
+ <>
+ <XDSTextInput
+ label="Search"
+ isLabelHidden
+ placeholder="Search..."
+ value=""
+ onChange={() => {}}
+ startIcon={MagnifyingGlassIcon}
+ />
+ <XDSButton
+ label="Status"
+ variant="secondary"
+ endContent={<XDSIcon icon={ChevronDownIcon} />}
+ />
+ <XDSButton
+ label="Priority"
+ variant="secondary"
+ endContent={<XDSIcon icon={ChevronDownIcon} />}
+ />
+ </>
+ }
+ endContent={
+ <XDSMoreMenu
+ items={[
+ {label: 'Compact view'},
+ {label: 'Comfortable view'},
+ {label: 'Export CSV'},
+ ]}
+ />
+ }
+ />
+ <XDSTable
+ idKey="id"
+ columns={[
+ {key: 'task', header: 'Task'},
+ {key: 'status', header: 'Status'},
+ {key: 'priority', header: 'Priority'},
+ ]}
+ data={[
+ {id: '1', task: 'Fix login bug', status: 'Open', priority: 'High'},
+ {
+ id: '2',
+ task: 'Update docs',
+ status: 'In progress',
+ priority: 'Medium',
+ },
+ {id: '3', task: 'Add unit tests', status: 'Open', priority: 'Low'},
+ ]}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarTableToolbar.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarTableToolbar.doc.mjs
deleted file mode 100644
index d601baa35b..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarTableToolbar.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toolbar — Table Toolbar',
- description:
- 'Data table toolbar with search input, filter buttons, and view options.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toolbar', 'TextInput', 'Button', 'MoreMenu', 'Table'],
-};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarTableToolbar.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarTableToolbar.tsx
deleted file mode 100644
index 3710d6d732..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarTableToolbar.tsx
+++ /dev/null
@@ -1,54 +0,0 @@
-'use client';
-
-import {XDSToolbar} from '@xds/core/Toolbar';
-import {XDSButton} from '@xds/core/Button';
-import {XDSTextInput} from '@xds/core/TextInput';
-import {XDSMoreMenu} from '@xds/core/MoreMenu';
-import {XDSTable} from '@xds/core/Table';
-
-export default function ToolbarTableToolbar() {
- return (
- <div style={{width: 700}}>
- <XDSToolbar
- label="Table filters"
- startContent={
- <>
- <XDSTextInput
- label="Search"
- isLabelHidden
- placeholder="Search..."
- size="sm"
- value=""
- onChange={() => {}}
- />
- <XDSButton label="Status" variant="secondary" size="sm" />
- <XDSButton label="Priority" variant="secondary" size="sm" />
- <XDSButton label="Assignee" variant="secondary" size="sm" />
- </>
- }
- endContent={
- <XDSMoreMenu
- items={[
- {label: 'Compact view'},
- {label: 'Comfortable view'},
- {label: 'Export CSV'},
- ]}
- />
- }
- />
- <XDSTable
- idKey="id"
- columns={[
- {key: 'name', header: 'Name'},
- {key: 'status', header: 'Status'},
- {key: 'priority', header: 'Priority'},
- ]}
- data={[
- {id: '1', name: 'Fix login bug', status: 'Open', priority: 'High'},
- {id: '2', name: 'Update docs', status: 'In Progress', priority: 'Medium'},
- {id: '3', name: 'Add tests', status: 'Open', priority: 'Low'},
- ]}
- />
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlot.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlot.doc.mjs
new file mode 100644
index 0000000000..7162948700
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlot.doc.mjs
@@ -0,0 +1,11 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toolbar — Three Slot',
+ description:
+ 'A toolbar with start, center, and end content using the three-column grid layout. Use when you need a centered title or heading with navigation and actions on either side.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toolbar', 'Button', 'Icon', 'Text', 'Card', 'Section'],
+};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlot.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlot.tsx
new file mode 100644
index 0000000000..9f42008ebc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlot.tsx
@@ -0,0 +1,45 @@
+'use client';
+
+import {XDSToolbar} from '@xds/core/Toolbar';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSHeading} from '@xds/core/Text';
+import {XDSCard} from '@xds/core/Card';
+import {XDSSection} from '@xds/core/Section';
+import {ArrowLeftIcon} from '@heroicons/react/24/outline';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ card: {
+ width: 600,
+ height: '100%',
+ marginTop: 260,
+ },
+});
+
+export default function ToolbarThreeSlot() {
+ return (
+ <XDSCard xstyle={styles.card}>
+ <XDSToolbar
+ label="Document toolbar"
+ dividers={['bottom']}
+ startContent={
+ <XDSButton
+ label="Back"
+ variant="ghost"
+ icon={<XDSIcon icon={ArrowLeftIcon} />}
+ isIconOnly
+ />
+ }
+ centerContent={<XDSHeading level={4}>Title</XDSHeading>}
+ endContent={
+ <>
+ <XDSButton label="Discard" variant="secondary" />
+ <XDSButton label="Save" variant="primary" />
+ </>
+ }
+ />
+ <XDSSection />
+ </XDSCard>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlotLayout.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlotLayout.doc.mjs
deleted file mode 100644
index b6ec55c7fa..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlotLayout.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Toolbar — Three-Slot Layout',
- description:
- 'Toolbar with start, center, and end slots for document-style headers.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Toolbar', 'Button', 'Heading'],
-};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlotLayout.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlotLayout.tsx
deleted file mode 100644
index 744b1bb1f8..0000000000
--- a/packages/cli/templates/blocks/components/Toolbar/ToolbarThreeSlotLayout.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-'use client';
-
-import {XDSToolbar} from '@xds/core/Toolbar';
-import {XDSButton} from '@xds/core/Button';
-import {XDSHeading} from '@xds/core/Text';
-
-export default function ToolbarThreeSlotLayout() {
- return (
- <XDSToolbar
- label="Document toolbar"
- startContent={
- <XDSButton
- label="Back"
- variant="ghost"
- icon={
- <svg
- width={16}
- height={16}
- viewBox="0 0 16 16"
- fill="none"
- stroke="currentColor"
- strokeWidth={1.5}
- strokeLinecap="round"
- strokeLinejoin="round">
- <path d="M10 3L5 8l5 5" />
- </svg>
- }
- isIconOnly
- />
- }
- centerContent={<XDSHeading level={4}>Q1 Planning Document</XDSHeading>}
- endContent={
- <>
- <XDSButton label="Discard" variant="secondary" />
- <XDSButton label="Save" />
- </>
- }
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarWithTabs.doc.mjs b/packages/cli/templates/blocks/components/Toolbar/ToolbarWithTabs.doc.mjs
new file mode 100644
index 0000000000..5c98eb6bf0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarWithTabs.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Toolbar — Tab Navigation',
+ description:
+ 'A toolbar with tabs in the start slot and an action button at the end. Use as a card or section header when content is split into tabs with a primary action alongside.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Toolbar', 'TabList', 'Button', 'Icon', 'Card', 'Section'],
+};
diff --git a/packages/cli/templates/blocks/components/Toolbar/ToolbarWithTabs.tsx b/packages/cli/templates/blocks/components/Toolbar/ToolbarWithTabs.tsx
new file mode 100644
index 0000000000..92f43368f1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Toolbar/ToolbarWithTabs.tsx
@@ -0,0 +1,46 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSToolbar} from '@xds/core/Toolbar';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSTabList, XDSTab} from '@xds/core/TabList';
+import {XDSCard} from '@xds/core/Card';
+import {XDSSection} from '@xds/core/Section';
+import {PlusIcon} from '@heroicons/react/24/outline';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ card: {
+ width: '100%',
+ height: '100%',
+ marginTop: 200,
+ },
+});
+
+export default function ToolbarWithTabs() {
+ const [tab, setTab] = useState('overview');
+ return (
+ <XDSCard xstyle={styles.card}>
+ <XDSToolbar
+ label="Section navigation"
+ dividers={['bottom']}
+ startContent={
+ <XDSTabList value={tab} onChange={setTab}>
+ <XDSTab value="overview" label="Overview" />
+ <XDSTab value="analytics" label="Analytics" />
+ <XDSTab value="settings" label="Settings" />
+ </XDSTabList>
+ }
+ endContent={
+ <XDSButton
+ label="New item"
+ icon={<XDSIcon icon={PlusIcon} />}
+ isIconOnly
+ />
+ }
+ />
+ <XDSSection />
+ </XDSCard>
+ );
+}
diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjs
index 35e6c3d9e2..89a6af3754 100644
--- a/packages/core/src/Toolbar/Toolbar.doc.mjs
+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -71,11 +71,15 @@ export const docs = {
],
usage: {
description:
- 'Toolbar is a horizontal container for grouping related actions and controls using start, center, and end content slots. Use Toolbar to provide contextual actions above content areas like tables, editors, or detail panels.',
+ 'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area — above a table, inside a card, or in a panel — not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
bestPractices: [
- {guidance: true, description: 'Group related actions together in the same slot for a clear visual hierarchy.'},
- {guidance: true, description: 'Use the compact density variant when space is limited or the toolbar is secondary to the main content.'},
- {guidance: false, description: 'Avoid overloading the toolbar with too many actions — use an overflow menu for less common items.'},
+ {guidance: true, description: 'Put secondary actions like "Back" on the left, and primary actions like "Save" on the right.'},
+ {guidance: true, description: 'Make temporary toolbars like bulk selection visually distinct so users can tell they\'re contextual — for example, with a background color or border.'},
+ {guidance: true, description: 'Visually separate the toolbar from the content below it — with a divider, a background variant, or both.'},
+ {guidance: true, description: 'Use Toolbar as a card header when the header has interactive actions like filter or add — it gives you slot layout, keyboard navigation, and size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough.'},
+ {guidance: false, description: 'Put too many actions in one toolbar — move less common items into a MoreMenu.'},
+ {guidance: false, description: 'Set size on individual child buttons — set it once on the toolbar and it cascades automatically.'},
+ {guidance: false, description: 'Use Toolbar for app-wide navigation like main menu links or sign out — use TopNav or LayoutHeader for that.'},
],
},
};
@@ -101,25 +105,33 @@ export const docsZh = {
],
usage: {
description:
- 'Toolbar is a horizontal container for grouping related actions and controls using start, center, and end content slots. Use Toolbar to provide contextual actions above content areas like tables, editors, or detail panels.',
+ 'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area — above a table, inside a card, or in a panel — not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
bestPractices: [
- {guidance: true, description: 'Group related actions together in the same slot for a clear visual hierarchy.'},
- {guidance: true, description: 'Use the compact density variant when space is limited or the toolbar is secondary to the main content.'},
- {guidance: false, description: 'Avoid overloading the toolbar with too many actions — use an overflow menu for less common items.'},
+ {guidance: true, description: 'Put secondary actions like "Back" on the left, and primary actions like "Save" on the right.'},
+ {guidance: true, description: 'Make temporary toolbars like bulk selection visually distinct so users can tell they\'re contextual — for example, with a background color or border.'},
+ {guidance: true, description: 'Visually separate the toolbar from the content below it — with a divider, a background variant, or both.'},
+ {guidance: true, description: 'Use Toolbar as a card header when the header has interactive actions like filter or add — it gives you slot layout, keyboard navigation, and size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough.'},
+ {guidance: false, description: 'Put too many actions in one toolbar — move less common items into a MoreMenu.'},
+ {guidance: false, description: 'Set size on individual child buttons — set it once on the toolbar and it cascades automatically.'},
+ {guidance: false, description: 'Use Toolbar for app-wide navigation like main menu links or sign out — use TopNav or LayoutHeader for that.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'General-purpose toolbar w/ start/center/end slots. Built on XDSSection w/ roving tabindex.',
+ description: 'Horizontal bar w/ left, center, right areas. For contextual actions in content, not page headers. Size cascades to children.',
usage: {
description:
- 'Toolbar is a horizontal container for grouping related actions and controls using start, center, and end content slots. Use Toolbar to provide contextual actions above content areas like tables, editors, or detail panels.',
+ 'Horizontal bar w/ left, optional center, right. For contextual actions within content (tables, cards, panels) — not page-level headers. Size cascades to children.',
bestPractices: [
- {guidance: true, description: 'Group related actions together in the same slot for a clear visual hierarchy.'},
- {guidance: true, description: 'Use the compact density variant when space is limited or the toolbar is secondary to the main content.'},
- {guidance: false, description: 'Avoid overloading the toolbar with too many actions — use an overflow menu for less common items.'},
+ {guidance: true, description: 'Secondary actions (Back) left, primary actions (Save) right.'},
+ {guidance: true, description: 'Make temporary toolbars (bulk selection) visually distinct — e.g. background color or border.'},
+ {guidance: true, description: 'Separate toolbar from content — divider, background variant, or both.'},
+ {guidance: true, description: 'Use Toolbar as card header when it has actions (filter, add). Just a title? Use LayoutHeader/Section.'},
+ {guidance: false, description: 'Overload with actions — use MoreMenu for overflow.'},
+ {guidance: false, description: 'Set size on child buttons — set once on toolbar, it cascades.'},
+ {guidance: false, description: 'Use for app-wide nav (menu links, sign out) — use TopNav/LayoutHeader.'},
],
},
components: [