Skip to content

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

TypeScript

Improve Kbd docs page and block examples (#1678)

Ted McDonald905b955b1ea3
diff --git a/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.doc.mjs b/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.doc.mjs
index a63fa74316..37970a9f4b 100644
--- a/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.doc.mjs
+++ b/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'Kbd — Inline Instructions',
- description:
- 'Keyboard shortcuts rendered inline within instructional text, showing how to guide users through keyboard interactions.',
+ description: 'Keyboard shortcuts rendered inline within instructional text',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Kbd', 'VStack', 'Text'],
diff --git a/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.tsx b/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.tsx
index f5c69baceb..f809b687f1 100644
--- a/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.tsx
+++ b/packages/cli/templates/blocks/components/Kbd/KbdInlineInstructions.tsx
@@ -1,7 +1,7 @@
'use client';
import {XDSKbd} from '@xds/core/Kbd';
-import {XDSVStack} from '@xds/core/Layout';
+import {XDSVStack} from '@xds/core/Stack';
import {XDSText} from '@xds/core/Text';
export default function KbdInlineInstructions() {
diff --git a/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.doc.mjs b/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.doc.mjs
index 1c60a260a9..c444fa3c23 100644
--- a/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.doc.mjs
+++ b/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'Kbd — Menu Shortcuts',
- description:
- 'A context menu style list with action labels and their corresponding keyboard shortcuts aligned to the right.',
+ description: 'Menu-style list pairing action labels with their keyboard shortcuts',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Kbd', 'Text'],
+ componentsUsed: ['Kbd', 'Card', 'List'],
};
diff --git a/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.tsx b/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.tsx
index a43e9f6b39..038a4a43e2 100644
--- a/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.tsx
+++ b/packages/cli/templates/blocks/components/Kbd/KbdMenuShortcuts.tsx
@@ -1,7 +1,8 @@
'use client';
import {XDSKbd} from '@xds/core/Kbd';
-import {XDSText} from '@xds/core/Text';
+import {XDSCard} from '@xds/core/Card';
+import {XDSList, XDSListItem} from '@xds/core/List';
const menuItems = [
{label: 'Cut', keys: 'mod+x'},
@@ -13,29 +14,16 @@ const menuItems = [
export default function KbdMenuShortcuts() {
return (
- <div
- style={{
- display: 'flex',
- flexDirection: 'column',
- gap: 4,
- padding: 8,
- border: '1px solid #e0e0e0',
- borderRadius: 8,
- width: 250,
- }}>
- {menuItems.map((item) => (
- <div
- key={item.label}
- style={{
- display: 'flex',
- justifyContent: 'space-between',
- alignItems: 'center',
- padding: 8,
- }}>
- <XDSText type="body">{item.label}</XDSText>
- <XDSKbd keys={item.keys} />
- </div>
- ))}
- </div>
+ <XDSCard padding={0}>
+ <XDSList density="compact">
+ {menuItems.map(item => (
+ <XDSListItem
+ key={item.label}
+ label={item.label}
+ endContent={<XDSKbd keys={item.keys} />}
+ />
+ ))}
+ </XDSList>
+ </XDSCard>
);
}
diff --git a/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.doc.mjs b/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.doc.mjs
index ed625c85b4..88c05efd99 100644
--- a/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.doc.mjs
+++ b/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'Kbd — Modifier Combinations',
- description:
- 'Common keyboard modifier combinations and special keys rendered as keyboard shortcut badges.',
+ description: 'Modifier combinations and special keys rendered as shortcut badges',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Kbd', 'VStack', 'HStack', 'Text'],
diff --git a/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.tsx b/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.tsx
index 793e69e71e..8400487677 100644
--- a/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.tsx
+++ b/packages/cli/templates/blocks/components/Kbd/KbdModifierCombos.tsx
@@ -1,7 +1,7 @@
'use client';
import {XDSKbd} from '@xds/core/Kbd';
-import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSVStack, XDSHStack} from '@xds/core/Stack';
import {XDSText} from '@xds/core/Text';
export default function KbdModifierCombos() {
diff --git a/packages/core/src/Kbd/Kbd.doc.mjs b/packages/core/src/Kbd/Kbd.doc.mjs
index 61e0985778..1efaff7674 100644
--- a/packages/core/src/Kbd/Kbd.doc.mjs
+++ b/packages/core/src/Kbd/Kbd.doc.mjs
@@ -34,11 +34,11 @@ export const docs = {
targets: [{className: 'xds-kbd'}],
},
usage: {
- description: 'Displays a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and documentation to visually communicate key combinations to users.',
+ description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
bestPractices: [
- { guidance: true, description: 'Place keyboard shortcuts near the action they describe, such as in a tooltip or menu item.' },
- { guidance: true, description: 'Use the "mod" key name for platform-adaptive display — it renders as ⌘ on Mac and Ctrl on other platforms.' },
- { guidance: false, description: 'Use Kbd as the only way to discover an action — keyboard shortcuts should supplement visible labels and controls.' },
+ { guidance: true, description: 'Place shortcuts near the action they trigger — in a tooltip, menu item, or inline instruction.' },
+ { guidance: true, description: 'Use mod instead of ctrl or cmd — it automatically adapts to the user\'s platform.' },
+ { guidance: false, description: 'Use Kbd as the only way to discover an action — shortcuts should supplement visible controls, not replace them.' },
],
},
};
@@ -77,11 +77,11 @@ export const docsZh = {
targets: [{className: 'xds-kbd'}],
},
usage: {
- description: 'Displays a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and documentation to visually communicate key combinations to users.',
+ description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
bestPractices: [
- { guidance: true, description: 'Place keyboard shortcuts near the action they describe, such as in a tooltip or menu item.' },
- { guidance: true, description: 'Use the "mod" key name for platform-adaptive display — it renders as ⌘ on Mac and Ctrl on other platforms.' },
- { guidance: false, description: 'Use Kbd as the only way to discover an action — keyboard shortcuts should supplement visible labels and controls.' },
+ { guidance: true, description: 'Place shortcuts near the action they trigger — in a tooltip, menu item, or inline instruction.' },
+ { guidance: true, description: 'Use mod instead of ctrl or cmd — it automatically adapts to the user\'s platform.' },
+ { guidance: false, description: 'Use Kbd as the only way to discover an action — shortcuts should supplement visible controls, not replace them.' },
],
},
};
@@ -89,13 +89,13 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description:
- 'Displays keyboard shortcut as styled <kbd> elements. Use in tooltips, menus + docs to show key combinations.',
+ 'Renders keyboard shortcut as styled key badges. Use in tooltips, menus + help text to show key combinations.',
usage: {
- description: 'Displays a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and documentation to visually communicate key combinations to users.',
+ description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
bestPractices: [
- { guidance: true, description: 'Place keyboard shortcuts near the action they describe, such as in a tooltip or menu item.' },
- { guidance: true, description: 'Use the "mod" key name for platform-adaptive display — it renders as ⌘ on Mac and Ctrl on other platforms.' },
- { guidance: false, description: 'Use Kbd as the only way to discover an action — keyboard shortcuts should supplement visible labels and controls.' },
+ { guidance: true, description: 'Place shortcuts near the action they trigger — in a tooltip, menu item, or inline instruction.' },
+ { guidance: true, description: 'Use mod instead of ctrl or cmd — it automatically adapts to the user\'s platform.' },
+ { guidance: false, description: 'Use Kbd as the only way to discover an action — shortcuts should supplement visible controls, not replace them.' },
],
},
propDescriptions: {