Skip to content

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

TypeScript

fix(cli): correct Avatar size and MobileNav docs for agent discoverability (#2671)

Cindy Zhange54a833c889b
diff --git a/internal/vibe-tests/src/setup-environment.mjs b/internal/vibe-tests/src/setup-environment.mjs
index 71292fb3d7..770b9dc42c 100644
--- a/internal/vibe-tests/src/setup-environment.mjs
+++ b/internal/vibe-tests/src/setup-environment.mjs
@@ -71,6 +71,10 @@ export function createAgentProject(target, iterDir, promptId) {
const cliLink = path.join(projectDir, 'node_modules', '@xds', 'cli');
fs.symlinkSync(path.join(REPO_ROOT, 'packages', 'cli'), cliLink, 'dir');
+ // Symlink node_modules/@xds/theme-default → packages/themes/default
+ const themeDefaultLink = path.join(projectDir, 'node_modules', '@xds', 'theme-default');
+ fs.symlinkSync(path.join(REPO_ROOT, 'packages', 'themes', 'default'), themeDefaultLink, 'dir');
+
// Symlink node_modules/.bin/xds → cli bin so npx xds works
const binDir = path.join(projectDir, 'node_modules', '.bin');
ensureDir(binDir);
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index 26571ef463..69f388efeb 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -60,8 +60,8 @@ export const docs = {
},
{
name: 'size',
- type: 'XDSAvatarSize',
- description: 'Avatar size (named or numeric pixel value).',
+ type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number",
+ description: "Avatar size. Named sizes: 'tiny' (20px), 'xsmall' (24px), 'small' (36px), 'medium' (48px), 'large' (72px). Also accepts specific pixel values (16, 20, 24, 32, 36, 40, 48, 60, 64, 72, 80, 96, 120).",
default: "'small'",
},
{
@@ -141,7 +141,7 @@ export const docsZh = {
{name: 'fallbackSrc', type: 'string', description: '主图片加载失败时的备用图片。'},
{name: 'name', type: 'string', description: '用户姓名,用于生成首字母和替代文本。'},
{name: 'alt', type: 'string', description: '替代文本(未提供时回退到 name)。'},
- {name: 'size', type: 'XDSAvatarSize', description: '头像尺寸(命名值或数值像素值)。', default: "'small'"},
+ {name: 'size', type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number", description: "头像尺寸。命名值:'tiny' (20px)、'xsmall' (24px)、'small' (36px)、'medium' (48px)、'large' (72px)。也接受具体像素值。", default: "'small'"},
{name: 'status', type: 'ReactNode', description: '角落内容,用于状态指示器。'},
],
},
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index 76f707b2fc..06ede25150 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -8,46 +8,69 @@ export const docs = {
group: 'Navigation',
category: 'Navigation',
isHiddenFromOverview: true,
- keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer"],
- props: [
- {
- name: 'isOpen',
- type: 'boolean',
- description: 'Whether the drawer is open.',
- required: true,
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description:
- 'Called when the drawer visibility changes (backdrop click, Escape key, or close button).',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.',
- required: true,
- },
+ keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer","toggle"],
+ components: [
{
- name: 'title',
- type: 'string',
- description: 'Optional title shown at the top of the drawer.',
+ name: 'XDSMobileNav',
+ displayName: 'Mobile Nav',
+ description: 'A slide-out drawer for mobile navigation. Accepts SideNav children.',
+ props: [
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the drawer is open. Inside XDSAppShell, this is managed automatically via context. Outside XDSAppShell, provide this prop to control the drawer yourself.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description:
+ 'Called when the drawer visibility changes (backdrop click, Escape key, or close button). Inside XDSAppShell, this is managed automatically via context.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.',
+ required: true,
+ },
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description: 'Header content for the drawer. Rendered next to the close button. Pass a string for a simple text heading, or a ReactNode for custom content (logo, search bar, etc.).',
+ },
+ {
+ name: 'width',
+ type: 'number',
+ description:
+ 'Drawer width in pixels. Capped at 85vw to prevent overflow on small screens.',
+ default: '280',
+ },
+ {
+ name: 'side',
+ type: "'start' | 'end'",
+ description:
+ 'Which side the drawer slides from. Start is left in LTR, right in RTL.',
+ default: "'start'",
+ },
+ ],
},
{
- name: 'width',
- type: 'number',
- description:
- 'Drawer width in pixels. Capped at 85vw to prevent overflow on small screens.',
- default: '280',
- },
- {
- name: 'side',
- type: "'start' | 'end'",
- description:
- 'Which side the drawer slides from. Start is left in LTR, right in RTL.',
- default: "'start'",
+ name: 'XDSMobileNavToggle',
+ displayName: 'Mobile Nav Toggle',
+ description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from XDSAppShell context automatically — does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Custom content to render instead of the default hamburger icon.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the toggle button.',
+ default: "'Open navigation'",
+ },
+ ],
},
],
theming: {
@@ -57,10 +80,11 @@ export const docs = {
},
usage: {
description:
- 'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
+ 'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical. Inside XDSAppShell, use XDSMobileNavToggle as the trigger — it reads state from context automatically.',
bestPractices: [
{ guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
- { guidance: true, description: 'Provide a title when the drawer\'s purpose is not obvious from its content.' },
+ { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
+ { guidance: true, description: 'Inside XDSAppShell, use XDSMobileNavToggle to open the drawer — it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
{ guidance: false, description: 'Use MobileNav on desktop — use a persistent SideNav instead.' },
],
},
@@ -91,9 +115,9 @@ export const docsZh = {
required: true,
},
{
- name: 'title',
- type: 'string',
- description: '显示在抽屉顶部的可选标题。',
+ name: 'header',
+ type: 'ReactNode',
+ description: '抽屉的头部内容。渲染在关闭按钮旁边。传入字符串作为简单文本标题,或传入 ReactNode 作为自定义内容。',
},
{
name: 'width',
@@ -120,7 +144,7 @@ export const docsZh = {
'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
bestPractices: [
{ guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
- { guidance: true, description: 'Provide a title when the drawer\'s purpose is not obvious from its content.' },
+ { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
{ guidance: false, description: 'Use MobileNav on desktop — use a persistent SideNav instead.' },
],
},
@@ -135,7 +159,7 @@ export const docsDense = {
'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
bestPractices: [
{ guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
- { guidance: true, description: 'Provide a title when the drawer\'s purpose is not obvious from its content.' },
+ { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
{ guidance: false, description: 'Use MobileNav on desktop — use a persistent SideNav instead.' },
],
},
@@ -145,7 +169,7 @@ export const docsDense = {
'Called when drawer visibility changes (backdrop click, Escape key, close button).',
children:
'Drawer content; typically XDSSideNavSection/XDSSideNavItem or any ReactNode.',
- title: 'Optional title at top of drawer.',
+ header: 'Header content for the drawer (string or ReactNode). Rendered next to close button.',
width: 'Drawer width px. Capped at 85vw to prevent overflow on small screens.',
side: 'Slide direction. Start=left LTR, right RTL.',
},