Skip to content

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

TypeScript

reshape UsageDoc: replace features/accessibility/notes with bestPractices (#1423)

Joey00ec56193155
diff --git a/packages/cli/src/api/discover.mjs b/packages/cli/src/api/discover.mjs
index d3be04d32b..843e3fca36 100644
--- a/packages/cli/src/api/discover.mjs
+++ b/packages/cli/src/api/discover.mjs
@@ -14,7 +14,7 @@ function validateDocs(docs) {
if (!docs.usage || typeof docs.usage.description !== 'string') return 'docs.usage.description is missing or not a string';
if (docs.props && !Array.isArray(docs.props)) return 'docs.props must be an array';
if (docs.components && !Array.isArray(docs.components)) return 'docs.components must be an array';
- if (docs.usage?.features && !Array.isArray(docs.usage.features)) return 'docs.usage.features must be an array';
+ if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices)) return 'docs.usage.bestPractices must be an array';
return null;
}
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index e208fbad87..9611032b46 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -120,10 +120,13 @@ export function formatFull(docs, options = {}) {
sections.push('');
}
- const features = docs.usage?.features || docs.features;
- if (features?.length) {
- sections.push('## Features\n');
- sections.push(features.map(f => `- ${f}`).join('\n') + '\n');
+ if (docs.usage?.bestPractices?.length) {
+ sections.push('## Best Practices\n');
+ for (const bp of docs.usage.bestPractices) {
+ const badge = bp.guidance ? '**Do:**' : '**Don\'t:**';
+ sections.push(`- ${badge} ${bp.description}`);
+ }
+ sections.push('');
}
// Single component props
@@ -244,24 +247,13 @@ export function formatFull(docs, options = {}) {
}
}
- const a11y = docs.usage?.accessibility || docs.accessibility;
- if (a11y?.length) {
- sections.push('## Accessibility\n');
- sections.push(a11y.map(a => `- ${a}`).join('\n') + '\n');
- }
-
- const notes = docs.usage?.notes || docs.notes;
- if (notes?.length) {
- sections.push('## Notes\n');
- sections.push(notes.map(n => `- ${n}`).join('\n') + '\n');
- }
return sections.join('\n');
}
/**
* Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).
- * Includes: import, features, props, keyboard, notes.
+ * Includes: import, best practices, props, theming.
*/
export function formatCompact(docs, componentName, importHint) {
const displayName = componentName.startsWith('XDS')
@@ -286,10 +278,13 @@ export function formatCompact(docs, componentName, importHint) {
sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);
}
- const features = docs.usage?.features || docs.features;
- if (features?.length) {
- sections.push('## Features\n');
- sections.push(features.map(f => `- ${f}`).join('\n') + '\n');
+ if (docs.usage?.bestPractices?.length) {
+ sections.push('## Best Practices\n');
+ for (const bp of docs.usage.bestPractices) {
+ const badge = bp.guidance ? '**Do:**' : '**Don\'t:**';
+ sections.push(`- ${badge} ${bp.description}`);
+ }
+ sections.push('');
}
// Props
@@ -316,12 +311,6 @@ export function formatCompact(docs, componentName, importHint) {
}
}
- const compactNotes = docs.usage?.notes || docs.notes;
- if (compactNotes?.length) {
- sections.push('## Notes\n');
- sections.push(compactNotes.map(n => `- ${n}`).join('\n') + '\n');
- }
-
// CSS custom properties (compact includes these for theme consumers)
if (docs.theming?.cssProperties?.length) {
sections.push('## CSS Properties\n');
diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjs
index 0151f63be2..3da4a5fc5c 100644
--- a/packages/cli/src/lib/component-loader.mjs
+++ b/packages/cli/src/lib/component-loader.mjs
@@ -9,19 +9,12 @@ function mergeTranslation(docs, translation) {
const merged = {...docs};
- // Merge prose into usage (new unified format)
+ // Merge prose into usage
if (merged.usage) {
merged.usage = {...merged.usage};
- if (translation.description) merged.usage.description = translation.description;
- if (translation.features) merged.usage.features = translation.features;
- if (translation.notes) merged.usage.notes = translation.notes;
- if (translation.accessibility) merged.usage.accessibility = translation.accessibility;
- if (translation.keyboard) {
- merged.usage.accessibility = [
- ...(merged.usage.accessibility || []).filter(a => !a.startsWith('Keyboard:')),
- `Keyboard: ${translation.keyboard}`,
- ];
- }
+ if (translation.usage?.description) merged.usage.description = translation.usage.description;
+ else if (translation.description) merged.usage.description = translation.description;
+ if (translation.usage?.bestPractices) merged.usage.bestPractices = translation.usage.bestPractices;
}
// Legacy top-level fields (for docsZh that are full ComponentDoc clones)
diff --git a/packages/cli/src/lib/string-utils.mjs b/packages/cli/src/lib/string-utils.mjs
index b261cc1f63..1eef79c2be 100644
--- a/packages/cli/src/lib/string-utils.mjs
+++ b/packages/cli/src/lib/string-utils.mjs
@@ -165,15 +165,15 @@ export async function searchComponents(needle, coreDir, components) {
}
}
- // Feature search (whole word boundary)
- const searchFeatures = docs.usage?.features || docs.features;
- if (searchFeatures && Array.isArray(searchFeatures) && term.length >= 3) {
- for (const feat of searchFeatures) {
- const featLower = feat.toLowerCase();
+ // Best practices search (whole word boundary)
+ const bestPractices = docs.usage?.bestPractices;
+ if (bestPractices && Array.isArray(bestPractices) && term.length >= 3) {
+ for (const bp of bestPractices) {
+ const bpLower = bp.description.toLowerCase();
const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const re = new RegExp('\\b' + escaped + '\\b');
- if (re.test(featLower)) {
- addMatch(comp, 50, 'feature mentions "' + term + '"');
+ if (re.test(bpLower)) {
+ addMatch(comp, 50, 'best practice mentions "' + term + '"');
break;
}
}
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index 81c3932019..62472dde07 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -14,16 +14,11 @@ export const docs = {
],
usage: {
description:
- 'Confirmation dialog for destructive or irreversible actions. Uses role="alertdialog" with required title, description, and cancel/action buttons.',
- features: [
- 'No backdrop dismiss: Cannot be closed by clicking outside the dialog',
- 'Built-in buttons: Ghost cancel and configurable action button rendered internally',
- 'Action does not auto-close: Supports async operations with loading states',
- 'Imperative API: useXDSImperativeAlertDialog for fire-and-forget usage',
- ],
- accessibility: [
- 'Uses role="alertdialog" with aria-labelledby and aria-describedby',
- 'Keyboard: Escape triggers the cancel action',
+ 'AlertDialog is a confirmation dialog for destructive or irreversible actions. Use it to require explicit user confirmation before proceeding with actions like deleting content or discarding changes.',
+ bestPractices: [
+ {guidance: true, description: 'Clearly describe the consequences of the action in the description text so users can make an informed decision.'},
+ {guidance: true, description: 'Keep the action button label specific and descriptive, such as "Delete project" rather than a generic "OK".'},
+ {guidance: false, description: 'Use AlertDialog for non-destructive actions or simple informational messages — use a standard Dialog instead.'},
],
},
props: [
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index 26f6daa46f..96567c7000 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -5,28 +5,12 @@ export const docs = {
keywords: ["appshell","layout","scaffold","sidebar","sidenav","topnav","header","navigation","dashboard","shell","page","frame"],
usage: {
description:
- 'Application-level layout shell providing header, side navigation, and main content area. Composes XDSLayout internally and replaces the XDSPage + XDSPageLayout pattern.',
- features: [
- 'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',
- 'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',
- 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via mobileNav breakpoint',
- 'Mobile: collapsed sideNav renders as an overlay with backdrop',
- 'Composes XDSLayout internally for automatic padding collapse, scroll containment, and slot awareness',
- ],
- accessibility: [
- 'Semantic HTML via XDSLayout slots — each slot maps to a proper landmark element.',
- '<main> content area has role="main" for landmark navigation.',
- 'SideNav has role="navigation" with aria-label="Application navigation".',
- 'Skip-to-content link is visually hidden but shown on focus for keyboard users.',
- 'Keyboard: Escape key closes the mobile sideNav overlay.',
- ],
- notes: [
- 'When a TopNav is present, omit XDSSideNavHeading from the SideNav — the TopNav already provides app identity. Adding both would double the identity.',
- 'When there is no TopNav, include XDSSideNavHeading inside the SideNav so the app name and logo are present.',
- 'XDSAppShell composes XDSLayout internally: topNav + banner map to XDSLayoutHeader, sideNav maps to XDSLayoutPanel, and children map to XDSLayoutContent.',
- 'SideNav collapse animations currently snap open/closed; ViewTransitions support is planned.',
- 'In "auto" height mode, TopNav gets position: sticky; top: 0 and SideNav gets position: sticky; top: <header-height>.',
- 'In "fill" height mode, the shell fills 100dvh, TopNav is pinned at the top, and both the SideNav and content area have independent scroll containers.',
+ 'AppShell is an application-level layout providing header, side navigation, and main content areas. Use it to scaffold the top-level structure of a dashboard or admin interface with consistent navigation patterns.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the height mode that matches your content — use "fill" for dashboards with independent scroll regions and "auto" for content-driven pages.'},
+ {guidance: true, description: 'When a TopNav is present, omit SideNavHeading from the SideNav to avoid duplicating the app identity.'},
+ {guidance: false, description: 'Nest an AppShell inside another AppShell or use it for sub-page layouts — it is intended as the outermost layout frame.'},
+ {guidance: false, description: 'Mix multiple navigation patterns within the same shell — pick either topNav, sideNav, or both and use them consistently.'},
],
},
props: [
@@ -114,30 +98,12 @@ export const docsZh = {
name: 'AppShell',
usage: {
description:
- '应用级布局外壳,提供顶部导航栏、侧边导航栏和主内容区域——内部组合使用 XDSLayout,替代 XDSPage + XDSPageLayout 模式。',
- features: [
- '两个导航插槽:topNav(水平导航栏)和 sideNav(垂直侧边栏)',
- '两种高度模式:fill(视口高度,独立滚动容器)和 auto(页面滚动,导航栏吸顶)',
- '受控和非受控的 sideNav 折叠,通过 mobileNav breakpoint 支持响应式自动折叠',
- '移动端:折叠的 sideNav 以带遮罩层的浮层形式展示',
- '内部组合使用 XDSLayout,自动处理内边距折叠、滚动容器和插槽感知',
- '语义化 HTML:<main> 带 role="main",SideNav 带 role="navigation",跳转到内容链接',
- 'Escape 键关闭移动端 sideNav 浮层',
- ],
- accessibility: [
- '通过 XDSLayout 插槽实现语义化 HTML——每个插槽对应一个合适的地标元素。',
- '<main> 内容区域具有 role="main",用于地标导航。',
- 'SideNav 具有 role="navigation" 和 aria-label="Application navigation"。',
- '跳转到内容链接在视觉上隐藏,但在键盘聚焦时显示,方便键盘用户使用。',
- 'Escape 键关闭移动端 sideNav 浮层。',
- ],
- notes: [
- '当存在 TopNav 时,请勿在 SideNav 中使用 XDSSideNavHeading——TopNav 已提供了应用标识。同时使用两者会导致标识重复。',
- '当没有 TopNav 时,请在 SideNav 中添加 XDSSideNavHeading,以确保应用名称和图标可见。',
- 'XDSAppShell 内部组合使用 XDSLayout:topNav + banner 映射到 XDSLayoutHeader,sideNav 映射到 XDSLayoutPanel,children 映射到 XDSLayoutContent。',
- 'SideNav 折叠动画目前为瞬间切换;计划支持 ViewTransitions。',
- '在 "auto" 高度模式下,TopNav 使用 position: sticky; top: 0,SideNav 使用 position: sticky; top: <header-height>。',
- '在 "fill" 高度模式下,外壳填满 100dvh,TopNav 固定在顶部,SideNav 和内容区域各有独立的滚动容器。',
+ 'AppShell is an application-level layout providing header, side navigation, and main content areas. Use it to scaffold the top-level structure of a dashboard or admin interface with consistent navigation patterns.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the height mode that matches your content — use "fill" for dashboards with independent scroll regions and "auto" for content-driven pages.'},
+ {guidance: true, description: 'When a TopNav is present, omit SideNavHeading from the SideNav to avoid duplicating the app identity.'},
+ {guidance: false, description: 'Nest an AppShell inside another AppShell or use it for sub-page layouts — it is intended as the outermost layout frame.'},
+ {guidance: false, description: 'Mix multiple navigation patterns within the same shell — pick either topNav, sideNav, or both and use them consistently.'},
],
},
props: [
@@ -201,30 +167,16 @@ export const docsZh = {
export const docsDense = {
description:
'app-level layout shell w/ header, side nav, main content; composes XDSLayout internally, replaces XDSPage+XDSPageLayout',
- features: [
- 'two nav slots: topNav (horizontal bar) + sideNav (vertical sidebar)',
- 'two height modes: fill (viewport 100dvh, independent scroll) + auto (page-scroll w/ sticky nav)',
- 'controlled+uncontrolled sideNav collapse w/ responsive auto-collapse via mobileNav breakpoint',
- 'mobile: collapsed sideNav renders as overlay w/ backdrop',
- 'composes XDSLayout internally for auto padding collapse, scroll containment, slot awareness',
- 'semantic HTML: <main> role="main", SideNav role="navigation", skip-to-content link',
- 'Escape closes mobile sideNav overlay',
- ],
- notes: [
- 'w/ TopNav, omit SideNavHeading from SideNav to avoid double identity',
- 'w/o TopNav, include SideNavHeading for app name+logo',
- 'composes XDSLayout: topNav+banner map to XDSLayoutHeader, sideNav to XDSLayoutPanel, children to XDSLayoutContent',
- 'collapse animations snap open/closed; ViewTransitions planned',
- '"auto" height: TopNav sticky top:0, SideNav sticky top:<header-height>',
- '"fill" height: 100dvh, TopNav pinned, SideNav+content have independent scroll',
- ],
- accessibility: [
- 'semantic HTML via XDSLayout slots, each slot maps to landmark element',
- '<main> has role="main" for landmark nav',
- 'SideNav has role="navigation" w/ aria-label="Application navigation"',
- 'skip-to-content link visually hidden, shown on focus for keyboard users',
- 'Escape closes mobile sideNav overlay',
- ],
+ usage: {
+ description:
+ 'AppShell is an application-level layout providing header, side navigation, and main content areas. Use it to scaffold the top-level structure of a dashboard or admin interface with consistent navigation patterns.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the height mode that matches your content — use "fill" for dashboards with independent scroll regions and "auto" for content-driven pages.'},
+ {guidance: true, description: 'When a TopNav is present, omit SideNavHeading from the SideNav to avoid duplicating the app identity.'},
+ {guidance: false, description: 'Nest an AppShell inside another AppShell or use it for sub-page layouts — it is intended as the outermost layout frame.'},
+ {guidance: false, description: 'Mix multiple navigation patterns within the same shell — pick either topNav, sideNav, or both and use them consistently.'},
+ ],
+ },
propDescriptions: {
children: 'main content area, rendered inside <main>',
topNav: 'top nav slot, typically XDSTopNav',
diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
index 4bbaba566c..e32e0fbfca 100644
--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs
+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
@@ -5,11 +5,11 @@ export const docs = {
keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],
usage: {
description:
- 'Maintains a specific aspect ratio for its children, useful for responsive media containers like embedded videos and images.',
- features: [
- 'Accepts any numeric ratio expressed as width/height (e.g. 16/9, 4/3, 1)',
- 'Children are positioned absolutely to fill the container',
- 'Supports theming via the aspectRatio component key',
+ 'AspectRatio maintains a specific width-to-height ratio for its children. Use it for responsive media containers like embedded videos, images, or thumbnails that need consistent proportions.',
+ bestPractices: [
+ {guidance: true, description: 'Express the ratio as a width/height fraction such as 16/9 or 4/3 for readability.'},
+ {guidance: true, description: 'Use for media containers like videos and images where consistent proportions are critical across screen sizes.'},
+ {guidance: false, description: 'Use AspectRatio for general layout containers that don\'t require a fixed proportion — use standard layout components instead.'},
],
},
props: [
@@ -43,11 +43,12 @@ export const docs = {
export const docsZh = {
name: 'AspectRatio',
usage: {
- description: '为子元素保持特定的宽高比。',
- features: [
- '接受任何以宽/高表示的数字比例(例如 16/9、4/3、1)',
- '子元素通过绝对定位填充容器',
- '通过 aspectRatio 组件键支持主题定制',
+ description:
+ 'AspectRatio maintains a specific width-to-height ratio for its children. Use it for responsive media containers like embedded videos, images, or thumbnails that need consistent proportions.',
+ bestPractices: [
+ {guidance: true, description: 'Express the ratio as a width/height fraction such as 16/9 or 4/3 for readability.'},
+ {guidance: true, description: 'Use for media containers like videos and images where consistent proportions are critical across screen sizes.'},
+ {guidance: false, description: 'Use AspectRatio for general layout containers that don\'t require a fixed proportion — use standard layout components instead.'},
],
},
props: [
@@ -70,11 +71,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'maintains specific aspect ratio for children',
- features: [
- 'any numeric ratio as width/height (e.g. 16/9, 4/3, 1)',
- 'children positioned absolutely to fill container',
- 'themeable via aspectRatio component key',
- ],
+ usage: {
+ description:
+ 'AspectRatio maintains a specific width-to-height ratio for its children. Use it for responsive media containers like embedded videos, images, or thumbnails that need consistent proportions.',
+ bestPractices: [
+ {guidance: true, description: 'Express the ratio as a width/height fraction such as 16/9 or 4/3 for readability.'},
+ {guidance: true, description: 'Use for media containers like videos and images where consistent proportions are critical across screen sizes.'},
+ {guidance: false, description: 'Use AspectRatio for general layout containers that don\'t require a fixed proportion — use standard layout components instead.'},
+ ],
+ },
propDescriptions: {
ratio: 'width/height ratio (e.g. 16/9, 1)',
children: 'content positioned absolutely to fill container',
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index 98901b6ef6..5b177aa30f 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -5,26 +5,12 @@ export const docs = {
keywords: ["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],
usage: {
description:
- 'Displays a user profile picture with automatic fallback to initials when no image is available. Use to represent a user or entity visually alongside user information.',
- features: [
- 'Image loading: Primary and fallback image sources',
- 'Initials fallback: Auto-generates initials from user name',
- 'Default icon: Generic person icon when no image or name provided',
- 'Sizes: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values',
- 'Status slot: Corner position for status indicators or badges',
- 'Size-aware status dot: Built-in XDSAvatarStatusDot that scales proportionally with avatar size',
- ],
- accessibility: [
- 'Proper role and aria-label support',
- ],
- notes: [
- 'Always circular shape (border-radius: 50%)',
- 'Uses color.deemphasized and color.textSecondary for fallback background',
- 'Initials extracted from first and last word of name',
- 'XDSAvatarSizeContext provides the resolved numeric size to sub-components',
- 'Status dot uses CIRCLE_EDGE_OFFSET_RATIO for positioning at the 45° point on the circle edge',
- 'Fallback cascade: (1) src loads → show image; (2) src fails → try fallbackSrc; (3) fallbackSrc fails/missing → show initials from name; (4) no name → show generic person icon',
- 'Status dot size tiers: avatar ≤ 36px → 8px dot with 1px border; avatar 40–72px → 16px dot with 2px border; avatar ≥ 96px → 24px dot with 4px border',
+ 'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
+ bestPractices: [
+ {guidance: true, description: 'Always provide a name prop so the component can generate meaningful initials and alt text when the image fails to load.'},
+ {guidance: true, description: 'Use the status slot with XDSAvatarStatusDot to indicate online presence or availability when relevant to the context.'},
+ {guidance: false, description: 'Use Avatar for decorative images or logos that aren\'t representing a person or entity — use an image or icon component instead.'},
+ {guidance: false, description: 'Override the circular shape — Avatars are always round to maintain visual consistency across the system.'},
],
},
theming: {
@@ -101,24 +87,13 @@ export const docs = {
export const docsZh = {
name: 'Avatar',
usage: {
- description: '头像组件,用于显示用户头像图片,支持降级回退。',
- features: [
- '图片加载:主图片源和备用图片源',
- '首字母回退:根据用户姓名自动生成首字母缩写',
- '默认图标:未提供图片或姓名时显示通用人物图标',
- '尺寸:tiny(20px)、xsmall(24px)、small(36px)、medium(48px)、large(128px),以及自定义数值像素',
- '状态插槽:角落位置用于状态指示器或徽章',
- '尺寸感知状态点:内置 XDSAvatarStatusDot,随头像尺寸等比缩放',
- '无障碍:支持正确的 role 和 aria-label',
- ],
- notes: [
- '始终为圆形(border-radius: 50%)',
- '回退背景使用 color.deemphasized 和 color.textSecondary',
- '首字母从姓名的第一个和最后一个单词中提取',
- 'XDSAvatarSizeContext 向子组件提供解析后的数值尺寸',
- '状态点使用 CIRCLE_EDGE_OFFSET_RATIO 定位在圆形边缘的 45° 位置',
- '回退级联:(1) src 加载成功 → 显示图片;(2) src 加载失败 → 尝试 fallbackSrc;(3) fallbackSrc 失败/缺失 → 显示姓名首字母;(4) 无姓名 → 显示通用人物图标',
- '状态点尺寸层级:头像 ≤ 36px → 8px 点 + 1px 边框;头像 40–72px → 16px 点 + 2px 边框;头像 ≥ 96px → 24px 点 + 4px 边框',
+ description:
+ 'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
+ bestPractices: [
+ {guidance: true, description: 'Always provide a name prop so the component can generate meaningful initials and alt text when the image fails to load.'},
+ {guidance: true, description: 'Use the status slot with XDSAvatarStatusDot to indicate online presence or availability when relevant to the context.'},
+ {guidance: false, description: 'Use Avatar for decorative images or logos that aren\'t representing a person or entity — use an image or icon component instead.'},
+ {guidance: false, description: 'Override the circular shape — Avatars are always round to maintain visual consistency across the system.'},
],
},
theming: {
@@ -165,24 +140,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'user avatar w/ profile pictures + fallback support',
- features: [
- 'image loading: primary + fallback sources',
- 'initials fallback: auto-generates from user name',
- 'default icon: generic person icon w/o image or name',
- 'sizes: tiny(20px), xsmall(24px), small(36px), medium(48px), large(128px) + numeric px',
- 'status slot: corner position for indicators/badges',
- 'size-aware status dot: XDSAvatarStatusDot scales proportionally w/ avatar',
- 'proper role + aria-label support',
- ],
- notes: [
- 'always circular (border-radius: 50%)',
- 'color.deemphasized + color.textSecondary for fallback bg',
- 'initials from first+last word of name',
- 'XDSAvatarSizeContext gives resolved numeric size to sub-components',
- 'status dot uses CIRCLE_EDGE_OFFSET_RATIO for 45 deg circle edge positioning',
- 'fallback cascade: src, fallbackSrc, initials from name, generic person icon',
- 'status dot tiers: avatar <=36px: 8px dot 1px border; 40-72px: 16px dot 2px border; >=96px: 24px dot 4px border',
- ],
+ usage: {
+ description:
+ 'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
+ bestPractices: [
+ {guidance: true, description: 'Always provide a name prop so the component can generate meaningful initials and alt text when the image fails to load.'},
+ {guidance: true, description: 'Use the status slot with XDSAvatarStatusDot to indicate online presence or availability when relevant to the context.'},
+ {guidance: false, description: 'Use Avatar for decorative images or logos that aren\'t representing a person or entity — use an image or icon component instead.'},
+ {guidance: false, description: 'Override the circular shape — Avatars are always round to maintain visual consistency across the system.'},
+ ],
+ },
components: [
{
name: 'XDSAvatar',
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
index 14682a27ff..c3b64c0a1f 100644
--- a/packages/core/src/Badge/Badge.doc.mjs
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -29,7 +29,12 @@ export const docs = {
},
usage: {
description:
- 'Badges display system or categorical information such as status indicators, counts, or labels. Use semantic color variants (neutral, info, success, warning, error) for system status and non-semantic colors for categorization. Always pair icons with labels and keep labels concise.',
+ 'Badge displays system or categorical information such as status indicators, counts, or labels. Use semantic color variants for system status and non-semantic colors for categorization and tagging.',
+ bestPractices: [
+ {guidance: true, description: 'Use semantic variants (success, warning, error) to communicate system status and non-semantic colors for categorization.'},
+ {guidance: true, description: 'Keep badge labels concise — ideally one or two words — and always pair icons with a text label.'},
+ {guidance: false, description: 'Use badges as interactive elements — they are informational only and should not be clickable.'},
+ ],
anatomy: [
{name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
{name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
@@ -40,7 +45,19 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Badge',
- usage: {description: '用于显示状态指示器、计数或标签的徽章组件。'},
+ usage: {
+ description:
+ 'Badge displays system or categorical information such as status indicators, counts, or labels. Use semantic color variants for system status and non-semantic colors for categorization and tagging.',
+ bestPractices: [
+ {guidance: true, description: 'Use semantic variants (success, warning, error) to communicate system status and non-semantic colors for categorization.'},
+ {guidance: true, description: 'Keep badge labels concise — ideally one or two words — and always pair icons with a text label.'},
+ {guidance: false, description: 'Use badges as interactive elements — they are informational only and should not be clickable.'},
+ ],
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
+ {name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
+ ],
+ },
props: [
{
name: 'variant',
@@ -67,6 +84,19 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'badge for status indicators, counts, or labels',
+ usage: {
+ description:
+ 'Badge displays system or categorical information such as status indicators, counts, or labels. Use semantic color variants for system status and non-semantic colors for categorization and tagging.',
+ bestPractices: [
+ {guidance: true, description: 'Use semantic variants (success, warning, error) to communicate system status and non-semantic colors for categorization.'},
+ {guidance: true, description: 'Keep badge labels concise — ideally one or two words — and always pair icons with a text label.'},
+ {guidance: false, description: 'Use badges as interactive elements — they are informational only and should not be clickable.'},
+ ],
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},
+ {name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},
+ ],
+ },
propDescriptions: {
variant: 'visual style variant',
label: 'badge text content',
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index e25572c73a..4a996e84c3 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -5,26 +5,12 @@ export const docs = {
keywords: ["banner","alert","notification","callout","notice","status","message","info","warning","error","success","toast"],
usage: {
description:
- 'Persistent status notification that displays a prominent message and related actions. Communicates critical or non-critical information for info, warning, error, or success scenarios. Keep titles and descriptions to 1–2 lines and default to the collapsed state.',
- features: [
- 'Two-part layout: colored status header with icon, title, description, action buttons, and optional dismiss; optional card-background content area below',
- 'When no children are provided, only the colored header renders',
- 'Self-managed dismiss state — banner hides itself on dismiss without requiring external state wiring',
- 'onDismiss callback fires alongside the internal state change for logging or backend sync',
- 'Card container (default): has border-radius with optional card content area below the colored header',
- 'Section container: no border-radius, full-width for page-level banners',
- ],
- accessibility: [
- 'Uses role="alert" for error and warning statuses',
- 'Uses role="status" for info and success statuses',
- 'Dismiss button has aria-label="Dismiss"',
- 'Status icon is aria-hidden="true" — status is conveyed by the ARIA role instead',
- ],
- notes: [
- 'Default status icons from @heroicons/react/24/solid: InformationCircleIcon (info), ExclamationTriangleIcon (warning), XCircleIcon (error), CheckCircleIcon (success)',
- 'Status colors: info uses --color-accent-muted, warning uses --color-warning-muted, error uses --color-error-muted, success uses --color-success-muted',
- 'Banner uses `status` as its extensible theming axis. Custom statuses via `defineTheme` components: `status:neutral`.',
- 'Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',
+ 'Banner is a persistent status notification that displays a prominent message with related actions. Use it to communicate critical or non-critical information for info, warning, error, or success scenarios at the page or section level.',
+ bestPractices: [
+ {guidance: true, description: 'Keep titles and descriptions to 1–2 lines and choose the appropriate status variant to match the severity of the message.'},
+ {guidance: true, description: 'Use the card container for inline contextual messages and the section container for full-width page-level notifications.'},
+ {guidance: false, description: 'Use a Banner for transient notifications that should auto-dismiss — use a Toast instead.'},
+ {guidance: false, description: 'Stack multiple Banners of the same status — consolidate related messages into a single Banner.'},
],
anatomy: [
{name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
@@ -114,26 +100,22 @@ export const docs = {
export const docsZh = {
name: 'Banner',
usage: {
- description: '持久性状态通知,用于展示信息、警告、错误或成功消息。',
- features: [
- '双区域布局:带图标、标题、描述、操作按钮和可选关闭按钮的彩色状态头部;下方可选的卡片背景内容区',
- '未提供 children 时,仅渲染彩色头部',
- '自管理关闭状态——横幅在关闭时自动隐藏,无需外部状态管理',
- 'onDismiss 回调在内部状态变更的同时触发,用于日志记录或后端同步',
- '默认状态图标来自 @heroicons/react/24/solid:InformationCircleIcon(info)、ExclamationTriangleIcon(warning)、XCircleIcon(error)、CheckCircleIcon(success)',
- '状态颜色:info 使用 --color-accent-muted,warning 使用 --color-warning-muted,error 使用 --color-error-muted,success 使用 --color-success-muted',
- 'Card 变体(默认):带圆角,彩色头部下方可选卡片内容区',
- 'Section 变体:无圆角,全宽,适用于页面级横幅',
- ],
- accessibility: [
- '错误和警告状态使用 role="alert"',
- '信息和成功状态使用 role="status"',
- '关闭按钮带有 aria-label="Dismiss"',
- '状态图标设置为 aria-hidden="true"——状态信息通过 ARIA role 传达',
+ description:
+ 'Banner is a persistent status notification that displays a prominent message with related actions. Use it to communicate critical or non-critical information for info, warning, error, or success scenarios at the page or section level.',
+ bestPractices: [
+ {guidance: true, description: 'Keep titles and descriptions to 1–2 lines and choose the appropriate status variant to match the severity of the message.'},
+ {guidance: true, description: 'Use the card container for inline contextual messages and the section container for full-width page-level notifications.'},
+ {guidance: false, description: 'Use a Banner for transient notifications that should auto-dismiss — use a Toast instead.'},
+ {guidance: false, description: 'Stack multiple Banners of the same status — consolidate related messages into a single Banner.'},
],
- notes: [
- 'Banner 使用 `status` 作为可扩展的主题轴。通过 defineTheme components 添加自定义状态:`status:neutral`。',
- '折叠支持已规划:内容区将通过 useXDSCollapsible 支持折叠(issue #187)',
+ anatomy: [
+ {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
+ {name: 'Heading', required: false, description: 'Required if no description is provided.'},
+ {name: 'Description', required: false, description: 'Required if no heading is provided.'},
+ {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},
+ {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},
+ {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},
+ {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},
],
},
props: [
@@ -178,25 +160,25 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'persistent status notification for info, warning, error, success messages',
- features: [
- 'two-part layout: colored status header w/ icon+title+description+actions+dismiss; optional card-bg content below',
- 'w/o children, only colored header renders',
- 'self-managed dismiss state, hides w/o external state wiring',
- 'onDismiss fires alongside internal state change for logging/backend sync',
- 'default status icons from @heroicons/react/24/solid: InformationCircleIcon, ExclamationTriangleIcon, XCircleIcon, CheckCircleIcon',
- 'status colors: info=accent-deemphasized, warning=warning-deemphasized, error=negative-deemphasized, success=positive-deemphasized',
- 'card container (default): border-radius w/ optional card content below header',
- 'section container: no border-radius, full-width for page-level banners',
- ],
- notes: [
- 'collapsible support planned via useXDSCollapsible (issue #187)',
- ],
- accessibility: [
- 'role="alert" for error+warning',
- 'role="status" for info+success',
- 'dismiss button has aria-label="Dismiss"',
- 'status icon aria-hidden="true", status conveyed by ARIA role',
- ],
+ usage: {
+ description:
+ 'Banner is a persistent status notification that displays a prominent message with related actions. Use it to communicate critical or non-critical information for info, warning, error, or success scenarios at the page or section level.',
+ bestPractices: [
+ {guidance: true, description: 'Keep titles and descriptions to 1–2 lines and choose the appropriate status variant to match the severity of the message.'},
+ {guidance: true, description: 'Use the card container for inline contextual messages and the section container for full-width page-level notifications.'},
+ {guidance: false, description: 'Use a Banner for transient notifications that should auto-dismiss — use a Toast instead.'},
+ {guidance: false, description: 'Stack multiple Banners of the same status — consolidate related messages into a single Banner.'},
+ ],
+ anatomy: [
+ {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},
+ {name: 'Heading', required: false, description: 'Required if no description is provided.'},
+ {name: 'Description', required: false, description: 'Required if no heading is provided.'},
+ {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},
+ {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},
+ {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},
+ {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},
+ ],
+ },
propDescriptions: {
status: 'controls icon+color',
title: 'title text/ReactNode in header',
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index c5be3998be..bad6796cd4 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -5,19 +5,11 @@ export const docs = {
keywords: ["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],
usage: {
description:
- 'A secondary navigation trail with semantic HTML that orients the user within a content hierarchy. Use to show the user\'s position relative to the product architecture and enable quick back-and-forth navigation.',
- features: [
- 'Configurable separator between items (defaults to /)',
- 'Two visual variants: default and supporting (smaller, secondary text)',
- 'Supports icons before item labels via startIcon',
- 'Auto-detects the last child as the current page when no isCurrent is set',
- ],
- accessibility: [
- 'Container renders as a <nav aria-label> landmark; the label defaults to "Breadcrumb" and is customizable via the label prop',
- 'Items are placed inside an <ol> with individual <li> wrappers for correct list semantics',
- 'The current page item receives aria-current="page"',
- 'Separators are rendered with aria-hidden="true" so screen readers skip them',
- 'Auto-detects the last child as the current item when no isCurrent prop is explicitly set',
+ '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.',
+ 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.'},
],
},
theming: {
@@ -114,22 +106,12 @@ export const docs = {
export const docsZh = {
name: 'Breadcrumbs',
usage: {
- description: '带语义化 HTML 的导航面包屑路径。',
- features: [
- '渲染包含有序面包屑项列表的 <nav> 地标元素',
- '可配置项目间的分隔符(默认为 /)',
- '两种视觉变体:default 和 supporting(更小,次要文本样式)',
- '当前页面项标记为 aria-current="page"',
- '分隔符通过 aria-hidden 对辅助技术隐藏',
- '通过 startIcon 支持在项目标签前显示图标',
- '未设置 isCurrent 时自动检测最后一个子元素为当前页面',
- ],
- accessibility: [
- '容器渲染为 <nav aria-label> 地标元素;标签默认为 "Breadcrumb",可通过 label 属性自定义',
- '项目放置在 <ol> 内,每个项目用 <li> 包裹以确保正确的列表语义',
- '当前页面项接收 aria-current="page"',
- '分隔符使用 aria-hidden="true" 渲染,屏幕阅读器会跳过它们',
- '未显式设置 isCurrent 属性时,自动检测最后一个子元素为当前项',
+ 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.',
+ 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.'},
],
},
theming: {
@@ -178,22 +160,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'navigation breadcrumb trail w/ semantic HTML',
- features: [
- 'renders <nav> landmark w/ ordered breadcrumb list',
- 'configurable separator between items (default /)',
- 'two variants: default + supporting (smaller, secondary text)',
- 'current page marked w/ aria-current="page"',
- 'separators hidden from assistive tech via aria-hidden',
- 'startIcon before item labels',
- 'auto-detects last child as current page w/o isCurrent',
- ],
- accessibility: [
- '<nav aria-label> landmark; label defaults to "Breadcrumb", customizable via label prop',
- 'items in <ol> w/ <li> wrappers for list semantics',
- 'current page gets aria-current="page"',
- 'separators aria-hidden="true" so screen readers skip',
- 'auto-detects last child as current w/o isCurrent set',
- ],
+ 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.',
+ 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.'},
+ ],
+ },
components: [
{
name: 'XDSBreadcrumbs',
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 3ec0828277..dce62b231e 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -7,37 +7,12 @@ export const docs = {
usage: {
description:
- 'Buttons provide visual cues for actions and events, allowing users to commit actions and navigate a page flow. XDSButton supports primary, secondary, ghost, and destructive variants across three sizes, with built-in loading states and async action handling. Use secondary for most actions, reserve primary for a single emphasized action per layout, and destructive for deletion with confirmation.',
- features: [
- "Variants: 'primary', 'secondary', 'ghost', 'destructive'",
- 'Sizes: sm (28px), md (32px), lg (36px)',
- 'Loading state: Shows spinner, disables interaction, announces via live region',
- 'Focus visible: Accessible focus outline with variant-specific colors',
- 'Reduced motion: Respects prefers-reduced-motion for transitions',
- 'Tooltip + disabled: Uses aria-disabled instead of native disabled so the button stays focusable for keyboard tooltip access',
- 'Form integration: type, name, value, form props for native form submission',
- 'Async actions: onClickAction with automatic loading state via useTransition',
- ],
- accessibility: [
- 'Renders a native <button> element for correct semantics and keyboard support',
- 'Icon-only buttons (isIconOnly={true}) set aria-label from the label prop',
- 'Loading state sets aria-busy and announces "Loading" via a role="status" live region',
- 'Content is hidden from assistive tech during loading via aria-hidden',
- 'When tooltip is present and button is disabled, uses aria-disabled instead of native disabled to keep the button focusable for keyboard tooltip access',
- 'Warns in development when icon-only buttons have an empty label (WCAG 4.1.2)',
- 'aria-label, aria-busy, and aria-disabled are placed after ...props spread to prevent clobbering',
- 'Keyboard: Enter/Space activates the button; Tab/Shift+Tab moves focus in and out',
- ],
- notes: [
- 'XDSButtonVariant type is derived from the variants StyleX object using keyof typeof variants.',
- 'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',
- 'Destructive variant uses colorTokens.negative for its focus outline color.',
- 'endContent is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',
- 'When isIconOnly is true, the button renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon — SVG components, emoji, or text.',
- 'endContent is ignored when isIconOnly is true to preserve the square aspect ratio.',
- 'onClick fires before onClickAction; calling preventDefault in onClick prevents onClickAction from running.',
- 'type defaults to "button" (not "submit") to prevent accidental form submission.',
- 'Disabled background gradient is cleared (backgroundImage: none) to prevent hover tint leaking through opacity.',
+ 'Buttons provide visual cues for actions and events. These fundamental components allow users to commit actions and navigate a page flow. Use a Button when a user needs to submit a form, start a new task or action, or trigger a new UI element to appear on the page.',
+ bestPractices: [
+ {guidance: true, description: 'Use secondary for most actions and reserve primary for a single emphasized action per layout.'},
+ {guidance: true, description: 'Include a clear, concise label that describes the action the button performs.'},
+ {guidance: false, description: 'Place more than one primary button in the same view — this dilutes the visual hierarchy.'},
+ {guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions.'},
],
anatomy: [
{name: 'Icon', required: false, description: 'A leading icon that visually represents the meaning of the button label.'},
@@ -161,40 +136,19 @@ export const docs = {
export const docsZh = {
name: 'Button',
usage: {
- description: 'XDSButton 组件,支持多种变体、尺寸和加载状态。',
- features: [
- "变体:'primary'、'secondary'、'ghost'、'destructive'",
- '尺寸:sm(28px)、md(32px)、lg(36px)',
- '加载状态:显示加载旋转器,禁用交互,通过实时区域播报',
- '焦点可见:带有变体特定颜色的无障碍焦点轮廓',
- '悬停/激活状态:通过 backgroundImage 使用叠加颜色,实现一致的层级效果',
- '减少动画:尊重 prefers-reduced-motion',
- '工具提示 + 禁用:使用 aria-disabled 代替原生 disabled,使按钮保持可聚焦以供键盘访问工具提示',
- '表单集成:type、name、value、form 属性支持原生表单提交',
- '异步操作:onClickAction 通过 useTransition 自动显示加载状态',
- ],
- accessibility: [
- '渲染原生 <button> 元素以确保正确的语义和键盘支持',
- '纯图标按钮(icon 无 children)从 label 属性设置 aria-label',
- '加载状态设置 aria-busy 并通过 role="status" 实时区域播报"Loading"',
- '加载期间通过 aria-hidden 对辅助技术隐藏内容',
- '当存在工具提示且按钮禁用时,使用 aria-disabled 代替原生 disabled 以保持键盘可聚焦',
- '开发环境下,纯图标按钮标签为空时发出警告(WCAG 4.1.2)',
- 'aria-label、aria-busy、aria-disabled 放置在 ...props 展开之后以防止覆盖',
- 'Keyboard: Enter/Space 激活按钮;Tab/Shift+Tab 移入和移出焦点',
+ description:
+ 'Buttons provide visual cues for actions and events. These fundamental components allow users to commit actions and navigate a page flow. Use a Button when a user needs to submit a form, start a new task or action, or trigger a new UI element to appear on the page.',
+ bestPractices: [
+ {guidance: true, description: 'Use secondary for most actions and reserve primary for a single emphasized action per layout.'},
+ {guidance: true, description: 'Include a clear, concise label that describes the action the button performs.'},
+ {guidance: false, description: 'Place more than one primary button in the same view — this dilutes the visual hierarchy.'},
+ {guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions.'},
],
- notes: [
- 'XDSButtonVariant 类型通过 keyof typeof variants 从 variants StyleX 对象派生。',
- '悬停/激活状态使用 backgroundImage 和 linear-gradient 在基础背景上叠加覆盖颜色。',
- 'destructive 变体使用 colorTokens.negative 作为焦点轮廓颜色。',
- 'endContent 包裹在带有 color: inherit 的 <span> 中,使图标/徽章在所有变体中匹配按钮文本颜色。',
- '仅提供 icon 而不提供 children 时,按钮变为纯图标模式:渲染为正方形(aspectRatio: 1/1),label 用作 aria-label(不可视渲染)。支持任何 ReactNode 作为图标——SVG 组件、emoji 或文本。',
- '纯图标按钮(提供 icon 但不提供 children 时)会忽略 endContent,以保持正方形的宽高比。',
- '为了无障碍性,优先使用 XDSButton 而非 <div onClick> 或 <span onClick>——它提供键盘导航、焦点管理和屏幕阅读器支持。',
- '纯图标按钮适用于工具栏、操作网格和紧凑控件。',
- 'onClick 在 onClickAction 之前触发;在 onClick 中调用 preventDefault 会阻止 onClickAction 运行。',
- 'type 默认为 "button"(非 "submit")以防止意外的表单提交。',
- '禁用状态清除背景渐变(backgroundImage: none)以防止悬停色调通过不透明度泄漏。',
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A leading icon that visually represents the meaning of the button label.'},
+ {name: 'Label', required: true, description: 'A text label describing the button action. Required for accessibility.'},
+ {name: 'End content', required: false, description: 'Trailing content that provides affordance to the type of action performed. Recommended when the expected action is non-obvious.'},
+ {name: 'Spinner', required: false, description: 'Indicates a loading state when the button action is not immediate.'},
],
},
props: [
@@ -256,40 +210,22 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'button w/ multiple variants, sizes, loading state',
- features: [
- "variants: primary, secondary, ghost, destructive",
- 'sizes: sm(28px), md(32px), lg(36px)',
- 'loading state: shows spinner+disables interaction, announces via live region',
- 'focus visible: accessible focus outline w/ variant-specific colors',
- 'hover/active: overlay colors via backgroundImage for consistent layering',
- 'reduced motion: respects prefers-reduced-motion',
- 'tooltip+disabled: aria-disabled keeps button focusable for keyboard tooltip',
- 'form integration: type, name, value, form props',
- 'async actions: onClickAction w/ automatic loading via useTransition',
- ],
- accessibility: [
- 'Native <button> for correct semantics + keyboard support.',
- 'Icon-only buttons (isIconOnly) set aria-label from label prop.',
- 'Loading sets aria-busy + announces via role="status" live region.',
- 'Content hidden from AT during loading via aria-hidden.',
- 'Tooltip+disabled uses aria-disabled to stay focusable.',
- 'Dev warning on empty label for icon-only (WCAG 4.1.2).',
- 'aria-label, aria-busy, aria-disabled after ...props spread to prevent clobbering.',
- ],
- keyboard: 'Enter/Space=activate; Tab/Shift+Tab=move focus in/out.',
- notes: [
- 'XDSButtonVariant derived from keyof typeof variants StyleX object',
- 'hover/active use backgroundImage linear-gradient overlay on base bg',
- 'destructive variant uses colorTokens.negative for focus outline',
- 'endContent wrapped in <span> w/ color:inherit, matches button text across variants',
- 'isIconOnly=true: square (aspectRatio:1/1), label=aria-label, any ReactNode as icon',
- 'endContent ignored when isIconOnly to preserve square ratio',
- 'prefer XDSButton over <div onClick> for a11y: keyboard nav, focus management, screen reader',
- 'icon-only suits toolbars, action grids, compact controls',
- 'onClick fires before onClickAction; preventDefault in onClick stops onClickAction',
- 'type defaults to "button" (not "submit") to prevent accidental form submission',
- 'disabled clears backgroundImage:none to prevent hover tint leaking through opacity',
- ],
+ usage: {
+ description:
+ 'Buttons provide visual cues for actions and events. These fundamental components allow users to commit actions and navigate a page flow. Use a Button when a user needs to submit a form, start a new task or action, or trigger a new UI element to appear on the page.',
+ bestPractices: [
+ {guidance: true, description: 'Use secondary for most actions and reserve primary for a single emphasized action per layout.'},
+ {guidance: true, description: 'Include a clear, concise label that describes the action the button performs.'},
+ {guidance: false, description: 'Place more than one primary button in the same view — this dilutes the visual hierarchy.'},
+ {guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions.'},
+ ],
+ anatomy: [
+ {name: 'Icon', required: false, description: 'A leading icon that visually represents the meaning of the button label.'},
+ {name: 'Label', required: true, description: 'A text label describing the button action. Required for accessibility.'},
+ {name: 'End content', required: false, description: 'Trailing content that provides affordance to the type of action performed. Recommended when the expected action is non-obvious.'},
+ {name: 'Spinner', required: false, description: 'Indicates a loading state when the button action is not immediate.'},
+ ],
+ },
propDescriptions: {
label: 'accessible label; visible text by default, aria-label when isIconOnly',
variant: 'visual style variant',
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 555cde647b..1352ed310c 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -5,33 +5,12 @@ export const docs = {
keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],
usage: {
description:
- 'A calendar component for date selection supporting single and range selection modes with customizable constraints and locale options.',
- features: [
- "Selection Modes: 'single' (default) and 'range'",
- 'Multi-Month Display: Show 1 or 2 months side by side',
- 'Date Constraints: min, max, and custom dateConstraints functions',
- 'Locale Options: weekStartsOn for configurable first day of week',
- 'Week Numbers: Optional ISO week number column',
- 'Controlled/Uncontrolled: Supports both patterns via value/defaultValue',
- 'Nav buttons auto-disable when min/max boundary is within the current month',
- ],
- accessibility: [
- 'Keyboard: Escape cancels in-progress range selection',
- 'Day name headers use role="columnheader", day buttons expose data-date attribute',
- 'Outside days are aria-disabled and not clickable even when visible',
- 'Selected date receives roving tabindex priority over today',
- 'Day cell transitions respect prefers-reduced-motion',
- ],
- notes: [
- 'ISODateString type: `${number}${number}${number}${number}-${number}${number}-${number}${number}`',
- 'DayOfWeek type: 0 | 1 | 2 | 3 | 4 | 5 | 6',
- 'DateRange interface: { start: ISODateString; end: ISODateString }',
- 'Day buttons render a data-date="YYYY-MM-DD" attribute for testing and scripting',
- 'Roving tabindex priority: selected date > today > first enabled day',
- 'In range mode, pressing Escape resets the pending start date without firing onChange',
- 'Previous/next month buttons become disabled when the current view contains the min or max date',
- 'Outside days (adjacent month) are rendered with aria-disabled="true" and ignore clicks',
- 'Day cell transitions are suppressed under @media (prefers-reduced-motion: reduce)',
+ 'Calendar displays a month-view grid for selecting dates, supporting single and range selection modes. Use when users need to pick a specific date or date range within a constrained set of options.',
+ bestPractices: [
+ {guidance: true, description: 'Set min and max dates to constrain selection to a valid range for the task.'},
+ {guidance: true, description: 'Use range mode for start/end date scenarios like booking or scheduling.'},
+ {guidance: false, description: 'Use a calendar for selecting dates far in the past or future — prefer a date input for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without explaining why they are unavailable.'},
],
},
props: [
@@ -124,31 +103,13 @@ export const docs = {
export const docsZh = {
name: 'Calendar',
usage: {
- description: 'XDSCalendar 日历组件,支持单选和范围选择模式的日期选取。',
- features: [
- "选择模式:'single'(默认)和 'range'",
- '多月显示:并排显示 1 或 2 个月份',
- '日期约束:min、max 和自定义 dateConstraints 函数',
- '区域选项:weekStartsOn 可配置每周的起始日',
- '周数:可选的 ISO 周数列',
- '受控/非受控:通过 value/defaultValue 支持两种模式',
- '键盘:Escape 取消正在进行的范围选择',
- '无障碍:星期名称使用 role="columnheader",日期按钮暴露 data-date 属性',
- '无障碍:外部日期设为 aria-disabled 且不可点击',
- '无障碍:选中日期获得漫游 tabindex 优先级',
- '导航按钮在 min/max 边界所在月份时自动禁用',
- '动效:日期单元格过渡遵循 prefers-reduced-motion',
- ],
- notes: [
- 'ISODateString 类型:`${number}${number}${number}${number}-${number}${number}-${number}${number}`',
- 'DayOfWeek 类型:0 | 1 | 2 | 3 | 4 | 5 | 6',
- 'DateRange 接口:{ start: ISODateString; end: ISODateString }',
- '日期按钮渲染 data-date="YYYY-MM-DD" 属性,用于测试和脚本',
- '漫游 tabindex 优先级:选中日期 > 今天 > 第一个启用日期',
- '范围模式下按 Escape 重置待选起始日期,不触发 onChange',
- '上/下月按钮在当前视图包含 min 或 max 日期时禁用',
- '外部日期(相邻月份)以 aria-disabled="true" 渲染且忽略点击',
- '日期单元格过渡在 @media (prefers-reduced-motion: reduce) 下被抑制',
+ description:
+ 'Calendar displays a month-view grid for selecting dates, supporting single and range selection modes. Use when users need to pick a specific date or date range within a constrained set of options.',
+ bestPractices: [
+ {guidance: true, description: 'Set min and max dates to constrain selection to a valid range for the task.'},
+ {guidance: true, description: 'Use range mode for start/end date scenarios like booking or scheduling.'},
+ {guidance: false, description: 'Use a calendar for selecting dates far in the past or future — prefer a date input for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without explaining why they are unavailable.'},
],
},
props: [
@@ -191,28 +152,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'calendar for date selection w/ single+range modes',
- features: [
- "selection modes: single (default) + range",
- 'multi-month: 1 or 2 side by side',
- 'date constraints: min, max, custom dateConstraints fns',
- 'weekStartsOn for configurable first day of week',
- 'optional ISO week number column',
- 'controlled/uncontrolled via value/defaultValue',
- 'Escape cancels in-progress range selection',
- 'a11y: columnheader on day names, data-date on buttons, outside days aria-disabled',
- 'selected date gets roving tabindex priority; nav buttons disable at min/max boundary',
- 'prefers-reduced-motion suppresses day cell transitions',
- ],
- notes: [
- 'ISODateString type: YYYY-MM-DD template literal',
- 'DayOfWeek type: 0|1|2|3|4|5|6',
- 'DateRange: { start: ISODateString; end: ISODateString }',
- 'data-date attr on day buttons for testing/scripting',
- 'tabindex priority: selected > today > first enabled',
- 'Escape in range mode resets start, no onChange fired',
- 'prev/next buttons disabled when view contains min/max',
- 'outside days: aria-disabled + click ignored',
- ],
+ usage: {
+ description:
+ 'Calendar displays a month-view grid for selecting dates, supporting single and range selection modes. Use when users need to pick a specific date or date range within a constrained set of options.',
+ bestPractices: [
+ {guidance: true, description: 'Set min and max dates to constrain selection to a valid range for the task.'},
+ {guidance: true, description: 'Use range mode for start/end date scenarios like booking or scheduling.'},
+ {guidance: false, description: 'Use a calendar for selecting dates far in the past or future — prefer a date input for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without explaining why they are unavailable.'},
+ ],
+ },
propDescriptions: {
mode: 'selection mode',
value: 'controlled selected value',
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 3e5e6a9348..d1b5608d14 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -5,17 +5,11 @@ export const docs = {
keywords: ["card","surface","panel","container","elevated","shadow","box","paper","tile","well"],
usage: {
description:
- 'Card container that groups related information inside elevated containers for visual organization. Use when explicit grouping is needed — prefer sections as the default and escalate to cards only when stronger visual distinction is required.',
- features: [
- 'Top-level container for elevated content',
- 'Provides card-specific appearance: background, shadow, and border-radius',
- 'Supports `padding={0}` for edge-to-edge content',
- 'Composable with XDSLayout, XDSCollapsible, and XDSCollapsibleGroup',
- 'Background color variants: default, muted, and 10 non-semantic palette colors',
- ],
- notes: [
- 'Sets CSS variables for child layout components',
- 'Card elevation adapts automatically based on the background surface.',
+ 'Card is an elevated container that groups related information for visual organization. Use cards when explicit grouping is needed and sections alone do not provide enough visual distinction.',
+ bestPractices: [
+ {guidance: true, description: 'Reserve cards for content that benefits from visual separation — default to sections first.'},
+ {guidance: true, description: 'Use a consistent padding value across sibling cards to maintain visual alignment.'},
+ {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use a different container.'},
],
anatomy: [
{name: 'Card Header', required: false, description: 'Displays a title and optional end content.'},
@@ -86,13 +80,17 @@ export const docs = {
export const docsZh = {
name: 'Card',
usage: {
- description: '具有阴影和主题样式的卡片容器组件。',
- features: [
- '用于承载内容的顶层容器',
- '提供卡片特有的外观:背景、阴影和圆角',
- '为子布局组件设置 CSS 变量',
- '支持 `padding={0}` 实现边到边内容',
- '可与 XDSLayout、XDSCollapsible 和 XDSCollapsibleGroup 组合使用',
+ description:
+ 'Card is an elevated container that groups related information for visual organization. Use cards when explicit grouping is needed and sections alone do not provide enough visual distinction.',
+ bestPractices: [
+ {guidance: true, description: 'Reserve cards for content that benefits from visual separation — default to sections first.'},
+ {guidance: true, description: 'Use a consistent padding value across sibling cards to maintain visual alignment.'},
+ {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use a different container.'},
+ ],
+ anatomy: [
+ {name: 'Card Header', required: false, description: 'Displays a title and optional end content.'},
+ {name: 'Card Body', required: true, description: 'Accepts any content.'},
+ {name: 'Card Footer', required: false, description: 'Contains actions.'},
],
},
props: [
@@ -125,13 +123,20 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'elevated container w/ themed styling',
- features: [
- 'top-level container for elevated content',
- 'card appearance: background, shadow, border-radius',
- 'sets CSS vars for child layout components',
- 'optional full-bleed mode removes padding for edge-to-edge content',
- 'composable w/ XDSLayout, XDSCollapsible, XDSCollapsibleGroup',
- ],
+ usage: {
+ description:
+ 'Card is an elevated container that groups related information for visual organization. Use cards when explicit grouping is needed and sections alone do not provide enough visual distinction.',
+ bestPractices: [
+ {guidance: true, description: 'Reserve cards for content that benefits from visual separation — default to sections first.'},
+ {guidance: true, description: 'Use a consistent padding value across sibling cards to maintain visual alignment.'},
+ {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use a different container.'},
+ ],
+ anatomy: [
+ {name: 'Card Header', required: false, description: 'Displays a title and optional end content.'},
+ {name: 'Card Body', required: true, description: 'Accepts any content.'},
+ {name: 'Card Footer', required: false, description: 'Contains actions.'},
+ ],
+ },
propDescriptions: {
width: 'card width (number=px, string=as-is)',
height: 'card height (number=px, string=as-is)',
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 5423b746be..803a9654cf 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -5,24 +5,12 @@ export const docs = {
keywords: ['carousel', 'slider', 'scroll', 'gallery', 'filmstrip', 'swiper', 'horizontal', 'overflow', 'snap'],
usage: {
description:
- 'Horizontal scroll container with fade-edge overflow indication, optional navigation buttons, and scroll-snap support.',
- features: [
- 'Overflow Detection: Gradient fades appear at edges when content overflows, signaling more items',
- 'Navigation Buttons: Prev/next buttons appear on hover (desktop only) via XDSLayer top-layer rendering',
- 'Scroll Snap: Optional snap-to-item behavior for precise item alignment',
- 'Gap Scale: Configurable item spacing using the spacing token scale (0 to 4)',
- 'Scale Animation: Items scale down slightly when entering/exiting the viewport via scroll-driven animation',
- ],
- accessibility: [
- 'Root element uses role="region" with aria-roledescription="carousel" for screen reader context.',
- 'Navigation buttons have accessible labels ("Scroll left", "Scroll right").',
- 'Scroll behavior and scale animations respect prefers-reduced-motion.',
- ],
- notes: [
- 'Navigation buttons render on the top layer via XDSLayer, so they escape parent overflow clipping.',
- 'The fade-edge effect uses CSS mask-image gradients that transition smoothly.',
- 'Each child is wrapped in a flex-shrink:0 container with scroll-snap-align:start when snap is enabled.',
- 'Items use scroll-driven animation (animationTimeline: view(inline)) for the scale effect.',
+ 'Carousel is a horizontal scroll container with fade-edge overflow indication and optional navigation buttons. Use to present a set of items that exceeds the available width, such as a gallery or filmstrip of cards.',
+ bestPractices: [
+ {guidance: true, description: 'Enable scroll-snap when each item should be viewed individually rather than as a continuous strip.'},
+ {guidance: true, description: 'Provide a descriptive aria-label so assistive technology users understand the carousel\'s content.'},
+ {guidance: false, description: 'Use a carousel for critical content that users must see — not all users scroll horizontally.'},
+ {guidance: false, description: 'Auto-advance carousel items — let the user control scrolling at their own pace.'},
],
},
props: [
@@ -47,26 +35,13 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
- description: '水平滚动容器,具有渐变边缘溢出指示、可选导航按钮和滚动吸附支持。',
- features: [
- '溢出检测:当内容溢出时,边缘出现渐变淡化效果,提示还有更多项目',
- '导航按钮:鼠标悬停时显示上一个/下一个按钮(仅桌面端),通过 XDSLayer 顶层渲染',
- '滚动吸附:可选的吸附到项目行为,实现精确的项目对齐',
- '间距比例:使用间距令牌比例(0 到 4)配置项目间距',
- '缩放动画:项目在进入/离开视口时通过滚动驱动动画略微缩小',
- '无障碍:role="region",带 aria-roledescription="carousel" 和可配置的 aria-label',
- '减少动效:尊重 prefers-reduced-motion 的滚动行为和入场动画',
- ],
- accessibility: [
- '根元素使用 role="region" 和 aria-roledescription="carousel",为屏幕阅读器提供上下文。',
- '导航按钮具有无障碍标签("向左滚动"、"向右滚动")。',
- '滚动行为和缩放动画尊重 prefers-reduced-motion。',
- ],
- notes: [
- '导航按钮通过 XDSLayer 在顶层渲染,因此它们可以逃离父级溢出裁剪。',
- '渐变边缘效果使用 CSS mask-image 渐变,过渡平滑。',
- '启用吸附时,每个子元素被包裹在 flex-shrink:0 容器中,带有 scroll-snap-align:start。',
- '项目使用滚动驱动动画(animationTimeline: view(inline))实现缩放效果。',
+ description:
+ 'Carousel is a horizontal scroll container with fade-edge overflow indication and optional navigation buttons. Use to present a set of items that exceeds the available width, such as a gallery or filmstrip of cards.',
+ bestPractices: [
+ {guidance: true, description: 'Enable scroll-snap when each item should be viewed individually rather than as a continuous strip.'},
+ {guidance: true, description: 'Provide a descriptive aria-label so assistive technology users understand the carousel\'s content.'},
+ {guidance: false, description: 'Use a carousel for critical content that users must see — not all users scroll horizontally.'},
+ {guidance: false, description: 'Auto-advance carousel items — let the user control scrolling at their own pace.'},
],
},
propDescriptions: {
@@ -81,15 +56,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'horizontal scroll container w/ fade-edge overflow, optional prev/next nav buttons on top layer, scroll-snap',
- features: [
- 'overflow detection: gradient fades at edges when content overflows',
- 'nav buttons: prev/next on hover (desktop) via XDSLayer top-layer',
- 'scroll-snap: optional snap-to-item alignment',
- 'gap scale: spacing token scale 0-4',
- 'scale animation: items shrink at viewport edges via scroll-driven anim',
- 'a11y: role=region + aria-roledescription=carousel',
- 'prefers-reduced-motion: smooth scroll + scale anim disabled',
- ],
+ usage: {
+ description:
+ 'Carousel is a horizontal scroll container with fade-edge overflow indication and optional navigation buttons. Use to present a set of items that exceeds the available width, such as a gallery or filmstrip of cards.',
+ bestPractices: [
+ {guidance: true, description: 'Enable scroll-snap when each item should be viewed individually rather than as a continuous strip.'},
+ {guidance: true, description: 'Provide a descriptive aria-label so assistive technology users understand the carousel\'s content.'},
+ {guidance: false, description: 'Use a carousel for critical content that users must see — not all users scroll horizontally.'},
+ {guidance: false, description: 'Auto-advance carousel items — let the user control scrolling at their own pace.'},
+ ],
+ },
propDescriptions: {
children: 'carousel items in horizontal scroll',
gap: 'item spacing via spacing token scale',
@@ -97,15 +73,4 @@ export const docsDense = {
hasSnap: 'scroll-snap; children snap to start edge',
'aria-label': 'accessible label for carousel region',
},
- accessibility: [
- 'root: role=region + aria-roledescription=carousel',
- 'nav buttons: "Scroll left"/"Scroll right" labels',
- 'respects prefers-reduced-motion',
- ],
- notes: [
- 'nav buttons on top layer via XDSLayer; escape parent overflow',
- 'fade-edge: CSS mask-image gradients w/ smooth transition',
- 'children wrapped in flex-shrink:0 + scroll-snap-align:start when snap on',
- 'scroll-driven animation (animationTimeline: view(inline)) for scale effect',
- ],
};
diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjs
index 5a1097c46d..cec84f9026 100644
--- a/packages/core/src/Center/Center.doc.mjs
+++ b/packages/core/src/Center/Center.doc.mjs
@@ -44,11 +44,12 @@ export const docs = {
],
},
usage: {
- description: 'Centers children horizontally and/or vertically using flexbox.',
- features: [
- 'Supports centering on both axes, horizontal only, or vertical only',
- 'Inline-flex mode for centering inline content such as text and icons',
- 'Accepts explicit width and height to size the container',
+ description:
+ 'Center is a layout primitive that centers its children horizontally and/or vertically using flexbox. Use it to quickly align content within a container without writing custom centering styles.',
+ bestPractices: [
+ {guidance: true, description: 'Use the axis prop to center only in the direction you need — avoid unnecessary centering on both axes.'},
+ {guidance: true, description: 'Set isInline when centering small inline content like icons or text within a line.'},
+ {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout for page-level structure instead.'},
],
},
};
@@ -57,11 +58,12 @@ export const docs = {
export const docsZh = {
name: 'Center',
usage: {
- description: '使用 flexbox 将子元素水平和/或垂直居中。',
- features: [
- '支持双轴居中、仅水平居中或仅垂直居中',
- '内联 flex 模式,用于居中文本和图标等内联内容',
- '接受显式的宽度和高度来设置容器尺寸',
+ description:
+ 'Center is a layout primitive that centers its children horizontally and/or vertically using flexbox. Use it to quickly align content within a container without writing custom centering styles.',
+ bestPractices: [
+ {guidance: true, description: 'Use the axis prop to center only in the direction you need — avoid unnecessary centering on both axes.'},
+ {guidance: true, description: 'Set isInline when centering small inline content like icons or text within a line.'},
+ {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout for page-level structure instead.'},
],
},
props: [
@@ -92,11 +94,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'centers children horizontally+vertically via flexbox',
- features: [
- 'centering on both axes, horizontal only, or vertical only',
- 'inline-flex mode for inline content like text+icons',
- 'accepts explicit width+height to size container',
- ],
+ usage: {
+ description:
+ 'Center is a layout primitive that centers its children horizontally and/or vertically using flexbox. Use it to quickly align content within a container without writing custom centering styles.',
+ bestPractices: [
+ {guidance: true, description: 'Use the axis prop to center only in the direction you need — avoid unnecessary centering on both axes.'},
+ {guidance: true, description: 'Set isInline when centering small inline content like icons or text within a line.'},
+ {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout for page-level structure instead.'},
+ ],
+ },
propDescriptions: {
axis: 'centering direction(s)',
width: 'container width (px or CSS)',
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 155b7ec7ce..3f704a4378 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -162,26 +162,12 @@ export const docs = {
},
],
usage: {
- description: 'Chat components for building AI chat interfaces. Provides layout primitives (MessageList, Message, Bubble, SystemMessage) and a composer with trigger menus and attachments for constructing full chat experiences.',
- features: [
- 'Composition model — MessageList > Message > Bubble',
- 'Sender-aware styling (user, assistant, system) via context',
- 'Auto-scroll with "New messages" indicator',
- 'Infinite scroll via onScrollToTopAction with useTransition',
- 'Density variants: compact, balanced, spacious (flows via context)',
- 'System messages with optional divider variant for date separators',
- 'Free-form children — not all content needs a bubble',
- 'Timestamp display: hover or header',
- 'Message status indicators (sending, sent, delivered, read, error)',
- 'role="log" with aria-live="polite" for accessibility',
- 'Composer layout shell with named semantic slots',
- 'ContentEditable input with @ mention and / command trigger menus',
- 'Imperative handle on ComposerInput for programmatic token/text insertion',
- 'Tokenized text rendering in message bubbles via XDSChatTokenizedText',
- 'XDSSearchSource integration — reuses Typeahead search sources',
- 'Concentric radius — inner elements follow outer shell curvature',
- 'Themeable via --composer-radius and --composer-padding CSS vars',
- 'Extractable send/stop button (XDSChatSendButton) with automatic composer context',
+ description: 'Chat components provide layout primitives and a composer for building AI chat interfaces. Use Chat when building conversational UIs that need message display, sender-aware styling, and rich input with trigger menus and attachments.',
+ bestPractices: [
+ { guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
+ { guidance: true, description: 'Use the named slots on XDSChatComposer (attachments, headerActions, footerActions) to keep the input layout structured and extensible.' },
+ { guidance: false, description: 'Place metadata or names on both the bubble and the message wrapper — use one or the other based on whether the content has a bubble boundary.' },
+ { guidance: false, description: 'Bypass XDSChatLayout for full-page chat — it handles auto-scroll, density adaptation, and composer docking automatically.' },
],
},
};
@@ -214,27 +200,12 @@ docs.components.push(chatLayoutScrollButtonComponent);
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
- description:
- 'AI 聊天界面组件。布局(MessageList、Message、Bubble、SystemMessage)+ 编写器(Composer、ComposerInput 触发菜单、ComposerAttachments)。',
- features: [
- '组合模型 — MessageList > Message > Bubble',
- '根据发送者自动调整样式(user、assistant、system),通过上下文传递',
- '自动滚动,带有"新消息"指示器',
- '通过 onScrollToTopAction 和 useTransition 实现无限滚动',
- '密度变体:compact、balanced、spacious(通过上下文传递)',
- '系统消息,可选分割线变体用于日期分隔',
- '自由子元素 — 并非所有内容都需要气泡包裹',
- '时间戳显示:悬停或标题',
- '消息状态指示器(sending、sent、delivered、read、error)',
- 'role="log" 配合 aria-live="polite" 实现无障碍访问',
- '编写器布局外壳,具有命名语义插槽',
- 'ContentEditable 输入框,支持 @ 提及和 / 命令触发菜单',
- 'ComposerInput 命令式句柄,支持编程式插入标记/文本',
- '通过 XDSChatTokenizedText 在消息气泡中渲染标记文本',
- 'XDSSearchSource 集成 — 复用 Typeahead 搜索源',
- '同心圆角 — 内部元素跟随外部外壳曲率',
- '通过 --composer-radius 和 --composer-padding CSS 变量实现主题化',
- '可提取的发送/停止按钮(XDSChatSendButton),自动读取编写器上下文',
+ description: 'Chat components provide layout primitives and a composer for building AI chat interfaces. Use Chat when building conversational UIs that need message display, sender-aware styling, and rich input with trigger menus and attachments.',
+ bestPractices: [
+ { guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
+ { guidance: true, description: 'Use the named slots on XDSChatComposer (attachments, headerActions, footerActions) to keep the input layout structured and extensible.' },
+ { guidance: false, description: 'Place metadata or names on both the bubble and the message wrapper — use one or the other based on whether the content has a bubble boundary.' },
+ { guidance: false, description: 'Bypass XDSChatLayout for full-page chat — it handles auto-scroll, density adaptation, and composer docking automatically.' },
],
},
components: [
@@ -385,26 +356,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'AI chat components. Layout (MessageList>Message>Bubble+SystemMessage) + Composer (shell w/ slots, ContentEditable input w/ trigger menus, attachments)',
- features: [
- 'composition: MessageList > Message > Bubble',
- 'sender-aware styling (user/assistant/system) via context',
- 'auto-scroll w/ "New messages" indicator',
- 'infinite scroll via onScrollToTopAction w/ useTransition',
- 'density: compact/balanced/spacious (flows via context)',
- 'system msgs w/ optional divider variant for date separators',
- 'free-form children; not all content needs bubble',
- 'timestamp: hover or header display',
- 'msg status indicators (sending/sent/delivered/read/error)',
- 'role="log" + aria-live="polite" for a11y',
- 'composer layout shell w/ named semantic slots',
- 'ContentEditable input w/ @ mention + / command trigger menus',
- 'imperative handle on ComposerInput for programmatic token/text insert',
- 'tokenized text rendering in msg bubbles via XDSChatTokenizedText',
- 'XDSSearchSource integration; reuses Typeahead search sources',
- 'concentric radius; inner elements follow outer shell curvature',
- 'themeable via --composer-radius + --composer-padding CSS vars',
- 'extractable send/stop btn (XDSChatSendButton) w/ auto composer context',
- ],
+ usage: {
+ description: 'Chat components provide layout primitives and a composer for building AI chat interfaces. Use Chat when building conversational UIs that need message display, sender-aware styling, and rich input with trigger menus and attachments.',
+ bestPractices: [
+ { guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
+ { guidance: true, description: 'Use the named slots on XDSChatComposer (attachments, headerActions, footerActions) to keep the input layout structured and extensible.' },
+ { guidance: false, description: 'Place metadata or names on both the bubble and the message wrapper — use one or the other based on whether the content has a bubble boundary.' },
+ { guidance: false, description: 'Bypass XDSChatLayout for full-page chat — it handles auto-scroll, density adaptation, and composer docking automatically.' },
+ ],
+ },
components: [
{
name: 'XDSChatMessageList',
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index e7f6ce19ab..950bc29e20 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -105,25 +105,12 @@ export const docs = {
],
},
usage: {
- description: 'A checkbox input for toggling boolean values. Use for toggling a single boolean setting, or select multiple options from a set with CheckboxList for groups.',
- features: [
- 'Accessible — always includes a label (can be visually hidden)',
- 'Indeterminate state — supports indeterminate for "select all" patterns',
- 'Descriptions — optional description text below the label',
- 'Sizes — sm (compact) and md (default)',
- 'Async actions — onChangeAction with optimistic updates and loading spinner',
- 'Status messages — error, warning, success validation feedback',
- 'Optional/required indicators — label suffix with field state',
- 'Label icons — optional icon before label text',
- 'Disabled state — full support for disabled state styling',
- 'Reduced motion — respects prefers-reduced-motion',
- ],
- notes: [
- 'Uses a hidden native <input type="checkbox"> for accessibility with a custom visual checkbox overlay.',
- 'The visual checkbox responds to hover, focus, and checked states via ancestor selectors (stylex.when.ancestor).',
- 'Label is clickable and properly associated with the input via htmlFor/id.',
- 'Focus outline uses the standard XDS focus ring token.',
- 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling.',
+ description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',
+ bestPractices: [
+ { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },
+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },
+ { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },
],
},
};
@@ -132,25 +119,12 @@ export const docs = {
export const docsZh = {
name: 'CheckboxInput',
usage: {
- description: '复选框输入组件,用于切换布尔值。',
- features: [
- '无障碍——始终包含标签(可视觉隐藏)',
- '不确定状态——支持"全选"模式的不确定状态',
- '描述——标签下方可选的描述文本',
- '尺寸——sm(紧凑)和 md(默认)',
- '异步操作——onChangeAction 带乐观更新和加载旋转器',
- '状态消息——错误、警告、成功验证反馈',
- '可选/必填指示器——带字段状态的标签后缀',
- '标签图标——标签文本前可选图标',
- '禁用状态——完整支持禁用状态样式',
- '减少动画——尊重 prefers-reduced-motion',
- ],
- notes: [
- '使用隐藏的原生 <input type="checkbox"> 确保无障碍性,并覆盖自定义视觉复选框。',
- '视觉复选框通过祖先选择器(stylex.when.ancestor)响应悬停、焦点和选中状态。',
- '标签可点击,并通过 htmlFor/id 与输入框正确关联。',
- '焦点轮廓使用标准的 XDS 焦点环令牌。',
- '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复切换。',
+ description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',
+ bestPractices: [
+ { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },
+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },
+ { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },
],
},
props: [
@@ -196,25 +170,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'checkbox for toggling boolean values',
- features: [
- 'accessible; always includes label (can be visually hidden)',
- 'indeterminate state for "select all" patterns',
- 'optional description text below label',
- 'sizes: sm (compact), md (default)',
- 'async actions w/ onChangeAction, optimistic updates, loading spinner',
- 'status messages: error/warning/success validation',
- 'optional/required field indicators',
- 'label icons',
- 'full disabled state styling',
- 'respects prefers-reduced-motion',
- ],
- notes: [
- 'hidden native <input type="checkbox"> w/ custom visual overlay',
- 'visual checkbox responds to hover, focus, checked via ancestor selectors (stylex.when.ancestor)',
- 'label clickable + associated via htmlFor/id',
- 'focus outline uses XDS focus ring token',
- 'interaction blocked during busy state to prevent double-toggling',
- ],
+ usage: {
+ description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',
+ bestPractices: [
+ { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },
+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },
+ { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },
+ ],
+ },
propDescriptions: {
ref: 'ref forwarded to underlying <input>',
label: 'label text; always rendered for a11y',
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index c688625170..f166029a4e 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -130,29 +130,12 @@ export const docs = {
},
],
usage: {
- description: 'A checkbox group for multi-value selection from a list of options. Use when users need to select multiple visible options from a set. For single selection use RadioList; for long option lists consider MultiSelector.',
- features: [
- 'Accessible — uses native <input type="checkbox"> with proper ARIA attributes',
- 'Collection mode — parent manages selected values as string[], items derive checked state',
- 'Standalone mode — individual items use isChecked/onCheck for independent control',
- 'Density — compact, balanced, spacious via XDSList integration',
- 'Dividers — optional border dividers between items',
- 'Indeterminate — supports three-state checkbox (true, false, indeterminate) in standalone mode',
- 'Descriptions — optional secondary text per item',
- 'End content — slot for badges, actions, or other content after the label',
- 'Disabled state — supports disabling the entire group or individual items',
- 'Async actions — onChangeAction with optimistic updates and busy state',
- 'Full-row click — clicking anywhere on the row toggles the checkbox',
- 'Field integration — uses XDSField for label, description, and status messaging',
- ],
- notes: [
- 'XDSCheckboxList composes XDSField (label, description, status) and XDSList (density, dividers)',
- 'XDSCheckboxListItem can be used inside XDSCheckboxList (collection mode) or XDSList (standalone mode)',
- 'In collection mode, XDSCheckboxListItem requires a `value` prop — throws if missing',
- 'Uses XDSCheckboxInput internally with isLabelHidden for the checkbox visual',
- 'Full-row click target with guard against interactive endContent children',
- 'Async actions use useOptimistic + useTransition for immediate visual feedback',
- 'Density maps to checkbox size: compact → sm, balanced/spacious → md',
+ description: 'CheckboxList is a grouped set of checkboxes for selecting multiple options from a visible list. Use it when users need to pick several items at once. For single selection use RadioList; for long option sets consider MultiSelector.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a clear group label that describes what the options represent.' },
+ { guidance: true, description: 'Use collection mode (value/onChange on the group) to let the parent manage selected state as a string array.' },
+ { guidance: false, description: 'Use CheckboxList when only one option can be selected — use RadioList instead.' },
+ { guidance: false, description: 'Place interactive elements in endContent that conflict with the full-row click target.' },
],
},
};
@@ -161,29 +144,12 @@ export const docs = {
export const docsZh = {
name: 'CheckboxList',
usage: {
- description: '用于从选项列表中进行多值选择的复选框组组件。支持集合模式(父组件管理状态)和独立模式(逐项状态)。',
- features: [
- '无障碍 - 使用原生 <input type="checkbox">,配合正确的 ARIA 属性',
- '集合模式 - 父组件将选中值管理为 string[],子项派生选中状态',
- '独立模式 - 各项使用 isChecked/onCheck 进行独立控制',
- '密度 - 通过 XDSList 集成支持紧凑、平衡、宽敞三种密度',
- '分隔线 - 列表项之间的可选边框分隔线',
- '不确定状态 - 独立模式下支持三态复选框(true、false、indeterminate)',
- '描述 - 每个选项可选的辅助文本',
- '尾部内容 - 标签后的徽章、操作或其他内容插槽',
- '禁用状态 - 支持禁用整个组或单个选项',
- '异步操作 - onChangeAction 配合乐观更新和忙碌状态',
- '全行点击 - 点击行中任意位置均可切换复选框',
- '字段集成 - 使用 XDSField 提供标签、描述和状态消息',
- ],
- notes: [
- 'XDSCheckboxList 组合 XDSField(标签、描述、状态)和 XDSList(密度、分隔线)',
- 'XDSCheckboxListItem 可在 XDSCheckboxList(集合模式)或 XDSList(独立模式)内使用',
- '在集合模式下,XDSCheckboxListItem 需要 `value` 属性——缺失时会抛出错误',
- '内部使用带 isLabelHidden 的 XDSCheckboxInput 作为复选框视觉元素',
- '全行点击目标,带有对交互式尾部内容子元素的防护',
- '异步操作使用 useOptimistic + useTransition 实现即时视觉反馈',
- '密度映射到复选框尺寸:compact → sm,balanced/spacious → md',
+ description: 'CheckboxList is a grouped set of checkboxes for selecting multiple options from a visible list. Use it when users need to pick several items at once. For single selection use RadioList; for long option sets consider MultiSelector.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a clear group label that describes what the options represent.' },
+ { guidance: true, description: 'Use collection mode (value/onChange on the group) to let the parent manage selected state as a string array.' },
+ { guidance: false, description: 'Use CheckboxList when only one option can be selected — use RadioList instead.' },
+ { guidance: false, description: 'Place interactive elements in endContent that conflict with the full-row click target.' },
],
},
components: [
@@ -226,28 +192,15 @@ export const docsZh = {
export const docsDense = {
description:
'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',
- features: [
- 'Accessible; uses native <input type="checkbox"> w/ proper ARIA attributes',
- 'Collection mode; parent manages selected values as string[]',
- 'Standalone mode; items use isChecked/onCheck independently',
- 'Density; compact, balanced, spacious via XDSList',
- 'Dividers; optional border dividers between items',
- 'Indeterminate; three-state checkbox in standalone mode',
- 'End content; slot for badges/actions after label',
- 'Disabled state; group-level or individual',
- 'Async actions; onChangeAction w/ optimistic updates + busy state',
- 'Full-row click; toggles checkbox, guards interactive endContent',
- 'Field integration; XDSField for label, description, status',
- ],
- notes: [
- 'XDSCheckboxList composes XDSField (label, description, status) + XDSList (density, dividers)',
- 'XDSCheckboxListItem works inside XDSCheckboxList (collection) or XDSList (standalone)',
- 'Collection mode requires `value` prop on items; throws if missing',
- 'Uses XDSCheckboxInput w/ isLabelHidden for checkbox visual',
- 'Full-row click target w/ guard against interactive endContent children',
- 'Async uses useOptimistic + useTransition for immediate feedback',
- 'Density maps to checkbox size: compact → sm, balanced/spacious → md',
- ],
+ usage: {
+ description: 'CheckboxList is a grouped set of checkboxes for selecting multiple options from a visible list. Use it when users need to pick several items at once. For single selection use RadioList; for long option sets consider MultiSelector.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a clear group label that describes what the options represent.' },
+ { guidance: true, description: 'Use collection mode (value/onChange on the group) to let the parent manage selected state as a string array.' },
+ { guidance: false, description: 'Use CheckboxList when only one option can be selected — use RadioList instead.' },
+ { guidance: false, description: 'Place interactive elements in endContent that conflict with the full-row click target.' },
+ ],
+ },
components: [
{
name: 'XDSCheckboxList',
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
index 6b66154a20..9b00f8516b 100644
--- a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
+++ b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs
@@ -49,31 +49,12 @@ export const docs = {
],
},
usage: {
- description:
- 'CodeBlock provides syntax-highlighted code display using the CSS Custom Highlight API for zero-DOM-overhead coloring, with a span-based fallback for unsupported browsers. XDSCode renders inline code within prose with monospace styling.',
- features: [
- 'CSS Custom Highlight API: zero-DOM-overhead syntax coloring; spans fallback for unsupported browsers',
- 'Line numbers: optional gutter via hasLineNumbers',
- 'Line highlighting: 1-indexed lines via highlightLines',
- 'Copy button: built-in with onCopy callback',
- 'Header: optional title + language label',
- 'Sizes: sm and md',
- 'Wrapping: isWrapped toggles long-line wrapping vs horizontal scroll',
- 'Languages: TypeScript, JavaScript, CSS, HTML, JSON, plaintext (default)',
- 'XDSCode: inline code element with monospace styling for use inside prose',
- ],
- accessibility: [
- 'XDSCodeBlock renders as <pre> with nested <code> for correct semantic markup.',
- 'Copy button has an accessible label and uses aria-live to announce copy success.',
- 'Line numbers are aria-hidden to avoid screen reader noise.',
- 'Title and language label are visible text in the header, not tooltips.',
- ],
- notes: [
- 'Uses CSS Custom Highlight API (CSS.highlights) when available; falls back to span-based rendering automatically.',
- 'Tokenization is async -- initial render shows unstyled code, highlights applied on next paint.',
- 'SYNC_TOKENIZE_THRESHOLD: short code strings tokenized synchronously to avoid async flash.',
- 'Custom tokenizers support unsupported languages -- pass {type, start, end}[] token array.',
- 'Token types map to xds-token-{type} CSS classes for custom syntax theme overrides.',
+ description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use XDSCodeBlock for fenced multi-line code and XDSCode for inline code within prose.',
+ bestPractices: [
+ { guidance: true, description: 'Set the language prop to enable syntax highlighting — use "plaintext" when the language is unknown or not supported.' },
+ { guidance: true, description: 'Use XDSCode for short inline code references within body text, and XDSCodeBlock for standalone multi-line snippets.' },
+ { guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },
+ { guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
],
},
};
@@ -81,31 +62,12 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
- description:
- '使用 CSS Custom Highlight API 实现零 DOM 开销语法高亮的代码块,不支持时回退到基于 span 的渲染。XDSCode 用于在正文中渲染内联代码。',
- features: [
- 'CSS Custom Highlight API:零 DOM 开销语法高亮;不支持浏览器时回退到 span',
- '行号:通过 hasLineNumbers 显示可选的行号栏',
- '行高亮:通过 highlightLines 指定 1-indexed 的高亮行',
- '复制按钮:内置,支持 onCopy 回调',
- '标题栏:可选的标题和语言标签',
- '尺寸:sm 和 md 两种',
- '换行:isWrapped 切换长行换行与水平滚动',
- '语言:TypeScript、JavaScript、CSS、HTML、JSON、plaintext(默认)',
- 'XDSCode:用于正文中内联代码的等宽字体样式元素',
- ],
- accessibility: [
- 'XDSCodeBlock 渲染为带嵌套 <code> 的 <pre>,具有正确的语义标记。',
- '复制按钮有无障碍标签,并使用 aria-live 播报复制成功。',
- '行号设置 aria-hidden 以避免屏幕阅读器噪音。',
- '标题和语言标签是标题栏中的可见文本,而非工具提示。',
- ],
- notes: [
- '可用时使用 CSS Custom Highlight API(CSS.highlights),自动回退到基于 span 的渲染。',
- '分词是异步的——初始渲染显示未高亮代码,下一帧应用高亮。',
- 'SYNC_TOKENIZE_THRESHOLD:短代码字符串同步分词以避免异步闪烁。',
- '自定义分词器支持内置不支持的语言——传入 {type, start, end}[] token 数组。',
- 'Token 类型映射到 xds-token-{type} CSS 类,支持自定义语法主题覆盖。',
+ description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use XDSCodeBlock for fenced multi-line code and XDSCode for inline code within prose.',
+ bestPractices: [
+ { guidance: true, description: 'Set the language prop to enable syntax highlighting — use "plaintext" when the language is unknown or not supported.' },
+ { guidance: true, description: 'Use XDSCode for short inline code references within body text, and XDSCodeBlock for standalone multi-line snippets.' },
+ { guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },
+ { guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
],
},
components: [
@@ -150,30 +112,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'syntax-highlighted code block via CSS Custom Highlight API (0-DOM overhead); span-based fallback; XDSCode for inline code in prose',
- features: [
- 'CSS Custom Highlight API: 0-DOM-overhead syntax coloring; span fallback',
- 'line numbers: optional gutter via hasLineNumbers',
- 'line highlighting: 1-indexed via highlightLines',
- 'copy button: built-in w/ onCopy callback',
- 'header: optional title + language label',
- 'sizes: sm/md',
- 'wrapping: isWrapped toggles wrap vs h-scroll',
- 'languages: TS/JS/CSS/HTML/JSON/plaintext',
- 'XDSCode: inline code element w/ monospace styling for prose',
- ],
- accessibility: [
- '<pre>+<code> for correct semantic markup',
- 'copy button: a11y label + aria-live announces copy success',
- 'line numbers: aria-hidden',
- 'title/language: visible text in header',
- ],
- notes: [
- 'CSS.highlights API when available; auto-fallback to span rendering',
- 'tokenization async -- highlights applied on next paint',
- 'SYNC_TOKENIZE_THRESHOLD: short code tokenized sync to avoid flash',
- 'custom tokenizer: pass {type,start,end}[] for unsupported languages',
- 'xds-token-{type} CSS classes for custom syntax theme overrides',
- ],
+ usage: {
+ description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use XDSCodeBlock for fenced multi-line code and XDSCode for inline code within prose.',
+ bestPractices: [
+ { guidance: true, description: 'Set the language prop to enable syntax highlighting — use "plaintext" when the language is unknown or not supported.' },
+ { guidance: true, description: 'Use XDSCode for short inline code references within body text, and XDSCodeBlock for standalone multi-line snippets.' },
+ { guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },
+ { guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
+ ],
+ },
components: [
{
name: 'XDSCodeBlock',
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index ec7feb4a1e..3d31c47ede 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -85,25 +85,12 @@ export const docs = {
},
],
usage: {
- description: 'A collapsible content primitive for revealing and hiding content on demand. Use to present additional information in lists or to hide content that can be revealed when needed.',
- features: [
- 'XDSCollapsible makes any content collapsible — a trigger toggles visibility of the content area',
- 'Handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator',
- 'Supports uncontrolled (defaultIsOpen), controlled (isOpen / onOpenChange), and group-coordinated modes',
- 'XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (single mode) or multiple (multiple mode) can be open at a time',
- 'XDSCollapsibleGroup renders no wrapper DOM element',
- 'When inside a group, XDSCollapsible defers open/close state to the group context via the value prop',
- ],
- accessibility: [
- 'Trigger renders as a <button> with aria-expanded reflecting the current open state',
- 'A chevron indicator provides a visual affordance for the expanded/collapsed state',
- 'Keyboard: Enter or Space activates the trigger button to toggle open/close state',
- ],
- notes: [
- 'XDSCollapsible manages its own open/close state by default (uncontrolled)',
- 'When nested inside an XDSCollapsibleGroup with a matching value prop, it defers to the group context',
- 'XDSCollapsibleGroup provides context with isOpen(value) and toggle(value) methods',
- 'The group renders no wrapper DOM — layout is the responsibility of the consumer (e.g. XDSVStack)',
+ description: 'Collapsible is a content primitive that reveals and hides content on demand via a trigger button. Use it to progressively disclose secondary information in lists, settings, or detail panels.',
+ bestPractices: [
+ { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for accordion-style patterns where only one section should be open at a time.' },
+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view.' },
+ { guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },
+ { guidance: false, description: 'Nest collapsibles deeply — more than two levels makes content hard to discover and navigate.' },
],
},
};
@@ -112,25 +99,12 @@ export const docs = {
export const docsZh = {
name: 'Collapsible',
usage: {
- description: '可折叠内容原语和分组协调。',
- features: [
- 'XDSCollapsible 使任何内容可折叠——触发器切换内容区域的可见性',
- '处理状态管理、无障碍(aria-expanded、键盘激活)和折叠指示器',
- '支持非受控(defaultIsOpen)、受控(isOpen / onOpenChange)和分组协调模式',
- 'XDSCollapsibleGroup 协调多个 XDSCollapsible 实例,使同一时间只有一个(single 模式)或多个(multiple 模式)可以展开',
- 'XDSCollapsibleGroup 不渲染包裹 DOM 元素',
- '在分组内时,XDSCollapsible 通过 value 属性将展开/收起状态委托给分组上下文',
- ],
- accessibility: [
- '触发器渲染为带有 aria-expanded 的 <button>,反映当前展开状态',
- '折叠指示器为展开/收起状态提供视觉提示',
- 'Keyboard: Enter 或 Space 激活触发按钮以切换展开/收起状态。',
- ],
- notes: [
- 'XDSCollapsible 默认自行管理展开/收起状态(非受控)',
- '嵌套在具有匹配 value 属性的 XDSCollapsibleGroup 内时,委托给分组上下文',
- 'XDSCollapsibleGroup 通过 isOpen(value) 和 toggle(value) 方法提供上下文',
- '分组不渲染包裹 DOM——布局由使用者负责(如 XDSVStack)',
+ description: 'Collapsible is a content primitive that reveals and hides content on demand via a trigger button. Use it to progressively disclose secondary information in lists, settings, or detail panels.',
+ bestPractices: [
+ { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for accordion-style patterns where only one section should be open at a time.' },
+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view.' },
+ { guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },
+ { guidance: false, description: 'Nest collapsibles deeply — more than two levels makes content hard to discover and navigate.' },
],
},
theming: {
@@ -170,25 +144,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'collapsible content primitive + group coordination',
- features: [
- 'XDSCollapsible makes content collapsible; trigger toggles content visibility',
- 'handles state, a11y (aria-expanded, keyboard), chevron indicator',
- 'uncontrolled (defaultIsOpen), controlled (isOpen/onOpenChange), group-coordinated modes',
- 'XDSCollapsibleGroup coordinates multiple instances; single or multiple open at once',
- 'XDSCollapsibleGroup renders no wrapper DOM',
- 'inside group, defers open/close state to group context via value prop',
- ],
- keyboard: 'Enter/Space activates trigger to toggle open/close',
- accessibility: [
- 'trigger renders as <button> w/ aria-expanded reflecting open state',
- 'chevron indicator shows expanded/collapsed visual affordance',
- ],
- notes: [
- 'manages own open/close state by default (uncontrolled)',
- 'nested in XDSCollapsibleGroup w/ matching value, defers to group context',
- 'group context exposes isOpen(value) + toggle(value) methods',
- 'group renders no wrapper DOM; layout is consumer responsibility (e.g. XDSVStack)',
- ],
+ usage: {
+ description: 'Collapsible is a content primitive that reveals and hides content on demand via a trigger button. Use it to progressively disclose secondary information in lists, settings, or detail panels.',
+ bestPractices: [
+ { guidance: true, description: 'Use XDSCollapsibleGroup with type="single" for accordion-style patterns where only one section should be open at a time.' },
+ { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view.' },
+ { guidance: false, description: 'Hide critical or required content behind a collapsible — users may not discover it.' },
+ { guidance: false, description: 'Nest collapsibles deeply — more than two levels makes content hard to discover and navigate.' },
+ ],
+ },
components: [
{
name: 'XDSCollapsible',
diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
index 3e8120d7c1..c9961153ce 100644
--- a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
@@ -287,33 +287,12 @@ export const docs = {
],
},
usage: {
- description:
- 'CommandPalette is a searchSource-driven command palette dialog that provides filtering, keyboard navigation, grouping, and selection. It uses the same XDSSearchSource interface as XDSTypeahead, supporting static, async, or hybrid data sources.',
- features: [
- 'searchSource: same XDSSearchSource interface as XDSTypeahead — static, async, or hybrid',
- 'Auto-grouping: items with auxiliaryData.group are auto-grouped in default rendering',
- 'createStaticSource: utility for static lists with optional keyword matching',
- 'Async support: spinner shows in input while search resolves',
- 'Keyboard navigation: arrow keys, Enter to select, Escape to close',
- 'Picker mode: value/onValueChange for persistent selection',
- 'Composable: XDSCommandPaletteInput, XDSCommandPaletteList, XDSCommandPaletteGroup, XDSCommandPaletteItem, XDSCommandPaletteFooter, XDSCommandPaletteEmpty',
- 'renderItem: custom per-item render while preserving auto-grouping',
- ],
- accessibility: [
- 'Dialog uses XDSDialog — native <dialog> with showModal() for correct modal ARIA semantics.',
- 'Input renders as a search input with combobox role, aria-expanded, and aria-controls pointing to the list.',
- 'List renders as role="listbox" with aria-label.',
- 'Items render as role="option" with aria-selected.',
- 'Keyboard navigation uses useCombobox from XDSSelector for consistent arrow key, Home/End, Enter, and Escape behavior.',
- 'Spinner in input uses role="status" to announce loading to screen readers.',
- 'Keyboard: Arrow Up/Down navigate items; Enter selects highlighted item; Escape closes palette; Tab moves focus to footer actions.',
- ],
- notes: [
- 'Uses XDSSearchSource interface — the same as XDSTypeahead. Any source compatible with XDSTypeahead works here.',
- 'createStaticSource supports keyword-based matching in addition to substring matching.',
- 'Auto-grouping reads auxiliaryData.group from each item — no extra config needed.',
- 'Picker mode (value/onValueChange) keeps the palette open and tracks a persistent selection.',
- 'The isBusy signal from searchSource drives the spinner in XDSCommandPaletteInput automatically.',
+ description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by XDSSearchSource for filtering and selection.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
+ { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },
+ { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus — use XDSMenu or XDSSelector for inline selections.' },
+ { guidance: false, description: 'Add too many groups or items — curate results to keep the palette fast and scannable.' },
],
},
};
@@ -321,33 +300,12 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
- description:
- '由 searchSource 驱动的命令面板对话框。提供搜索源,即可获得过滤、键盘导航、分组和选择功能。与 XDSTypeahead 使用相同的 XDSSearchSource 接口。',
- features: [
- 'searchSource:与 XDSTypeahead 相同的 XDSSearchSource 接口——静态、异步或混合',
- '自动分组:auxiliaryData.group 中的项目在默认渲染中自动分组',
- 'createStaticSource:用于静态列表的工具函数,支持关键词匹配',
- '异步支持:搜索解析时在输入框中显示加载指示器',
- '键盘导航:方向键、Enter 选择、Escape 关闭',
- '选择器模式:通过 value/onValueChange 实现持久选择',
- '可组合:XDSCommandPaletteInput、XDSCommandPaletteList、XDSCommandPaletteGroup 等子组件',
- 'renderItem:自定义每个条目的渲染,同时保留自动分组',
- ],
- accessibility: [
- '对话框使用 XDSDialog——原生 <dialog> 配合 showModal() 实现正确的模态 ARIA 语义。',
- '输入框渲染为搜索输入,具有 combobox 角色、aria-expanded 和指向列表的 aria-controls。',
- '列表渲染为 role="listbox",带有 aria-label。',
- '条目渲染为 role="option",带有 aria-selected。',
- '键盘导航使用 XDSSelector 的 useCombobox,确保方向键、Home/End、Enter 和 Escape 行为一致。',
- '输入框中的加载指示器使用 role="status" 向屏幕阅读器播报加载状态。',
- 'Keyboard: 上下方向键:导航条目;Enter:选择高亮条目;Escape:关闭面板;Tab:移动焦点到页脚操作',
- ],
- notes: [
- '使用 XDSSearchSource 接口——与 XDSTypeahead 相同。任何与 XDSTypeahead 兼容的源都可以在此使用。',
- 'createStaticSource 除子字符串匹配外还支持关键词匹配。',
- '自动分组读取每个条目的 auxiliaryData.group——无需额外配置。',
- '选择器模式(value/onValueChange)保持面板打开并跟踪持久选择。',
- '来自 searchSource 的 isBusy 信号自动驱动 XDSCommandPaletteInput 中的加载指示器。',
+ description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by XDSSearchSource for filtering and selection.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
+ { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },
+ { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus — use XDSMenu or XDSSelector for inline selections.' },
+ { guidance: false, description: 'Add too many groups or items — curate results to keep the palette fast and scannable.' },
],
},
components: [
@@ -422,32 +380,15 @@ export const docsZh = {
export const docsDense = {
description:
'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same XDSSearchSource interface as XDSTypeahead',
- features: [
- 'searchSource: same interface as XDSTypeahead — static/async/hybrid',
- 'auto-grouping: auxiliaryData.group auto-groups items',
- 'createStaticSource: util for static lists w/ keyword matching',
- 'async: spinner in input while search resolves',
- 'keyboard: arrow keys, Enter=select, Escape=close',
- 'picker mode: value/onValueChange for persistent selection',
- 'composable: Input, List, Group, Item, Footer, Empty sub-components',
- 'renderItem: custom per-item render w/ auto-grouping preserved',
- ],
- accessibility: [
- 'dialog uses XDSDialog native <dialog> w/ showModal() for modal ARIA semantics',
- 'input: combobox role, aria-expanded, aria-controls to list',
- 'list: role="listbox" w/ aria-label',
- 'items: role="option" w/ aria-selected',
- 'keyboard nav via useCombobox from XDSSelector',
- 'spinner: role="status" announces loading',
- ],
- keyboard: 'Arrow Up/Down=navigate; Enter=select; Escape=close; Tab=footer actions',
- notes: [
- 'XDSSearchSource interface — same as XDSTypeahead; any compatible source works',
- 'createStaticSource: keyword matching + substring matching',
- 'auto-grouping reads auxiliaryData.group — no extra config',
- 'picker mode keeps palette open, tracks persistent selection',
- 'isBusy from searchSource drives spinner automatically',
- ],
+ usage: {
+ description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by XDSSearchSource for filtering and selection.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
+ { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },
+ { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus — use XDSMenu or XDSSelector for inline selections.' },
+ { guidance: false, description: 'Add too many groups or items — curate results to keep the palette fast and scannable.' },
+ ],
+ },
components: [
{
name: 'XDSCommandPalette',
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index 83c6a22bdd..a0bf1de200 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -132,21 +132,12 @@ export const docs = {
],
},
usage: {
- description: 'A date input field combining a text input with a calendar popover for date selection. Use when users need to input a date, such as scheduling events or form submissions.',
- features: [
- 'Text Input — manual date entry with flexible parsing (supports various formats)',
- 'Calendar Popover — click icon or use keyboard to open calendar picker',
- 'Date Constraints — min, max, and custom dateConstraints functions',
- 'Status Indicators — error, warning, and success states with messages',
- 'Accessibility — full keyboard navigation, focus trapping, screen reader support',
- 'Field Integration — built on XDSField for consistent label, description, and validation states',
- ],
- accessibility: [
- 'Keyboard: Tab moves between input and calendar icon button; Enter/Space on icon opens/closes the calendar; Escape closes the calendar popover; Arrow keys navigate between days; Page Up/Down navigate between months',
- ],
- notes: [
- 'The text input accepts multiple date formats: ISO (2026-01-28), US (01/28/2026, 1/28/2026), and written (Jan 28, 2026 / January 28 2026).',
- 'Invalid input reverts to the previous valid value on blur.',
+ description: 'A date input field that combines a text input with a calendar popover for selecting dates. Use when users need to enter a specific date, such as scheduling events, setting deadlines, or completing form submissions.',
+ bestPractices: [
+ { guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
+ { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
+ { 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.' },
],
},
};
@@ -155,21 +146,12 @@ export const docs = {
export const docsZh = {
name: 'DateInput',
usage: {
- description: 'XDSDateInput 日期输入组件,将文本输入与日历弹出层结合用于日期选择。',
- features: [
- '文本输入——手动输入日期,支持灵活的格式解析(支持多种格式)',
- '日历弹出层——点击图标或使用键盘打开日历选择器',
- '日期约束——min、max 和自定义 dateConstraints 函数',
- '状态指示器——错误、警告和成功状态及消息',
- '无障碍——完整的键盘导航、焦点捕获、屏幕阅读器支持',
- '字段集成——基于 XDSField 构建,提供一致的标签、描述和验证状态',
- ],
- accessibility: [
- 'Keyboard: Tab 在输入框和日历图标按钮间移动;Enter/Space 点击图标打开/关闭日历;Escape 关闭日历弹出层;方向键在日期间导航;Page Up/Down 在月份间导航。',
- ],
- notes: [
- '文本输入接受多种日期格式:ISO(2026-01-28)、美式(01/28/2026、1/28/2026)和书面格式(Jan 28, 2026 / January 28 2026)。',
- '无效输入在失焦时恢复为上一个有效值。',
+ description: 'A date input field that combines a text input with a calendar popover for selecting dates. Use when users need to enter a specific date, such as scheduling events, setting deadlines, or completing form submissions.',
+ bestPractices: [
+ { guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
+ { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
+ { 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.' },
],
},
props: [
@@ -217,19 +199,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'text input w/ calendar popover for date selection',
- features: [
- 'manual date entry w/ flexible parsing (various formats)',
- 'calendar popover via icon click or keyboard',
- 'date constraints: min, max, custom dateConstraints fns',
- 'error, warning, success status indicators w/ messages',
- 'full keyboard nav, focus trapping, screen reader support',
- 'built on XDSField for consistent label, description, validation',
- ],
- keyboard: 'Tab=move between input+calendar icon; Enter/Space on icon=open/close calendar; Escape=close; Arrow keys=navigate days; PageUp/Down=navigate months',
- notes: [
- 'accepts multiple date formats: ISO (2026-01-28), US (01/28/2026, 1/28/2026), written (Jan 28, 2026 / January 28 2026)',
- 'invalid input reverts to previous valid value on blur',
- ],
+ usage: {
+ description: 'A date input field that combines a text input with a calendar popover for selecting dates. Use when users need to enter a specific date, such as scheduling events, setting deadlines, or completing form submissions.',
+ bestPractices: [
+ { guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },
+ { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },
+ { 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.' },
+ ],
+ },
propDescriptions: {
label: 'label text',
isLabelHidden: 'visually hide label',
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 39ac3dec25..98dfe20a91 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -119,28 +119,12 @@ export const docs = {
},
],
usage: {
- description: "A modal dialog that communicates important information and pauses the user's workflow. Built on the native <dialog> element with automatic focus trapping, backdrop, and purpose-based dismissal control. Use for multi-step workflows, confirmations before destructive actions, or information requiring acknowledgement.",
- features: [
- "Native <dialog>: Uses the browser's built-in modal behavior via showModal()",
- 'Automatic focus trap: Focus is trapped within the dialog when open (browser-native)',
- 'Backdrop: Native ::backdrop pseudo-element with blur effect',
- 'Variants: standard (configurable dimensions) and fullscreen (full viewport)',
- 'Purpose-based dismissal: required, form, and info control Escape key and backdrop-click behavior',
- 'Custom positioning: Static position support via the position prop',
- 'Accessible: Proper ARIA attributes and keyboard navigation',
- ],
- accessibility: [
- 'Uses the native <dialog> element with showModal() for correct ARIA modal semantics.',
- 'Focus is automatically trapped by the browser when using showModal().',
- 'XDSDialogHeader title receives focus when the dialog opens.',
- 'Keyboard: Escape closes the dialog (unless purpose="required"); focus is trapped inside the dialog while open.',
- ],
- notes: [
- 'Height is unset (grows with content) and constrained by the maxHeight prop.',
- 'When variant="fullscreen", the width, maxHeight, and position props are ignored.',
- 'For form purpose, backdrop click is only allowed before the user has interacted with the dialog.',
- 'Purpose=required disables both Escape key and backdrop click; purpose=form disables backdrop click after interaction; purpose=info (default) allows both.',
- 'XDSDialog is designed to be used with XDSLayout as its child.',
+ description: 'A modal dialog that interrupts the user workflow to communicate important information or request a decision. Use for confirmations before destructive actions, multi-step workflows, or content that requires acknowledgement before proceeding.',
+ bestPractices: [
+ { guidance: true, description: 'Choose the right purpose (required, form, info) to match the importance of the content.' },
+ { guidance: true, description: 'Include a clear title in the header so users immediately understand the dialog context.' },
+ { 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.' },
],
anatomy: [
{name: 'Body', required: true, description: 'The main content area of the dialog.'},
@@ -272,29 +256,19 @@ export const docsZh = {
},
],
usage: {
- description:
- '使用原生 <dialog> 元素的模态对话框,支持自动焦点捕获、遮罩层和基于用途的关闭控制。',
- features: [
- '原生 <dialog>:通过 showModal() 使用浏览器内置的模态行为',
- '自动焦点捕获:对话框打开时焦点被限制在内部(浏览器原生支持)',
- '遮罩层:原生 ::backdrop 伪元素,带模糊效果',
- '变体:standard(可配置尺寸)和 fullscreen(全视口)',
- '基于用途的关闭控制:required、form 和 info 控制 Escape 键和遮罩层点击行为',
- '自定义定位:通过 position 属性支持静态定位',
- '无障碍:正确的 ARIA 属性和键盘导航',
- ],
- accessibility: [
- '使用原生 <dialog> 元素配合 showModal() 以获得正确的 ARIA 模态语义。',
- '使用 showModal() 时,浏览器会自动捕获焦点。',
- '对话框打开时,XDSDialogHeader 的标题会获得焦点。',
- 'Keyboard: Escape 关闭对话框(purpose="required" 时除外);对话框打开时焦点被限制在内部。',
+ description: 'A modal dialog that interrupts the user workflow to communicate important information or request a decision. Use for confirmations before destructive actions, multi-step workflows, or content that requires acknowledgement before proceeding.',
+ bestPractices: [
+ { guidance: true, description: 'Choose the right purpose (required, form, info) to match the importance of the content.' },
+ { guidance: true, description: 'Include a clear title in the header so users immediately understand the dialog context.' },
+ { 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.' },
],
- notes: [
- '高度未设置(随内容增长),受 maxHeight 属性约束。',
- '当 variant="fullscreen" 时,width、maxHeight 和 position 属性会被忽略。',
- '对于 form 用途,仅在用户与对话框交互之前允许点击遮罩层关闭。',
- 'purpose=required 禁用 Escape 键和遮罩层点击;purpose=form 在交互后禁用遮罩层点击;purpose=info(默认)两者都允许。',
- 'XDSDialog 设计为与 XDSLayout 配合使用作为其子组件。',
+ anatomy: [
+ {name: 'Body', required: true, description: 'The main content area of the dialog.'},
+ {name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},
+ {name: 'Footer', required: true, description: 'Contains action buttons, links, and page count.'},
+ {name: 'Left Panel', required: false, description: 'Used for navigation or completion stages.'},
+ {name: 'Right Panel', required: false, description: 'Used for supplementary information.'},
],
},
};
@@ -302,28 +276,22 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'modal dialog using native <dialog> w/ auto focus trapping, backdrop, purpose-based dismissal',
- features: [
- 'native <dialog>: browser built-in modal via showModal()',
- 'auto focus trap inside dialog (browser-native)',
- 'native ::backdrop pseudo-element w/ blur',
- 'variants: standard (configurable dims) + fullscreen (full viewport)',
- 'purpose-based dismissal: required, form, info control Escape+backdrop-click',
- 'static position via position prop',
- 'proper ARIA attrs + keyboard nav',
- ],
- keyboard: 'Escape closes dialog (unless purpose="required"); focus trapped inside while open',
- accessibility: [
- 'native <dialog> w/ showModal() for correct ARIA modal semantics',
- 'focus auto-trapped by browser via showModal()',
- 'XDSDialogHeader title receives focus on open',
- ],
- notes: [
- 'height unset (grows w/ content), constrained by maxHeight',
- 'variant="fullscreen" ignores width, maxHeight, position',
- 'form purpose: backdrop click only allowed before user interaction',
- 'required=no Escape+no backdrop click; form=no backdrop click after interaction; info=both allowed',
- 'designed for use w/ XDSLayout as child',
- ],
+ usage: {
+ description: 'A modal dialog that interrupts the user workflow to communicate important information or request a decision. Use for confirmations before destructive actions, multi-step workflows, or content that requires acknowledgement before proceeding.',
+ bestPractices: [
+ { guidance: true, description: 'Choose the right purpose (required, form, info) to match the importance of the content.' },
+ { guidance: true, description: 'Include a clear title in the header so users immediately understand the dialog context.' },
+ { 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.' },
+ ],
+ anatomy: [
+ {name: 'Body', required: true, description: 'The main content area of the dialog.'},
+ {name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},
+ {name: 'Footer', required: true, description: 'Contains action buttons, links, and page count.'},
+ {name: 'Left Panel', required: false, description: 'Used for navigation or completion stages.'},
+ {name: 'Right Panel', required: false, description: 'Used for supplementary information.'},
+ ],
+ },
components: [
{
name: 'XDSDialog',
diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjs
index 514f052b2b..6980541b46 100644
--- a/packages/core/src/Divider/Divider.doc.mjs
+++ b/packages/core/src/Divider/Divider.doc.mjs
@@ -43,13 +43,11 @@ export const docs = {
],
},
usage: {
- description: 'A visual separator for dividing content sections. Use subtle dividers to demote sections, emphasized dividers for interactive element boundaries, and strong dividers for high-contrast separation.',
- features: [
- 'Supports horizontal and vertical orientations',
- 'Optional label centered on the divider line',
- 'Subtle and strong visual weight variants',
- 'Full-bleed mode extends the divider to container edges via negative margins',
- 'Themeable via className — target .xds-divider with variant and orientation classes',
+ description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
+ bestPractices: [
+ { guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
+ { guidance: true, description: 'Add a label to the divider when sections need a visible category heading.' },
+ { guidance: false, description: 'Overuse dividers — rely on spacing and layout to separate content when possible.' },
],
},
};
@@ -94,13 +92,11 @@ export const docsZh = {
],
},
usage: {
- description: '带有可选标签的视觉分隔线,使用 XDS 设计令牌。',
- features: [
- '支持水平和垂直方向',
- '可选标签居中显示在分隔线上',
- '柔和和加强两种视觉粗细变体',
- '全出血模式通过负边距将分隔线延伸至容器边缘',
- '可通过 className 进行主题定制 — 使用变体和方向类定位 .xds-divider',
+ description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
+ bestPractices: [
+ { guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
+ { guidance: true, description: 'Add a label to the divider when sections need a visible category heading.' },
+ { guidance: false, description: 'Overuse dividers — rely on spacing and layout to separate content when possible.' },
],
},
};
@@ -108,13 +104,14 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'visual separator w/ optional label, using XDS design tokens',
- features: [
- 'horizontal+vertical orientations',
- 'optional centered label on divider line',
- 'subtle+strong visual weight variants',
- 'full-bleed mode extends to container edges via negative margins',
- 'themeable via className; target .xds-divider w/ variant+orientation classes',
- ],
+ usage: {
+ description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
+ bestPractices: [
+ { guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
+ { guidance: true, description: 'Add a label to the divider when sections need a visible category heading.' },
+ { guidance: false, description: 'Overuse dividers — rely on spacing and layout to separate content when possible.' },
+ ],
+ },
propDescriptions: {
orientation: 'divider orientation',
label: 'optional centered label on divider',
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index b0ed782a83..3ef8af5b08 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -171,28 +171,12 @@ export const docs = {
},
],
usage: {
- description: 'A dropdown menu for displaying actionable items in a popup. Use to present action options as a next step in a process or as sub-navigation to guide users to a destination.',
- features: [
- 'Button customization: Customize the trigger button via the `button` prop (supports all XDSButton props)',
- 'Data-driven items: Pass items via the `items` prop with support for sections and dividers',
- 'Controlled/Uncontrolled: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes',
- 'Custom menu width: Override default width (matches button) via `menuWidth` prop',
- 'Sections: Group related items with optional headers using `XDSDropdownMenuSection`',
- 'Keyboard navigation: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)',
- 'Accessibility: Proper ARIA roles (menu, menuitem) and attributes',
- 'Custom rendering: Optional `children` render function with `XDSDropdownMenuItem` helper',
- ],
- accessibility: [
- 'Uses proper ARIA roles: `menu` on the popup container, `menuitem` on each item',
- 'Focus returns to the trigger button when the menu closes',
- 'Keyboard navigation automatically skips disabled items',
- 'Keyboard: Arrow keys navigate items, Home/End jump to first/last, Enter/Space select, Escape closes the menu',
- ],
- notes: [
- 'Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',
- 'Uses `XDSButton` internally — chevron is passed via `endContent` and auto-hidden when `isIconOnly` is true',
- 'Items are tracked via the `items` prop to enable keyboard navigation',
- 'Light dismiss is enabled by default (clicking outside closes menu)',
+ description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
+ bestPractices: [
+ { guidance: true, description: 'Keep menu items concise and action-oriented so users can scan options quickly.' },
+ { guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },
+ { guidance: false, description: 'Use a DropdownMenu for navigation — use a navigation component instead.' },
+ { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
],
},
};
@@ -369,29 +353,12 @@ export const docsZh = {
},
],
usage: {
- description:
- '用于在弹出菜单中显示可操作项的下拉菜单组件。',
- features: [
- '按钮自定义:通过 `button` 属性自定义触发按钮(支持所有 XDSButton 属性)',
- '数据驱动项:通过 `items` 属性传递菜单项,支持分组和分隔线',
- '受控/非受控:同时支持受控(`isMenuOpen`/`onOpenChange`)和非受控模式',
- '自定义菜单宽度:通过 `menuWidth` 属性覆盖默认宽度(默认与按钮同宽)',
- '分组:使用 `XDSDropdownMenuSection` 将相关项分组并显示可选标题',
- '键盘导航:完整的键盘支持(方向键、Home、End、Enter、Space、Escape)',
- '无障碍:正确的 ARIA 角色(menu、menuitem)和属性',
- '自定义渲染:可选的 `children` 渲染函数,配合 `XDSDropdownMenuItem` 辅助组件',
- ],
- accessibility: [
- '使用正确的 ARIA 角色:弹出容器上使用 `menu`,每个菜单项使用 `menuitem`',
- '菜单关闭时焦点返回到触发按钮',
- '键盘导航自动跳过禁用的菜单项',
- 'Keyboard: 方向键导航菜单项,Home/End 跳转到首项/末项,Enter/Space 选择,Escape 关闭菜单',
- ],
- notes: [
- '使用 `useXDSLayer` 配合 `mode: "context"` 进行 CSS 锚点定位',
- '内部使用 `XDSButton`——chevron 通过 `endContent` 传递,图标按钮自动隐藏',
- '通过 `items` 属性跟踪菜单项以启用键盘导航',
- '默认启用轻量关闭(点击外部关闭菜单)',
+ description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
+ bestPractices: [
+ { guidance: true, description: 'Keep menu items concise and action-oriented so users can scan options quickly.' },
+ { guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },
+ { guidance: false, description: 'Use a DropdownMenu for navigation — use a navigation component instead.' },
+ { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
],
},
};
@@ -399,28 +366,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'dropdown menu for actionable items in popup',
- features: [
- 'customize trigger button via button prop (all XDSButton props)',
- 'data-driven items via items prop w/ sections+dividers',
- 'controlled (isMenuOpen/onOpenChange) + uncontrolled modes',
- 'custom menu width via menuWidth prop (default matches button)',
- 'group related items w/ optional headers via XDSDropdownMenuSection',
- 'full keyboard: Arrow keys, Home, End, Enter, Space, Escape',
- 'proper ARIA roles (menu, menuitem) + attrs',
- 'optional children render fn w/ XDSDropdownMenuItem helper',
- ],
- keyboard: 'Arrow keys=navigate items; Home/End=first/last; Enter/Space=select; Escape=close',
- accessibility: [
- 'ARIA roles: menu on popup, menuitem on each item',
- 'focus returns to trigger button on menu close',
- 'keyboard nav skips disabled items',
- ],
- notes: [
- 'uses useXDSLayer w/ mode:"context" for CSS anchor positioning',
- 'uses XDSButton internally — chevron via endContent, auto-hidden for icon-only',
- 'items tracked via items prop for keyboard nav',
- 'light dismiss enabled by default (click outside closes)',
- ],
+ usage: {
+ description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
+ bestPractices: [
+ { guidance: true, description: 'Keep menu items concise and action-oriented so users can scan options quickly.' },
+ { guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },
+ { guidance: false, description: 'Use a DropdownMenu for navigation — use a navigation component instead.' },
+ { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
+ ],
+ },
components: [
{
name: 'XDSDropdownMenu',
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index 40efcddafc..c6d66cdd55 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -56,20 +56,12 @@ export const docs = {
],
},
usage: {
- description: 'An empty state placeholder that provides guidance and context when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Be clear with messaging and offer a next step so users know how to proceed.',
- features: [
- 'Uses role="status" so screen readers announce the empty state automatically',
- 'Icon slot renders as decorative (aria-hidden="true") — no extra labeling needed',
- 'Title renders as a heading element (h1-h6, default h3) for correct document outline',
- 'Actions are laid out horizontally by default and stack vertically in compact mode',
- 'Compact variant reduces spacing for constrained content areas',
- 'Accepts xstyle, className, and style props for custom container adjustments',
- 'Forwarded ref lands on the root <div> container',
- ],
- accessibility: [
- 'Container uses role="status" to announce the empty state content to screen readers.',
- 'Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',
- 'Title renders as a heading element (h1-h6 via headingLevel prop, default h3), keeping it in the document heading outline.',
+ description: 'An empty state placeholder that provides guidance when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Always include a clear message and a call to action so users know how to proceed.',
+ bestPractices: [
+ { guidance: true, description: 'Include a clear title and a 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: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },
+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use an alert instead.' },
],
anatomy: [
{name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
@@ -136,21 +128,18 @@ export const docsZh = {
],
},
usage: {
- description:
- '用于无数据内容区域的空状态占位组件。显示图标或插图、标题、可选描述和操作按钮。',
- features: [
- '使用 role="status",屏幕阅读器会自动播报空状态内容',
- '图标插槽渲染为装饰性元素(aria-hidden="true"),无需额外标注',
- '标题渲染为标题元素(h1-h6,默认 h3),保持正确的文档大纲',
- '操作按钮默认水平排列,紧凑模式下垂直堆叠',
- '紧凑变体减少间距,适用于空间受限的内容区域',
- '接受 xstyle、className 和 style 属性用于自定义容器调整',
- '转发的 ref 指向根 <div> 容器',
+ description: 'An empty state placeholder that provides guidance when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Always include a clear message and a call to action so users know how to proceed.',
+ bestPractices: [
+ { guidance: true, description: 'Include a clear title and a 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: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },
+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use an alert instead.' },
],
- accessibility: [
- '容器使用 role="status" 向屏幕阅读器播报空状态内容。',
- '图标包装器具有 aria-hidden="true",使装饰性图标被辅助技术忽略。',
- '标题渲染为标题元素(通过 headingLevel 属性设置 h1-h6,默认 h3),保持在文档标题大纲中。',
+ anatomy: [
+ {name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
+ {name: 'Title', required: true, description: 'Primary message explaining the empty state.'},
+ {name: 'Subtitle', required: false, description: 'Additional context or explanation.'},
+ {name: 'Call to action', required: false, description: 'Buttons guiding the user to a next step.'},
],
},
};
@@ -159,20 +148,21 @@ export const docsZh = {
export const docsDense = {
description:
'Empty state placeholder for content areas w/ no data. Displays icon/illustration, title, optional description + action buttons.',
- features: [
- 'role="status" so screen readers auto-announce empty state',
- 'Icon slot renders decorative (aria-hidden="true"); no extra labeling needed',
- 'Title renders as heading (h1-h6, default h3) for correct document outline',
- 'Actions horizontal by default; stack vertically in compact mode',
- 'Compact variant reduces spacing for constrained areas',
- 'Accepts xstyle, className, style for container adjustments',
- 'Forwarded ref on root <div> container',
- ],
- accessibility: [
- 'Container uses role="status" to announce empty state to screen readers.',
- 'Icon wrapper has aria-hidden="true"; decorative icons ignored by assistive tech.',
- 'Title renders as heading (h1-h6 via headingLevel, default h3) in document outline.',
- ],
+ usage: {
+ description: 'An empty state placeholder that provides guidance when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Always include a clear message and a call to action so users know how to proceed.',
+ bestPractices: [
+ { guidance: true, description: 'Include a clear title and a 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: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },
+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use an alert instead.' },
+ ],
+ anatomy: [
+ {name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
+ {name: 'Title', required: true, description: 'Primary message explaining the empty state.'},
+ {name: 'Subtitle', required: false, description: 'Additional context or explanation.'},
+ {name: 'Call to action', required: false, description: 'Buttons guiding the user to a next step.'},
+ ],
+ },
propDescriptions: {
title: 'Primary msg rendered as heading (h1-h6) inside empty state.',
headingLevel: 'Controls HTML heading tag (h1-h6) for document outline.',
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 354167af91..925af102dd 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -213,27 +213,12 @@ export const docs = {
},
],
usage: {
- description: 'A form field wrapper that provides label, description, and optional/required indicators around an input. Use to wrap input components in forms for consistent labels, descriptions, and validation states.',
- features: [
- 'Label Support — required label for accessibility (can be visually hidden)',
- 'Description — optional description text displayed between the label and input',
- 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',
- 'Label Tooltip — optional info icon with tooltip at end of label',
- 'Disabled State — propagates disabled styling to label',
- 'Status Messages — attached/detached validation feedback with role="status" and aria-live="polite"',
- 'Accessible — label properly associated with input via htmlFor/id',
- 'Styled with StyleX — uses XDS design tokens for consistent styling',
- ],
- notes: [
- 'Parent components are responsible for generating IDs (using the useId hook).',
- 'Label is always rendered for accessibility; use isLabelHidden to hide visually.',
- 'Hidden label uses a CSS technique that remains accessible to screen readers.',
- 'Description is rendered when provided; if descriptionID is also provided, the description element gets that ID for aria-describedby association.',
- 'isOptional and isRequired are mutually exclusive; setting both will show "Optional" (dev warning emitted).',
- 'Optional/Required text appears on the same line as the label.',
- 'Status messages use role="status" and aria-live="polite" for screen reader announcements.',
- 'Use statusVariant="attached" (default) for bordered inputs; "detached" for checkboxes, switches, sliders.',
- 'isDisabled propagates disabled styling to the label (color + cursor).',
+ description: 'A form field wrapper that provides consistent labels, descriptions, and validation states around input controls. Use to wrap any input component in a form to ensure accessible labeling, optional/required indicators, and inline status feedback.',
+ bestPractices: [
+ { 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: 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.' },
],
},
};
@@ -452,28 +437,12 @@ export const docsZh = {
},
],
usage: {
- description:
- '表单字段包装组件,提供标签、描述以及可选/必填指示器。',
- features: [
- '标签支持 - 必需的标签用于无障碍访问(可视觉隐藏)',
- '描述 - 可选的描述文本,显示在标签和输入框之间',
- '可选/必填指示器 - 显示"Optional"或"Required"文本,带圆点分隔符',
- '标签工具提示 - 可选的信息图标,在标签末尾显示工具提示',
- '禁用状态 - 将禁用样式传递给标签',
- '状态消息 - attached/detached 验证反馈,带 role="status" 和 aria-live="polite"',
- '无障碍 - 通过 htmlFor/id 将标签与输入框正确关联',
- '使用 StyleX 样式 - 使用 XDS 设计令牌实现一致的样式',
- ],
- notes: [
- '父组件负责生成 ID(使用 useId hook)。',
- '标签始终渲染以确保无障碍访问;使用 isLabelHidden 进行视觉隐藏。',
- '隐藏标签使用 CSS 技术,屏幕阅读器仍可访问。',
- '提供 description 时会渲染描述文本;如果同时提供 descriptionID,描述元素会获得该 ID 用于 aria-describedby 关联。',
- 'isOptional 和 isRequired 互斥;同时设置两者将显示"Optional"(开发模式下发出警告)。',
- '可选/必填文本与标签显示在同一行。',
- '状态消息使用 role="status" 和 aria-live="polite" 进行屏幕阅读器播报。',
- '使用 statusVariant="attached"(默认)用于带边框的输入框;"detached" 用于复选框、开关、滑块。',
- 'isDisabled 将禁用样式传递给标签(颜色 + 光标)。',
+ description: 'A form field wrapper that provides consistent labels, descriptions, and validation states around input controls. Use to wrap any input component in a form to ensure accessible labeling, optional/required indicators, and inline status feedback.',
+ bestPractices: [
+ { 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: 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.' },
],
},
};
@@ -482,27 +451,15 @@ export const docsZh = {
export const docsDense = {
description:
'Form field wrapper providing label, description + optional/required indicators.',
- features: [
- 'Label support; required for a11y (can be visually hidden)',
- 'Optional description text between label + input',
- 'Optional/Required indicators w/ bullet separator',
- 'Label tooltip; optional info icon w/ tooltip at end of label',
- 'Disabled state; propagates disabled styling to label',
- 'Status messages; attached/detached validation feedback w/ role="status" + aria-live="polite"',
- 'Label properly associated w/ input via htmlFor/id',
- 'Styled w/ StyleX; uses XDS design tokens for consistent styling',
- ],
- notes: [
- 'Parent components generate IDs (useId hook).',
- 'Label always rendered for a11y; use isLabelHidden to hide visually.',
- 'Hidden label uses CSS technique accessible to screen readers.',
- 'Description rendered when provided; descriptionID sets element ID for aria-describedby.',
- 'isOptional + isRequired mutually exclusive; both set shows "Optional" (dev warning).',
- 'Optional/Required text on same line as label.',
- 'Status messages use role="status" + aria-live="polite" for screen reader announcements.',
- 'statusVariant="attached" (default) for bordered inputs; "detached" for checkboxes/switches/sliders.',
- 'isDisabled propagates disabled styling to label (color + cursor).',
- ],
+ usage: {
+ description: 'A form field wrapper that provides consistent labels, descriptions, and validation states around input controls. Use to wrap any input component in a form to ensure accessible labeling, optional/required indicators, and inline status feedback.',
+ bestPractices: [
+ { 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: 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.' },
+ ],
+ },
components: [
{
name: 'XDSField',
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index 6852748a20..a5c9cb0d2e 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -30,18 +30,11 @@ export const docs = {
],
},
usage: {
- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Wraps input components to collect structured user input with validation and confirmation. Best suited for sign-in flows, creating or editing objects, and settings — prefer single column layouts with top-aligned labels for step-by-step flows.',
- features: [
- "Three layout modes: 'vertical' (default), 'horizontal', and 'horizontal-labels'",
- 'Direction context via XDSFormLayoutContext — children can read the current layout direction',
- 'Responsive: horizontal-labels collapses to vertical on narrow viewports (<=480px)',
- 'Nestable: inner FormLayout overrides context for its children',
- 'Purely spatial: does not manage form state or render <form> — form submission is separate',
- ],
- notes: [
- 'Renders a <div>, not a <form>. Use a separate <form> element and connect submit buttons via the HTML form attribute.',
- 'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',
- 'Also accepts standard HTML div attributes (id, role, aria-*, etc.) via rest props.',
+ description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',
+ bestPractices: [
+ { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },
+ { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },
+ { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },
],
anatomy: [
{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
@@ -81,19 +74,16 @@ export const docsZh = {
],
},
usage: {
- description:
- '用于以一致的间距和方向排列表单字段的空间布局容器。',
- features: [
- '三种布局模式:\'vertical\'(默认)、\'horizontal\' 和 \'horizontal-labels\'',
- '通过 XDSFormLayoutContext 提供方向上下文 - 子组件可以读取当前布局方向',
- '响应式:horizontal-labels 在窄视口(<=480px)时折叠为垂直布局',
- '可嵌套:内部 FormLayout 会为其子组件覆盖上下文',
- '纯空间布局:不管理表单状态或渲染 <form> - 表单提交是独立的',
+ description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',
+ bestPractices: [
+ { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },
+ { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },
+ { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },
],
- notes: [
- '渲染 <div> 而非 <form>。使用单独的 <form> 元素,并通过 HTML form 属性连接提交按钮。',
- 'XDSFormLayoutContext 向子组件提供 { direction }。从 @xds/core/FormLayout 导入以在自定义组件中读取布局方向。',
- '还通过 rest props 接受标准 HTML div 属性(id、role、aria-* 等)。',
+ anatomy: [
+ {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
+ {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
+ {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
],
},
};
@@ -102,18 +92,19 @@ export const docsZh = {
export const docsDense = {
description:
'Spatial layout container for arranging form fields w/ consistent spacing + direction.',
- features: [
- "Three layout modes: 'vertical' (default), 'horizontal', 'horizontal-labels'",
- 'Direction context via XDSFormLayoutContext; children read current layout direction',
- 'Responsive: horizontal-labels collapses to vertical on narrow viewports (<=480px)',
- 'Nestable: inner FormLayout overrides context for children',
- 'Purely spatial: no form state management or <form> rendering',
- ],
- notes: [
- 'Renders <div> not <form>. Use separate <form> + HTML form attribute for submit buttons.',
- 'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout.',
- 'Accepts standard HTML div attributes (id, role, aria-*) via rest props.',
- ],
+ usage: {
+ description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',
+ bestPractices: [
+ { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },
+ { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },
+ { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },
+ ],
+ anatomy: [
+ {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
+ {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
+ {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+ ],
+ },
propDescriptions: {
direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
children: 'Form fields to arrange. Accepts XDS inputs + XDSField-wrapped custom controls.',
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index 391ed80686..2ee6865255 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -4,18 +4,11 @@ export const docs = {
name: 'Grid',
keywords: ["grid","columns","responsive","auto-fit","masonry","tiles","row","col","simplegrid"],
usage: {
- description:
- 'CSS Grid-based layout with responsive auto-fit support. Use for any grid layout instead of manual CSS grid — it handles gap tokens and works with any column count.',
- features: [
- 'Fixed-column grids via the `columns` prop',
- 'Responsive auto-fit columns via `minChildWidth` — items wrap based on available space',
- 'Combine `minChildWidth` and `columns` to cap the maximum number of columns',
- 'Gap tokens via `SpacingScale` values for `gap`, `rowGap`, and `columnGap`',
- 'Vertical and horizontal item alignment via `align` and `justify`',
- 'XDSGridSpan lets individual items span multiple columns or rows',
- ],
- notes: [
- 'Use XDSGrid for any grid layout instead of manual CSS grid (`display: "grid"`, `gridTemplateColumns`). It handles gap tokens and works with any column count.',
+ description: 'A CSS Grid-based layout component with responsive auto-fit support. Use Grid for any multi-column layout instead of manual CSS grid — it handles gap tokens and responsive column behavior automatically.',
+ bestPractices: [
+ { guidance: true, description: 'Use minChildWidth for responsive layouts that adapt to container size.' },
+ { guidance: true, description: 'Combine minChildWidth and columns to set a maximum column count while still allowing responsive wrapping.' },
+ { guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },
],
},
theming: {
@@ -211,18 +204,11 @@ export const docsZh = {
},
],
usage: {
- description: '基于 CSS Grid 的布局组件,支持响应式自动适配。',
- features: [
- '通过 `columns` 属性实现固定列网格',
- '通过 `minChildWidth` 实现响应式自动适配列 - 项目根据可用空间自动换行',
- '组合 `minChildWidth` 和 `columns` 来限制最大列数',
- '通过 `SpacingScale` 值为 `gap`、`rowGap` 和 `columnGap` 设置间距令牌',
- '通过 `align` 和 `justify` 实现垂直和水平项对齐',
- 'XDSGridSpan 允许单个项跨越多列或多行',
- '主题支持 - 通过 `grid` 组件键覆盖根样式',
- ],
- notes: [
- '对于任何网格布局,请使用 XDSGrid 代替手动 CSS grid(`display: "grid"`、`gridTemplateColumns`)。它处理间距令牌并支持任意列数。',
+ description: 'A CSS Grid-based layout component with responsive auto-fit support. Use Grid for any multi-column layout instead of manual CSS grid — it handles gap tokens and responsive column behavior automatically.',
+ bestPractices: [
+ { guidance: true, description: 'Use minChildWidth for responsive layouts that adapt to container size.' },
+ { guidance: true, description: 'Combine minChildWidth and columns to set a maximum column count while still allowing responsive wrapping.' },
+ { guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },
],
},
};
@@ -230,18 +216,14 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'CSS Grid-based layout w/ responsive auto-fit support.',
- features: [
- 'Fixed-column grids via columns prop',
- 'Responsive auto-fit columns via minChildWidth; items wrap based on available space',
- 'Combine minChildWidth + columns to cap max columns',
- 'Gap tokens via SpacingScale for gap, rowGap, columnGap',
- 'Vertical + horizontal item alignment via align + justify',
- 'XDSGridSpan lets items span multiple columns/rows',
- 'Theming support; override root styles via grid component key',
- ],
- notes: [
- 'Use XDSGrid for any grid layout instead of manual CSS grid. Handles gap tokens w/ any column count.',
- ],
+ usage: {
+ description: 'A CSS Grid-based layout component with responsive auto-fit support. Use Grid for any multi-column layout instead of manual CSS grid — it handles gap tokens and responsive column behavior automatically.',
+ bestPractices: [
+ { guidance: true, description: 'Use minChildWidth for responsive layouts that adapt to container size.' },
+ { guidance: true, description: 'Combine minChildWidth and columns to set a maximum column count while still allowing responsive wrapping.' },
+ { guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },
+ ],
+ },
components: [
{
name: 'XDSGrid',
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index a2fc5930fd..8a55f454c9 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -132,26 +132,12 @@ export const docs = {
},
],
usage: {
- description:
- 'A hover/focus triggered overlay for displaying rich, interactive content anchored to a trigger element. Use hover cards for non-critical supplementary information, progressive disclosure, or non-interruptive education \u2014 for plain text hints use Tooltip, for menus use Popover.',
- features: [
- 'CSS Anchor Positioning for automatic placement relative to trigger elements',
- 'Popover API for top-layer rendering \u2014 no React portals needed',
- 'Hover triggers with configurable show and hide delays',
- 'Focus triggers with auto-detection for focusable elements',
- 'Stay-open behavior when mouse/focus moves into the hover card',
- 'Hover indication (dashed underline) for text-only triggers',
- ],
- accessibility: [
- 'Links the hover card content to the trigger via aria-describedby.',
- 'When composing multiple aria-describedby sources, merge them with a utility.',
- 'Keyboard: Escape dismisses the hover card and returns focus to the trigger; focus events trigger show/hide based on the focusTrigger option.',
- ],
- notes: [
- 'useXDSHoverCard returns a describedBy id \u2014 pass it as aria-describedby on the trigger for screen reader support.',
- 'When composing multiple aria-describedby sources, merge them with a utility: ids.filter(Boolean).join(" ") || undefined.',
- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',
- 'display:contents wrapper preserves children refs.',
+ description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',
+ bestPractices: [
+ { 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: 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.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
@@ -294,27 +280,17 @@ export const docsZh = {
},
],
usage: {
- description:
- '悬停/聚焦触发的浮层,用于显示锚定到触发元素的富交互内容。',
- features: [
- 'CSS 锚点定位:相对于触发元素自动放置',
- 'Popover API 实现顶层渲染,无需 React 传送门',
- '悬停触发:可配置显示和隐藏延迟',
- '聚焦触发:自动检测可聚焦元素',
- '鼠标/焦点移入悬浮卡片时保持打开',
- 'display:contents 包装器保留子元素 ref',
- '悬停指示(虚线下划线)用于纯文本触发器',
- ],
- accessibility: [
- '通过 aria-describedby 将悬浮卡片内容关联到触发器。',
- '当组合多个 aria-describedby 来源时,使用工具函数合并。',
- '按 Escape 键关闭悬浮卡片并将焦点返回到触发器。',
- 'Keyboard: Escape 关闭悬浮卡片。焦点触发器根据 focusTrigger 选项控制显示/隐藏。',
+ description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',
+ bestPractices: [
+ { 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: 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.' },
],
- notes: [
- 'useXDSHoverCard 返回一个 describedBy id,将其作为 aria-describedby 传递给触发器以支持屏幕阅读器。',
- '当组合多个 aria-describedby 来源时,使用工具函数合并:ids.filter(Boolean).join(" ") || undefined。',
- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',
+ anatomy: [
+ {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
+ {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},
+ {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},
],
},
};
@@ -323,26 +299,20 @@ export const docsZh = {
export const docsDense = {
description:
'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',
- features: [
- 'CSS Anchor Positioning for auto-placement relative to triggers',
- 'Popover API for top-layer rendering; no React portals needed',
- 'Hover triggers w/ configurable show + hide delays',
- 'Focus triggers w/ auto-detection for focusable elements',
- 'Stay-open when mouse/focus moves into hover card',
- 'display:contents wrapper preserves children refs',
- 'Hover indication (dashed underline) for text-only triggers',
- ],
- notes: [
- 'useXDSHoverCard returns describedBy id; pass as aria-describedby on trigger for screen reader support.',
- 'Merge multiple aria-describedby sources w/ ids.filter(Boolean).join(" ") || undefined.',
- 'LayerPlacement: above | below | start | end. LayerAlignment: start | center | end.',
- ],
- accessibility: [
- 'Links hover card content to trigger via aria-describedby.',
- 'Merge multiple aria-describedby sources w/ utility.',
- 'Escape dismisses hover card + returns focus to trigger.',
- ],
- keyboard: 'Escape closes hover card. Focus triggers show/hide based on focusTrigger option.',
+ usage: {
+ description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',
+ bestPractices: [
+ { 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: 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.' },
+ ],
+ anatomy: [
+ {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
+ {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},
+ {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},
+ ],
+ },
components: [
{
name: 'XDSHoverCard',
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index a771aae59d..abcecca8eb 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -29,29 +29,11 @@ export const docs = {
],
},
usage: {
- description:
- 'Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.',
- features: [
- "Semantic Icon Names: Use names like 'close' or 'chevronDown' — resolved from the theme's icon registry",
- 'Direct Icon Components: Pass any SVG icon component (heroicons, lucide, etc.) directly',
- "Theme-Adaptable: Semantic icons automatically match the active theme's icon set",
- 'Built-in Fallbacks: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme',
- 'Theme Colors: Color variants mapped to XDS icon color tokens',
- 'Consistent Sizing: Four size options aligned with common UI patterns',
- ],
- accessibility: [
- 'Icons are hidden from screen readers by default via aria-hidden="true" since icons are typically decorative.',
- 'For meaningful icons, set aria-hidden={false}, role="img", and aria-label to provide accessible context.',
- ],
- notes: [
- 'When icon is a semantic name string, resolution order is: (1) theme registry — if an XDSTheme is active and provides an icon for that name, it is used; (2) built-in fallback — otherwise, a lightweight inline SVG is rendered. Components always render visually complete, even without a theme. Themes can override any or all icons; the registry accepts partial overrides.',
- 'When icon is a component, additional SVG props (like aria-label, role) are passed through to the underlying SVG element.',
- 'flexShrink: 0 prevents icons from shrinking in flex containers.',
- 'String mode wraps the resolved icon in a <span> with fontSize-based sizing so 1em-based registry icons scale correctly.',
- 'Component mode passes stylex.props directly to the SVG element for zero-overhead styling.',
- 'Semantic icon names and their usages — close (CloseButton, TimeInput): ✕ close/dismiss; chevronDown (DropdownMenu, Selector, TabMenu): ▾ expand/dropdown; chevronLeft (Calendar): ‹ previous; chevronRight (Calendar): › next; check (Selector, TabMenu): ✓ selected item; checkCircle (Input status): ✓○ success; xCircle (Input status): ✕○ error; warning (Input status): △! warning; info (FieldLabel): ⓘ information tooltip; calendar (DateInput): 📅 date picker; clock (TimeInput): 🕐 time picker; externalLink (Link): ↗ opens in new window.',
- 'Color token mappings — primary: --color-icon-primary (default); secondary: --color-icon-secondary (de-emphasized); tertiary: --color-icon-secondary (subtle/background); disabled: --color-icon-disabled (disabled state); accent: --color-accent (interactive/actionable); positive: --color-success (success/confirmation); negative: --color-error (error/destructive); warning: --color-warning (caution/attention); inherit: currentColor (inherits from parent text color).',
- 'Size dimensions — xsm: 12x12px (dense UI, badges, indicators); sm: 16x16px (inline with text, compact UI); md: 20x20px (default, buttons, inputs); lg: 24x24px (emphasis, standalone icons).',
+ description: 'Renders icons using XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme. Use Icon wherever a visual symbol is needed to reinforce meaning or provide wayfinding.',
+ bestPractices: [
+ { guidance: true, description: 'Use semantic icon names when available — they automatically adapt to the active theme.' },
+ { guidance: true, description: 'Pair standalone icons with an accessible label (aria-label) when they convey meaning beyond decoration.' },
+ { guidance: false, description: 'Rely on an icon alone to communicate critical information — always pair with text or an accessible label.' },
],
},
};
@@ -85,30 +67,11 @@ export const docsZh = {
],
},
usage: {
- description:
- '使用 XDS 设计系统颜色和尺寸渲染图标。支持直接使用 SVG 图标组件和语义图标名称(可自动适配当前主题)。',
- features: [
- "语义图标名称:使用 'close' 或 'chevronDown' 等名称,从主题的图标注册表中解析",
- '直接图标组件:直接传入任何 SVG 图标组件(heroicons、lucide 等)',
- '主题适配:语义图标自动匹配当前活动主题的图标集',
- '内置回退:12 个轻量级内联 SVG(约 1.4KB)确保在无主题时也能正常渲染',
- '主题颜色:颜色变体映射到 XDS 图标颜色令牌',
- '一致的尺寸:四种尺寸选项,与常见 UI 模式对齐',
- '无障碍:图标默认对屏幕阅读器隐藏(aria-hidden)',
- ],
- accessibility: [
- '图标默认通过 aria-hidden="true" 对屏幕阅读器隐藏,因为图标通常是装饰性的。',
- '对于有意义的图标,设置 aria-hidden={false}、role="img" 和 aria-label 以提供无障碍上下文。',
- ],
- notes: [
- '当 icon 为语义名称字符串时,解析顺序为:(1) 主题注册表——如果 XDSTheme 处于活动状态并为该名称提供了图标,则使用该图标;(2) 内置回退——否则渲染轻量级内联 SVG。组件始终能完整渲染,即使没有主题。主题可以覆盖任意或所有图标;注册表接受部分覆盖。',
- '当 icon 为组件时,额外的 SVG 属性(如 aria-label、role)会透传到底层 SVG 元素。',
- 'flexShrink: 0 防止图标在 flex 容器中被压缩。',
- '字符串模式将解析后的图标包装在 <span> 中,使用基于 fontSize 的尺寸,使基于 1em 的注册表图标正确缩放。',
- '组件模式将 stylex.props 直接传递给 SVG 元素,实现零开销样式。',
- '语义图标名称及其用途——close(CloseButton、TimeInput):✕ 关闭/消除;chevronDown(DropdownMenu、Selector、TabMenu):▾ 展开/下拉;chevronLeft(Calendar):‹ 上一个;chevronRight(Calendar):› 下一个;check(Selector、TabMenu):✓ 已选项;checkCircle(Input 状态):✓○ 成功;xCircle(Input 状态):✕○ 错误;warning(Input 状态):△! 警告;info(FieldLabel):ⓘ 信息提示;calendar(DateInput):📅 日期选择器;clock(TimeInput):🕐 时间选择器;externalLink(Link):↗ 在新窗口中打开。',
- '颜色令牌映射——primary:--color-icon-primary(默认);secondary:--color-icon-secondary(弱化);tertiary:--color-icon-secondary(微妙/背景);disabled:--color-icon-disabled(禁用状态);accent:--color-accent(交互/可操作);positive:--color-success(成功/确认);negative:--color-error(错误/危险);warning:--color-warning(警告/注意);inherit:currentColor(继承父文本颜色)。',
- '尺寸规格——xsm:12x12px(密集 UI、徽章、指示器);sm:16x16px(与文本内联、紧凑 UI);md:20x20px(默认,按钮、输入框);lg:24x24px(强调、独立图标)。',
+ description: 'Renders icons using XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme. Use Icon wherever a visual symbol is needed to reinforce meaning or provide wayfinding.',
+ bestPractices: [
+ { guidance: true, description: 'Use semantic icon names when available — they automatically adapt to the active theme.' },
+ { guidance: true, description: 'Pair standalone icons with an accessible label (aria-label) when they convey meaning beyond decoration.' },
+ { guidance: false, description: 'Rely on an icon alone to communicate critical information — always pair with text or an accessible label.' },
],
},
};
@@ -117,29 +80,14 @@ export const docsZh = {
export const docsDense = {
description:
'Renders icons w/ XDS design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
- features: [
- "Semantic icon names: use 'close' or 'chevronDown'; resolved from theme icon registry",
- 'Direct icon components: pass any SVG component (heroicons, lucide, etc.)',
- "Theme-adaptable: semantic icons auto-match active theme's icon set",
- 'Built-in fallbacks: 12 lightweight inline SVGs (~1.4KB) ensure rendering w/o theme',
- 'Theme colors: variants mapped to XDS icon color tokens',
- 'Consistent sizing: four size options aligned w/ common UI patterns',
- 'Accessible: icons hidden from screen readers by default (aria-hidden)',
- ],
- notes: [
- 'Semantic name resolution: (1) theme registry if XDSTheme active; (2) built-in fallback inline SVG. Themes accept partial overrides.',
- 'Component icon passes extra SVG props (aria-label, role) through to SVG element.',
- 'flexShrink: 0 prevents shrinking in flex containers.',
- 'String mode wraps in <span> w/ fontSize-based sizing for 1em registry icons.',
- 'Component mode passes stylex.props directly to SVG for zero-overhead styling.',
- 'Semantic names: close (CloseButton, TimeInput) chevronDown (DropdownMenu, Selector, TabMenu) chevronLeft/Right (Calendar) check (Selector, TabMenu) checkCircle/xCircle/warning (Input status) info (FieldLabel) calendar (DateInput) clock (TimeInput) externalLink (Link).',
- 'Color tokens: primary=--color-icon-primary; secondary=--color-icon-secondary; tertiary=--color-icon-secondary; disabled=--color-icon-disabled; accent=--color-accent; positive=--color-success; negative=--color-error; warning=--color-warning; inherit=currentColor.',
- 'Size: xsm=12x12px sm=16x16px md=20x20px lg=24x24px.',
- ],
- accessibility: [
- 'Icons hidden from screen readers by default via aria-hidden="true"; typically decorative.',
- 'For meaningful icons: set aria-hidden={false}, role="img", aria-label for accessible context.',
- ],
+ usage: {
+ description: 'Renders icons using XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme. Use Icon wherever a visual symbol is needed to reinforce meaning or provide wayfinding.',
+ bestPractices: [
+ { guidance: true, description: 'Use semantic icon names when available — they automatically adapt to the active theme.' },
+ { guidance: true, description: 'Pair standalone icons with an accessible label (aria-label) when they convey meaning beyond decoration.' },
+ { guidance: false, description: 'Rely on an icon alone to communicate critical information — always pair with text or an accessible label.' },
+ ],
+ },
propDescriptions: {
icon: 'Semantic name or SVG icon component.',
color: 'Color variant mapped to XDS icon color tokens.',
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index 0018c8ceab..6d5293136a 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -60,23 +60,11 @@ export const docs = {
],
usage: {
- description:
- 'An icon-only button that wraps XDSButton with isIconOnly always true. Use when an action can be clearly represented by a single icon without visible text.',
- features: [
- 'Composition wrapper — delegates all behavior to XDSButton with isIconOnly=true',
- 'Same variants, sizes, and states as XDSButton',
- 'label prop becomes aria-label for accessibility',
- 'icon prop is required (enforced by TypeScript)',
- ],
- accessibility: [
- 'Uses aria-label from the label prop for screen reader accessibility.',
- 'Same keyboard and screen reader behavior as XDSButton with isIconOnly.',
- ],
- notes: [
- 'Prefer XDSIconButton over <XDSButton isIconOnly> for explicit intent.',
- 'Explicit component name — greppable, codemod-safe, import-level detection.',
- 'children and endContent are not accepted (omitted from props type).',
- 'All other XDSButton props (variant, size, onClick, etc.) are forwarded.',
+ description: 'An icon-only button for compact actions that can be clearly represented by a single icon. Use IconButton in toolbars, table rows, and dense UI areas where space is limited and the icon meaning is universally understood.',
+ bestPractices: [
+ { guidance: true, description: 'Always provide a descriptive label prop — it becomes the aria-label for screen reader users.' },
+ { guidance: true, description: 'Add a tooltip to clarify the action for sighted users who may not recognize the icon.' },
+ { guidance: false, description: 'Use an icon-only button when the action is ambiguous — add visible text or use a standard Button instead.' },
],
},
};
diff --git a/packages/core/src/Kbd/Kbd.doc.mjs b/packages/core/src/Kbd/Kbd.doc.mjs
index 3c7d408e81..61e0985778 100644
--- a/packages/core/src/Kbd/Kbd.doc.mjs
+++ b/packages/core/src/Kbd/Kbd.doc.mjs
@@ -34,22 +34,11 @@ export const docs = {
targets: [{className: 'xds-kbd'}],
},
usage: {
- description:
- 'Displays a keyboard shortcut as styled <kbd> elements. Use in tooltips, menus, and documentation to show key combinations.',
- features: [
- 'Key parsing — splits "mod+k" into individual styled <kbd> elements',
- 'Modifier symbols — maps mod/ctrl/alt/shift/enter/backspace/escape/arrows to platform symbols',
- 'Inline display — renders as inline-flex for use inside text, tooltips, and menus',
- ],
- accessibility: [
- 'Renders with aria-hidden="true" — keyboard shortcuts are visual hints, not primary content.',
- 'Uses semantic <kbd> elements for each key.',
- 'Keyboard: Not interactive — purely presentational.',
- ],
- notes: [
- 'Fixed 20px height with min-width 20px per key badge.',
- 'Uses --color-background-body background and --color-text-secondary text color.',
- 'Key display symbols follow macOS conventions (⌘, ⌥, ⇧, ⌃).',
+ description: 'Displays a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and documentation to visually communicate key combinations to users.',
+ 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.' },
],
},
};
@@ -88,23 +77,11 @@ export const docsZh = {
targets: [{className: 'xds-kbd'}],
},
usage: {
- description:
- '将键盘快捷键显示为样式化的 <kbd> 元素。适用于工具提示、菜单和文档中展示按键组合。',
- features: [
- '按键解析 — 将 "mod+k" 拆分为独立的样式化 <kbd> 元素',
- '修饰符符号 — 将 mod/ctrl/alt/shift/enter/backspace/escape/箭头键映射为平台符号',
- '内联显示 — 以 inline-flex 方式渲染,适用于文本、工具提示和菜单中',
- '无障碍 — 使用 aria-hidden="true",因为快捷键是可见标签的补充信息',
- ],
- accessibility: [
- '使用 aria-hidden="true" 渲染 — 键盘快捷键是视觉提示,不是主要内容',
- '每个按键使用语义化的 <kbd> 元素',
- 'Keyboard: 非交互式 — 纯展示用途',
- ],
- notes: [
- '固定 20px 高度,每个按键徽章最小宽度 20px',
- '使用 --color-background-body 背景色和 --color-text-secondary 文字颜色',
- '按键显示符号遵循 macOS 惯例(⌘、⌥、⇧、⌃)',
+ description: 'Displays a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and documentation to visually communicate key combinations to users.',
+ 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.' },
],
},
};
@@ -113,22 +90,14 @@ export const docsZh = {
export const docsDense = {
description:
'Displays keyboard shortcut as styled <kbd> elements. Use in tooltips, menus + docs to show key combinations.',
- features: [
- 'Key parsing; splits "mod+k" into individual styled <kbd> elements',
- 'Modifier symbols; maps mod/ctrl/alt/shift/enter/backspace/escape/arrows to platform symbols',
- 'Inline display; renders as inline-flex for use inside text, tooltips + menus',
- 'Accessible; aria-hidden="true" since shortcuts supplementary to visible labels',
- ],
- notes: [
- 'Fixed 20px height w/ min-width 20px per key badge',
- 'Uses --color-background-body background + --color-text-secondary text color',
- 'Key display symbols follow macOS conventions (\u2318, \u2325, \u21e7, \u2303)',
- ],
- accessibility: [
- 'Renders w/ aria-hidden="true"; keyboard shortcuts are visual hints, not primary content',
- 'Uses semantic <kbd> elements for each key',
- ],
- keyboard: 'Not interactive; purely presentational',
+ usage: {
+ description: 'Displays a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and documentation to visually communicate key combinations to users.',
+ 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.' },
+ ],
+ },
propDescriptions: {
keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index b86c781b7c..49962a59a7 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -36,24 +36,11 @@ export const docs = {
],
usage: {
description:
- 'Core hook for overlay positioning using CSS Anchor Positioning and the Popover API — no React portals needed. Popover, HoverCard, and Tooltip build on this foundation.',
- features: [
- 'CSS Anchor Positioning for automatic placement relative to trigger elements',
- 'Popover API for top-layer rendering — no React portals needed',
- 'Type-safe mode system: context mode (anchor positioning) and fixed mode (manual coordinates)',
- 'TypeScript enforces correct render props per mode at compile time',
- 'Graceful degradation in Firefox: Popover API works, anchor positioning degrades acceptably',
- 'Full support in Chrome and Safari',
- ],
- accessibility: [
- 'The Layer hook provides the positioning and visibility foundation. ARIA patterns are implemented by the higher-level components (XDSPopover, XDSHoverCard, XDSTooltip).',
- 'Keyboard: Escape closes any open layer.',
- ],
- notes: [
- 'CSS Anchor Positioning is fully supported in Chrome and Safari. Firefox supports the Popover API but not anchor positioning — this is an acceptable degradation.',
- 'useXDSLayer context mode: pass a ref to the trigger element, then call render(children, { placement?, alignment? }). Fixed mode: call show() to display, then render(children, { x, y }) with required coordinates.',
- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',
- 'For click-triggered popovers, use XDSPopover (in @xds/core/Popover). For hover overlays, use XDSHoverCard (in @xds/core/HoverCard). For tooltips, use XDSTooltip (in @xds/core/Tooltip).',
+ 'Layer is a core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for building popovers, hover cards, and tooltips without React portals.',
+ bestPractices: [
+ { guidance: true, description: 'Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates.' },
+ { guidance: true, description: 'Build on higher-level components like Popover, HoverCard, and Tooltip instead of using Layer directly for common overlay patterns.' },
+ { guidance: false, description: 'Implement ARIA patterns directly in a Layer — leave accessibility semantics to the higher-level components that build on it.' },
],
},
};
@@ -95,24 +82,11 @@ export const docsZh = {
],
usage: {
description:
- '使用 CSS 锚点定位和 Popover API 实现覆盖层定位的核心 Hook,无需 React Portal。Popover、HoverCard 和 Tooltip 基于此构建,各自位于独立目录中。',
- features: [
- 'CSS 锚点定位:自动相对于触发元素进行放置',
- 'Popover API 实现顶层渲染,无需 React Portal',
- '类型安全的模式系统:上下文模式(锚点定位)和固定模式(手动坐标)',
- 'TypeScript 在编译时为每种模式强制执行正确的渲染属性',
- 'Firefox 中优雅降级:Popover API 可用,锚点定位可接受地降级',
- '完全支持 Chrome 和 Safari',
- ],
- accessibility: [
- 'Layer Hook 提供定位和可见性基础。ARIA 模式由更高级别的组件(XDSPopover、XDSHoverCard、XDSTooltip)实现。',
- 'Keyboard: Escape 键关闭任何打开的层。',
- ],
- notes: [
- 'CSS 锚点定位在 Chrome 和 Safari 中完全支持。Firefox 支持 Popover API 但不支持锚点定位,这是一种可接受的降级。',
- 'useXDSLayer 上下文模式:将 ref 传递给触发元素,然后调用 render(children, { placement?, alignment? })。固定模式:调用 show() 显示,然后使用必需的坐标调用 render(children, { x, y })。',
- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',
- '对于点击触发的弹出层,使用 XDSPopover(位于 @xds/core/Popover)。对于悬停覆盖层,使用 XDSHoverCard(位于 @xds/core/HoverCard)。对于工具提示,使用 XDSTooltip(位于 @xds/core/Tooltip)。',
+ 'Layer is a core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for building popovers, hover cards, and tooltips without React portals.',
+ bestPractices: [
+ { guidance: true, description: 'Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates.' },
+ { guidance: true, description: 'Build on higher-level components like Popover, HoverCard, and Tooltip instead of using Layer directly for common overlay patterns.' },
+ { guidance: false, description: 'Implement ARIA patterns directly in a Layer — leave accessibility semantics to the higher-level components that build on it.' },
],
},
};
@@ -121,24 +95,15 @@ export const docsZh = {
export const docsDense = {
description:
'Core hook for overlay positioning using CSS Anchor Positioning + Popover API; no React portals needed. Popover, HoverCard, Tooltip build on this.',
- features: [
- 'CSS Anchor Positioning for auto-placement relative to triggers',
- 'Popover API for top-layer rendering; no React portals needed',
- 'Type-safe mode system: context (anchor positioning) + fixed (manual coordinates)',
- 'TypeScript enforces correct render props per mode at compile time',
- 'Graceful degradation in Firefox: Popover API works, anchor positioning degrades acceptably',
- 'Full support in Chrome + Safari',
- ],
- notes: [
- 'CSS Anchor Positioning fully supported in Chrome + Safari. Firefox supports Popover API but not anchor positioning; acceptable degradation.',
- 'Context mode: pass ref to trigger, call render(children, { placement?, alignment? }). Fixed mode: call show() then render(children, { x, y }).',
- 'LayerPlacement: above | below | start | end. LayerAlignment: start | center | end.',
- 'For click popovers use XDSPopover (@xds/core/Popover). Hover overlays use XDSHoverCard (@xds/core/HoverCard). Tooltips use XDSTooltip (@xds/core/Tooltip).',
- ],
- accessibility: [
- 'Layer hook provides positioning + visibility foundation. ARIA patterns implemented by higher-level components (XDSPopover, XDSHoverCard, XDSTooltip).',
- ],
- keyboard: 'Escape closes any open layer.',
+ usage: {
+ description:
+ 'Layer is a core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for building popovers, hover cards, and tooltips without React portals.',
+ bestPractices: [
+ { guidance: true, description: 'Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates.' },
+ { guidance: true, description: 'Build on higher-level components like Popover, HoverCard, and Tooltip instead of using Layer directly for common overlay patterns.' },
+ { guidance: false, description: 'Implement ARIA patterns directly in a Layer — leave accessibility semantics to the higher-level components that build on it.' },
+ ],
+ },
components: [
{
name: 'useXDSLayer',
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index fce17635b6..2415d6ec96 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -212,20 +212,12 @@ export const docs = {
],
usage: {
description:
- 'Composable utilities and components for building structured layouts with a container/content separation pattern. Use XDSLayout for page shells with header, sidebar(s), content, and footer slots — for simple stacking, use XDSHStack/XDSVStack instead.',
- features: [
- 'Primitive + higher-order architecture — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order',
- 'Directional padding via CSS variables — inner/outer, horizontal/vertical padding control',
- 'Context-aware defaults — components detect their slot and self-adjust',
- 'Automatic RTL support — uses CSS logical properties',
- 'XDSLayout provides a page shell with header, sidebar(s), content, and footer slots',
- 'XDSHStack and XDSVStack for simple stacking layouts',
- 'XDSStackItem for fill/alignment control within stacks',
- ],
- notes: [
- 'XDSLayoutContainer sets CSS variables that child components read: --layout-padding-outer-x (outer horizontal padding), --layout-padding-outer-y (outer vertical padding), --layout-padding-inner-x (inner horizontal padding used by Header, Footer, Content, Panel), --layout-padding-inner-y (inner vertical padding used by Header, Footer, Content, Panel).',
- 'Architecture layers from top to bottom: Higher-Order Components (XDSCard, XDSSection), Layout Structure (XDSLayout + XDSLayoutHeader/Footer/Content/Panel), Primitive (XDSLayoutContainer sets CSS variables), Layout Utilities (XDSHStack, XDSVStack, stack(), stackItem()).',
- 'All layout utilities and components are exported from @xds/core/Layout.',
+ 'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use XDSLayout for full app layouts and XDSHStack/XDSVStack for simple directional stacking.',
+ bestPractices: [
+ { guidance: true, description: 'Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },
+ { guidance: true, description: 'Use XDSHStack and XDSVStack for simple directional stacking within a content area.' },
+ { guidance: false, description: 'Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead.' },
+ { guidance: false, description: 'Nest multiple XDSLayout components — use one per page shell and compose content within its slots.' },
],
},
};
@@ -443,21 +435,12 @@ export const docsZh = {
],
usage: {
description:
- '用于构建结构化布局的可组合工具和组件,采用容器/内容分离模式。',
- features: [
- '基础 + 高阶架构:XDSLayoutContainer 是基础组件;XDSCard、XDSSection 是高阶组件',
- '通过 CSS 变量实现方向性内边距控制:内/外、水平/垂直内边距',
- '上下文感知默认值:组件检测其所在插槽并自动调整',
- '自动 RTL 支持:使用 CSS 逻辑属性',
- 'XDSLayout 提供带有页眉、侧边栏、内容和页脚插槽的页面外壳',
- 'XDSHStack 和 XDSVStack 用于简单的堆叠布局',
- 'XDSStackItem 用于堆叠中的填充/对齐控制',
- ],
- notes: [
- '使用 XDSLayout 构建页面外壳和应用布局,适用于任何带有页眉栏、侧边栏导航、可滚动内容区域或操作页脚的 UI。不要用于简单堆叠(请改用 XDSVStack/XDSHStack)。',
- 'XDSLayoutContainer 设置子组件读取的 CSS 变量:--layout-padding-outer-x(外部水平内边距)、--layout-padding-outer-y(外部垂直内边距)、--layout-padding-inner-x(Header、Footer、Content、Panel 使用的内部水平内边距)、--layout-padding-inner-y(Header、Footer、Content、Panel 使用的内部垂直内边距)。',
- '从上到下的架构层级:高阶组件(XDSCard、XDSSection)、布局结构(XDSLayout + XDSLayoutHeader/Footer/Content/Panel)、基础层(XDSLayoutContainer 设置 CSS 变量)、布局工具(XDSHStack、XDSVStack、stack()、stackItem())。',
- '所有布局工具和组件均从 @xds/core/Layout 导出。',
+ 'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use XDSLayout for full app layouts and XDSHStack/XDSVStack for simple directional stacking.',
+ bestPractices: [
+ { guidance: true, description: 'Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },
+ { guidance: true, description: 'Use XDSHStack and XDSVStack for simple directional stacking within a content area.' },
+ { guidance: false, description: 'Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead.' },
+ { guidance: false, description: 'Nest multiple XDSLayout components — use one per page shell and compose content within its slots.' },
],
},
};
@@ -466,21 +449,16 @@ export const docsZh = {
export const docsDense = {
description:
'Composable utilities + components for structured layouts w/ container/content separation pattern.',
- features: [
- 'Primitive + higher-order architecture; XDSLayoutContainer is primitive; XDSCard, XDSSection higher-order',
- 'Directional padding via CSS variables; inner/outer, horizontal/vertical padding control',
- 'Context-aware defaults; components detect slot + self-adjust',
- 'Automatic RTL support; uses CSS logical properties',
- 'XDSLayout provides page shell w/ header, sidebar(s), content, footer slots',
- 'XDSHStack + XDSVStack for simple stacking layouts',
- 'XDSStackItem for fill/alignment control within stacks',
- ],
- notes: [
- 'Use XDSLayout for page shells + app layouts (header bar, sidebar nav, scrollable content, action footer). Not for simple stacking (use XDSVStack/XDSHStack).',
- 'XDSLayoutContainer sets CSS vars child components read: --layout-padding-outer-x (outer horizontal), --layout-padding-outer-y (outer vertical), --layout-padding-inner-x (inner horizontal for Header/Footer/Content/Panel), --layout-padding-inner-y (inner vertical for Header/Footer/Content/Panel).',
- 'Architecture layers top to bottom: Higher-Order (XDSCard, XDSSection), Layout Structure (XDSLayout + Header/Footer/Content/Panel), Primitive (XDSLayoutContainer sets CSS vars), Utilities (XDSHStack, XDSVStack, stack(), stackItem()).',
- 'All layout utilities + components exported from @xds/core/Layout.',
- ],
+ usage: {
+ description:
+ 'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use XDSLayout for full app layouts and XDSHStack/XDSVStack for simple directional stacking.',
+ bestPractices: [
+ { guidance: true, description: 'Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer.' },
+ { guidance: true, description: 'Use XDSHStack and XDSVStack for simple directional stacking within a content area.' },
+ { guidance: false, description: 'Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead.' },
+ { guidance: false, description: 'Nest multiple XDSLayout components — use one per page shell and compose content within its slots.' },
+ ],
+ },
components: [
{
name: 'XDSLayout',
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index f91d60d94b..4432df3e96 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -98,29 +98,12 @@ export const docs = {
],
usage: {
description:
- 'Styled anchor link with multiple variants, external link support, and polymorphic rendering for custom link components (Next.js Link, React Router Link). Use for inline text navigation or standalone actions — write descriptive, concise link text and avoid icon-only links without a visible label.',
- features: [
- "Color control: Uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",
- 'External links: Opens in new tab with external link icon',
- 'Tooltip support: Display tooltip text on hover',
- 'Underline control: Always show underline or only on hover',
- 'Inline support: Inherits parent font styles when used within text',
- 'Standalone mode: Applies base font sizing for independent links',
- 'Disabled state: Visual and interaction disabled',
- 'Focus visible: Accessible focus outline',
- 'Polymorphic link: Render as a custom component via `as` prop or XDSLinkProvider',
- ],
- notes: [
- 'By default, links inherit font family, size, line-height, and weight from parent elements.',
- 'Use isStandalone prop when the link is not inline within other text content.',
- 'isExternalLink automatically sets target="_blank" and rel="noopener noreferrer" for security.',
- 'Disabled state uses aria-disabled and pointer-events: none for accessibility.',
- 'Tooltip wraps the link in XDSTooltip component when provided.',
- 'XDSLinkComponentType is React.ElementType, allowing both string tags ("a") and custom components.',
- 'XDSLinkContext is separated from XDSLinkProvider (mirrors ThemeContext/XDSTheme pattern) so consumers can import the context without the full provider.',
- 'XDSLinkProvider memoizes its context value to prevent unnecessary re-renders.',
- 'Polymorphic link resolution order: (1) per-component as prop (highest priority), (2) XDSLinkProvider context, (3) native <a> element (default).',
- 'All XDS components that render links (XDSLink, XDSTopNavItem, XDSSideNavItem, XDSBreadcrumbItem, XDSTab) support rendering as a custom link component.',
+ 'Link is a styled anchor element for inline and standalone text navigation with external link support and polymorphic rendering. Use it for navigating between pages or to external URLs within body text or as standalone actions.',
+ bestPractices: [
+ { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination or action.' },
+ { guidance: true, description: 'Use isStandalone when the link appears outside of inline text, so it receives proper base font sizing.' },
+ { guidance: false, description: 'Use icon-only links without a visible text label — always include descriptive text.' },
+ { guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },
],
anatomy: [
{name: 'Label', required: true, description: 'The visible text of the link.'},
@@ -229,29 +212,17 @@ export const docsZh = {
],
usage: {
description:
- 'XDSLink 组件,用于创建带有多种变体和功能的样式化锚点链接,以及用于渲染自定义链接组件(Next.js Link、React Router Link 等)的多态链接基础设施。',
- features: [
- "颜色控制:使用 XDSText 的 color 属性(默认 'active'、'secondary'、'inherit' 等)",
- '外部链接:在新标签页中打开,带有外部链接图标',
- '工具提示支持:悬停时显示提示文本',
- '下划线控制:始终显示下划线或仅在悬停时显示',
- '内联支持:在文本中使用时继承父级字体样式',
- '独立模式:为独立链接应用基础字体大小',
- '禁用状态:视觉和交互均被禁用',
- '焦点可见:无障碍焦点轮廓',
- '多态链接:通过 `as` 属性或 XDSLinkProvider 渲染为自定义组件',
+ 'Link is a styled anchor element for inline and standalone text navigation with external link support and polymorphic rendering. Use it for navigating between pages or to external URLs within body text or as standalone actions.',
+ bestPractices: [
+ { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination or action.' },
+ { guidance: true, description: 'Use isStandalone when the link appears outside of inline text, so it receives proper base font sizing.' },
+ { guidance: false, description: 'Use icon-only links without a visible text label — always include descriptive text.' },
+ { guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },
],
- notes: [
- '默认情况下,链接从父元素继承字体族、大小、行高和字重',
- '当链接不在其他文本内容中内联使用时,使用 isStandalone 属性',
- 'isExternalLink 自动设置 target="_blank" 和 rel="noopener noreferrer" 以确保安全',
- '禁用状态使用 aria-disabled 和 pointer-events: none 以确保无障碍性',
- '提供 tooltip 时,链接会被包裹在 XDSTooltip 组件中',
- 'XDSLinkComponentType 是 React.ElementType,允许字符串标签("a")和自定义组件',
- 'XDSLinkContext 与 XDSLinkProvider 分离(与 ThemeContext/XDSTheme 模式一致),以便消费者可以在不引入完整 Provider 的情况下导入上下文',
- 'XDSLinkProvider 对其上下文值进行缓存以防止不必要的重新渲染',
- '多态链接解析顺序:(1)单组件 as 属性(最高优先级),(2)XDSLinkProvider 上下文,(3)原生 <a> 元素(默认)',
- '所有渲染链接的 XDS 组件(XDSLink、XDSTopNavItem、XDSSideNavItem、XDSBreadcrumbItem、XDSTab)都支持渲染为自定义链接组件',
+ anatomy: [
+ {name: 'Label', required: true, description: 'The visible text of the link.'},
+ {name: 'Right icon', required: false, description: 'Icon placed after the label to indicate an action affordance.'},
+ {name: 'Left icon', required: false, description: 'Icon placed before the label to represent meaning.'},
],
},
};
@@ -260,29 +231,21 @@ export const docsZh = {
export const docsDense = {
description:
'Styled anchor links w/ multiple variants + polymorphic link infra for custom link components (Next.js Link, React Router Link, etc.).',
- features: [
- "Color control: uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",
- 'External links: opens new tab w/ external link icon',
- 'Tooltip support: displays tooltip text on hover',
- 'Underline control: always show underline or only on hover',
- 'Inline support: inherits parent font styles when used within text',
- 'Standalone mode: applies base font sizing for independent links',
- 'Disabled state: visual + interaction disabled',
- 'Focus visible: accessible focus outline',
- 'Polymorphic link: render as custom component via `as` prop or XDSLinkProvider',
- ],
- notes: [
- 'Links inherit font family, size, line-height, weight from parent elements',
- 'Use isStandalone when link not inline within other text content',
- 'isExternalLink auto-sets target="_blank" + rel="noopener noreferrer" for security',
- 'Disabled state uses aria-disabled + pointer-events: none for accessibility',
- 'Tooltip wraps link in XDSTooltip when provided',
- 'XDSLinkComponentType is React.ElementType; allows string tags ("a") + custom components',
- 'XDSLinkContext separated from XDSLinkProvider (mirrors ThemeContext/XDSTheme pattern); consumers import context w/o full provider',
- 'XDSLinkProvider memoizes context value to prevent unnecessary re-renders',
- 'Resolution order: (1) per-component as prop (highest priority), (2) XDSLinkProvider context, (3) native <a> element (default)',
- 'All XDS link components (XDSLink, XDSTopNavItem, XDSSideNavItem, XDSBreadcrumbItem, XDSTab) support custom link rendering',
- ],
+ usage: {
+ description:
+ 'Link is a styled anchor element for inline and standalone text navigation with external link support and polymorphic rendering. Use it for navigating between pages or to external URLs within body text or as standalone actions.',
+ bestPractices: [
+ { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination or action.' },
+ { guidance: true, description: 'Use isStandalone when the link appears outside of inline text, so it receives proper base font sizing.' },
+ { guidance: false, description: 'Use icon-only links without a visible text label — always include descriptive text.' },
+ { guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'The visible text of the link.'},
+ {name: 'Right icon', required: false, description: 'Icon placed after the label to indicate an action affordance.'},
+ {name: 'Left icon', required: false, description: 'Icon placed before the label to represent meaning.'},
+ ],
+ },
components: [
{
name: 'XDSLink',
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 1843b103b5..3b407caf55 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -113,28 +113,12 @@ export const docs = {
],
usage: {
description:
- 'Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model where XDSList wraps XDSListItem sub-components. Place lists within a container such as a card or dialog.',
- features: [
- 'Composition model — XDSList wraps XDSListItem sub-components',
- 'Density variants: compact, balanced, spacious',
- 'Optional dividers between items',
- 'Optional header associated via aria-labelledby',
- 'List marker styles: none, disc, decimal (renders <ol>), circle',
- 'Interactive items via invisible button or anchor pattern',
- 'Start and end content slots (icon, avatar, badge, chevron)',
- ],
- accessibility: [
- 'Semantic <ul> / <ol> with <li> elements.',
- 'role="list" added when listStyle=\'none\' (Safari fix for list semantics removed by CSS list-style:none).',
- 'aria-labelledby links the header element to the list.',
- 'aria-selected on selected items.',
- 'aria-disabled on disabled items.',
- 'Dividers are aria-hidden="true".',
- 'Interactive items are keyboard-focusable via Tab.',
- ],
- notes: [
- 'Invisible button pattern: when onClick is provided, an invisible <button> wraps the label + description for accessibility. The <li> is the visual container with hover/press styles. startContent and endContent are siblings to the button (not inside it). Container click fires onClick unless the click originated from an interactive child. :focus-within on the container shows the focus outline.',
- 'When href is provided instead of onClick, the same invisible pattern uses an <a> element.',
+ 'List renders a vertical collection of items with consistent spacing, dividers, and optional marker styles. Use it to display ordered or unordered groups of related content within cards, dialogs, or panels.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a header to label the list and give context to screen readers via aria-labelledby.' },
+ { guidance: true, description: 'Use startContent and endContent slots to add visual context like icons, avatars, or badges to each item.' },
+ { guidance: false, description: 'Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.' },
+ { guidance: false, description: 'Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.' },
],
anatomy: [
{name: 'List title', required: true, description: 'Heading that labels the list.'},
@@ -258,28 +242,18 @@ export const docsZh = {
],
usage: {
description:
- '用于渲染项目集合的垂直列表组件,提供一致的间距、分割线和标记样式。采用组合模式:XDSList 包裹 XDSListItem 子组件。',
- features: [
- '组合模式 — XDSList 包裹 XDSListItem 子组件',
- '密度变体:紧凑、均衡、宽松',
- '可选的项目间分割线',
- '可选的标题,通过 aria-labelledby 关联',
- '列表标记样式:无、实心圆点、数字(渲染 <ol>)、空心圆',
- '通过隐形按钮或锚点模式实现可交互项目',
- '起始和结束内容插槽(图标、头像、徽章、箭头)',
- ],
- accessibility: [
- '语义化 <ul> / <ol> 配合 <li> 元素',
- '当 listStyle=\'none\' 时添加 role="list"(Safari 修复:CSS list-style:none 会移除列表语义)',
- 'aria-labelledby 将标题元素与列表关联',
- '选中项目上设置 aria-selected',
- '禁用项目上设置 aria-disabled',
- '分割线设置 aria-hidden="true"',
- '可交互项目通过 Tab 键可获取焦点',
+ 'List renders a vertical collection of items with consistent spacing, dividers, and optional marker styles. Use it to display ordered or unordered groups of related content within cards, dialogs, or panels.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a header to label the list and give context to screen readers via aria-labelledby.' },
+ { guidance: true, description: 'Use startContent and endContent slots to add visual context like icons, avatars, or badges to each item.' },
+ { guidance: false, description: 'Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.' },
+ { guidance: false, description: 'Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.' },
],
- notes: [
- '隐形按钮模式:当提供 onClick 时,一个不可见的 <button> 包裹标签和描述以确保无障碍访问。<li> 作为带有悬停/按下样式的视觉容器。startContent 和 endContent 是按钮的兄弟元素(不在按钮内部)。容器点击触发 onClick,除非点击来源于可交互子元素。容器上的 :focus-within 显示焦点轮廓。',
- '当提供 href 而非 onClick 时,相同的隐形模式使用 <a> 元素。',
+ anatomy: [
+ {name: 'List title', required: true, description: 'Heading that labels the list.'},
+ {name: 'Description', required: false, description: 'Supplementary text below the title.'},
+ {name: 'List items', required: true, description: 'Individual entries, which may include icons or images.'},
+ {name: 'Item description', required: false, description: 'Additional detail for an individual list item.'},
],
},
};
@@ -288,28 +262,22 @@ export const docsZh = {
export const docsDense = {
description:
'Vertical list for rendering item collections w/ consistent spacing, dividers, marker styles. Composition model: XDSList wraps XDSListItem sub-components.',
- features: [
- 'Composition model; XDSList wraps XDSListItem sub-components',
- 'Density variants: compact, balanced, spacious',
- 'Optional dividers between items',
- 'Optional header associated via aria-labelledby',
- 'List marker styles: none, disc, decimal (renders <ol>), circle',
- 'Interactive items via invisible button or anchor pattern',
- 'Start + end content slots (icon, avatar, badge, chevron)',
- ],
- accessibility: [
- 'Semantic <ul> / <ol> w/ <li> elements',
- "role=\"list\" added when listStyle='none' (Safari fix for list semantics removed by CSS list-style:none)",
- 'aria-labelledby links header element to list',
- 'aria-selected on selected items',
- 'aria-disabled on disabled items',
- 'Dividers are aria-hidden="true"',
- 'Interactive items keyboard-focusable via Tab',
- ],
- notes: [
- 'Invisible button pattern: onClick wraps label+description in invisible <button> for accessibility. <li> is visual container w/ hover/press styles. startContent + endContent siblings to button (not inside). Container click fires onClick unless from interactive child. :focus-within shows focus outline.',
- 'When href provided instead of onClick, same invisible pattern uses <a> element.',
- ],
+ usage: {
+ description:
+ 'List renders a vertical collection of items with consistent spacing, dividers, and optional marker styles. Use it to display ordered or unordered groups of related content within cards, dialogs, or panels.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a header to label the list and give context to screen readers via aria-labelledby.' },
+ { guidance: true, description: 'Use startContent and endContent slots to add visual context like icons, avatars, or badges to each item.' },
+ { guidance: false, description: 'Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior.' },
+ { guidance: false, description: 'Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection.' },
+ ],
+ anatomy: [
+ {name: 'List title', required: true, description: 'Heading that labels the list.'},
+ {name: 'Description', required: false, description: 'Supplementary text below the title.'},
+ {name: 'List items', required: true, description: 'Individual entries, which may include icons or images.'},
+ {name: 'Item description', required: false, description: 'Additional detail for an individual list item.'},
+ ],
+ },
components: [
{
name: 'XDSList',
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index c1552ebcc5..b8e8297da7 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -103,25 +103,11 @@ export const docs = {
},
usage: {
description:
- 'Renders a markdown string as XDS-styled components, supporting headings, paragraphs, bold, italic, code, lists, tables, links, images, blockquotes, horizontal rules, and task lists. Handles streaming text delivery with a smooth fade-in animation.',
- features: [
- 'Zero dependencies — built-in markdown parser, no external library',
- 'Streaming mode — smooth fade-in animation for chunk-by-chunk text delivery',
- 'XDS integration — uses XDSList, XDSCodeBlock, XDSCode, and XDSCheckboxList for semantic output',
- 'Heading level shift — headingLevelStart maps # to any h1-h6 level for page hierarchy',
- 'Link interception — onLinkClick handler can intercept or prevent link navigation',
- 'Density — default and compact spacing modes',
- 'Task lists — GitHub Flavored Markdown checkboxes rendered via XDSCheckboxList in isReadOnly mode',
- 'Tables — rendered as accessible HTML tables with XDS typography',
- 'Citation chips — sources prop renders [id] and 【id】 markers as linked chips with label or number style',
- 'Content width — contentWidth constrains prose to a readable width while tables and code blocks expand to the full container',
- ],
- accessibility: [
- 'Root element uses role="document" to establish a document landmark for screen readers.',
- 'Lists are rendered as semantic <ul>/<ol> elements.',
- 'Tables include proper <thead>/<tbody> with alignment attributes.',
- 'Task list checkboxes are rendered via XDSCheckboxList with isReadOnly.',
- 'Code blocks use XDSCodeBlock with appropriate ARIA attributes.',
+ 'Markdown renders a markdown string as XDS-styled components with support for headings, lists, tables, code blocks, and more. Use it for displaying user-generated or AI-streamed content with consistent design-system styling.',
+ bestPractices: [
+ { guidance: true, description: 'Set headingLevelStart to fit the surrounding page hierarchy when embedding markdown within a section.' },
+ { guidance: true, description: 'Use contentWidth to constrain prose to a readable line length in wide layouts.' },
+ { guidance: false, description: 'Use Markdown for hand-authored rich text layouts — use XDSText and heading components directly instead.' },
],
},
};
@@ -215,25 +201,11 @@ export const docsZh = {
},
usage: {
description:
- '将 Markdown 字符串渲染为 XDS 组件。支持标题、段落、粗体、斜体、代码、列表、表格、链接、图片、引用块、水平线和任务列表。支持流式文本的逐字符淡入动画。',
- features: [
- '零依赖 — 内置 Markdown 解析器,无需外部库',
- '流式模式 — 逐块文本渲染时平滑淡入动画',
- 'XDS 集成 — 使用 XDSList、XDSCodeBlock、XDSCode 和 XDSCheckboxList 输出语义内容',
- '标题级别偏移 — headingLevelStart 将 # 映射到任意 h1-h6 级别',
- '链接拦截 — onLinkClick 可拦截或阻止链接导航',
- '密度 — 默认和紧凑间距模式',
- '任务列表 — GitHub 风格 Markdown 复选框通过 XDSCheckboxList 以只读模式渲染',
- '表格 — 渲染为带 XDS 排版的语义 HTML 表格',
- '引用标签 — sources 属性将 [id] 和 【id】 标记渲染为带链接的标签或编号徽章',
- '内容宽度 — contentWidth 将正文限制在可读宽度内,表格和代码块扩展到完整容器宽度',
- ],
- accessibility: [
- '根元素使用 role="document" 为屏幕阅读器建立文档地标。',
- '列表渲染为语义化 <ul>/<ol> 元素。',
- '表格包含带对齐属性的 <thead>/<tbody>。',
- '任务列表复选框通过 XDSCheckboxList 以 isReadOnly 模式渲染。',
- '代码块使用 XDSCodeBlock 并附带适当的 ARIA 属性。',
+ 'Markdown renders a markdown string as XDS-styled components with support for headings, lists, tables, code blocks, and more. Use it for displaying user-generated or AI-streamed content with consistent design-system styling.',
+ bestPractices: [
+ { guidance: true, description: 'Set headingLevelStart to fit the surrounding page hierarchy when embedding markdown within a section.' },
+ { guidance: true, description: 'Use contentWidth to constrain prose to a readable line length in wide layouts.' },
+ { guidance: false, description: 'Use Markdown for hand-authored rich text layouts — use XDSText and heading components directly instead.' },
],
},
};
@@ -242,15 +214,15 @@ export const docsDense = {
n: 'Markdown',
d: 'Renders markdown string as XDS components. Headings, bold, italic, code, lists, tables, links, blockquotes, task lists. Streaming with fade-in animation.',
kw: ['markdown', 'rich text', 'prose', 'renderer', 'streaming', 'markup', 'md'],
- f: [
- 'Zero-dep parser. Streaming fade-in. XDSList/XDSCodeBlock/XDSCheckboxList integration.',
- 'headingLevelStart: maps # to any h1-h6. Clamped at h6.',
- 'onLinkClick: intercept/prevent link nav. Return false to cancel.',
- 'density: default/compact block spacing.',
- 'Task lists via XDSCheckboxList isReadOnly. Tables as semantic HTML.',
- 'Citation chips: sources prop + [id]/【id】 markers. label or number style.',
- 'contentWidth constrains prose; tables/code expand to full width.',
- ],
+ usage: {
+ description:
+ 'Markdown renders a markdown string as XDS-styled components with support for headings, lists, tables, code blocks, and more. Use it for displaying user-generated or AI-streamed content with consistent design-system styling.',
+ bestPractices: [
+ { guidance: true, description: 'Set headingLevelStart to fit the surrounding page hierarchy when embedding markdown within a section.' },
+ { guidance: true, description: 'Use contentWidth to constrain prose to a readable line length in wide layouts.' },
+ { guidance: false, description: 'Use Markdown for hand-authored rich text layouts — use XDSText and heading components directly instead.' },
+ ],
+ },
p: {
children: 'Markdown string. Required.',
density: "Block spacing. 'default'|'compact'. Default: 'default'.",
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 256613ffbe..d66ab0ea58 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -88,21 +88,12 @@ export const docs = {
],
usage: {
description:
- 'A labeled list for displaying key-value metadata, providing a comprehensive overview of an object\'s attributes. Uses semantic HTML <dl>/<dt>/<dd> with layout control, column modes, and consistent styling via a composition model of XDSMetadataList and XDSMetadataListItem sub-components.',
- features: [
- 'Composition model — XDSMetadataList wraps XDSMetadataListItem sub-components',
- 'Column modes: single, multi (auto-fill), or fixed number',
- 'Label positioning: start (side-by-side) or top (stacked)',
- 'Horizontal orientation with flex-wrap',
- 'Show more / show less toggle when items exceed maxNumOfItems',
- 'Optional title heading above the list',
- 'Optional icon before label text',
- 'Semantic <dl>/<dt>/<dd> HTML structure',
- ],
- accessibility: [
- 'Semantic <dl> with <dt>/<dd> pairs',
- 'aria-controls links the show more/less button to the list',
- 'aria-expanded indicates whether the list is fully expanded',
+ 'MetadataList displays key-value pairs of metadata using semantic definition list markup. Use it in detail panels, summary sections, or anywhere an object\'s attributes need a structured overview.',
+ bestPractices: [
+ { guidance: true, description: 'Choose label position based on content length — use \'start\' for short values and \'top\' for long or complex values.' },
+ { guidance: true, description: 'Use maxNumOfItems to collapse long lists and keep the page scannable.' },
+ { guidance: false, description: 'Use MetadataList for tabular data with multiple columns of values — use a table component instead.' },
+ { guidance: false, description: 'Mix unrelated metadata items within the same list — group related attributes together.' },
],
anatomy: [
{name: 'Title', required: false, description: 'Optional title for the metadata list.'},
@@ -140,21 +131,19 @@ export const docsZh = {
},
],
usage: {
- description: '以标签/值对显示组件元数据,支持列布局、折叠和方向变体。',
- features: [
- '组合模型——XDSMetadataList 包裹 XDSMetadataListItem 子组件',
- '列模式:单列、多列(自动填充)或固定数量',
- '标签位置:start(并排)或 top(堆叠)',
- '水平方向,带 flex-wrap',
- '当项目超出 maxNumOfItems 时显示更多/更少切换',
- '可选标题插槽',
- '标签文本前可选图标',
- '语义化 HTML:带 <dt>/<dd> 对的 <dl>',
+ description:
+ 'MetadataList displays key-value pairs of metadata using semantic definition list markup. Use it in detail panels, summary sections, or anywhere an object\'s attributes need a structured overview.',
+ bestPractices: [
+ { guidance: true, description: 'Choose label position based on content length — use \'start\' for short values and \'top\' for long or complex values.' },
+ { guidance: true, description: 'Use maxNumOfItems to collapse long lists and keep the page scannable.' },
+ { guidance: false, description: 'Use MetadataList for tabular data with multiple columns of values — use a table component instead.' },
+ { guidance: false, description: 'Mix unrelated metadata items within the same list — group related attributes together.' },
],
- accessibility: [
- '语义化 <dl>,带 <dt>/<dd> 对',
- 'aria-controls 将显示更多/更少按钮链接到列表',
- 'aria-expanded 指示列表是否完全展开',
+ anatomy: [
+ {name: 'Title', required: false, description: 'Optional title for the metadata list.'},
+ {name: 'Label', required: true, description: 'The key label for each metadata entry.'},
+ {name: 'Metadata', required: true, description: 'The value displayed in various formats.'},
+ {name: 'Disclosure', required: false, description: 'Collapse/expand control for the list.'},
],
},
};
@@ -162,21 +151,22 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'label/value metadata display; column layout, collapse, orientation variants',
- features: [
- 'composition: XDSMetadataList wraps XDSMetadataListItem',
- 'columns: single, multi (auto-fill), fixed count',
- 'label position: start (side-by-side) or top (stacked)',
- 'horizontal orientation w/ flex-wrap',
- 'show more/less toggle when items exceed maxNumOfItems',
- 'optional title slot',
- 'optional icon before label',
- 'semantic: <dl> w/ <dt>/<dd> pairs',
- ],
- accessibility: [
- 'semantic <dl> w/ <dt>/<dd>',
- 'aria-controls links show more/less to list',
- 'aria-expanded indicates expand state',
- ],
+ usage: {
+ description:
+ 'MetadataList displays key-value pairs of metadata using semantic definition list markup. Use it in detail panels, summary sections, or anywhere an object\'s attributes need a structured overview.',
+ bestPractices: [
+ { guidance: true, description: 'Choose label position based on content length — use \'start\' for short values and \'top\' for long or complex values.' },
+ { guidance: true, description: 'Use maxNumOfItems to collapse long lists and keep the page scannable.' },
+ { guidance: false, description: 'Use MetadataList for tabular data with multiple columns of values — use a table component instead.' },
+ { guidance: false, description: 'Mix unrelated metadata items within the same list — group related attributes together.' },
+ ],
+ anatomy: [
+ {name: 'Title', required: false, description: 'Optional title for the metadata list.'},
+ {name: 'Label', required: true, description: 'The key label for each metadata entry.'},
+ {name: 'Metadata', required: true, description: 'The value displayed in various formats.'},
+ {name: 'Disclosure', required: false, description: 'Collapse/expand control for the list.'},
+ ],
+ },
components: [
{
name: 'XDSMetadataList',
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index 8201015ba7..a17827e5c1 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -51,22 +51,11 @@ export const docs = {
},
usage: {
description:
- 'Slide-out drawer overlay for mobile navigation, the mobile counterpart to XDSSideNav. Accepts the same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode), providing navigation on mobile viewports where a persistent side nav is not practical.',
- features: [
- 'Native <dialog> element with showModal() for top-layer rendering — no z-index stacking issues',
- 'Animated slide-in from start or end edge with backdrop fade',
- 'Shares children with XDSSideNav — extract nav sections into a variable and render in both',
- 'RTL-aware: automatically mirrors slide direction for right-to-left layouts',
- 'Respects prefers-reduced-motion: reduces animation duration',
- ],
- accessibility: [
- 'Uses native <dialog> with showModal() for correct ARIA modal semantics.',
- "aria-label set to title or 'Navigation' as fallback.",
- 'Focus trapping provided by showModal() (browser-native).',
- 'Escape key closes via native cancel event.',
- 'Backdrop click closes the drawer.',
- 'Body scroll locked while modal is open.',
- 'Keyboard: Escape closes the drawer; Tab/Shift+Tab cycles focus within the drawer (browser-native focus trapping).',
+ 'MobileNav is a slide-out drawer overlay for mobile navigation. It serves as the mobile counterpart to SideNav and accepts the same children. Use it on mobile viewports where a persistent side navigation is not practical.',
+ bestPractices: [
+ { guidance: true, description: 'Share the same navigation children between MobileNav and SideNav by extracting them into a variable.' },
+ { guidance: true, description: 'Provide a descriptive title to improve context and screen reader clarity.' },
+ { guidance: false, description: 'Use MobileNav on desktop viewports where a persistent SideNav would be more appropriate.' },
],
},
};
@@ -121,22 +110,11 @@ export const docsZh = {
},
usage: {
description:
- '用于移动端导航的滑出式抽屉覆盖层。作为 XDSSideNav 的移动端对应组件,接受相同的子元素(XDSSideNavSection、XDSSideNavItem 或任何 ReactNode)。',
- features: [
- '原生 <dialog> 元素配合 showModal() 实现顶层渲染,无 z-index 层叠问题',
- '从起始边缘或结束边缘滑入动画,配合背景遮罩淡入效果',
- '与 XDSSideNav 共享子元素,将导航区块提取为变量即可在两者中渲染',
- 'RTL 感知:自动镜像滑动方向以适配从右到左的布局',
- '遵循 prefers-reduced-motion:减少动画持续时间',
- ],
- accessibility: [
- '使用原生 <dialog> 配合 showModal() 以获得正确的 ARIA 模态语义。',
- "aria-label 设置为标题,回退值为 'Navigation'。",
- 'showModal() 提供焦点捕获(浏览器原生)。',
- '通过原生 cancel 事件,按 Escape 键关闭。',
- '点击背景遮罩关闭抽屉。',
- '模态框打开时锁定页面滚动。',
- 'Keyboard: Escape 关闭抽屉;Tab/Shift+Tab 在抽屉内循环切换焦点(浏览器原生焦点捕获)',
+ 'MobileNav is a slide-out drawer overlay for mobile navigation. It serves as the mobile counterpart to SideNav and accepts the same children. Use it on mobile viewports where a persistent side navigation is not practical.',
+ bestPractices: [
+ { guidance: true, description: 'Share the same navigation children between MobileNav and SideNav by extracting them into a variable.' },
+ { guidance: true, description: 'Provide a descriptive title to improve context and screen reader clarity.' },
+ { guidance: false, description: 'Use MobileNav on desktop viewports where a persistent SideNav would be more appropriate.' },
],
},
};
@@ -145,23 +123,15 @@ export const docsZh = {
export const docsDense = {
description:
'Slide-out drawer overlay for mobile navigation. Mobile counterpart to XDSSideNav; accepts same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode).',
- features: [
- 'Native <dialog> w/ showModal() for top-layer rendering; no z-index stacking issues',
- 'Animated slide-in from start or end edge w/ backdrop fade',
- 'Shares children w/ XDSSideNav; extract nav sections into variable + render in both',
- 'RTL-aware: auto mirrors slide direction for right-to-left layouts',
- 'Respects prefers-reduced-motion: reduces animation duration',
- ],
- accessibility: [
- 'Uses native <dialog> w/ showModal() for correct ARIA modal semantics.',
- "aria-label set to title or 'Navigation' as fallback.",
- 'Focus trapping provided by showModal() (browser-native).',
- 'Escape key closes via native cancel event.',
- 'Backdrop click closes drawer.',
- 'Body scroll locked while modal open.',
- ],
- keyboard:
- 'Escape closes drawer; Tab/Shift+Tab cycles focus within drawer (browser-native focus trapping)',
+ usage: {
+ description:
+ 'MobileNav is a slide-out drawer overlay for mobile navigation. It serves as the mobile counterpart to SideNav and accepts the same children. Use it on mobile viewports where a persistent side navigation is not practical.',
+ bestPractices: [
+ { guidance: true, description: 'Share the same navigation children between MobileNav and SideNav by extracting them into a variable.' },
+ { guidance: true, description: 'Provide a descriptive title to improve context and screen reader clarity.' },
+ { guidance: false, description: 'Use MobileNav on desktop viewports where a persistent SideNav would be more appropriate.' },
+ ],
+ },
propDescriptions: {
isOpen: 'Whether drawer is open.',
onOpenChange:
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index 25cdf8f73b..38e428ce52 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -62,24 +62,12 @@ export const docs = {
},
usage: {
description:
- 'Overflow menu with a three-dot icon trigger for presenting secondary or overflow actions in a compact space. A convenience wrapper that composes an icon-only XDSButton with a dropdown menu, eliminating the boilerplate of wiring up state management, positioning, and accessibility attributes.',
- features: [
- "Zero-config defaults: three-dot icon, 'More options' label, ghost variant — just pass items",
- 'Data-driven items: same items prop as XDSDropdownMenu (items, dividers, sections)',
- 'Icon-only trigger: always renders as a square icon button with aria-label',
- 'Tooltip: shows label on hover, hidden when menu is open',
- 'Custom rendering: optional children render function for custom item content',
- ],
- accessibility: [
- 'Proper ARIA roles: menu and menuitem on dropdown elements.',
- 'Trigger button has aria-haspopup="menu" and aria-expanded.',
- 'aria-activedescendant tracks the highlighted menu item.',
- 'Disabled items have aria-disabled set.',
- 'Sections use role="group" with aria-label.',
- 'Keyboard: Arrow keys navigate items; Home/End jump to first/last; Enter/Space select highlighted item; Escape closes menu.',
- ],
- notes: [
- 'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',
+ 'MoreMenu is a compact overflow menu triggered by a three-dot icon button. Use it to present secondary or overflow actions in tight spaces such as table rows, card headers, or toolbars.',
+ bestPractices: [
+ { guidance: true, description: 'Use for secondary or overflow actions that do not need to be always visible.' },
+ { guidance: true, description: 'Provide a meaningful label to describe the menu context for screen reader users.' },
+ { guidance: false, description: 'Place primary actions inside a MoreMenu — primary actions should be directly visible.' },
+ { guidance: false, description: 'Use MoreMenu when you need a labeled trigger button with a chevron — use DropdownMenu instead.' },
],
},
};
@@ -145,25 +133,12 @@ export const docsZh = {
},
usage: {
description:
- '带有三点图标触发器的溢出菜单。一个便捷的包装组件,将仅图标的 XDSButton 与下拉菜单组合在一起,省去了手动连接状态管理、定位和无障碍属性的模板代码。',
- features: [
- "零配置默认值:三点图标、'More options' 标签、ghost 变体,只需传入 items",
- '数据驱动的菜单项:与 XDSDropdownMenu 相同的 items 属性(项目、分割线、分组)',
- '仅图标触发器:始终渲染为带 aria-label 的方形图标按钮',
- '工具提示:悬停时显示标签,菜单打开时隐藏',
- '自定义渲染:可选的 children 渲染函数用于自定义项目内容',
- ],
- accessibility: [
- '正确的 ARIA 角色:下拉元素上设置 menu 和 menuitem。',
- '触发按钮设置了 aria-haspopup="menu" 和 aria-expanded。',
- 'aria-activedescendant 跟踪高亮的菜单项。',
- '禁用项目设置了 aria-disabled。',
- '分组使用 role="group" 配合 aria-label。',
- 'Keyboard: 方向键导航项目;Home/End 跳转到第一项/最后一项;Enter/Space 选择高亮项目;Escape 关闭菜单',
- ],
- notes: [
- '如需完全控制触发器渲染或菜单内容,请直接组合 XDSButton + useXDSLayer + XDSDropdownMenuItem。',
- '在紧凑空间(表格行、卡片标题)中使用 XDSMoreMenu 作为仅图标的溢出操作。使用 XDSDropdownMenu 作为带标签和箭头的触发按钮。',
+ 'MoreMenu is a compact overflow menu triggered by a three-dot icon button. Use it to present secondary or overflow actions in tight spaces such as table rows, card headers, or toolbars.',
+ bestPractices: [
+ { guidance: true, description: 'Use for secondary or overflow actions that do not need to be always visible.' },
+ { guidance: true, description: 'Provide a meaningful label to describe the menu context for screen reader users.' },
+ { guidance: false, description: 'Place primary actions inside a MoreMenu — primary actions should be directly visible.' },
+ { guidance: false, description: 'Use MoreMenu when you need a labeled trigger button with a chevron — use DropdownMenu instead.' },
],
},
};
@@ -172,26 +147,16 @@ export const docsZh = {
export const docsDense = {
description:
'Overflow menu w/ three-dot icon trigger. Convenience wrapper composing icon-only XDSButton w/ dropdown menu, eliminating boilerplate for state management, positioning, accessibility.',
- features: [
- "Zero-config defaults: three-dot icon, 'More options' label, ghost variant; just pass items",
- 'Data-driven items: same items prop as XDSDropdownMenu (items, dividers, sections)',
- 'Icon-only trigger: always renders as square icon button w/ aria-label',
- 'Tooltip: shows label on hover, hidden when menu open',
- 'Custom rendering: optional children render function for custom item content',
- ],
- accessibility: [
- 'Proper ARIA roles: menu + menuitem on dropdown elements.',
- 'Trigger button has aria-haspopup="menu" + aria-expanded.',
- 'aria-activedescendant tracks highlighted menu item.',
- 'Disabled items have aria-disabled set.',
- 'Sections use role="group" w/ aria-label.',
- ],
- keyboard:
- 'Arrow keys navigate items; Home/End jump to first/last; Enter/Space select highlighted item; Escape closes menu',
- notes: [
- 'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',
- 'Use XDSMoreMenu for icon-only overflow actions in tight spaces (table rows, card headers). Use XDSDropdownMenu for labeled trigger buttons w/ chevrons.',
- ],
+ usage: {
+ description:
+ 'MoreMenu is a compact overflow menu triggered by a three-dot icon button. Use it to present secondary or overflow actions in tight spaces such as table rows, card headers, or toolbars.',
+ bestPractices: [
+ { guidance: true, description: 'Use for secondary or overflow actions that do not need to be always visible.' },
+ { guidance: true, description: 'Provide a meaningful label to describe the menu context for screen reader users.' },
+ { guidance: false, description: 'Place primary actions inside a MoreMenu — primary actions should be directly visible.' },
+ { guidance: false, description: 'Use MoreMenu when you need a labeled trigger button with a chevron — use DropdownMenu instead.' },
+ ],
+ },
propDescriptions: {
items: 'Menu items (actions, dividers, sections). Same type as XDSDropdownMenu items.',
label: 'Accessible label (aria-label) + tooltip text.',
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 3df11f35ae..3c017d415b 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -141,26 +141,12 @@ export const docs = {
],
usage: {
description:
- 'Multi-select dropdown with checkboxes for choosing multiple items from a list. Designed for small, finite sets like column toggles or filter facets — not a replacement for XDSTokenizer.',
- features: [
- 'Checkbox-based multi-select — dropdown stays open on toggle',
- 'Supports string items, object items with optional icon and disabled state, dividers, and labeled sections',
- 'Optional select-all with indeterminate state',
- 'Optional search filtering',
- 'Three trigger display modes: count, labels, badges',
- 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',
- 'Size variants: sm, md, lg',
- 'Full keyboard navigation with typeahead support',
- 'Accessible — role="combobox" trigger, role="listbox" with aria-multiselectable, real checkbox inputs',
- ],
- accessibility: [
- 'Uses role="combobox" on the trigger button.',
- 'Dropdown listbox uses aria-multiselectable="true".',
- 'Each option uses role="option" with aria-selected.',
- 'Real XDSCheckboxInput for each item — no fake checkboxes.',
- 'Select-all checkbox rendered outside role="listbox".',
- 'Search input uses role="searchbox" with aria-controls.',
- 'Keyboard: ↑↓ navigate; Enter/Space toggle; Escape close; Home/End jump; A-Z typeahead (when search not shown).',
+ 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',
+ bestPractices: [
+ { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },
+ { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },
+ { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },
+ { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },
],
},
};
@@ -198,26 +184,13 @@ export const docsZh = {
},
],
usage: {
- description: '带复选框的多选下拉框,用于从列表中选择多项。适用于列切换或筛选条件等小型有限集合,不适用于替代 XDSTokenizer。',
- features: [
- '基于复选框的多选——切换时下拉框保持打开',
- '支持字符串项、带可选图标和禁用状态的对象项、分隔线和标签分组',
- '可选全选,带不确定状态',
- '可选搜索过滤',
- '三种触发显示模式:计数、标签、徽章',
- '集成 XDS 字段规范:label、description、isRequired、isOptional、isLabelHidden、status',
- '尺寸变体:sm、md、lg',
- '完整键盘导航,支持预输入',
- '无障碍访问——role="combobox" 触发器,带 aria-multiselectable 的 role="listbox",真实复选框输入',
- ],
- accessibility: [
- '触发按钮使用 role="combobox"。',
- '下拉列表框使用 aria-multiselectable="true"。',
- '每个选项使用带 aria-selected 的 role="option"。',
- '每项使用真实的 XDSCheckboxInput——无假复选框。',
- '全选复选框渲染在 role="listbox" 之外。',
- '搜索输入使用带 aria-controls 的 role="searchbox"。',
- 'Keyboard: ↑↓ 导航,Enter/空格切换,Escape 关闭,Home/End 跳转,A-Z 预输入(不显示搜索时)。',
+ description:
+ 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',
+ bestPractices: [
+ { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },
+ { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },
+ { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },
+ { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },
],
},
};
@@ -225,26 +198,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'checkbox multi-select dropdown for finite sets like column toggles or filter facets',
- features: [
- 'checkbox multi-select; dropdown stays open on toggle',
- 'strings, objects w/ icon+disabled, dividers, sections',
- 'optional select-all w/ indeterminate state',
- 'optional search filtering',
- 'trigger modes: count, labels, badges',
- 'XDS field: label, description, isRequired, isOptional, isLabelHidden, status',
- 'sizes: sm, md, lg',
- 'full keyboard nav w/ typeahead',
- 'a11y: role="combobox" trigger, listbox w/ aria-multiselectable, real checkboxes',
- ],
- keyboard: '↑↓ nav, Enter/Space toggle, Escape close, Home/End jump, A-Z typeahead (no search).',
- accessibility: [
- 'role="combobox" on trigger.',
- 'aria-multiselectable="true" on listbox.',
- 'role="option" w/ aria-selected per option.',
- 'real XDSCheckboxInput per item.',
- 'select-all outside role="listbox".',
- 'role="searchbox" w/ aria-controls on search.',
- ],
+ usage: {
+ description:
+ 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',
+ bestPractices: [
+ { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },
+ { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },
+ { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },
+ { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },
+ ],
+ },
components: [
{
name: 'XDSMultiSelector',
diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjs
index fdcaed6599..2d0628d24f 100644
--- a/packages/core/src/NavIcon/NavIcon.doc.mjs
+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs
@@ -19,11 +19,11 @@ export const docs = {
},
usage: {
description:
- 'Circular icon container with accent background for navigation headers.',
- features: [
- 'Shared — used in both XDSTopNavHeading and XDSPageNavHeader',
- 'Accent background — uses --color-accent with --color-on-accent contrast',
- 'Fixed size — renders at the medium (--size-element-md) design token size',
+ 'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',
+ bestPractices: [
+ { guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },
+ { guidance: true, description: 'Pass an XDSIcon or similarly sized icon component to ensure proper proportions.' },
+ { guidance: false, description: 'Use NavIcon for interactive purposes — it is a display-only container, not a button.' },
],
},
};
@@ -47,11 +47,11 @@ export const docsZh = {
},
usage: {
description:
- '用于导航头部的带强调色背景的圆形图标容器。',
- features: [
- '共享 — 同时用于 XDSTopNavHeading 和 XDSPageNavHeader',
- '强调色背景 — 使用 --color-accent 配合 --color-on-accent 对比色',
- '固定尺寸 — 以中等尺寸 (--size-element-md) 设计令牌渲染',
+ 'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',
+ bestPractices: [
+ { guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },
+ { guidance: true, description: 'Pass an XDSIcon or similarly sized icon component to ensure proper proportions.' },
+ { guidance: false, description: 'Use NavIcon for interactive purposes — it is a display-only container, not a button.' },
],
},
};
@@ -60,11 +60,15 @@ export const docsZh = {
export const docsDense = {
description:
'Circular icon container w/ accent background for navigation headers.',
- features: [
- 'Shared; used in both XDSTopNavHeading + XDSPageNavHeader',
- 'Accent background; uses --color-accent w/ --color-on-accent contrast',
- 'Fixed size; renders at medium (--size-element-md) design token size',
- ],
+ usage: {
+ description:
+ 'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',
+ bestPractices: [
+ { guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },
+ { guidance: true, description: 'Pass an XDSIcon or similarly sized icon component to ensure proper proportions.' },
+ { guidance: false, description: 'Use NavIcon for interactive purposes — it is a display-only container, not a button.' },
+ ],
+ },
propDescriptions: {
icon: 'Icon element inside circular background. Should be XDSIcon or similar.',
},
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index b443af40e0..e1852e2bc6 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -156,34 +156,12 @@ export const docs = {
},
usage: {
description:
- 'A number input component for collecting and editing numeric values with validation support. Use within forms with support for min/max/step constraints, units display, and error/warning/success validation states.',
- features: [
- 'Label Support — required label for accessibility (can be visually hidden)',
- 'Description — optional description text displayed between the label and input',
- 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',
- 'Label Tooltip — optional info icon with tooltip at end of label',
- 'Label Icon — optional icon before the label text',
- 'Accessible — label properly associated with input via htmlFor/id',
- 'Size Variants — three sizes (sm, md, lg) for different contexts',
- 'Status Handling — error, warning, and success states with messages',
- 'Number Constraints — support for min, max, and step attributes',
- 'Validated onChange — only calls onChange when the entered value passes validation',
- 'Units Display — optional units suffix (e.g., "%" or "GB")',
- 'Integer Mode — option to restrict to integers only',
- 'Native Controls — uses type="number" for browser step controls',
- 'Event Callbacks — onFocus, onBlur, and onEnter handlers',
- ],
- accessibility: [
- 'Label is always rendered and associated with the input via htmlFor/id using the useId hook.',
- 'Use isLabelHidden to hide the label visually while keeping it accessible to screen readers via a CSS technique.',
- 'Wraps XDSField for consistent label, description, and optional/required indicator handling.',
- ],
- notes: [
- 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" is shown.',
- 'Uses type="number" to enable native browser step controls (up/down arrows).',
- 'Validated onChange: only calls onChange when the entered value is a valid number that passes min/max/integer constraints.',
- 'Uses internal pending state to allow free-form typing while validating on commit.',
- 'Units are displayed as a lighter grey suffix after the input value.',
+ 'NumberInput is a form input for collecting and editing numeric values with built-in validation. Use it when users need to enter quantities, measurements, or other constrained numeric data with optional min, max, and step controls.',
+ bestPractices: [
+ { guidance: true, description: 'Set appropriate min, max, and step constraints to guide users toward valid values.' },
+ { guidance: true, description: 'Display units (e.g. "%" or "GB") to clarify what the number represents.' },
+ { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.' },
+ { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
],
anatomy: [
{name: 'Label', required: true, description: 'The label for the number input.'},
@@ -350,35 +328,19 @@ export const docsZh = {
},
usage: {
description:
- '用于收集带验证的数字用户输入的数字输入组件。',
- features: [
- '标签支持 - 必需的标签用于无障碍访问(可视觉隐藏)',
- '描述 - 可选的描述文本,显示在标签和输入框之间',
- '可选/必填指示器 - 显示"Optional"或"Required"文本,带圆点分隔符',
- '标签工具提示 - 可选的信息图标,在标签末尾显示工具提示',
- '标签图标 - 可选的标签文本前图标',
- '无障碍 - 通过 htmlFor/id 将标签与输入框正确关联',
- '使用 StyleX 样式 - 使用 XDS 设计令牌实现一致的样式',
- '尺寸变体 - 三种尺寸(sm、md、lg)适用于不同场景',
- '状态处理 - 错误、警告和成功状态及消息',
- '数值约束 - 支持 min、max 和 step 属性',
- '验证性 onChange - 仅在输入值通过验证时调用 onChange',
- '单位显示 - 可选的单位后缀(例如"%"或"GB")',
- '整数模式 - 可选择仅限整数输入',
- '原生控件 - 使用 type="number" 获取浏览器步进控件',
- '事件回调 - onFocus、onBlur 和 onEnter 处理器',
- ],
- accessibility: [
- '标签始终渲染,并通过 useId hook 使用 htmlFor/id 与输入框关联。',
- '使用 isLabelHidden 视觉隐藏标签,同时通过 CSS 技术保持屏幕阅读器可访问。',
- '包装 XDSField 以实现一致的标签、描述和可选/必填指示器处理。',
+ 'NumberInput is a form input for collecting and editing numeric values with built-in validation. Use it when users need to enter quantities, measurements, or other constrained numeric data with optional min, max, and step controls.',
+ bestPractices: [
+ { guidance: true, description: 'Set appropriate min, max, and step constraints to guide users toward valid values.' },
+ { guidance: true, description: 'Display units (e.g. "%" or "GB") to clarify what the number represents.' },
+ { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.' },
+ { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
],
- notes: [
- 'isOptional 和 isRequired 互斥;同时设置两者将显示"Optional"。',
- '使用 type="number" 启用浏览器原生步进控件(上/下箭头)。',
- '验证性 onChange:仅在输入值为通过 min/max/整数约束的有效数字时调用 onChange。',
- '使用内部待定状态以允许自由输入,同时在提交时进行验证。',
- '单位以浅灰色后缀显示在输入值之后。',
+ anatomy: [
+ {name: 'Label', required: true, description: 'The label for the number input.'},
+ {name: 'Description', required: false, description: 'Additional description text below the label.'},
+ {name: 'Icon', required: false, description: 'An optional icon within the input.'},
+ {name: 'Placeholder', required: false, description: 'Placeholder text shown when the input is empty.'},
+ {name: 'Spinner', required: false, description: 'Increment and decrement controls for the value.'},
],
},
};
@@ -386,35 +348,23 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Number input component for collecting numeric user input w/ validation.',
- features: [
- 'Label support; required label for accessibility (can be visually hidden)',
- 'Description; optional text between label + input',
- 'Optional/Required indicators; display "Optional" or "Required" w/ bullet separator',
- 'Label tooltip; optional info icon w/ tooltip at label end',
- 'Label icon; optional icon before label text',
- 'Accessible; label associated w/ input via htmlFor/id',
- 'Styled w/ StyleX; uses XDS design tokens for consistent styling',
- 'Size variants; three sizes (sm, md, lg) for different contexts',
- 'Status handling; error, warning, success states w/ messages',
- 'Number constraints; support for min, max, step attributes',
- 'Validated onChange; only calls onChange when value passes validation',
- 'Units display; optional units suffix (e.g. "%" or "GB")',
- 'Integer mode; option to restrict to integers only',
- 'Native controls; uses type="number" for browser step controls',
- 'Event callbacks; onFocus, onBlur, onEnter handlers',
- ],
- accessibility: [
- 'Label always rendered + associated w/ input via htmlFor/id using useId hook.',
- 'Use isLabelHidden to hide label visually while keeping screen reader access via CSS.',
- 'Wraps XDSField for consistent label, description, optional/required indicator handling.',
- ],
- notes: [
- 'isOptional + isRequired mutually exclusive; both set shows "Optional".',
- 'Uses type="number" to enable native browser step controls (up/down arrows).',
- 'Validated onChange: only calls onChange when value is valid number passing min/max/integer constraints.',
- 'Uses internal pending state for free-form typing while validating on commit.',
- 'Units displayed as lighter grey suffix after input value.',
- ],
+ usage: {
+ description:
+ 'NumberInput is a form input for collecting and editing numeric values with built-in validation. Use it when users need to enter quantities, measurements, or other constrained numeric data with optional min, max, and step controls.',
+ bestPractices: [
+ { guidance: true, description: 'Set appropriate min, max, and step constraints to guide users toward valid values.' },
+ { guidance: true, description: 'Display units (e.g. "%" or "GB") to clarify what the number represents.' },
+ { guidance: false, description: 'Use NumberInput for free-form text that happens to contain numbers — use TextInput instead.' },
+ { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'The label for the number input.'},
+ {name: 'Description', required: false, description: 'Additional description text below the label.'},
+ {name: 'Icon', required: false, description: 'An optional icon within the input.'},
+ {name: 'Placeholder', required: false, description: 'Placeholder text shown when the input is empty.'},
+ {name: 'Spinner', required: false, description: 'Increment and decrement controls for the value.'},
+ ],
+ },
propDescriptions: {
label: 'Label text (always rendered for accessibility).',
value: 'Current input value.',
diff --git a/packages/core/src/OverflowList/OverflowList.doc.mjs b/packages/core/src/OverflowList/OverflowList.doc.mjs
index 4a1c9a457e..cc95c9bb70 100644
--- a/packages/core/src/OverflowList/OverflowList.doc.mjs
+++ b/packages/core/src/OverflowList/OverflowList.doc.mjs
@@ -67,25 +67,11 @@ export const docs = {
},
usage: {
description:
- 'Horizontal list that hides items exceeding the available width and shows a custom overflow indicator. Uses a hidden measurement container to avoid layout flicker.',
- features: [
- "Hides items that don't fit in the container width",
- 'Custom overflow indicator via overflowRenderer — receives the list of hidden items',
- 'Indicator space reserved via hidden measurement — no manual width needed',
- 'Collapse from start or end',
- 'Minimum visible items guarantee',
- 'observeParent behavior for content-sized containers alongside siblings',
- ],
- accessibility: [
- 'The hidden measurement container is aria-hidden and inert — it does not appear in the accessibility tree.',
- 'The visible container renders a plain div with no implicit role. Add aria-label if the list has semantic meaning.',
- 'When using overflowRenderer with a dropdown, ensure the trigger has a meaningful label (e.g., "+3 more actions").',
- ],
- notes: [
- 'Overflow detection uses ResizeObserver on the container or its parent, depending on the behavior prop.',
- 'The overflowRenderer is rendered in a hidden measurement container at full item count to reserve the correct space before any items are hidden.',
- 'Items are measured in the hidden container without visible paint — switching from hidden to visible is instant with no layout shift.',
- "For collapseFrom='start', items are hidden from the beginning and the overflow indicator appears at the start.",
+ 'OverflowList is a horizontal list that automatically hides items exceeding the available width and shows a custom overflow indicator. Use it for breadcrumbs, toolbars, tag lists, or any row of items that needs to collapse gracefully at smaller widths.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a meaningful overflow indicator via overflowRenderer, such as a "+N more" badge or dropdown.' },
+ { guidance: true, description: 'Set minVisibleItems to guarantee key items remain visible regardless of container size.' },
+ { guidance: false, description: 'Use OverflowList for vertical layouts — it is designed exclusively for horizontal item rows.' },
],
},
};
@@ -141,26 +127,11 @@ export const docsZh = {
],
usage: {
description:
- '横向列表,当宽度不足时隐藏超出的项目并显示自定义指示器。使用隐藏的测量容器避免布局抖动。',
- features: [
- '隐藏超出容器宽度的项目',
- '通过 overflowRenderer 自定义溢出指示器 — 接收隐藏项目列表',
- '通过隐藏测量预留指示器空间 — 无需手动指定宽度',
- '从起始或末尾折叠',
- '保证最小可见项目数',
- '支持 observeParent 模式,用于与兄弟元素并排的内容尺寸容器',
- ],
- accessibility: [
- '隐藏的测量容器设置了 aria-hidden 和 inert — 不出现在无障碍树中。',
- '可见容器渲染为普通 div,无隐式角色。如果列表有语义含义,请添加 aria-label。',
- '使用下拉菜单作为 overflowRenderer 时,确保触发按钮有有意义的标签(如"+3 个更多操作")。',
- ],
- notes: [
- '溢出检测使用 ResizeObserver 监听容器或其父元素,具体取决于 behavior 属性。',
- 'overflowRenderer 在隐藏测量容器中以完整项目数渲染,以在隐藏任何项目前预留正确的空间。',
- '项目在隐藏容器中测量,无可见渲染 — 从隐藏切换到可见是即时的,无布局偏移。',
- "使用 collapseFrom='start' 时,项目从起始处隐藏,溢出指示器出现在起始位置。",
- '使用 minVisibleItems 保证无论可用空间多少,始终显示至少 N 个项目。',
+ 'OverflowList is a horizontal list that automatically hides items exceeding the available width and shows a custom overflow indicator. Use it for breadcrumbs, toolbars, tag lists, or any row of items that needs to collapse gracefully at smaller widths.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a meaningful overflow indicator via overflowRenderer, such as a "+N more" badge or dropdown.' },
+ { guidance: true, description: 'Set minVisibleItems to guarantee key items remain visible regardless of container size.' },
+ { guidance: false, description: 'Use OverflowList for vertical layouts — it is designed exclusively for horizontal item rows.' },
],
},
};
@@ -168,26 +139,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'horizontal list w/ overflow indicator — hides items beyond container width',
- features: [
- 'hide items beyond container width',
- 'custom overflow indicator via overflowRenderer — receives hidden items',
- 'indicator space auto-reserved via hidden measurement',
- 'collapse from start or end',
- 'min visible items guarantee',
- 'observeParent mode for content-sized containers',
- ],
- notes: [
- 'overflow detection: ResizeObserver on container or parent (depends on behavior)',
- 'overflowRenderer measured at full item count to pre-reserve indicator space',
- 'instant switch hidden to visible, no layout shift',
- "collapseFrom='start': items hidden from beginning, indicator at start",
- 'minVisibleItems: N items always visible regardless of space',
- ],
- accessibility: [
- 'hidden measurement container: aria-hidden + inert, not in a11y tree',
- 'visible container: plain div, no role, add aria-label if list has semantic meaning',
- 'overflow dropdown: ensure trigger has meaningful aria-label',
- ],
+ usage: {
+ description:
+ 'OverflowList is a horizontal list that automatically hides items exceeding the available width and shows a custom overflow indicator. Use it for breadcrumbs, toolbars, tag lists, or any row of items that needs to collapse gracefully at smaller widths.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a meaningful overflow indicator via overflowRenderer, such as a "+N more" badge or dropdown.' },
+ { guidance: true, description: 'Set minVisibleItems to guarantee key items remain visible regardless of container size.' },
+ { guidance: false, description: 'Use OverflowList for vertical layouts — it is designed exclusively for horizontal item rows.' },
+ ],
+ },
propDescriptions: {
children: 'items to render, each child should be a single element',
overflowRenderer: 'renders overflow indicator, receives hidden items w/ index',
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index 6f0ef89948..2b084fbcc2 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -105,28 +105,12 @@ export const docs = {
},
usage: {
description:
- 'Standalone pagination controls for navigating through pages of content. Communicates the number of elements that can be loaded within a given context, supporting multiple display variants and working with known totals or cursor-based pagination.',
- features: [
- "Five display variants: 'pages', 'count', 'compact', 'dots', 'none'",
- 'Offset and cursor-based pagination: provide totalItems/totalPages for known totals, or hasMore for cursor-based',
- 'Page size selector: shows a dropdown when pageSizeOptions is provided',
- 'Ellipsis truncation for page numbers via generatePageRange utility',
- 'React transitions: onChangeAction uses useTransition for built-in loading state',
- "Sizes: 'sm' and 'md'",
- ],
- accessibility: [
- 'Root is <nav> with configurable aria-label.',
- 'Current page button has aria-current="page".',
- 'Prev/next buttons have descriptive aria-label.',
- 'Ellipsis elements are aria-hidden.',
- 'All interactive elements are keyboard accessible.',
- ],
- notes: [
- "Page number buttons use XDSButton (variant='ghost' for inactive, variant='primary' for active) for theming and swizzle compatibility.",
- "Prev/next buttons use XDSButton with variant='ghost' and icon-only mode.",
- 'Dot indicators use xds-pagination-dot className with size and active state classes for theme targeting.',
- 'Returns null when totalItems <= 0 or totalPages <= 0.',
- 'Also exports generatePageRange utility for computing visible page numbers with ellipsis.',
+ 'Pagination provides controls for navigating through pages of content. Use it to break large data sets into manageable pages, supporting multiple display variants for different density needs.',
+ bestPractices: [
+ { guidance: true, description: 'Choose the variant that best matches the information density of your layout — page numbers for precise navigation, dots for carousels.' },
+ { guidance: true, description: 'Provide totalItems or totalPages when the total is known so users can see how much content remains.' },
+ { guidance: false, description: 'Show Pagination when all items fit on a single page.' },
+ { guidance: false, description: 'Mix different Pagination variants within the same view.' },
],
},
};
@@ -236,28 +220,12 @@ export const docsZh = {
},
usage: {
description:
- '用于在内容页面之间导航的独立分页控件。支持多种显示变体,适用于已知总数或基于游标的分页。',
- features: [
- "五种显示变体:'pages'、'count'、'compact'、'dots'、'none'",
- '偏移量和游标分页:提供 totalItems/totalPages 用于已知总数,或 hasMore 用于游标分页',
- '每页大小选择器:提供 pageSizeOptions 时显示下拉菜单',
- '通过 generatePageRange 工具函数实现页码省略号截断',
- 'React transitions:onChangeAction 使用 useTransition 实现内置加载状态',
- "尺寸:'sm' 和 'md'",
- ],
- accessibility: [
- '根元素为 <nav>,带可配置的 aria-label。',
- '当前页按钮具有 aria-current="page"。',
- '上一页/下一页按钮具有描述性的 aria-label。',
- '省略号元素为 aria-hidden。',
- '所有交互元素均支持键盘访问。',
- ],
- notes: [
- "页码按钮使用 XDSButton(非活动状态 variant='ghost',活动状态 variant='primary')以兼容主题和 swizzle。",
- "上一页/下一页按钮使用 XDSButton,variant='ghost' 且仅图标模式。",
- '点指示器使用 xds-pagination-dot 类名,带有 size 和 active 状态类以支持主题定位。',
- '当 totalItems <= 0 或 totalPages <= 0 时返回 null。',
- '还导出 generatePageRange 工具函数,用于计算带省略号的可见页码。',
+ 'Pagination provides controls for navigating through pages of content. Use it to break large data sets into manageable pages, supporting multiple display variants for different density needs.',
+ bestPractices: [
+ { guidance: true, description: 'Choose the variant that best matches the information density of your layout — page numbers for precise navigation, dots for carousels.' },
+ { guidance: true, description: 'Provide totalItems or totalPages when the total is known so users can see how much content remains.' },
+ { guidance: false, description: 'Show Pagination when all items fit on a single page.' },
+ { guidance: false, description: 'Mix different Pagination variants within the same view.' },
],
},
};
@@ -266,28 +234,16 @@ export const docsZh = {
export const docsDense = {
description:
'Standalone pagination controls for navigating content pages. Supports multiple display variants + works w/ known totals or cursor-based pagination.',
- features: [
- "Five display variants: 'pages', 'count', 'compact', 'dots', 'none'",
- 'Offset + cursor-based pagination: totalItems/totalPages for known totals, hasMore for cursor-based',
- 'Page size selector: shows dropdown when pageSizeOptions provided',
- 'Ellipsis truncation for page numbers via generatePageRange utility',
- 'React transitions: onChangeAction uses useTransition for built-in loading state',
- "Sizes: 'sm' and 'md'",
- ],
- accessibility: [
- 'Root is <nav> w/ configurable aria-label.',
- 'Current page button has aria-current="page".',
- 'Prev/next buttons have descriptive aria-label.',
- 'Ellipsis elements are aria-hidden.',
- 'All interactive elements keyboard accessible.',
- ],
- notes: [
- "Page number buttons use XDSButton (variant='ghost' inactive, variant='primary' active) for theming + swizzle compatibility.",
- "Prev/next buttons use XDSButton w/ variant='ghost' + icon-only mode.",
- 'Dot indicators use xds-pagination-dot className w/ size + active state classes for theme targeting.',
- 'Returns null when totalItems <= 0 or totalPages <= 0.',
- 'Exports generatePageRange utility for computing visible page numbers w/ ellipsis.',
- ],
+ usage: {
+ description:
+ 'Pagination provides controls for navigating through pages of content. Use it to break large data sets into manageable pages, supporting multiple display variants for different density needs.',
+ bestPractices: [
+ { guidance: true, description: 'Choose the variant that best matches the information density of your layout — page numbers for precise navigation, dots for carousels.' },
+ { guidance: true, description: 'Provide totalItems or totalPages when the total is known so users can see how much content remains.' },
+ { guidance: false, description: 'Show Pagination when all items fit on a single page.' },
+ { guidance: false, description: 'Mix different Pagination variants within the same view.' },
+ ],
+ },
propDescriptions: {
page: 'Current page number (1-based).',
onChange: 'Called on page change.',
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index ff7a5236cb..9c84661238 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -141,28 +141,12 @@ export const docs = {
},
usage: {
description:
- 'A click-triggered popover for displaying interactive content anchored to a trigger element, implementing the button + dialog ARIA pattern. Use for secondary actions or supplementary information that does not warrant a full dialog — for hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
- features: [
- 'CSS Anchor Positioning for automatic placement relative to trigger elements',
- 'Popover API for top-layer rendering — no React portals needed',
- 'Controlled and uncontrolled modes',
- 'Light dismiss support (click outside or Escape to close)',
- 'Focus trap inside open popovers',
- 'ARIA button + dialog pattern applied automatically to trigger elements',
- 'Sibling mode via anchorRef for external trigger elements',
- 'Stable anchor wrapper immune to pressed-state transforms',
- ],
- accessibility: [
- 'Implements the button + dialog ARIA pattern: aria-haspopup, aria-expanded, and aria-controls are set on the trigger button automatically.',
- 'Traps focus inside the popover dialog while it is open.',
- 'Supports keyboard activation for role="button" elements (Enter and Space) in addition to native <button> click synthesis.',
- 'Keyboard: Escape closes the popover; Enter/Space open the popover when the trigger has focus; focus is trapped inside an open popover.',
- ],
- notes: [
- 'XDSPopover locates the trigger button inside children by searching for <button> or [role="button"] — the child tree must contain one. It applies click/keydown handlers and aria-haspopup, aria-expanded, aria-controls automatically.',
- 'XDSPopover uses an inline-flex anchor wrapper so that pressed-state transforms on the trigger (e.g. :active scale) do not shift the anchor position and cause popover jitter.',
- 'In sibling mode (anchorRef prop), XDSPopover attaches to an external ref rather than wrapping children — useful when the trigger and overlay are not parent/child.',
- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',
+ 'Popover displays interactive content anchored to a trigger element, activated on click. Use it for secondary actions or supplementary information that does not warrant a full dialog. For hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
+ bestPractices: [
+ { guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
+ { guidance: true, description: 'Provide a clear close affordance — light dismiss or an explicit close button — so users can easily return to the main content.' },
+ { guidance: false, description: 'Nest popovers inside other popovers, as it creates confusing focus and navigation patterns.' },
+ { guidance: false, description: 'Use a Popover for content that requires heavy user input — use a Dialog instead.' },
],
anatomy: [
{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -309,28 +293,17 @@ export const docsZh = {
},
usage: {
description:
- '一个点击触发的弹出框,用于显示锚定到触发元素的交互式内容,实现了按钮 + 对话框的 ARIA 模式。',
- features: [
- '使用 CSS 锚点定位,相对于触发元素自动放置',
- '使用 Popover API 进行顶层渲染——无需 React 传送门',
- '受控和非受控模式',
- '轻量关闭支持(点击外部或按 Escape 关闭)',
- '在打开的弹出框内捕获焦点',
- 'ARIA 按钮 + 对话框模式自动应用于触发元素',
- '通过 anchorRef 实现兄弟模式,用于外部触发元素',
- '稳定的锚点包装器,不受按压状态变换的影响',
- ],
- accessibility: [
- '实现了按钮 + 对话框的 ARIA 模式:aria-haspopup、aria-expanded 和 aria-controls 会自动设置在触发按钮上。',
- '在弹出框对话框打开时,焦点被捕获在其内部。',
- '支持 role="button" 元素的键盘激活(Enter 和 Space),以及原生 <button> 的点击合成。',
- 'Keyboard: Escape 关闭弹出框。当触发器获得焦点时,Enter/Space 打开弹出框。焦点被捕获在打开的弹出框内。',
+ 'Popover displays interactive content anchored to a trigger element, activated on click. Use it for secondary actions or supplementary information that does not warrant a full dialog. For hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
+ bestPractices: [
+ { guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
+ { guidance: true, description: 'Provide a clear close affordance — light dismiss or an explicit close button — so users can easily return to the main content.' },
+ { guidance: false, description: 'Nest popovers inside other popovers, as it creates confusing focus and navigation patterns.' },
+ { guidance: false, description: 'Use a Popover for content that requires heavy user input — use a Dialog instead.' },
],
- notes: [
- 'XDSPopover 通过搜索 <button> 或 [role="button"] 来定位子元素中的触发按钮——子树中必须包含一个。它会自动应用 click/keydown 处理程序以及 aria-haspopup、aria-expanded、aria-controls 属性。',
- 'XDSPopover 使用 inline-flex 锚点包装器,以确保触发器上的按压状态变换(如 :active scale)不会偏移锚点位置并导致弹出框抖动。',
- '在兄弟模式下(anchorRef 属性),XDSPopover 附加到外部 ref 而不是包裹子元素——适用于触发器和浮层不是父子关系的情况。',
- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',
+ anatomy: [
+ {name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
+ {name: 'Body', required: true, description: 'Main content area of the popover.'},
+ {name: 'Trigger Element', required: true, description: 'The button or link that toggles the popover open.'},
],
},
};
@@ -339,29 +312,21 @@ export const docsZh = {
export const docsDense = {
description:
'Click-triggered popover displaying interactive content anchored to trigger element; implements button+dialog ARIA pattern.',
- features: [
- 'CSS Anchor Positioning for auto placement relative to trigger',
- 'Popover API for top-layer rendering; no React portals needed',
- 'Controlled + uncontrolled modes',
- 'Light dismiss support (click outside or Escape to close)',
- 'Focus trap inside open popovers',
- 'ARIA button+dialog pattern auto-applied to trigger elements',
- 'Sibling mode via anchorRef for external trigger elements',
- 'Stable anchor wrapper immune to pressed-state transforms',
- ],
- notes: [
- 'XDSPopover finds trigger button in children by searching <button> or [role="button"]; child tree must contain one. Applies click/keydown handlers + aria-haspopup, aria-expanded, aria-controls automatically.',
- 'Uses inline-flex anchor wrapper so pressed-state transforms (e.g. :active scale) don\'t shift anchor position causing jitter.',
- 'Sibling mode (anchorRef prop) attaches to external ref instead of wrapping children; useful when trigger+overlay not parent/child.',
- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',
- ],
- accessibility: [
- 'Implements button+dialog ARIA pattern: aria-haspopup, aria-expanded, aria-controls set on trigger button automatically.',
- 'Traps focus inside popover dialog while open.',
- 'Supports keyboard activation for role="button" elements (Enter+Space) plus native <button> click synthesis.',
- ],
- keyboard:
- 'Escape closes popover. Enter/Space open popover when trigger focused. Focus trapped inside open popover.',
+ usage: {
+ description:
+ 'Popover displays interactive content anchored to a trigger element, activated on click. Use it for secondary actions or supplementary information that does not warrant a full dialog. For hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',
+ bestPractices: [
+ { guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
+ { guidance: true, description: 'Provide a clear close affordance — light dismiss or an explicit close button — so users can easily return to the main content.' },
+ { guidance: false, description: 'Nest popovers inside other popovers, as it creates confusing focus and navigation patterns.' },
+ { guidance: false, description: 'Use a Popover for content that requires heavy user input — use a Dialog instead.' },
+ ],
+ anatomy: [
+ {name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
+ {name: 'Body', required: true, description: 'Main content area of the popover.'},
+ {name: 'Trigger Element', required: true, description: 'The button or link that toggles the popover open.'},
+ ],
+ },
components: [
{
name: 'XDSPopover',
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index f064ba986b..5edb1864b1 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -117,21 +117,11 @@ export const docs = {
],
usage: {
description:
- 'Structured filter bar where each token represents a filter (field + operator + value). Users select fields from a typeahead dropdown, configure operators and values in an edit popover, and manage filters as removable tokens. Use for complex multi-dimensional filtering; for simple single-field search, use a text input instead.',
- features: [
- 'Typeahead field selection with search and aliases',
- 'Edit popover with field, operator, and value selectors',
- 'Support for 13 value types: string, integer, float, enum, date, time, and more',
- 'Token-based display with click-to-edit and remove',
- 'Imperative API for focus/blur control via ref',
- 'Read-only mode for displaying filters without editing',
- ],
- accessibility: [
- 'Built on XDSTokenizer which provides combobox pattern with aria-expanded and aria-autocomplete.',
- 'Filter tokens have accessible labels with field name, operator, and value.',
- 'Edit popover uses XDSPopover with focus trapping and light dismiss.',
- 'Clear all button has accessible label.',
- 'Keyboard: Type to search fields; Enter to select; Click token to edit; Backspace on empty input removes last filter; Escape closes popover.',
+ 'PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.',
+ bestPractices: [
+ { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
+ { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
+ { guidance: false, description: 'Use PowerSearch for simple keyword searches — a standard text input is more appropriate for single-field lookups.' },
],
},
};
@@ -253,21 +243,11 @@ export const docsZh = {
],
usage: {
description:
- '结构化过滤栏,每个令牌代表一个过滤器(字段 + 运算符 + 值)。用户从预输入下拉菜单中选择字段,在编辑弹出窗口中配置运算符和值,并将过滤器作为可移除的令牌进行管理。',
- features: [
- '预输入字段选择,支持搜索和别名',
- '编辑弹出窗口,包含字段、运算符和值选择器',
- '支持 13 种值类型:字符串、整数、浮点数、枚举、日期、时间等',
- '令牌式显示,支持点击编辑和移除',
- '通过 ref 提供命令式 API 控制聚焦/失焦',
- '只读模式,显示过滤器但不允许编辑',
- ],
- accessibility: [
- '基于 XDSTokenizer 构建,提供 combobox 模式,包含 aria-expanded 和 aria-autocomplete。',
- '过滤器令牌具有包含字段名、运算符和值的无障碍标签。',
- '编辑弹出窗口使用 XDSPopover,支持焦点捕获和轻量关闭。',
- '清除全部按钮具有无障碍标签。',
- 'Keyboard: 输入搜索字段;回车选择;点击令牌编辑;空输入时退格删除最后一个过滤器;Escape 关闭弹出窗口',
+ 'PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.',
+ bestPractices: [
+ { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
+ { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
+ { guidance: false, description: 'Use PowerSearch for simple keyword searches — a standard text input is more appropriate for single-field lookups.' },
],
},
};
@@ -276,22 +256,15 @@ export const docsZh = {
export const docsDense = {
description:
'Structured filter bar where each token represents filter (field+operator+value). Users select fields from typeahead dropdown, configure operators+values in edit popover, manage filters as removable tokens.',
- features: [
- 'Typeahead field selection w/ search + aliases',
- 'Edit popover w/ field, operator, value selectors',
- 'Support for 13 value types: string, integer, float, enum, date, time, more',
- 'Token-based display w/ click-to-edit + remove',
- 'Imperative API for focus/blur control via ref',
- 'Read-only mode for displaying filters w/o editing',
- ],
- accessibility: [
- 'Built on XDSTokenizer providing combobox pattern w/ aria-expanded + aria-autocomplete.',
- 'Filter tokens have accessible labels w/ field name, operator, value.',
- 'Edit popover uses XDSPopover w/ focus trapping + light dismiss.',
- 'Clear all button has accessible label.',
- ],
- keyboard:
- 'Type to search fields; Enter to select; Click token to edit; Backspace on empty input removes last filter; Escape closes popover',
+ usage: {
+ description:
+ 'PowerSearch is a structured filter bar where each token represents a field, operator, and value. Use it for complex multi-dimensional filtering when users need to combine multiple search criteria. For simple single-field search, use a text input instead.',
+ bestPractices: [
+ { guidance: true, description: 'Define clear, descriptive field names and aliases so users can quickly find the filter they need.' },
+ { guidance: true, description: 'Provide a result count to give users feedback on how their filters affect the data set.' },
+ { guidance: false, description: 'Use PowerSearch for simple keyword searches — a standard text input is more appropriate for single-field lookups.' },
+ ],
+ },
propDescriptions: {
config: 'Configuration defining available fields, operators, value types.',
filters: 'Currently active filters.',
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index d9a024f20c..31a16cf971 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -67,22 +67,11 @@ export const docs = {
},
usage: {
description:
- 'A progress bar for displaying determinate or indeterminate progress of a process. Use for showing completion progress of known-length operations or indicating indeterminate loading states with a known container size.',
- features: [
- 'Supports four semantic color variants: accent, positive, warning, negative',
- 'Supports custom value label formatter via formatValueLabel',
- ],
- accessibility: [
- 'Determinate: uses role="meter" with aria-valuenow, aria-valuemin, aria-valuemax',
- 'Indeterminate: uses role="progressbar" without value attributes',
- 'Label is always connected via aria-labelledby',
- 'aria-valuetext provides human-readable value description (determinate only)',
- 'Indeterminate animation respects prefers-reduced-motion',
- ],
- notes: [
- 'ProgressBar is intentionally minimal — it handles the meter/track and an optional value label. For additional context like descriptions, status icons, or custom label placements, compose them alongside the bar using layout components.',
- 'Do not add props for label placement, progress descriptions, or embedded icons. These are composition concerns, not meter concerns.',
- 'Single track height: 8px',
+ 'ProgressBar displays the completion progress of a process as a horizontal bar. Use it for determinate operations where the duration is known, or as an indeterminate indicator when progress cannot be calculated.',
+ bestPractices: [
+ { guidance: true, description: 'Use a determinate bar when the total amount of work is known, and switch to indeterminate only when it is not.' },
+ { guidance: true, description: 'Choose a semantic color variant that reflects the nature of the process — accent for neutral, positive for success, warning or negative for alerts.' },
+ { guidance: false, description: 'Add custom label placements or status icons inside the bar — compose them alongside using layout components.' },
],
},
};
@@ -154,23 +143,11 @@ export const docsZh = {
},
usage: {
description:
- '用于显示确定或不确定进度的进度条组件。',
- features: [
- '确定模式使用 role="meter",配合 aria-valuenow、aria-valuemin 和 aria-valuemax',
- '不确定模式使用 role="progressbar",不包含值属性',
- '标签始终通过 aria-labelledby 关联',
- 'aria-valuetext 提供人类可读的值描述(仅限确定模式)',
- '不确定动画遵循 prefers-reduced-motion 偏好设置',
- '支持四种语义颜色变体:accent、positive、warning、negative',
- '单一轨道高度:8px',
- '支持通过 formatValueLabel 自定义值标签格式化器',
- ],
- accessibility: [
- '确定模式:使用 role="meter",配合 aria-valuenow、aria-valuemin、aria-valuemax',
- '不确定模式:使用 role="progressbar",不包含值属性',
- '标签始终通过 aria-labelledby 关联',
- 'aria-valuetext 提供人类可读的值描述(仅限确定模式)',
- '不确定动画遵循 prefers-reduced-motion 偏好设置',
+ 'ProgressBar displays the completion progress of a process as a horizontal bar. Use it for determinate operations where the duration is known, or as an indeterminate indicator when progress cannot be calculated.',
+ bestPractices: [
+ { guidance: true, description: 'Use a determinate bar when the total amount of work is known, and switch to indeterminate only when it is not.' },
+ { guidance: true, description: 'Choose a semantic color variant that reflects the nature of the process — accent for neutral, positive for success, warning or negative for alerts.' },
+ { guidance: false, description: 'Add custom label placements or status icons inside the bar — compose them alongside using layout components.' },
],
},
};
@@ -179,23 +156,15 @@ export const docsZh = {
export const docsDense = {
description:
'Progress bar for displaying determinate or indeterminate progress.',
- features: [
- 'Determinate mode uses role="meter" w/ aria-valuenow, aria-valuemin, aria-valuemax',
- 'Indeterminate mode uses role="progressbar" w/o value attributes',
- 'Label always connected via aria-labelledby',
- 'aria-valuetext provides human-readable value description (determinate only)',
- 'Indeterminate animation respects prefers-reduced-motion',
- 'Supports four semantic color variants: accent, positive, warning, negative',
- 'Single track height: 8px',
- 'Supports custom value label formatter via formatValueLabel',
- ],
- accessibility: [
- 'Determinate: uses role="meter" w/ aria-valuenow, aria-valuemin, aria-valuemax',
- 'Indeterminate: uses role="progressbar" w/o value attributes',
- 'Label always connected via aria-labelledby',
- 'aria-valuetext provides human-readable value description (determinate only)',
- 'Indeterminate animation respects prefers-reduced-motion',
- ],
+ usage: {
+ description:
+ 'ProgressBar displays the completion progress of a process as a horizontal bar. Use it for determinate operations where the duration is known, or as an indeterminate indicator when progress cannot be calculated.',
+ bestPractices: [
+ { guidance: true, description: 'Use a determinate bar when the total amount of work is known, and switch to indeterminate only when it is not.' },
+ { guidance: true, description: 'Choose a semantic color variant that reflects the nature of the process — accent for neutral, positive for success, warning or negative for alerts.' },
+ { guidance: false, description: 'Add custom label placements or status icons inside the bar — compose them alongside using layout components.' },
+ ],
+ },
propDescriptions: {
label: 'Accessible label (required).',
value: 'Current value (ignored when indeterminate).',
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index db206384a5..cef2ee0a9e 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -144,25 +144,12 @@ export const docs = {
],
usage: {
description:
- 'A radio group component for single-value selection from a list of options. Use when presenting a limited set of mutually exclusive choices where only one can be selected. For multiple selections use CheckboxList; for long option lists consider Selector.',
- features: [
- 'Supports vertical and horizontal layouts',
- 'Size variants: sm (18px radio, 20px wrapper) and md (22px radio, 24px wrapper)',
- 'Optional description text per item',
- 'startContent and endContent slots on each item',
- 'Supports disabling the entire group or individual items',
- 'Field integration via XDSField for label, description, required/optional, and status messaging',
- ],
- accessibility: [
- 'Uses native <input type="radio"> with proper role="radiogroup" and ARIA attributes',
- ],
- notes: [
- 'XDSRadioList creates a RadioListContext that provides name, value, onChange, isDisabled, isRequired, size, and status to child items',
- 'XDSRadioListItem must be used within an XDSRadioList — throws if context is missing',
- 'Uses a hidden native <input type="radio"> with a custom visual overlay for consistent styling',
- 'Focus outline uses the standard XDS focus outline token with 2px offset',
- 'Hover states use color-mix() for consistent overlay tinting',
- 'Size variants match CheckboxInput dimensions for visual consistency',
+ 'RadioList presents a group of mutually exclusive options for single-value selection. Use it when users must choose exactly one option from a small, visible set. For multiple selections use CheckboxList; for long option lists consider Selector.',
+ bestPractices: [
+ { guidance: true, description: 'Keep the number of options small enough to display without scrolling — typically 2 to 7 choices.' },
+ { guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },
+ { guidance: false, description: 'Use a RadioList when more than one selection is needed — switch to CheckboxList for multi-select scenarios.' },
+ { guidance: false, description: 'Use a RadioList for very long lists of options — use a Selector or Combobox for discoverability.' },
],
anatomy: [
{name: 'Header', required: false, description: 'Optional heading above the radio list.'},
@@ -317,23 +304,17 @@ export const docsZh = {
],
usage: {
description:
- '用于从选项列表中进行单值选择的单选按钮组组件。',
- features: [
- '无障碍 - 使用原生 <input type="radio">,配合正确的 role="radiogroup" 和 ARIA 属性',
- '方向 - 支持垂直和水平布局',
- '尺寸 - sm(18px 单选按钮,20px 容器)和 md(22px 单选按钮,24px 容器)',
- '描述 - 每个选项可选的描述文本',
- '自定义内容 - 每个选项上的 startContent 和 endContent 插槽',
- '禁用状态 - 支持禁用整个组或单个选项',
- '字段集成 - 使用 XDSField 提供标签、描述、必填/可选和状态消息',
+ 'RadioList presents a group of mutually exclusive options for single-value selection. Use it when users must choose exactly one option from a small, visible set. For multiple selections use CheckboxList; for long option lists consider Selector.',
+ bestPractices: [
+ { guidance: true, description: 'Keep the number of options small enough to display without scrolling — typically 2 to 7 choices.' },
+ { guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },
+ { guidance: false, description: 'Use a RadioList when more than one selection is needed — switch to CheckboxList for multi-select scenarios.' },
+ { guidance: false, description: 'Use a RadioList for very long lists of options — use a Selector or Combobox for discoverability.' },
],
- notes: [
- 'XDSRadioList 创建一个 RadioListContext,向子项提供 name、value、onChange、isDisabled、isRequired、size 和 status',
- 'XDSRadioListItem 必须在 XDSRadioList 内部使用——如果缺少上下文会抛出错误',
- '使用隐藏的原生 <input type="radio"> 配合自定义视觉覆盖层以保持样式一致性',
- '焦点轮廓使用标准 XDS 焦点轮廓令牌,偏移量为 2px',
- '悬停状态使用 color-mix() 实现一致的覆盖层着色',
- '尺寸变体与 CheckboxInput 的尺寸匹配,保持视觉一致性',
+ anatomy: [
+ {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
+ {name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},
+ {name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},
],
},
};
@@ -342,23 +323,21 @@ export const docsZh = {
export const docsDense = {
description:
'Radio group component for single-value selection from list of options.',
- features: [
- 'Accessible; uses native <input type="radio"> w/ proper role="radiogroup" + ARIA attributes',
- 'Orientation; supports vertical + horizontal layouts',
- 'Sizes; sm (18px radio, 20px wrapper) + md (22px radio, 24px wrapper)',
- 'Descriptions; optional description text per item',
- 'Custom content; startContent + endContent slots on each item',
- 'Disabled state; supports disabling entire group or individual items',
- 'Field integration; uses XDSField for label, description, required/optional, status messaging',
- ],
- notes: [
- 'XDSRadioList creates RadioListContext providing name, value, onChange, isDisabled, isRequired, size, status to child items',
- 'XDSRadioListItem must be within XDSRadioList; throws if context missing',
- 'Uses hidden native <input type="radio"> w/ custom visual overlay for consistent styling',
- 'Focus outline uses standard XDS focus outline token w/ 2px offset',
- 'Hover states use color-mix() for consistent overlay tinting',
- 'Size variants match CheckboxInput dimensions for visual consistency',
- ],
+ usage: {
+ description:
+ 'RadioList presents a group of mutually exclusive options for single-value selection. Use it when users must choose exactly one option from a small, visible set. For multiple selections use CheckboxList; for long option lists consider Selector.',
+ bestPractices: [
+ { guidance: true, description: 'Keep the number of options small enough to display without scrolling — typically 2 to 7 choices.' },
+ { guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },
+ { guidance: false, description: 'Use a RadioList when more than one selection is needed — switch to CheckboxList for multi-select scenarios.' },
+ { guidance: false, description: 'Use a RadioList for very long lists of options — use a Selector or Combobox for discoverability.' },
+ ],
+ anatomy: [
+ {name: 'Header', required: false, description: 'Optional heading above the radio list.'},
+ {name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},
+ {name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},
+ ],
+ },
components: [
{
name: 'XDSRadioList',
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index 1181460aea..9d353bc6eb 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -70,13 +70,11 @@ export const docs = {
},
usage: {
description:
- 'Container with background variants for creating visually distinct regions on a page. Automatically escapes parent container padding for edge-to-edge fills. Prefer sections over cards as the default page structure; use cards only when stronger visual distinction is needed.',
- features: [
- 'Background variants: section, transparent, and wash',
- 'Automatically escapes parent container padding for edge-to-edge fills',
- 'Supports divider borders on any combination of sides (top, bottom, start, end)',
- 'Flexible sizing via SizeValue for width, height, maxWidth, and minHeight',
- 'Supports `padding={0}` for edge-to-edge content',
+ 'Section is a container with background variants for creating visually distinct regions on a page. It automatically escapes parent padding for edge-to-edge fills. Use sections as the default page structure; reach for cards only when stronger visual distinction is needed.',
+ bestPractices: [
+ { guidance: true, description: 'Use dividers to separate adjacent sections when background variants alone do not provide enough visual contrast.' },
+ { guidance: true, description: 'Default to the section variant for standard content regions; reserve wash for highlighted or grouped areas.' },
+ { guidance: false, description: 'Wrap content in a Section and a Card together — choose one container type to avoid redundant nesting.' },
],
},
};
@@ -151,13 +149,11 @@ export const docsZh = {
},
usage: {
description:
- '带有背景变体的容器,用于创建视觉上可区分的区域,自动突破父容器内边距实现全宽填充。',
- features: [
- '背景变体:section、transparent 和 wash',
- '自动突破父容器内边距实现全宽填充',
- '支持在任意边的组合上设置分隔线边框(top、bottom、start、end)',
- '通过 SizeValue 灵活设置宽度、高度、最大宽度和最小高度',
- '支持 `padding={0}` 实现全宽内容',
+ 'Section is a container with background variants for creating visually distinct regions on a page. It automatically escapes parent padding for edge-to-edge fills. Use sections as the default page structure; reach for cards only when stronger visual distinction is needed.',
+ bestPractices: [
+ { guidance: true, description: 'Use dividers to separate adjacent sections when background variants alone do not provide enough visual contrast.' },
+ { guidance: true, description: 'Default to the section variant for standard content regions; reserve wash for highlighted or grouped areas.' },
+ { guidance: false, description: 'Wrap content in a Section and a Card together — choose one container type to avoid redundant nesting.' },
],
},
};
@@ -166,13 +162,15 @@ export const docsZh = {
export const docsDense = {
description:
'Container w/ background variants for creating visually distinct regions; auto-escapes parent container padding for edge-to-edge fills.',
- features: [
- 'Background variants: section, transparent, wash',
- 'Auto-escapes parent container padding for edge-to-edge fills',
- 'Supports divider borders on any combination of sides (top, bottom, start, end)',
- 'Flexible sizing via SizeValue for width, height, maxWidth, minHeight',
- 'Full-bleed mode removes internal padding for edge-to-edge content',
- ],
+ usage: {
+ description:
+ 'Section is a container with background variants for creating visually distinct regions on a page. It automatically escapes parent padding for edge-to-edge fills. Use sections as the default page structure; reach for cards only when stronger visual distinction is needed.',
+ bestPractices: [
+ { guidance: true, description: 'Use dividers to separate adjacent sections when background variants alone do not provide enough visual contrast.' },
+ { guidance: true, description: 'Default to the section variant for standard content regions; reserve wash for highlighted or grouped areas.' },
+ { guidance: false, description: 'Wrap content in a Section and a Card together — choose one container type to avoid redundant nesting.' },
+ ],
+ },
propDescriptions: {
variant: 'Background variant applied to section container.',
width: 'Section width; number interpreted as pixels, string used as-is.',
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 42225f8ad5..6d85d0f290 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -100,32 +100,12 @@ export const docs = {
],
usage: {
description:
- 'Segmented button group for single selection with radio group semantics. Visually resembles a tab bar but controls a value, not a view. Use for switching between a small set of mutually exclusive views or modes when all options should be visible at once. For two-state toggles, use ToggleButton; for page navigation, use Tabs.',
- features: [
- 'Animated indicator with raised surface background and box-shadow',
- 'Icon + label or icon-only items (isLabelHidden hides label visually, keeps it as aria-label)',
- 'Size variants: sm (compact for toolbars), md (default), lg (larger touch targets)',
- 'Disabled state: entire group or individual items via aria-disabled (maintains focusability)',
- ],
- accessibility: [
- 'Container has role="radiogroup" with aria-label from the label prop (never rendered visually)',
- 'Items have role="radio" with aria-checked indicating selection state',
- 'Roving tabindex: selected item has tabIndex=0, others have tabIndex=-1',
- 'Arrow keys navigate and select simultaneously (radio group pattern)',
- 'Disabled items use aria-disabled (not native disabled) to maintain focusability',
- 'Icon-only items use isLabelHidden — label becomes aria-label',
- 'Keyboard: ArrowRight/ArrowLeft navigate and select (wrapping); Home/End jump to first/last item; only the selected item is in the tab order.',
- ],
- notes: [
- 'Controlled-only — no uncontrolled mode in v1',
- 'Horizontal-only — no vertical orientation in v1',
- 'Deselection not allowed (radio semantics — always one selected)',
- 'Uses aria-disabled instead of native disabled to maintain keyboard focusability',
- 'Keyboard navigation skips disabled items',
- 'Track background uses --color-neutral, selected indicator uses --color-background-surface with --shadow-low',
- 'label prop on XDSSegmentedControl is aria-only (like XDSTabList aria-label), never rendered visually',
- 'Context-based communication: XDSSegmentedControlContext passes value/onChange/size/isDisabled from parent to children',
- 'Hover state: unselected items show overlay on hover with @media (hover: hover) guard',
+ 'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
+ bestPractices: [
+ {guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
+ {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
+ {guidance: false, description: 'Use for page-level navigation — use Tabs instead.'},
+ {guidance: false, description: 'Use for simple on/off states — use ToggleButton instead.'},
],
},
};
@@ -162,71 +142,28 @@ export const docsZh = {
],
usage: {
description:
- '分段按钮组,用于单选,具有单选组语义。外观类似标签栏,但控制的是值而非视图。',
- features: [
- '基于上下文通信:XDSSegmentedControlContext 将 value/onChange/size/isDisabled 从父组件传递给子组件',
- '单选组语义:role="radiogroup" 配合 role="radio" 子项和 aria-checked',
- '漫游焦点:仅选中项可通过 Tab 访问(tabIndex=0),其余为 tabIndex=-1',
- '键盘导航:ArrowLeft/ArrowRight 导航并选中,Home/End 跳转到首尾,循环切换',
- '动画指示器:选中项具有带 box-shadow 的凸起表面背景',
- '图标+文本或纯图标项(isLabelHidden 隐藏文本,保留为 aria-label)',
- '尺寸变体:sm(紧凑,适用于工具栏)、md(默认)、lg(更大触摸目标)',
- '禁用状态:可禁用整组或单个项,使用 aria-disabled 保持可聚焦性',
- '悬停状态:未选中项悬停时显示覆盖层,使用 @media (hover: hover) 保护',
- ],
- accessibility: [
- '容器具有 role="radiogroup",aria-label 来自 label 属性(不会渲染为可见内容)',
- '子项具有 role="radio",aria-checked 表示选中状态',
- '漫游焦点:选中项 tabIndex=0,其余 tabIndex=-1',
- '方向键同时导航和选中(单选组模式)',
- '禁用项使用 aria-disabled(非原生 disabled)以保持可聚焦性',
- '纯图标项使用 isLabelHidden,label 变为 aria-label',
- 'Keyboard: ArrowRight/ArrowLeft 导航并选中(循环)。Home/End 跳转到首尾项。仅选中项在 Tab 顺序中。',
- ],
- notes: [
- '仅受控模式,v1 无非受控模式',
- '仅水平方向,v1 无垂直方向',
- '不允许取消选中(单选语义,始终有一项选中)',
- '使用 aria-disabled 替代原生 disabled 以保持键盘可聚焦性',
- '键盘导航会跳过禁用项',
- '轨道背景使用 --color-neutral,选中指示器使用 --color-background-surface 配合 --shadow-low',
- 'XDSSegmentedControl 的 label 属性仅用于 aria(类似 XDSTabList 的 aria-label),不会渲染为可见内容',
+ 'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
+ bestPractices: [
+ {guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
+ {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
+ {guidance: false, description: 'Use for page-level navigation — use Tabs instead.'},
+ {guidance: false, description: 'Use for simple on/off states — use ToggleButton instead.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'segmented button group; single selection w/ radio group semantics; resembles tab bar but controls value not view',
- features: [
- 'context-based: XDSSegmentedControlContext passes value/onChange/size/isDisabled to children',
- 'radio group semantics: role="radiogroup" w/ role="radio" items+aria-checked',
- 'roving tabindex: selected=tabIndex=0; others tabIndex=-1',
- 'keyboard: ArrowLeft/Right navigate+select; Home/End first/last; wraps',
- 'animated indicator: selected item raised surface bg w/ box-shadow',
- 'icon+label or icon-only (isLabelHidden hides label visually; keeps aria-label)',
- 'sizes: sm (compact/toolbars) md (default) lg (larger touch)',
- 'disabled: group or individual via aria-disabled (maintains focusability)',
- 'hover: unselected items show overlay; @media (hover: hover) guard',
- ],
- accessibility: [
- 'container: role="radiogroup" w/ aria-label from label prop (never rendered)',
- 'items: role="radio" w/ aria-checked for selection',
- 'roving tabindex: selected=tabIndex=0; others=-1',
- 'arrows navigate+select simultaneously (radio group pattern)',
- 'disabled items use aria-disabled not native disabled; maintains focusability',
- 'icon-only: isLabelHidden; label becomes aria-label',
- ],
- keyboard: 'ArrowRight/Left navigate+select (wrap). Home/End first/last. Only selected in tab order.',
- notes: [
- 'controlled-only; no uncontrolled v1',
- 'horizontal-only; no vertical v1',
- 'no deselection (radio semantics; always one selected)',
- 'aria-disabled not native disabled; maintains keyboard focusability',
- 'keyboard nav skips disabled items',
- 'track bg: --color-neutral; selected indicator: --color-background-surface+--shadow-low',
- 'label prop aria-only (like XDSTabList aria-label); never rendered',
- ],
+ usage: {
+ description:
+ 'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
+ bestPractices: [
+ {guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
+ {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
+ {guidance: false, description: 'Use for page-level navigation — use Tabs instead.'},
+ {guidance: false, description: 'Use for simple on/off states — use ToggleButton instead.'},
+ ],
+ },
propDescriptions: {
value: 'currently selected value (controlled)',
onChange: 'callback on segment selection',
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index b5a594c562..b07d250ba0 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -125,19 +125,12 @@ export const docs = {
],
usage: {
description:
- 'Dropdown selector for choosing from a list of options, following XDS input conventions with label, status, and field props. Use for presenting 3\u201320 options in forms or settings; for 20+ options, use a searchable variant. Do not use for triggering actions \u2014 use Dropdown Menu instead.',
- features: [
- 'Supports string items (auto-converted to {value, label}), object items with optional icon and disabled state, dividers, and labeled sections',
- 'Custom item rendering via children render prop and XDSSelectorItem helper',
- 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',
- 'Size variants: sm, md, lg',
- ],
- accessibility: [
- 'Uses role="combobox" on the trigger button.',
- 'Dropdown uses role="listbox".',
- 'Section groups use role="group".',
- 'aria-activedescendant tracks the focused option.',
- 'Keyboard: \u2191\u2193 navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.',
+ 'A dropdown selector for choosing a single option from a list. Use Selector in forms or settings when presenting 3–20 options. For triggering actions instead of selecting values, use a Dropdown Menu.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a visible label so users understand what they are selecting.'},
+ {guidance: true, description: 'Use sections and dividers to organize long lists of related options.'},
+ {guidance: false, description: 'Use for action menus — use Dropdown Menu for triggering commands or navigation.'},
+ {guidance: false, description: 'Use when there are only two options — use a SegmentedControl or radio buttons instead.'},
],
anatomy: [
{name: 'Label', required: false, description: 'Text label displayed above the selector.'},
@@ -274,45 +267,44 @@ export const docsZh = {
],
usage: {
description:
- '用于从选项列表中进行选择的下拉选择器。遵循 XDS 输入规范,支持标签、状态和字段属性。',
- features: [
- '支持字符串选项(自动转换为 {value, label})、带可选图标和禁用状态的对象选项、分隔线和带标签的分组',
- '通过 children 渲染函数和 XDSSelectorItem 辅助组件实现自定义选项渲染',
- '集成 XDS 字段规范:label、description、isRequired、isOptional、isLabelHidden、status',
- '尺寸变体:sm、md、lg',
- '完整的键盘导航,支持输入快速定位',
- '无障碍 - 触发器使用 role="combobox",下拉菜单使用 role="listbox",分组使用 role="group",焦点追踪使用 aria-activedescendant',
+ 'A dropdown selector for choosing a single option from a list. Use Selector in forms or settings when presenting 3–20 options. For triggering actions instead of selecting values, use a Dropdown Menu.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a visible label so users understand what they are selecting.'},
+ {guidance: true, description: 'Use sections and dividers to organize long lists of related options.'},
+ {guidance: false, description: 'Use for action menus — use Dropdown Menu for triggering commands or navigation.'},
+ {guidance: false, description: 'Use when there are only two options — use a SegmentedControl or radio buttons instead.'},
],
- accessibility: [
- '触发按钮使用 role="combobox"。',
- '下拉菜单使用 role="listbox"。',
- '分组使用 role="group"。',
- 'aria-activedescendant 追踪当前聚焦的选项。',
- 'Keyboard: ↑↓ 导航,Enter/Space 选择,Escape 关闭,Home/End 跳转,A-Z 输入快速定位。',
+ anatomy: [
+ {name: 'Label', required: false, description: 'Text label displayed above the selector.'},
+ {name: 'Placeholder', required: false, description: 'Hint text shown when no value is selected.'},
+ {name: 'Description', required: false, description: 'Helper text providing additional context.'},
+ {name: 'Left Icon', required: false, description: 'Icon displayed to the left of the selected value.'},
+ {name: 'Value', required: true, description: 'The currently selected item displayed in the selector.'},
+ {name: 'List', required: true, description: 'The dropdown list of selectable options.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description:
- 'Dropdown selector for choosing from list of options. Follows XDS input conventions w/ label, status, field props.',
- features: [
- 'Supports string items (auto-converted to {value, label}), object items w/ optional icon + disabled state, dividers, labeled sections',
- 'Custom item rendering via children render prop + XDSSelectorItem helper',
- 'Integrates w/ XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',
- 'Size variants: sm, md, lg',
- 'Full keyboard navigation w/ typeahead support',
- 'Accessible; role="combobox" trigger, role="listbox" dropdown, role="group" for sections, aria-activedescendant for focus',
- ],
- keyboard:
- '\u2191\u2193 navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.',
- accessibility: [
- 'Uses role="combobox" on trigger button.',
- 'Dropdown uses role="listbox".',
- 'Section groups use role="group".',
- 'aria-activedescendant tracks focused option.',
- ],
+ usage: {
+ description:
+ 'A dropdown selector for choosing a single option from a list. Use Selector in forms or settings when presenting 3–20 options. For triggering actions instead of selecting values, use a Dropdown Menu.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a visible label so users understand what they are selecting.'},
+ {guidance: true, description: 'Use sections and dividers to organize long lists of related options.'},
+ {guidance: false, description: 'Use for action menus — use Dropdown Menu for triggering commands or navigation.'},
+ {guidance: false, description: 'Use when there are only two options — use a SegmentedControl or radio buttons instead.'},
+ ],
+ anatomy: [
+ {name: 'Label', required: false, description: 'Text label displayed above the selector.'},
+ {name: 'Placeholder', required: false, description: 'Hint text shown when no value is selected.'},
+ {name: 'Description', required: false, description: 'Helper text providing additional context.'},
+ {name: 'Left Icon', required: false, description: 'Icon displayed to the left of the selected value.'},
+ {name: 'Value', required: true, description: 'The currently selected item displayed in the selector.'},
+ {name: 'List', required: true, description: 'The dropdown list of selectable options.'},
+ ],
+ },
components: [
{
name: 'XDSSelector',
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index f106dc2418..b8c6a464c9 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -239,32 +239,12 @@ export const docs = {
],
usage: {
description:
- 'Sidebar navigation component for application pages, supporting sections, nested items, selected state, icons, and collapsible sidebar. Left nav is the default recommendation for 5+ navigation items or complex grouping. Do not use for filter-primary tools \u2014 use tabs or filter buttons instead.',
- features: [
- 'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',
- 'Smart header interaction boundary logic \u2014 links and menu trigger coexist without overlap',
- 'Nested items via children on XDSSideNavItem',
- 'Selected state with optional alternate icon for filled/outline variants',
- 'Section grouping with optional title, subtitle, and end content',
- 'Collapsible sidebar via collapsible prop \u2014 collapses to icon-only toolbar, uncontrolled or controlled',
- 'Resizable sidebar via resizable prop \u2014 drag handle at inline-end edge, pointer-based resize with min/max constraints',
- 'Heading text overflow detection with tooltip \u2014 shows full text on hover when truncated',
- 'Header end content slot for badges, status indicators, or action buttons',
- ],
- accessibility: [
- '<nav aria-label="Side navigation"> wraps the entire component',
- 'aria-current="page" is applied to the selected item',
- 'Sections use role="group" with aria-labelledby pointing to the section title',
- 'isHeaderHidden visually hides the section title while keeping it accessible to screen readers',
- 'Keyboard: Tab through items, Enter/Space to activate links',
- ],
- notes: [
- 'When used inside XDSAppShell alongside XDSTopNav, omit XDSSideNavHeading \u2014 the TopNav already provides app identity and including the header would duplicate it.',
- 'Without a TopNav, include XDSSideNavHeading to provide app identity.',
- 'Header interaction model: headingHref only \u2192 whole header is one link; headingHref + superheadingHref, no menu \u2192 each text is an independent link; menu only, no hrefs \u2192 whole header is the popover trigger; menu + hrefs \u2192 links are independent <a> elements, chevron/remaining area is the popover trigger.',
- 'Depends on useXDSPopover for the header menu popover and XDSIcon for rendering icon components in nav items.',
- 'XDSSideNavCollapseButton renders as an icon-only ghost button by default. Place it in footerIcons, header, or outside the sidenav (pass sideNavRef).',
- 'useXDSSideNavCollapse hook exposes { isCollapsed, toggle, isCollapsible } for custom collapse controls.',
+ 'A sidebar navigation component for organizing application pages with sections, nested items, and icons. Use SideNav as the primary navigation when an app has 5 or more destinations or requires hierarchical grouping.',
+ bestPractices: [
+ {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
+ {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+ {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.'},
+ {guidance: false, description: 'Use for filtering content — use tabs or filter buttons instead.'},
],
anatomy: [
{name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
@@ -514,64 +494,38 @@ export const docsZh = {
],
usage: {
description:
- '应用页面的侧边栏导航组件。支持分组、嵌套项、选中状态、图标和可折叠侧边栏。',
- features: [
- '五区域布局:header、topContent、children(可滚动)、footer、footerIcons',
- '智能头部交互边界逻辑——链接和菜单触发器共存而不重叠',
- '通过 XDSSideNavItem 的 children 实现嵌套项',
- '选中状态支持可选的替代图标,用于填充/轮廓变体',
- '分组支持可选的标题、副标题和尾部内容',
- '通过 collapsible 属性支持可折叠侧边栏——折叠为仅图标工具栏,支持非受控和受控模式',
- '无障碍 - nav 地标、aria-current="page"、分组使用 role="group" 配合 aria-labelledby',
- '键盘可导航 - Tab 切换项目,Enter/Space 激活',
- ],
- accessibility: [
- '<nav aria-label="Side navigation"> 包裹整个组件',
- 'aria-current="page" 应用于选中项',
- '分组使用 role="group",aria-labelledby 指向分组标题',
- 'isHeaderHidden 在视觉上隐藏分组标题,同时保持屏幕阅读器可访问',
- 'Keyboard: Tab 切换项目,Enter/Space 激活链接',
+ 'A sidebar navigation component for organizing application pages with sections, nested items, and icons. Use SideNav as the primary navigation when an app has 5 or more destinations or requires hierarchical grouping.',
+ bestPractices: [
+ {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
+ {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+ {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.'},
+ {guidance: false, description: 'Use for filtering content — use tabs or filter buttons instead.'},
],
- notes: [
- '在 XDSAppShell 中与 XDSTopNav 一起使用时,省略 XDSSideNavHeading——TopNav 已提供应用标识,包含头部会导致重复。',
- '没有 TopNav 时,包含 XDSSideNavHeading 以提供应用标识。',
- '头部交互模型:仅 headingHref → 整个头部是一个链接;headingHref + superheadingHref,无菜单 → 每段文本是独立链接;仅菜单,无 href → 整个头部是弹出框触发器;菜单 + href → 链接是独立的 <a> 元素,箭头/剩余区域是弹出框触发器。',
- '依赖 useXDSPopover 实现头部菜单弹出框,依赖 XDSIcon 在导航项中渲染图标组件。',
- 'XDSSideNavCollapseButton 默认渲染为仅图标的 ghost 按钮。可放置在 footerIcons、header 中,或侧边栏外部(传入 sideNavRef)。',
- 'useXDSSideNavCollapse hook 暴露 { isCollapsed, toggle, isCollapsible },用于自定义折叠控件。',
+ anatomy: [
+ {name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
+ {name: 'Navigation items', required: true, description: 'Sections and groups of navigable links.'},
+ {name: 'Collapse/expand toggle', required: false, description: 'Toggle to collapse or expand the side nav.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description:
- 'Sidebar nav for app pages. Sections, nested items, selected state, icons, collapsible sidebar.',
- features: [
- 'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',
- 'Smart header interaction boundary logic; links + menu trigger coexist w/o overlap',
- 'Nested items via children on XDSSideNavItem',
- 'Selected state w/ optional alternate icon for filled/outline variants',
- 'Section grouping w/ optional title, subtitle, end content',
- 'Collapsible sidebar via collapsible prop; collapses to icon-only toolbar, uncontrolled or controlled',
- 'Accessible; nav landmark, aria-current="page", role="group" w/ aria-labelledby on sections',
- 'Keyboard navigable; Tab through items, Enter/Space to activate',
- ],
- accessibility: [
- '<nav aria-label="Side navigation"> wraps entire component',
- 'aria-current="page" applied to selected item',
- 'Sections use role="group" w/ aria-labelledby pointing to section title',
- 'isHeaderHidden visually hides section title while keeping accessible to screen readers',
- ],
- keyboard: 'Tab through items, Enter/Space to activate links',
- notes: [
- 'W/ XDSAppShell alongside XDSTopNav, omit XDSSideNavHeading; TopNav already provides app identity.',
- 'W/o TopNav, include XDSSideNavHeading to provide app identity.',
- 'Header interaction model: headingHref only = whole header is one link; headingHref+superheadingHref no menu = each text independent link; menu only no hrefs = whole header is popover trigger; menu+hrefs = links are independent <a> elements, chevron/remaining is popover trigger.',
- 'Depends on useXDSPopover for header menu popover + XDSIcon for rendering icon components in nav items.',
- 'XDSSideNavCollapseButton renders as icon-only ghost button by default. Place in footerIcons, header, or outside sidenav (pass sideNavRef).',
- 'useXDSSideNavCollapse hook exposes { isCollapsed, toggle, isCollapsible } for custom collapse controls.',
- ],
+ usage: {
+ description:
+ 'A sidebar navigation component for organizing application pages with sections, nested items, and icons. Use SideNav as the primary navigation when an app has 5 or more destinations or requires hierarchical grouping.',
+ bestPractices: [
+ {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
+ {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
+ {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity — this duplicates branding.'},
+ {guidance: false, description: 'Use for filtering content — use tabs or filter buttons instead.'},
+ ],
+ anatomy: [
+ {name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},
+ {name: 'Navigation items', required: true, description: 'Sections and groups of navigable links.'},
+ {name: 'Collapse/expand toggle', required: false, description: 'Toggle to collapse or expand the side nav.'},
+ ],
+ },
components: [
{
name: 'XDSSideNav',
diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjs
index 3539d38616..034c1d08ae 100644
--- a/packages/core/src/Skeleton/Skeleton.doc.mjs
+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs
@@ -36,20 +36,12 @@ export const docs = {
},
usage: {
description:
- 'A placeholder loading component that displays an animated pulsing effect while content is loading. Use when content of known size is loading to build skeleton screens matching the layout. For unknown content dimensions, use Spinner instead.',
- features: [
- 'Smooth opacity animation using stepped timing for a subtle shimmer effect',
- 'Sequential skeletons can be staggered to create a wave effect',
- 'High contrast support: automatically adjusts for prefers-contrast: more',
- 'Flexible sizing: width and height accept pixels or any CSS value',
- 'Token-aligned radius: border radius options map directly to design tokens',
- ],
- notes: [
- 'Uses steps(10, end) timing function for a subtle shimmer effect.',
- 'Animation alternates between 0.25 and 1.0 opacity.',
- 'Background color comes from the glimmer token, with glimmerHighContrast for accessibility.',
- 'Numeric dimensions are converted to pixels; strings are passed through as-is.',
- 'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',
+ 'A placeholder loading component that displays an animated shimmer effect while content is loading. Use Skeleton to build loading screens that match the layout of the content being loaded. For content of unknown dimensions, use Spinner instead.',
+ bestPractices: [
+ {guidance: true, description: 'Match the size and shape of the content being loaded to create a realistic placeholder.'},
+ {guidance: true, description: 'Use the index prop to stagger multiple skeletons for a natural wave animation.'},
+ {guidance: false, description: 'Use when the content dimensions are unknown — use Spinner instead.'},
+ {guidance: false, description: 'Combine with a Spinner on the same content area — pick one loading pattern.'},
],
},
};
@@ -91,42 +83,28 @@ export const docsZh = {
},
usage: {
description:
- '占位加载组件,在内容加载时显示动画脉冲效果。',
- features: [
- '脉冲动画:使用分步计时的平滑透明度动画,呈现细腻的闪烁效果',
- '交错动画:连续的骨架屏可以交错排列以创建波浪效果',
- '高对比度支持:自动适配 prefers-contrast: more 用户偏好',
- '灵活尺寸:宽度和高度属性接受像素值或任意 CSS 值',
- '令牌对齐圆角:边框圆角选项直接映射到设计令牌',
- ],
- notes: [
- '使用 steps(10, end) 计时函数实现细腻的闪烁效果。',
- '动画在 0.25 和 1.0 透明度之间交替。',
- '背景颜色来自 glimmer 令牌,无障碍场景使用 glimmerHighContrast。',
- '数字类型的尺寸会转换为像素值;字符串类型按原样传递。',
- '动画时序常量:DELAY_TIME(1000ms)动画开始前的初始延迟,FADE_TIME(1000ms)一个透明度循环的持续时间,STAGGER_TIME(100ms)连续元素之间的延迟增量。',
+ 'A placeholder loading component that displays an animated shimmer effect while content is loading. Use Skeleton to build loading screens that match the layout of the content being loaded. For content of unknown dimensions, use Spinner instead.',
+ bestPractices: [
+ {guidance: true, description: 'Match the size and shape of the content being loaded to create a realistic placeholder.'},
+ {guidance: true, description: 'Use the index prop to stagger multiple skeletons for a natural wave animation.'},
+ {guidance: false, description: 'Use when the content dimensions are unknown — use Spinner instead.'},
+ {guidance: false, description: 'Combine with a Spinner on the same content area — pick one loading pattern.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description:
- 'Placeholder loading component displaying animated pulsing effect while content loads.',
- features: [
- 'Pulsing Animation: smooth opacity animation using stepped timing for subtle shimmer effect',
- 'Staggered Animation: sequential skeletons can be staggered to create wave effect',
- 'High Contrast Support: auto-adjusts for users w/ prefers-contrast: more',
- 'Flexible Sizing: width + height props accept pixels or any CSS value',
- 'Token-aligned Radius: border radius options map directly to design tokens',
- ],
- notes: [
- 'Uses steps(10, end) timing function for subtle shimmer effect.',
- 'Animation alternates between 0.25 and 1.0 opacity.',
- 'Background color from glimmer token, w/ glimmerHighContrast for accessibility.',
- 'Numeric dimensions converted to pixels; strings passed through as-is.',
- 'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',
- ],
+ usage: {
+ description:
+ 'A placeholder loading component that displays an animated shimmer effect while content is loading. Use Skeleton to build loading screens that match the layout of the content being loaded. For content of unknown dimensions, use Spinner instead.',
+ bestPractices: [
+ {guidance: true, description: 'Match the size and shape of the content being loaded to create a realistic placeholder.'},
+ {guidance: true, description: 'Use the index prop to stagger multiple skeletons for a natural wave animation.'},
+ {guidance: false, description: 'Use when the content dimensions are unknown — use Spinner instead.'},
+ {guidance: false, description: 'Combine with a Spinner on the same content area — pick one loading pattern.'},
+ ],
+ },
propDescriptions: {
width: 'Width in pixels (number) or CSS value (string).',
height: 'Height in pixels (number) or CSS value (string).',
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index 77674d744a..54c06390ed 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -131,28 +131,12 @@ export const docs = {
},
usage: {
description:
- 'A slider component for selecting numeric values or ranges with full keyboard and pointer support. Use to help users explore and select a number within a constrained range.',
- features: [
- 'Single and range modes: pass a number for single thumb, [number, number] for range',
- 'Supports horizontal and vertical layouts',
- 'Value display: tooltip (default), inline text, or none',
- 'Tick marks at specified positions with optional labels',
- 'Custom value formatting via formatValue for display and aria-valuetext',
- 'Field integration via XDSField for label, description, required/optional, and status messaging',
- ],
- accessibility: [
- 'Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.',
- 'The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',
- 'Tooltip display uses `XDSTooltip` with `delay={0}` and `focusTrigger="always"` so value is always visible on focus.',
- 'Keyboard: Arrow keys \u00b11 step, Page Up/Down \u00b110 steps, Home/End jump to min/max.',
- ],
- notes: [
- 'The ref is merged with an internal `trackRef` used for pointer position calculations.',
- 'Pointer capture is used during drag for smooth interaction even when the cursor leaves the track.',
- '`snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds.',
- 'In range mode, the closest thumb to the click position is selected automatically.',
- '`minStepsBetweenThumbs` enforces a minimum gap between range thumbs.',
- 'Vertical orientation inverts the Y axis so that bottom = min and top = max.',
+ 'A slider component for selecting a numeric value or range within defined bounds. Use Slider when users need to explore and choose from a continuous range, such as volume, price, or percentage values.',
+ bestPractices: [
+ {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
+ {guidance: true, description: 'Use formatValue to display meaningful units such as "$50" or "75%" instead of raw numbers.'},
+ {guidance: false, description: 'Use for precise numeric entry — pair with a text input or use TextInput alone instead.'},
+ {guidance: false, description: 'Set a step size so large that only a few positions are possible — use SegmentedControl or radio buttons instead.'},
],
},
};
@@ -288,63 +272,28 @@ export const docsZh = {
},
usage: {
description:
- '用于选择数值或范围的滑块组件,支持完整的键盘和指针交互。',
- features: [
- '单值和范围模式:传入 `number` 用于单滑块,`[number, number]` 用于范围',
- '方向:支持 `horizontal` 和 `vertical` 布局',
- '值显示:工具提示(默认)、内联文本或无',
- '刻度标记:在指定位置的可选标记,带标签',
- '键盘导航:方向键、Page Up/Down、Home/End',
- '拖拽交互:指针捕获实现平滑拖拽',
- '自定义格式化:`formatValue` 函数用于显示和 `aria-valuetext`',
- '字段集成:使用 `XDSField` 提供标签、描述、必填/可选和状态消息',
- '无障碍:使用 `role="slider"` 配合完整的 ARIA 属性',
- ],
- accessibility: [
- '每个滑块使用 `role="slider"`,配合 `aria-valuenow`、`aria-valuemin`、`aria-valuemax` 和 `aria-valuetext`。',
- '即使 `isLabelHidden` 为 true,标签也始终在 DOM 中渲染以确保无障碍可访问性。',
- '工具提示显示使用 `XDSTooltip`,配合 `delay={0}` 和 `focusTrigger="always"`,使值在聚焦时始终可见。',
- 'Keyboard: 方向键 ±1 步,Page Up/Down ±10 步,Home/End 跳转到最小值/最大值。',
- ],
- notes: [
- 'ref 与内部的 `trackRef` 合并,用于指针位置计算。',
- '拖拽期间使用指针捕获,即使光标离开轨道也能平滑交互。',
- '`snapToStep` 四舍五入到最近的有效步进值;`clamp` 强制执行最小/最大值边界。',
- '在范围模式下,自动选择距离点击位置最近的滑块。',
- '`minStepsBetweenThumbs` 强制范围滑块之间保持最小间距。',
- '垂直方向反转 Y 轴,使底部为最小值,顶部为最大值。',
+ 'A slider component for selecting a numeric value or range within defined bounds. Use Slider when users need to explore and choose from a continuous range, such as volume, price, or percentage values.',
+ bestPractices: [
+ {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
+ {guidance: true, description: 'Use formatValue to display meaningful units such as "$50" or "75%" instead of raw numbers.'},
+ {guidance: false, description: 'Use for precise numeric entry — pair with a text input or use TextInput alone instead.'},
+ {guidance: false, description: 'Set a step size so large that only a few positions are possible — use SegmentedControl or radio buttons instead.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'Numeric value/range selector w/ full keyboard + pointer support.',
- features: [
- 'Single + range modes: number for single thumb, [number, number] for range',
- 'Orientation: horizontal + vertical layouts',
- 'Value display: tooltip (default), inline text, or none',
- 'Tick marks: optional marks at specified positions w/ labels',
- 'Keyboard nav: Arrow keys, Page Up/Down, Home/End',
- 'Drag: pointer capture for smooth dragging',
- 'Custom formatting: formatValue fn for display + aria-valuetext',
- 'Field integration: uses XDSField for label, description, required/optional, status messaging',
- 'Accessible: role="slider" w/ full ARIA attributes',
- ],
- notes: [
- 'ref merged w/ internal trackRef for pointer position calc.',
- 'Pointer capture during drag for smooth interaction even when cursor leaves track.',
- 'snapToStep rounds to nearest valid step; clamp enforces min/max bounds.',
- 'Range mode auto-selects closest thumb to click position.',
- 'minStepsBetweenThumbs enforces min gap between range thumbs.',
- 'Vertical orientation inverts Y axis; bottom=min, top=max.',
- ],
- accessibility: [
- 'role="slider" w/ aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext on each thumb.',
- 'Label always in DOM for a11y even when isLabelHidden=true.',
- 'Tooltip uses XDSTooltip w/ delay={0} focusTrigger="always"; value visible on focus.',
- ],
- keyboard: 'Arrow=\u00b11 step; PageUp/PageDown=\u00b110 steps; Home/End=jump to min/max.',
+ usage: {
+ description:
+ 'A slider component for selecting a numeric value or range within defined bounds. Use Slider when users need to explore and choose from a continuous range, such as volume, price, or percentage values.',
+ bestPractices: [
+ {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
+ {guidance: true, description: 'Use formatValue to display meaningful units such as "$50" or "75%" instead of raw numbers.'},
+ {guidance: false, description: 'Use for precise numeric entry — pair with a text input or use TextInput alone instead.'},
+ {guidance: false, description: 'Set a step size so large that only a few positions are possible — use SegmentedControl or radio buttons instead.'},
+ ],
+ },
propDescriptions: {
label: 'Label text (always rendered for a11y).',
value: 'Current value; number for single thumb, [number, number] for range.',
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
index a1e0838c99..b3957bca71 100644
--- a/packages/core/src/Spinner/Spinner.doc.mjs
+++ b/packages/core/src/Spinner/Spinner.doc.mjs
@@ -42,22 +42,12 @@ export const docs = {
},
usage: {
description:
- 'An animated loading indicator for indeterminate wait states with an optional visible label. Use for indicating ongoing processes with unknown duration or inline loading states within buttons and other components. For content of known size, use Skeleton instead.',
- features: [
- 'Three sizes (sm, md, lg) matching existing inline spinners',
- 'Shade support: default for light backgrounds, onMedia for dark/accent backgrounds',
- 'Optional visible label (string or ReactNode) displayed below spinner',
- ],
- accessibility: [
- 'Uses role="status" with aria-label; defaults to label text or "Loading"',
- ],
- notes: [
- 'Uses CSS border technique: three visible borders + one transparent for the gap.',
- 'Animation: rotate(360deg) at 0.75s linear infinite.',
- 'Color inherits from currentColor, controlled by shade styles using theme tokens.',
- 'Element is a <span> with display: inline-block for inline composability.',
- 'XDSSpinner is intentionally minimal — compose with layout and text components for full loading states.',
- 'Size reference: sm = 10×10px / 3px border, md = 14×14px / 3px border, lg = 18×18px / 3px border.',
+ 'An animated loading indicator for indeterminate wait states. Use Spinner to signal ongoing processes with unknown duration, such as data fetching or form submission. For loading content of known dimensions, use Skeleton instead.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
+ {guidance: true, description: 'Choose the appropriate shade — use "onMedia" when placed on dark or accent-colored backgrounds.'},
+ {guidance: false, description: 'Use for content areas with known dimensions — use Skeleton to preserve layout instead.'},
+ {guidance: false, description: 'Stack multiple Spinners in the same view — use one to represent the overall loading state.'},
],
},
};
@@ -103,43 +93,28 @@ export const docsZh = {
},
usage: {
description:
- '带有可选可见标签的动画加载指示器。',
- features: [
- 'Canvas 动画:基于 Canvas 的轻量级旋转器,平滑 360° 旋转',
- '尺寸变体:三种尺寸(sm、md、lg),与现有内联旋转器匹配',
- '色调支持:默认色调用于浅色背景,onMedia 用于深色/强调色背景',
- '标签:可选可见标签(字符串或 ReactNode),显示在旋转器下方',
- '无障碍:role="status" 与 aria-label;默认为标签文本或 "Loading"',
- ],
- notes: [
- '使用 CSS 边框技术:三条可见边框 + 一条透明边框形成缺口。',
- '动画:rotate(360deg),0.75s linear infinite。',
- '颜色继承自 currentColor,通过使用主题令牌的色调样式控制。',
- '元素是一个 <span>,设置 display: inline-block 以支持内联组合。',
- 'XDSSpinner 设计上保持最小化——与布局和文本组件组合以实现完整的加载状态。',
- '尺寸参考:sm = 10×10px / 3px 边框,md = 14×14px / 3px 边框,lg = 18×18px / 3px 边框。',
+ 'An animated loading indicator for indeterminate wait states. Use Spinner to signal ongoing processes with unknown duration, such as data fetching or form submission. For loading content of known dimensions, use Skeleton instead.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
+ {guidance: true, description: 'Choose the appropriate shade — use "onMedia" when placed on dark or accent-colored backgrounds.'},
+ {guidance: false, description: 'Use for content areas with known dimensions — use Skeleton to preserve layout instead.'},
+ {guidance: false, description: 'Stack multiple Spinners in the same view — use one to represent the overall loading state.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'Animated loading indicator w/ optional visible label.',
- features: [
- 'Canvas animation: lightweight canvas-based spinner w/ smooth 360\u00b0 rotation',
- 'Size variants: sm (10px), md (14px), lg (18px) matching inline spinners',
- 'Shade support: default for light bg, onMedia for dark/accent bg',
- 'Label: optional ReactNode below spinner; string labels auto-set aria-label',
- 'Accessible: role="status" + aria-label; defaults to label text or "Loading"',
- ],
- notes: [
- 'Canvas renders spinner arcs at device pixel ratio.',
- 'Animation: rotate(360deg) at 0.75s linear infinite.',
- 'Color resolved from CSS custom properties via getComputedStyle.',
- 'Element is <span> w/ display: inline-block for inline composability.',
- 'label + aria-label are independent props; compose, never conflict.',
- 'Size ref: sm=10x10px/3px border, md=14x14px/3px border, lg=18x18px/3px border.',
- ],
+ usage: {
+ description:
+ 'An animated loading indicator for indeterminate wait states. Use Spinner to signal ongoing processes with unknown duration, such as data fetching or form submission. For loading content of known dimensions, use Skeleton instead.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
+ {guidance: true, description: 'Choose the appropriate shade — use "onMedia" when placed on dark or accent-colored backgrounds.'},
+ {guidance: false, description: 'Use for content areas with known dimensions — use Skeleton to preserve layout instead.'},
+ {guidance: false, description: 'Stack multiple Spinners in the same view — use one to represent the overall loading state.'},
+ ],
+ },
propDescriptions: {
size: 'Spinner size (10px, 14px, 18px).',
shade: 'Color shade for light or dark backgrounds.',
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 6f3ea3b0e4..3345ddf312 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -171,18 +171,12 @@ export const docs = {
],
usage: {
description:
- 'Stack provides layout primitives for arranging items in horizontal or vertical sequences. It uses flexbox-based layout with themed spacing tokens from the design system.',
- features: [
- 'Horizontal (XDSHStack) and vertical (XDSVStack) stacking',
- 'Themed spacing via gap tokens from the design system spacing scale',
- 'Individual item control via XDSStackItem',
- 'Polymorphic rendering support via the element prop',
- 'Low-level StyleX utilities (stack, stackItem) for advanced use cases',
- ],
- notes: [
- "Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",
- 'The gap prop accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
- 'stack and stackItem are low-level StyleX utilities for advanced cases where the component API is insufficient.',
+ 'Stack provides layout primitives for arranging items in horizontal or vertical sequences with consistent spacing. Use XDSHStack for row layouts and XDSVStack for column layouts when distributing child elements with uniform gaps from the design system spacing scale.',
+ bestPractices: [
+ { guidance: true, description: 'Use the gap prop with design system spacing tokens to maintain consistent spacing between stack children.' },
+ { guidance: true, description: 'Wrap individual items in XDSStackItem with size="fill" when an item should expand to consume remaining space.' },
+ { guidance: false, description: 'Apply custom margins between stack children — use the gap prop instead for uniform spacing.' },
+ { guidance: false, description: 'Nest stacks deeply when a single stack with wrap enabled could achieve the same layout.' },
],
},
};
@@ -359,18 +353,12 @@ export const docsZh = {
],
usage: {
description:
- '堆叠布局原语,使用基于 flexbox 的布局和主题化间距令牌,将元素排列为水平或垂直序列。',
- features: [
- '水平(XDSHStack)和垂直(XDSVStack)堆叠',
- '通过设计系统间距比例中的 gap 令牌实现主题化间距',
- '通过 XDSStackItem 实现单个元素的控制',
- '通过 element 属性支持多态渲染',
- '底层 StyleX 工具函数(stack、stackItem)用于高级用例',
- ],
- notes: [
- "从 '@xds/core/Layout' 导入:XDSHStack、XDSVStack、XDSStackItem、stack、stackItem。",
- 'gap 属性接受数值间距步进:0、0.5、1、1.5、2、3、4、5、6、8、10。',
- 'stack 和 stackItem 是底层 StyleX 工具函数,用于组件 API 无法满足需求的高级场景。',
+ 'Stack provides layout primitives for arranging items in horizontal or vertical sequences with consistent spacing. Use XDSHStack for row layouts and XDSVStack for column layouts when distributing child elements with uniform gaps from the design system spacing scale.',
+ bestPractices: [
+ { guidance: true, description: 'Use the gap prop with design system spacing tokens to maintain consistent spacing between stack children.' },
+ { guidance: true, description: 'Wrap individual items in XDSStackItem with size="fill" when an item should expand to consume remaining space.' },
+ { guidance: false, description: 'Apply custom margins between stack children — use the gap prop instead for uniform spacing.' },
+ { guidance: false, description: 'Nest stacks deeply when a single stack with wrap enabled could achieve the same layout.' },
],
},
};
@@ -378,18 +366,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Stack layout primitives for horizontal/vertical sequences using flexbox w/ themed spacing tokens.',
- features: [
- 'Horizontal (XDSHStack) + vertical (XDSVStack) stacking',
- 'Themed spacing via gap tokens from design system spacing scale',
- 'Individual item control via XDSStackItem',
- 'Polymorphic rendering via element prop',
- 'Low-level StyleX utilities (stack, stackItem) for advanced use',
- ],
- notes: [
- "Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",
- 'gap accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
- 'stack + stackItem are low-level StyleX utilities for cases where component API is insufficient.',
- ],
+ usage: {
+ description:
+ 'Stack provides layout primitives for arranging items in horizontal or vertical sequences with consistent spacing. Use XDSHStack for row layouts and XDSVStack for column layouts when distributing child elements with uniform gaps from the design system spacing scale.',
+ bestPractices: [
+ { guidance: true, description: 'Use the gap prop with design system spacing tokens to maintain consistent spacing between stack children.' },
+ { guidance: true, description: 'Wrap individual items in XDSStackItem with size="fill" when an item should expand to consume remaining space.' },
+ { guidance: false, description: 'Apply custom margins between stack children — use the gap prop instead for uniform spacing.' },
+ { guidance: false, description: 'Nest stacks deeply when a single stack with wrap enabled could achieve the same layout.' },
+ ],
+ },
components: [
{
name: 'XDSHStack',
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
index afacaeda3f..d0791cbd5a 100644
--- a/packages/core/src/StatusDot/StatusDot.doc.mjs
+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs
@@ -37,16 +37,12 @@ export const docs = {
},
usage: {
description:
- 'StatusDot is a small colored dot indicator for displaying status through semantic colors such as online/offline or severity levels. Pair it with a text label to ensure the status is accessible, as color alone should not convey meaning.',
- features: [
- 'Five semantic color variants: positive, warning, negative, info, neutral',
- 'Single size: 8px',
- 'Optional pulse animation that respects prefers-reduced-motion',
- ],
- accessibility: [
- 'Renders as <span role="img" aria-label={label}> for screen reader support.',
- 'Not focusable — intended as a decorative indicator only.',
- 'isPulsing animation respects prefers-reduced-motion: reduce.',
+ 'StatusDot is a small colored dot indicator that communicates status through semantic color variants. Use it alongside text labels to convey states like online/offline presence or severity levels, as color alone should not carry meaning.',
+ bestPractices: [
+ { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
+ { guidance: true, description: 'Provide a descriptive label prop for screen reader accessibility.' },
+ { guidance: false, description: 'Use StatusDot as the sole indicator of status without an accompanying text label.' },
+ { guidance: false, description: 'Enable the pulse animation for purely decorative purposes — reserve it for states that require immediate attention.' },
],
},
};
@@ -88,18 +84,12 @@ export const docsZh = {
},
usage: {
description:
- '用于状态展示的小型彩色圆点指示器(在线/离线、严重程度等)。',
- features: [
- '五种语义颜色变体:positive(正面)、warning(警告)、negative(负面)、info(信息)、neutral(中性)',
- '两种尺寸:sm(8px)和 md(10px)',
- '可选的脉冲动画,尊重 prefers-reduced-motion 设置',
- '无障碍支持 — 渲染为 <span role="img" aria-label={label}> 以支持屏幕阅读器',
- '不可聚焦(装饰性指示器)',
- ],
- accessibility: [
- '渲染为 <span role="img" aria-label={label}> 以支持屏幕阅读器。',
- '不可聚焦 — 仅作为装饰性指示器使用。',
- 'isPulsing 动画尊重 prefers-reduced-motion: reduce 设置。',
+ 'StatusDot is a small colored dot indicator that communicates status through semantic color variants. Use it alongside text labels to convey states like online/offline presence or severity levels, as color alone should not carry meaning.',
+ bestPractices: [
+ { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
+ { guidance: true, description: 'Provide a descriptive label prop for screen reader accessibility.' },
+ { guidance: false, description: 'Use StatusDot as the sole indicator of status without an accompanying text label.' },
+ { guidance: false, description: 'Enable the pulse animation for purely decorative purposes — reserve it for states that require immediate attention.' },
],
},
};
@@ -107,18 +97,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Small colored dot indicator for status display (online/offline, severity, etc).',
- features: [
- 'Five semantic color variants: positive, warning, negative, info, neutral',
- 'Single size: 8px',
- 'Optional pulse animation respecting prefers-reduced-motion',
- 'Accessible: <span role="img" aria-label={label}> for screen readers',
- 'Not focusable (decorative indicator)',
- ],
- accessibility: [
- 'Renders <span role="img" aria-label={label}> for screen readers.',
- 'Not focusable; decorative indicator only.',
- 'isPulsing animation respects prefers-reduced-motion: reduce.',
- ],
+ usage: {
+ description:
+ 'StatusDot is a small colored dot indicator that communicates status through semantic color variants. Use it alongside text labels to convey states like online/offline presence or severity levels, as color alone should not carry meaning.',
+ bestPractices: [
+ { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
+ { guidance: true, description: 'Provide a descriptive label prop for screen reader accessibility.' },
+ { guidance: false, description: 'Use StatusDot as the sole indicator of status without an accompanying text label.' },
+ { guidance: false, description: 'Enable the pulse animation for purely decorative purposes — reserve it for states that require immediate attention.' },
+ ],
+ },
propDescriptions: {
variant: 'Semantic color variant.',
label: 'Accessible label via aria-label.',
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index 8b177086e6..f9092f1edb 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -123,34 +123,12 @@ export const docs = {
},
usage: {
description:
- 'A toggle switch component for boolean values with integrated label support that conveys an on/off state taking effect immediately. Use for settings that apply instantly upon toggling; for changes requiring a separate submit step, use a checkbox instead.',
- features: [
- 'Boolean toggle with animated thumb for visual on/off states',
- 'Label integration — uses XDSFieldLabel for accessible labels with optional tooltip and icon',
- 'Label position — label can appear before or after the switch via labelPosition',
- 'Label spacing — supports spread layout to push label and switch to opposite ends',
- 'Description — optional description text displayed below the label',
- 'Optional/required indicators — visual markers for field status',
- 'Status messages — error, warning, success, or info message boxes below the switch',
- 'Async action support — onChangeAction with optimistic UI and built-in loading spinner',
- 'Reduced motion — respects prefers-reduced-motion for track and thumb transitions',
- ],
- accessibility: [
- 'Renders a native <input type="checkbox" role="switch"> for correct switch semantics',
- 'Label is always associated via htmlFor/id even when visually hidden',
- 'Description text is linked via aria-describedby on the input element',
- 'Status messages are linked via aria-describedby; aria-invalid is set when status type is "error"',
- 'aria-busy is set during async onChangeAction execution',
- 'Keyboard: Space toggles the switch; Tab/Shift+Tab moves focus in and out',
- ],
- notes: [
- 'Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)',
- 'Track and thumb use CSS transitions for background-color, transform, width, and height',
- 'Hover tints are applied via stylex.when.ancestor with a @media (hover: hover) guard',
- 'onChangeAction uses React useTransition and useOptimistic for seamless async toggling',
- 'Follows the same patterns as XDSCheckboxInput for structural consistency',
- 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling',
- 'Track and thumb transitions respect prefers-reduced-motion (0s duration when reduced motion preferred)',
+ 'Switch is a toggle control for boolean on/off states that take effect immediately. Use it for settings or preferences that apply instantly upon toggling. For changes requiring a separate submit step, use a checkbox instead.',
+ bestPractices: [
+ { guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
+ { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
+ { guidance: false, description: 'Use a switch for options that require a form submission to take effect — use a checkbox instead.' },
+ { guidance: false, description: 'Hide the label without providing accessible text — use isLabelHidden only when context makes the purpose obvious.' },
],
},
};
@@ -278,33 +256,12 @@ export const docsZh = {
},
usage: {
description:
- '用于布尔值的开关切换组件,集成标签支持。',
- features: [
- '布尔值切换 — 固定 40x24px 轨道,带动画效果的 16px(关闭)/ 20px(开启)滑块',
- '标签集成 — 使用 XDSFieldLabel 实现无障碍标签,支持可选的工具提示和图标',
- '标签位置 — 通过 labelPosition 可将标签放置在开关前面或后面',
- '标签间距 — 支持分散布局,将标签和开关推到容器两端',
- '描述 — 可选的描述文本,显示在标签下方',
- '可选/必填指示器 — 字段状态的可视标记',
- '状态消息 — 开关下方的错误、警告、成功或信息消息框',
- '异步操作支持 — onChangeAction 支持乐观 UI 和内置加载旋转器',
- '无障碍 — 原生复选框,具有 role="switch"、aria-describedby、aria-invalid、aria-busy',
- ],
- accessibility: [
- '渲染原生 <input type="checkbox" role="switch"> 以确保正确的开关语义',
- '标签始终通过 htmlFor/id 关联,即使视觉上被隐藏',
- '描述文本通过输入元素上的 aria-describedby 关联',
- '状态消息通过 aria-describedby 关联;当状态类型为 "error" 时设置 aria-invalid',
- '异步 onChangeAction 执行期间设置 aria-busy',
- 'Keyboard: 空格键切换开关;Tab/Shift+Tab 移入和移出焦点',
- ],
- notes: [
- '固定尺寸:40px 宽,24px 高,16px 滑块(关闭),20px 滑块(开启)',
- '轨道和滑块使用 CSS 过渡实现 background-color、transform、width 和 height 的动画',
- '悬停色调通过 stylex.when.ancestor 应用,带有 @media (hover: hover) 守卫',
- 'onChangeAction 使用 React useTransition 和 useOptimistic 实现无缝异步切换',
- 'labelPosition="start" 配合 labelSpacing="spread" 生成设置面板样式的布局',
- '遵循与 XDSCheckboxInput 相同的模式以保持结构一致性',
+ 'Switch is a toggle control for boolean on/off states that take effect immediately. Use it for settings or preferences that apply instantly upon toggling. For changes requiring a separate submit step, use a checkbox instead.',
+ bestPractices: [
+ { guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
+ { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
+ { guidance: false, description: 'Use a switch for options that require a form submission to take effect — use a checkbox instead.' },
+ { guidance: false, description: 'Hide the label without providing accessible text — use isLabelHidden only when context makes the purpose obvious.' },
],
},
};
@@ -312,33 +269,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Toggle switch for boolean values w/ integrated label support.',
- features: [
- 'Boolean toggle; fixed 40x24px track w/ animated 16px (off) / 20px (on) thumb',
- 'Label integration; uses XDSFieldLabel for accessible labels w/ optional tooltip + icon',
- 'Label position; label before or after switch via labelPosition',
- 'Label spacing; spread layout pushes label + switch to opposite ends',
- 'Description; optional text below label',
- 'Optional/required indicators; visual markers for field status',
- 'Status messages; error, warning, success, or info boxes below switch',
- 'Async action support; onChangeAction w/ optimistic UI + built-in loading spinner',
- 'Accessible; native checkbox w/ role="switch", aria-describedby, aria-invalid, aria-busy',
- ],
- notes: [
- 'Fixed dimensions: 40px wide, 24px high, 16px thumb (off), 20px thumb (on).',
- 'Track + thumb use CSS transitions for background-color, transform, width, height.',
- 'Hover tints via stylex.when.ancestor w/ @media (hover: hover) guard.',
- 'onChangeAction uses React useTransition + useOptimistic for seamless async toggling.',
- 'labelPosition="start" + labelSpacing="spread" produces settings panel layout.',
- 'Follows same patterns as XDSCheckboxInput for structural consistency.',
- ],
- accessibility: [
- 'Native <input type="checkbox" role="switch"> for correct semantics.',
- 'Label always associated via htmlFor/id even when visually hidden.',
- 'Description linked via aria-describedby on input element.',
- 'Status messages linked via aria-describedby; aria-invalid set on error type.',
- 'aria-busy set during async onChangeAction execution.',
- ],
- keyboard: 'Space=toggle; Tab/Shift+Tab=move focus in/out.',
+ usage: {
+ description:
+ 'Switch is a toggle control for boolean on/off states that take effect immediately. Use it for settings or preferences that apply instantly upon toggling. For changes requiring a separate submit step, use a checkbox instead.',
+ bestPractices: [
+ { guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
+ { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
+ { guidance: false, description: 'Use a switch for options that require a form submission to take effect — use a checkbox instead.' },
+ { guidance: false, description: 'Hide the label without providing accessible text — use isLabelHidden only when context makes the purpose obvious.' },
+ ],
+ },
propDescriptions: {
ref: 'ref forwarded to underlying <input>',
label: 'Label text (always rendered for a11y).',
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 338da7b775..9dc1afe6ce 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -129,35 +129,12 @@ export const docs = {
],
usage: {
description:
- 'TabList provides tab navigation with overflow menu support, organizing content into tabbed sections for quick access to categorized information. It renders as a semantic nav landmark with button or anchor tab items, and overflows into a "more" menu when horizontal space is limited.',
- features: [
- 'Single-responsibility XDSTab: renders as <button> or <a> (when href is provided) in the nav',
- 'Overflow menu: XDSTabMenu accepts an options prop and renders menu items internally from the dropdown',
- "Dynamic trigger label: menu trigger shows the selected option's label when one is active",
- "Menu heading: dropdown includes an XDSDivider with the menu's label as a separator heading",
- 'Selection indicator: selected menu items show a checkmark icon (matching XDSSelector pattern)',
- 'Hover state: unselected tabs show a gray underline on hover; no background hover overlay',
- ],
- accessibility: [
- 'XDSTabList renders as a <nav> landmark with aria-label="Tabs"',
- 'XDSTab renders as <button> or <a> — uses navigation pattern, not role="tab"',
- 'Selected XDSTab has aria-current="page"',
- 'XDSTabMenu trigger has aria-haspopup="menu", aria-expanded, and aria-controls pointing to the menu element',
- 'XDSTabMenu dropdown has role="menu" and aria-label matching the label prop',
- 'XDSTabMenu heading divider has role="separator"',
- 'XDSTabMenu items have role="menuitem" and aria-current="true" when selected',
- 'Keyboard: Tab moves focus between tab items; within XDSTabMenu dropdown: ArrowUp/ArrowDown navigate items (wrapping), Home/End jump to first/last item, Escape closes the menu',
- ],
- notes: [
- 'XDSTabListContext passes value/onChange/size from XDSTabList to children',
- 'XDSTab renders as <button> by default and as <a> when href is provided',
- 'XDSTabMenu renders menu items internally from the options prop — no child composition',
- 'Trigger label derives from options.find(o => o.value === ctx.value)?.label ?? label',
- 'Menu trigger underline scopes to the label text span only, not the chevron icon',
- 'Icons on menu items render via XDSIcon with size="sm" and color="secondary"',
- 'Selected menu items show a CheckIcon checkmark (matching XDSSelector pattern)',
- 'hasDivider on XDSTabList controls the bottom border (default: off)',
- 'Size uses sizeVars tokens for tab heights (sm/md/lg)',
+ 'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
+ bestPractices: [
+ { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
+ { guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+ { guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
+ { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
],
anatomy: [
{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
@@ -297,37 +274,17 @@ export const docsZh = {
],
usage: {
description:
- '支持溢出菜单的标签页导航组件,渲染为语义化的 nav 地标元素,包含按钮或锚点标签项。',
- features: [
- '基于上下文通信:XDSTabListContext 将 value/onChange/size 从 XDSTabList 传递给子组件',
- '单一职责的 XDSTab:在 nav 中渲染为 <button> 或 <a>(当提供 href 时)',
- '溢出菜单:XDSTabMenu 接受 options 属性,并从下拉菜单内部渲染菜单项',
- '动态触发器标签:当某个选项处于选中状态时,菜单触发器显示该选项的标签',
- '菜单标题:下拉菜单包含一个以菜单标签作为分隔标题的 XDSDivider',
- '选中指示器:选中的菜单项显示勾选图标(与 XDSSelector 模式一致)',
- '键盘导航:Tab 键在项目间移动焦点,ArrowUp/ArrowDown 在菜单中导航,Home/End 跳转,Escape 关闭菜单(通过 useListFocus 实现)',
- '悬停状态:未选中的标签在悬停时显示灰色下划线;无背景悬停遮罩',
- '无障碍:nav 地标元素,选中标签上的 aria-current="page",下拉菜单的 role="menu" + aria-label,aria-controls 连接触发器与菜单,菜单项的 role="menuitem",标题分隔线的 role="separator"',
- ],
- accessibility: [
- 'XDSTabList 渲染为带有 aria-label="Tabs" 的 <nav> 地标元素',
- 'XDSTab 渲染为 <button> 或 <a> — 使用导航模式,而非 role="tab"',
- '选中的 XDSTab 具有 aria-current="page"',
- 'XDSTabMenu 触发器具有 aria-haspopup="menu"、aria-expanded 和指向菜单元素的 aria-controls',
- 'XDSTabMenu 下拉菜单具有 role="menu" 和与 label 属性匹配的 aria-label',
- 'XDSTabMenu 标题分隔线具有 role="separator"',
- 'XDSTabMenu 菜单项具有 role="menuitem",选中时具有 aria-current="true"',
- 'Keyboard: Tab 键在标签项之间移动焦点;在 XDSTabMenu 下拉菜单中:ArrowUp/ArrowDown 导航菜单项(循环),Home/End 跳转到第一项/最后一项,Escape 关闭菜单。',
+ 'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
+ bestPractices: [
+ { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
+ { guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+ { guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
+ { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
],
- notes: [
- 'XDSTab 默认渲染为 <button>,当提供 href 时渲染为 <a>',
- 'XDSTabMenu 通过 options 属性在内部渲染菜单项 — 不使用子组件组合',
- '触发器标签来源于 options.find(o => o.value === ctx.value)?.label ?? label',
- '菜单触发器下划线仅作用于标签文本范围,不包含箭头图标',
- '菜单项上的图标通过 XDSIcon 渲染,尺寸为 "sm",颜色为 "secondary"',
- '选中的菜单项显示 CheckIcon 勾选标记(与 XDSSelector 模式一致)',
- 'XDSTabList 上的 hasDivider 控制底部边框(默认关闭)',
- 'Size 使用 sizeVars 令牌控制标签高度(sm/md/lg)',
+ anatomy: [
+ {name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
+ {name: 'Center-Fill Content', required: false, description: 'Stretches to fill available space.'},
+ {name: 'Right Content', required: false, description: 'Hugs content width.'},
],
},
};
@@ -335,37 +292,21 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Tab navigation w/ overflow menu support; semantic nav landmark w/ button or anchor tab items.',
- features: [
- 'Context-based: XDSTabListContext passes value/onChange/size from XDSTabList to children',
- 'Single-responsibility XDSTab: renders <button> or <a> (when href provided) in nav',
- 'Overflow menu: XDSTabMenu accepts options prop, renders menu items from dropdown',
- "Dynamic trigger label: shows selected option's label when active",
- "Menu heading: dropdown includes XDSDivider w/ menu's label as separator heading",
- 'Selection indicator: selected items show checkmark icon (matching XDSSelector pattern)',
- 'Keyboard nav: Tab between items, ArrowUp/Down in menu, Home/End, Escape closes (via useListFocus)',
- 'Hover state: unselected tabs show gray underline on hover; no bg hover overlay',
- 'Accessible: nav landmark, aria-current="page" on selected, role="menu" + aria-label on dropdown, aria-controls, role="menuitem", role="separator"',
- ],
- notes: [
- 'XDSTab renders <button> by default, <a> when href provided.',
- 'XDSTabMenu renders items internally from options prop; no child composition.',
- 'Trigger label: options.find(o => o.value === ctx.value)?.label ?? label.',
- 'Menu trigger underline scopes to label text span only, not chevron.',
- 'Icons on menu items via XDSIcon size="sm" color="secondary".',
- 'Selected menu items show CheckIcon (matching XDSSelector pattern).',
- 'hasDivider controls bottom border (default: off).',
- 'Size uses sizeVars tokens for tab heights (sm/md/lg).',
- ],
- accessibility: [
- 'XDSTabList renders <nav> w/ aria-label="Tabs".',
- 'XDSTab renders <button> or <a>; uses nav pattern, not role="tab".',
- 'Selected XDSTab has aria-current="page".',
- 'XDSTabMenu trigger has aria-haspopup="menu", aria-expanded, aria-controls.',
- 'XDSTabMenu dropdown has role="menu" + aria-label matching label prop.',
- 'XDSTabMenu heading divider has role="separator".',
- 'XDSTabMenu items have role="menuitem" + aria-current="true" when selected.',
- ],
- keyboard: 'Tab=move focus between items; ArrowUp/ArrowDown=navigate menu (wrapping); Home/End=first/last; Escape=close menu.',
+ usage: {
+ description:
+ 'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
+ bestPractices: [
+ { guidance: true, description: 'Keep tab labels short and descriptive so users can quickly scan available sections.' },
+ { guidance: true, description: 'Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen.' },
+ { guidance: false, description: 'Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead.' },
+ { guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories.' },
+ ],
+ anatomy: [
+ {name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},
+ {name: 'Center-Fill Content', required: false, description: 'Stretches to fill available space.'},
+ {name: 'Right Content', required: false, description: 'Hugs content width.'},
+ ],
+ },
components: [
{
name: 'XDSTabList',
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 8ed8be128d..fe546747c7 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -409,40 +409,12 @@ export const docs = {
],
usage: {
description:
- 'Table is a data-driven grid for displaying information with consistent data dimensionality. It supports rich cell content via renderCell, composing XDS components like XDSBadge, XDSStatusDot, and XDSAvatar inside cells. XDSBaseTable provides the unstyled structural core with a composable plugin pipeline for selection, sorting, pagination, and column management. Use lists or card-lists instead for simpler or inconsistent data.',
- features: [
- 'Data-driven rendering — pass data + columns, rows render automatically',
- 'Rich cell content via renderCell — compose XDS components (XDSBadge, XDSStatusDot, XDSText, XDSAvatar) inside table cells',
- 'Children mode — compose XDSTableRow/XDSTableCell directly for manual layouts',
- 'Plugin system — extend table behavior with composable transform plugins',
- 'Density variants: compact, balanced, spacious',
- 'Divider styles: rows, columns, grid, none',
- 'Column alignment: start (default), center, end — per-column via align prop',
- 'Row vertical alignment: middle (default), top, bottom — table-level via verticalAlign prop',
- 'Striped even rows and hover highlight via XDSTableContext',
- 'Selection via useXDSTableSelectionState + useXDSTableSelection — checkboxes, select-all, disabled row handling',
- 'Sorting via useXDSTableSortable — single or multi-column sort with header indicators',
- 'Pagination via useXDSTablePagination — client-side, server-side, or cursor-based with auto-rendered controls',
- 'Column visibility via useXDSTableColumnSettings — toggle, reorder, and reset columns with XDSMultiSelector integration',
- 'Column resize via useXDSTableColumnResize — drag-to-resize column headers with min/max constraints and proportional-preserving behavior',
- 'Auto-generated columns from data object keys when columns prop is omitted',
- 'Themeable via className — target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',
- ],
- accessibility: [
- 'Selection plugin sets aria-selected on selected body rows',
- 'Select-all and per-row checkboxes use visually hidden labels ("Select all rows", "Select row") via isLabelHidden',
- 'Non-selectable rows (getIsItemSelectable returns false) render no checkbox',
- 'Disabled rows (getIsItemEnabled returns false) render a disabled checkbox',
- ],
- notes: [
- 'Two-layer design: XDSBaseTable provides unstyled structure and the plugin pipeline; XDSTable wraps it with XDSTableContext and styled sub-components.',
- 'Styling is owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not by plugins — each reads XDSTableContext to apply density, dividers, striped, and hover styles.',
- 'XDSTable accepts plugins as a named Record<string, TablePlugin<T>> and converts to an ordered array internally; XDSBaseTable accepts an ordered array directly.',
- 'The selection plugin uses useSyncExternalStore so only the row whose selection state changed re-renders. useXDSTableSelectionState manages the selection set and handles disabled/selectable row filtering for select-all automatically.',
- 'useXDSTableColumnResize — drag-to-resize column headers. Proportional columns preserve their ratio when neighboring columns are resized. Pass columnWidths state and onColumnResizeEnd to control width persistence. Use minWidth/maxWidth for per-resize constraints.',
- 'Body rows are memoized via React.memo with a custom comparison. For optimal performance, define columns outside the component or memoize them to avoid triggering full re-renders.',
- 'Columns can be auto-generated from data keys using generateColumns(); column widths are expressed as proportional (fr-like) or fixed pixel values via the proportional() and pixel() helpers.',
- 'tableProps on XDSBaseTable passes additional HTML attributes directly to the <table> element.',
+ 'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
+ 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: 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.' },
],
anatomy: [
{name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
@@ -780,39 +752,20 @@ export const docsZh = {
],
usage: {
description:
- '数据驱动的表格,通过 renderCell 实现丰富的单元格内容。使用 XDSBadge、XDSStatusDot、XDSText、XDSAvatar 和布局基础组件组合单元格。XDSBaseTable 提供无样式的结构核心,配合可组合的插件管道。',
- features: [
- '数据驱动渲染 — 传入数据和列定义,行自动渲染',
- '通过 renderCell 实现丰富的单元格内容 — 在表格单元格中组合 XDS 组件(XDSBadge、XDSStatusDot、XDSText、XDSAvatar)',
- '子元素模式 — 直接组合 XDSTableRow/XDSTableCell 实现手动布局',
- '插件系统 — 通过可组合的转换插件扩展表格行为',
- '密度变体:紧凑、均衡、宽松',
- '分隔线样式:行、列、网格、无',
- '通过 XDSTableContext 实现偶数行条纹和悬停高亮',
- '通过 useXDSTableSelection 实现选择功能 — 复选框、全选、aria-selected',
- '通过 useXDSTableSortable 实现排序 — 单列或多列排序,表头指示器',
- '通过 useXDSTablePagination 实现分页 — 客户端、服务器端或游标分页,自动渲染控件',
- '通过 useXDSTableColumnSettings 实现列可见性 — 切换、排序和重置列',
- '通过 useXDSTableColumnResize 实现列调整 — 拖拽表头调整宽度,支持最小/最大约束和等比例调整',
- '主体行使用自定义比较进行记忆化 — 仅重新渲染更改的行',
- '省略 columns 属性时,自动从数据对象键生成列',
- '通过 className 实现主题化 — 目标选择器:.xds-base-table、.xds-table-row、.xds-table-cell、.xds-table-header-cell',
+ 'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
+ 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: 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.' },
],
- accessibility: [
- '选择插件在选中的主体行上设置 aria-selected',
- '全选和每行复选框通过 isLabelHidden 使用视觉隐藏标签("Select all rows"、"Select row")',
- '不可选择的行(getIsItemSelectable 返回 false)不渲染复选框',
- '禁用的行(getIsItemEnabled 返回 false)渲染禁用状态的复选框',
- ],
- notes: [
- '双层设计:XDSBaseTable 提供无样式结构和插件管道;XDSTable 使用 XDSTableContext 和带样式的子组件对其进行包装。',
- '样式由组件(XDSTableRow、XDSTableCell、XDSTableHeaderCell)控制,而非插件 — 每个组件读取 XDSTableContext 来应用密度、分隔线、条纹和悬停样式。',
- 'XDSTable 接受命名的 Record<string, TablePlugin<T>> 格式的插件,并在内部转换为有序数组;XDSBaseTable 直接接受有序数组。',
- '选择插件使用 React Context,使 SelectAllCheckbox 和 SelectionRowCheckbox 独立于行内容重新渲染 — 仅当选择状态变化时更新 context 值。',
- 'useXDSTableColumnResize — 拖拽表头调整列宽。比例列在调整相邻列时保持比例。传入 columnWidths 状态和 onColumnResizeEnd 控制宽度持久化。使用 minWidth/maxWidth 设置每次调整的约束范围。',
- '主体行通过带有自定义比较的 React.memo 进行记忆化。为获得最佳性能,请在组件外部定义列或对其进行记忆化,以避免触发全量重新渲染。',
- '可以使用 generateColumns() 从数据键自动生成列;列宽使用 proportional() 和 pixel() 辅助函数表达为比例值(类似 fr)或固定像素值。',
- 'XDSBaseTable 上的 tableProps 将额外的 HTML 属性直接传递给 <table> 元素。',
+ anatomy: [
+ {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
+ {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
+ {name: 'Footer', required: false, description: 'Displays summary or totals.'},
+ {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
+ {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
+ {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
],
},
};
@@ -820,37 +773,24 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Data-driven table w/ rich cell content via renderCell. Compose cells w/ XDSBadge, XDSStatusDot, XDSText, XDSAvatar, layout primitives. XDSBaseTable provides unstyled structural core w/ composable plugin pipeline.',
- features: [
- 'Data-driven rendering; pass data + columns, rows render automatically',
- 'Rich cell content via renderCell; compose XDS components inside cells',
- 'Children mode; compose XDSTableRow/XDSTableCell directly for manual layouts',
- 'Plugin system; extend behavior w/ composable transform plugins',
- 'Density variants: compact, balanced, spacious',
- 'Divider styles: rows, columns, grid, none',
- 'Striped even rows + hover highlight via XDSTableContext',
- 'Selection via useXDSTableSelectionState + useXDSTableSelection — checkboxes, select-all, disabled row handling',
- 'Sorting via useXDSTableSortable — single/multi-column sort w/ header indicators',
- 'Pagination via useXDSTablePagination — client-side, server-side, cursor-based w/ auto-rendered controls',
- 'Column visibility via useXDSTableColumnSettings — toggle, reorder, reset w/ XDSMultiSelector integration',
- 'Body rows memoized w/ custom comparison; only changed rows re-render',
- 'Auto-generated columns from data object keys when columns omitted',
- 'Themeable via className; target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',
- ],
- notes: [
- 'Two-layer design: XDSBaseTable=unstyled structure + plugin pipeline; XDSTable wraps w/ XDSTableContext + styled sub-components.',
- 'Styling owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not plugins; each reads XDSTableContext.',
- 'XDSTable accepts plugins as Record<string, TablePlugin<T>>, converts to ordered array; XDSBaseTable accepts ordered array directly.',
- 'Selection plugin uses React Context; checkboxes re-render independently from row content.',
- 'Body rows memoized via React.memo w/ custom comparison; define columns outside component or memoize to avoid full re-renders.',
- 'Columns auto-generated from data keys via generateColumns(); widths via proportional() + pixel() helpers.',
- 'tableProps on XDSBaseTable passes extra HTML attrs to <table> element.',
- ],
- accessibility: [
- 'Selection plugin sets aria-selected on selected body rows.',
- 'Select-all + per-row checkboxes use visually hidden labels ("Select all rows", "Select row") via isLabelHidden.',
- 'Non-selectable rows (getIsItemSelectable=false) render no checkbox.',
- 'Disabled rows (getIsItemEnabled=false) render disabled checkbox.',
- ],
+ usage: {
+ description:
+ 'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
+ 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: 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.' },
+ ],
+ anatomy: [
+ {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
+ {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
+ {name: 'Footer', required: false, description: 'Displays summary or totals.'},
+ {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
+ {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
+ {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
+ ],
+ },
components: [
{
name: 'XDSTable',
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 181ef0263c..3abce65ea3 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -200,19 +200,12 @@ export const docs = {
],
usage: {
description:
- 'Text provides typography components for the XDS design system, including semantic body text via XDSText, headings via XDSHeading, and a wrapper for applying typography styles to native HTML.',
- features: [
- 'Semantic text types (body, large, label, supporting, code) driven by theme tokens',
- 'Headings use native h1–h6 elements with optional aria-level override for decoupled visual vs document hierarchy',
- 'Line-clamp truncation with automatic overflow-detecting tooltip',
- 'Optical alignment (text-box-trim / capsize) for precise vertical rhythm',
- 'Tabular number support for aligned numeric data',
- 'All typography driven by CSS custom properties — fully themeable per-component',
- ],
- accessibility: [
- 'XDSHeading renders the correct semantic h1–h6 element based on the `level` prop.',
- 'When `accessibilityLevel` differs from `level`, `aria-level` is set so screen readers announce the correct document outline position while preserving the visual style.',
- 'Truncated text sets a native `title` attribute as a fallback, and also lazily renders an XDSTooltip for sighted keyboard users.',
+ 'Text provides typography primitives for the design system, including body text via XDSText and headings via XDSHeading. Use XDSText for all body copy with semantic type variants, and XDSHeading for section headings that render the correct h1–h6 element.',
+ bestPractices: [
+ { guidance: true, description: 'Use the type prop on XDSText to select a semantic text style rather than manually setting size and weight.' },
+ { guidance: true, description: 'Set accessibilityLevel on XDSHeading when the visual heading level differs from the document outline hierarchy.' },
+ { guidance: false, description: 'Override size and weight on XDSText when a semantic type already matches your use case.' },
+ { guidance: false, description: 'Skip heading levels in the document outline — maintain a logical h1 through h6 hierarchy for accessibility.' },
],
},
};
@@ -418,19 +411,12 @@ export const docsZh = {
],
usage: {
description:
- 'XDS 设计系统的排版组件,包括语义化正文文本、标题以及将排版样式应用于原生 HTML 的包装器。',
- features: [
- '语义化文本类型(body、large、label、supporting、code),由主题令牌驱动',
- '标题使用原生 h1–h6 元素,支持可选的 aria-level 覆盖,实现视觉层级与文档层级的解耦',
- '行截断,带自动溢出检测工具提示',
- '光学对齐(text-box-trim / capsize),实现精确的垂直节奏',
- '表格数字支持,用于对齐的数值数据',
- '所有排版由 CSS 自定义属性驱动 — 每个组件均可完全主题化',
- ],
- accessibility: [
- 'XDSHeading 根据 `level` 属性渲染正确的语义化 h1–h6 元素。',
- '当 `accessibilityLevel` 与 `level` 不同时,会设置 `aria-level`,使屏幕阅读器播报正确的文档大纲位置,同时保留视觉样式。',
- '截断文本设置原生 `title` 属性作为后备方案,并为有视力的键盘用户延迟渲染 XDSTooltip。',
+ 'Text provides typography primitives for the design system, including body text via XDSText and headings via XDSHeading. Use XDSText for all body copy with semantic type variants, and XDSHeading for section headings that render the correct h1–h6 element.',
+ bestPractices: [
+ { guidance: true, description: 'Use the type prop on XDSText to select a semantic text style rather than manually setting size and weight.' },
+ { guidance: true, description: 'Set accessibilityLevel on XDSHeading when the visual heading level differs from the document outline hierarchy.' },
+ { guidance: false, description: 'Override size and weight on XDSText when a semantic type already matches your use case.' },
+ { guidance: false, description: 'Skip heading levels in the document outline — maintain a logical h1 through h6 hierarchy for accessibility.' },
],
},
};
@@ -438,19 +424,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Typography components: semantic body text, headings, wrapper for applying typography styles to native HTML.',
- features: [
- 'Semantic text types (body, large, label, supporting, code) driven by theme tokens',
- 'Headings use native h1\u20136 w/ optional aria-level override for decoupled visual vs document hierarchy',
- 'Line-clamp truncation w/ automatic overflow-detecting tooltip',
- 'Optical alignment (text-box-trim / capsize) for precise vertical rhythm',
- 'Tabular number support for aligned numeric data',
- 'All typography driven by CSS custom properties; fully themeable per-component',
- ],
- accessibility: [
- 'XDSHeading renders correct semantic h1\u20136 based on level prop.',
- 'When accessibilityLevel differs from level, aria-level set for correct document outline.',
- 'Truncated text sets native title attr as fallback + lazily renders XDSTooltip for keyboard users.',
- ],
+ usage: {
+ description:
+ 'Text provides typography primitives for the design system, including body text via XDSText and headings via XDSHeading. Use XDSText for all body copy with semantic type variants, and XDSHeading for section headings that render the correct h1–h6 element.',
+ bestPractices: [
+ { guidance: true, description: 'Use the type prop on XDSText to select a semantic text style rather than manually setting size and weight.' },
+ { guidance: true, description: 'Set accessibilityLevel on XDSHeading when the visual heading level differs from the document outline hierarchy.' },
+ { guidance: false, description: 'Override size and weight on XDSText when a semantic type already matches your use case.' },
+ { guidance: false, description: 'Skip heading levels in the document outline — maintain a logical h1 through h6 hierarchy for accessibility.' },
+ ],
+ },
components: [
{
name: 'XDSText',
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index 19f77f9b14..fd46041e6a 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -155,38 +155,12 @@ export const docs = {
},
usage: {
description:
- 'TextArea is a multi-line text input for collecting longer user input such as comments, descriptions, or longer-form content. Use TextInput instead for single-line input, or a rich text editor for formatted content.',
- features: [
- 'Label support — required label for accessibility, can be visually hidden',
- 'Description — optional text displayed between the label and textarea',
- 'Optional/Required indicators — displays "Optional" or "Required" text with bullet separator',
- 'Status variants — warning, error, and success states with colored borders and icons',
- 'Character counter — displays current/max length when maxLength is set (does not enforce natively)',
- 'Start icon — optional icon rendered inside the leading edge of the input',
- 'Label tooltip — optional info icon with tooltip at the end of the label',
- 'Loading state — shows a spinner and uses optimistic updates via useOptimistic',
- 'Async action support — onChangeAction fires after onChange inside a React transition',
- 'Disabled state — visual opacity and cursor changes, no interaction',
- 'Resizable — vertical resize enabled by default',
- 'Spell check — browser spell checking enabled by default, configurable',
- 'Reduced motion — respects prefers-reduced-motion for input wrapper transitions',
- ],
- accessibility: [
- 'Label is always rendered in the DOM; use isLabelHidden to hide it visually while keeping it accessible.',
- 'The textarea id is generated via useId and linked to its label via htmlFor, ensuring correct label association.',
- 'aria-describedby is set to the description and/or status message IDs when those elements are present.',
- 'aria-required="true" is set when isRequired is true.',
- 'aria-invalid="true" is set when status.type is "error".',
- 'aria-busy is set while an optimistic update or loading state is active.',
- ],
- notes: [
- 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" takes precedence.',
- 'The component uses useOptimistic for instant UI feedback when onChangeAction returns a Promise.',
- 'Textarea has vertical resize enabled via CSS.',
- 'Wraps XDSField for consistent label, description, and status message layout.',
- 'The character counter uses optimisticValue and turns red when it exceeds maxLength.',
- 'Interaction is blocked during busy state (loading or pending async action) to prevent double-input.',
- 'Character counter is connected to the textarea via aria-describedby and uses aria-live="polite" for screen reader announcements.',
+ 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },
+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },
+ { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },
+ { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },
],
},
};
@@ -345,39 +319,12 @@ export const docsZh = {
},
usage: {
description:
- '用于收集较长用户输入的多行文本输入组件。',
- features: [
- '标签支持 — 必需的无障碍标签,可视觉隐藏',
- '描述 — 显示在标签和文本域之间的可选文本',
- '可选/必填指示器 — 显示带圆点分隔符的"可选"或"必填"文本',
- '状态变体 — 警告、错误和成功状态,带彩色边框和图标',
- '字符计数器 — 设置 maxLength 时显示当前/最大长度(不原生强制限制)',
- '起始图标 — 在输入框前端内部渲染的可选图标',
- '标签工具提示 — 标签末尾带工具提示的可选信息图标',
- '加载状态 — 显示旋转器并通过 useOptimistic 使用乐观更新',
- '异步操作支持 — onChangeAction 在 React transition 内于 onChange 之后触发',
- '禁用状态 — 视觉透明度和光标变化,无交互',
- '无障碍 — 标签通过 htmlFor/id 关联,aria-describedby、aria-required、aria-invalid、aria-busy',
- '可调整大小 — 默认启用垂直调整大小',
- '拼写检查 — 默认启用浏览器拼写检查,可配置',
- '减少动画 — 尊重 prefers-reduced-motion 输入包装过渡',
- ],
- accessibility: [
- '标签始终在 DOM 中渲染;使用 isLabelHidden 视觉上隐藏它,同时保持无障碍性。',
- '文本域 id 通过 useId 生成并通过 htmlFor 与其标签关联,确保正确的标签关联。',
- '当描述和/或状态消息元素存在时,aria-describedby 设置为相应的 ID。',
- '当 isRequired 为 true 时,设置 aria-required="true"。',
- '当 status.type 为 "error" 时,设置 aria-invalid="true"。',
- '乐观更新或加载状态活跃期间设置 aria-busy。',
- ],
- notes: [
- 'isOptional 和 isRequired 互斥;如果同时设置,"可选"优先。',
- '当 onChangeAction 返回 Promise 时,组件使用 useOptimistic 实现即时 UI 反馈。',
- '文本域通过 CSS 启用垂直调整大小。',
- '包装 XDSField 以实现一致的标签、描述和状态消息布局。',
- '字符计数器使用 optimisticValue,超出 maxLength 时变为红色。',
- '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复输入。',
- '字符计数器通过 aria-describedby 连接到文本域,并使用 aria-live="polite" 进行屏幕阅读器公告。',
+ 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },
+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },
+ { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },
+ { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },
],
},
};
@@ -385,39 +332,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Multi-line text input for collecting longer user input.',
- features: [
- 'Label support; required for a11y, can be visually hidden',
- 'Description; optional text between label+textarea',
- 'Optional/Required indicators; displays "Optional" or "Required" w/ bullet separator',
- 'Status variants; warning, error, success states w/ colored borders+icons',
- 'Character counter; displays current/max length when maxLength set',
- 'Start icon; optional icon inside leading edge of input',
- 'Label tooltip; optional info icon w/ tooltip at label end',
- 'Loading state; shows spinner, uses optimistic updates via useOptimistic',
- 'Async action support; onChangeAction fires after onChange in React transition',
- 'Disabled state; visual opacity+cursor changes, no interaction',
- 'Accessible; label via htmlFor/id, aria-describedby, aria-required, aria-invalid, aria-busy',
- 'Resizable; vertical resize enabled by default',
- 'Spell check; browser spell checking enabled by default, configurable',
- 'Reduced motion; respects prefers-reduced-motion for input wrapper transitions',
- ],
- notes: [
- 'isOptional+isRequired mutually exclusive; both set = "Optional" wins.',
- 'Uses useOptimistic for instant UI feedback when onChangeAction returns Promise.',
- 'Textarea has vertical resize via CSS.',
- 'Wraps XDSField for consistent label, description, status message layout.',
- 'Character counter uses optimisticValue; turns red when exceeds maxLength.',
- 'Interaction blocked during busy state to prevent double-input.',
- 'Counter connected via aria-describedby + aria-live="polite" for screen readers.',
- ],
- accessibility: [
- 'Label always in DOM; isLabelHidden hides visually, keeps a11y.',
- 'Textarea id via useId linked to label via htmlFor for correct association.',
- 'aria-describedby set to description+status message IDs when present.',
- 'aria-required="true" when isRequired is true.',
- 'aria-invalid="true" when status.type is "error".',
- 'aria-busy set during optimistic update or loading state.',
- ],
+ usage: {
+ description:
+ 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },
+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },
+ { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },
+ { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },
+ ],
+ },
propDescriptions: {
ref: 'ref forwarded to underlying <textarea>.',
label: 'Label text for textarea; always rendered for a11y.',
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 4e121872dc..060621cedb 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -131,30 +131,12 @@ export const docs = {
},
usage: {
description:
- 'TextInput enables users to enter or edit short-form text values with built-in label, description, validation status, and optional/required indicators. Size the input to reflect the expected content length and use validation messaging for required fields.',
- features: [
- 'Label support — required label for accessibility (can be visually hidden)',
- 'Description — optional text displayed between the label and input',
- 'Optional/Required indicators — "Optional" or "Required" text with bullet separator',
- 'Label tooltip — optional info icon with tooltip at the end of the label',
- 'Validation status — error, warning, and success states with colored borders and icons',
- 'Start icon — optional icon displayed at the start of the input',
- 'Loading state — shows a spinner and sets aria-busy while an async action is pending',
- 'Disabled state — visually dims the input and prevents interaction',
- 'Styled with StyleX — uses XDS design tokens for consistent styling',
- ],
- accessibility: [
- 'Label is always rendered and associated with the input via htmlFor/id (using useId). Use isLabelHidden to hide it visually while keeping it accessible to screen readers.',
- 'aria-describedby is set automatically when description or a status message is present.',
- 'aria-invalid="true" is set when status.type is "error".',
- 'aria-required="true" is set when isRequired is true.',
- 'aria-busy is set while an optimistic update or isLoading is active.',
- ],
- notes: [
- 'isOptional and isRequired are mutually exclusive — if both are set, "Optional" is shown.',
- 'onChangeAction fires after onChange inside a React transition, enabling useOptimistic for an instant UI update while the async work completes.',
- 'The component wraps XDSField for label, description, and optional/required rendering.',
- 'The size prop supports "sm", "md", and "lg".',
+ 'TextInput enables users to enter or edit short-form text such as names, emails, or search queries. Use it for single-line values where the expected input is brief, and pair it with validation status to guide users through required fields.',
+ bestPractices: [
+ { guidance: true, description: 'Size the input to reflect the expected content length so users can gauge how much to type.' },
+ { guidance: true, description: 'Use validation status messages to provide clear, contextual feedback on field errors.' },
+ { guidance: false, description: 'Use a TextInput for multi-line content like comments or descriptions — use TextArea instead.' },
+ { guidance: false, description: 'Rely on placeholder text as a substitute for a label.' },
],
anatomy: [
{name: 'Label', required: true, description: 'Text that identifies the input field.'},
@@ -295,31 +277,19 @@ export const docsZh = {
},
usage: {
description:
- '用于收集用户文本输入的文本输入组件,带有标签、描述、验证状态和可选/必填指示器。',
- features: [
- '标签支持 — 必需的无障碍标签(可视觉隐藏)',
- '描述 — 显示在标签和输入框之间的可选文本',
- '可选/必填指示器 — 带圆点分隔符的"可选"或"必填"文本',
- '标签工具提示 — 标签末尾带工具提示的可选信息图标',
- '验证状态 — 错误、警告和成功状态,带彩色边框和图标',
- '起始图标 — 显示在输入框起始位置的可选图标',
- '加载状态 — 异步操作挂起时显示旋转器并设置 aria-busy',
- '禁用状态 — 视觉上使输入框变暗并阻止交互',
- '无障碍 — 标签始终通过 htmlFor/id 与输入框关联;根据需要设置 aria-invalid、aria-required、aria-busy 和 aria-describedby',
- '使用 StyleX 样式化 — 使用 XDS 设计令牌实现一致的样式',
- ],
- accessibility: [
- '标签始终渲染并通过 htmlFor/id(使用 useId)与输入框关联。使用 isLabelHidden 视觉上隐藏它,同时保持屏幕阅读器的无障碍性。',
- '当描述或状态消息存在时,自动设置 aria-describedby。',
- '当 status.type 为 "error" 时,设置 aria-invalid="true"。',
- '当 isRequired 为 true 时,设置 aria-required="true"。',
- '乐观更新或 isLoading 活跃期间设置 aria-busy。',
+ 'TextInput enables users to enter or edit short-form text such as names, emails, or search queries. Use it for single-line values where the expected input is brief, and pair it with validation status to guide users through required fields.',
+ bestPractices: [
+ { guidance: true, description: 'Size the input to reflect the expected content length so users can gauge how much to type.' },
+ { guidance: true, description: 'Use validation status messages to provide clear, contextual feedback on field errors.' },
+ { guidance: false, description: 'Use a TextInput for multi-line content like comments or descriptions — use TextArea instead.' },
+ { guidance: false, description: 'Rely on placeholder text as a substitute for a label.' },
],
- notes: [
- 'isOptional 和 isRequired 互斥 — 如果同时设置,显示"可选"。',
- 'onChangeAction 在 React transition 内于 onChange 之后触发,启用 useOptimistic 以在异步工作完成时实现即时 UI 更新。',
- '组件包装 XDSField 以实现标签、描述和可选/必填的渲染。',
- 'size 属性支持 "sm"、"md" 和 "lg"。',
+ anatomy: [
+ {name: 'Label', required: true, description: 'Text that identifies the input field.'},
+ {name: 'Description', required: false, description: 'Helper text providing additional context.'},
+ {name: 'Icon', required: false, description: '16px icon displayed inside the input.'},
+ {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty.'},
+ {name: 'Spinner', required: false, description: 'Loading indicator for pending actions.'},
],
},
};
@@ -327,31 +297,23 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Text input for collecting user text w/ label, description, validation status, optional/required indicators.',
- features: [
- 'Label support; required for a11y (can be visually hidden)',
- 'Description; optional text between label+input',
- 'Optional/Required indicators; "Optional" or "Required" text w/ bullet separator',
- 'Label tooltip; optional info icon w/ tooltip at label end',
- 'Validation status; error, warning, success states w/ colored borders+icons',
- 'Start icon; optional icon at input start',
- 'Loading state; shows spinner+sets aria-busy while async action pending',
- 'Disabled state; dims input, prevents interaction',
- 'Accessible; label always associated via htmlFor/id; sets aria-invalid, aria-required, aria-busy, aria-describedby',
- 'Styled w/ StyleX; uses XDS design tokens for consistent styling',
- ],
- notes: [
- 'isOptional+isRequired mutually exclusive; both set = "Optional" shown.',
- 'onChangeAction fires after onChange in React transition, enables useOptimistic for instant UI update.',
- 'Wraps XDSField for label, description, optional/required rendering.',
- 'size supports "sm", "md", "lg".',
- ],
- accessibility: [
- 'Label always rendered+associated via htmlFor/id (useId). isLabelHidden hides visually, keeps screen reader access.',
- 'aria-describedby auto-set when description or status message present.',
- 'aria-invalid="true" when status.type is "error".',
- 'aria-required="true" when isRequired is true.',
- 'aria-busy set during optimistic update or isLoading.',
- ],
+ usage: {
+ description:
+ 'TextInput enables users to enter or edit short-form text such as names, emails, or search queries. Use it for single-line values where the expected input is brief, and pair it with validation status to guide users through required fields.',
+ bestPractices: [
+ { guidance: true, description: 'Size the input to reflect the expected content length so users can gauge how much to type.' },
+ { guidance: true, description: 'Use validation status messages to provide clear, contextual feedback on field errors.' },
+ { guidance: false, description: 'Use a TextInput for multi-line content like comments or descriptions — use TextArea instead.' },
+ { guidance: false, description: 'Rely on placeholder text as a substitute for a label.' },
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'Text that identifies the input field.'},
+ {name: 'Description', required: false, description: 'Helper text providing additional context.'},
+ {name: 'Icon', required: false, description: '16px icon displayed inside the input.'},
+ {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty.'},
+ {name: 'Spinner', required: false, description: 'Loading indicator for pending actions.'},
+ ],
+ },
propDescriptions: {
type: 'HTML input type.',
label: 'Label text for input; always rendered for a11y.',
diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
index 1a812fd9bb..dea3d52776 100644
--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs
+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
@@ -68,25 +68,11 @@ export const docs = {
},
usage: {
description:
- 'Thumbnail is a square preview card for image attachments. It shows a skeleton shimmer while uploading, the image on success, or a placeholder icon when no source is provided.',
- features: [
- 'Square 1:1 aspect ratio via CSS aspect-ratio',
- 'Skeleton shimmer during upload (isLoading)',
- 'Upload overlay with spinner when isLoading + src',
- 'Image preview with object-fit: cover',
- 'Hover shadow on interactive thumbnails (onClick)',
- 'Label shown as tooltip on hover, used as aria-label',
- 'Placeholder icon when no src',
- 'Disabled state blocks all interactions and reduces opacity',
- ],
- accessibility: [
- 'label prop provides aria-label for the thumbnail and its remove button.',
- 'onClick renders as a button for keyboard and screen reader access.',
- 'Remove button uses aria-label derived from the label prop.',
- ],
- notes: [
- 'APCA-based luminance detection for adaptive remove button contrast.',
- 'Concentric radius: button radius derived from container radius minus inset.',
+ 'Thumbnail is a square preview card for image attachments, showing a loading skeleton during upload and the image on success. Use it to represent uploaded files, image previews, or media attachments in compact layouts.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a descriptive label prop so the thumbnail and its remove button are accessible to screen readers.' },
+ { guidance: true, description: 'Use the isLoading state to show upload progress rather than displaying a broken or missing image.' },
+ { guidance: false, description: 'Use Thumbnail for non-image file types — use a file attachment component with an appropriate icon instead.' },
],
},
};
@@ -108,23 +94,11 @@ export const docsZh = {
},
usage: {
description:
- '图片附件的方形预览卡片。上传时显示骨架屏动画,成功时显示图片,无图片源时显示占位图标。',
- features: [
- '通过 CSS aspect-ratio 实现 1:1 正方形比例',
- '上传时骨架屏闪烁效果(isLoading)',
- 'isLoading + src 时显示上传覆盖层和加载指示器',
- '通过 object-fit: cover 预览图片',
- '基于 APCA 亮度检测的自适应移除按钮对比度',
- '同心圆角:按钮圆角由容器圆角减去内边距推导',
- '可交互缩略图(onClick)的悬停阴影',
- '标签作为悬停提示工具和 aria-label 显示',
- '无 src 时显示占位图标',
- '禁用状态阻止所有交互并降低不透明度',
- ],
- accessibility: [
- 'label 属性为缩略图及其移除按钮提供 aria-label。',
- 'onClick 渲染为按钮以支持键盘和屏幕阅读器访问。',
- '移除按钮使用从 label 属性推导的 aria-label。',
+ 'Thumbnail is a square preview card for image attachments, showing a loading skeleton during upload and the image on success. Use it to represent uploaded files, image previews, or media attachments in compact layouts.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a descriptive label prop so the thumbnail and its remove button are accessible to screen readers.' },
+ { guidance: true, description: 'Use the isLoading state to show upload progress rather than displaying a broken or missing image.' },
+ { guidance: false, description: 'Use Thumbnail for non-image file types — use a file attachment component with an appropriate icon instead.' },
],
},
};
@@ -133,12 +107,15 @@ 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'],
- f: [
- '1:1 aspect-ratio. Skeleton shimmer (isLoading). Upload overlay w/ spinner.',
- 'APCA luminance for adaptive remove button contrast. Concentric radius.',
- 'Hover shadow on onClick. Tooltip from label. Placeholder icon when no src.',
- 'Disabled state blocks interactions, reduces opacity.',
- ],
+ usage: {
+ description:
+ 'Thumbnail is a square preview card for image attachments, showing a loading skeleton during upload and the image on success. Use it to represent uploaded files, image previews, or media attachments in compact layouts.',
+ bestPractices: [
+ { guidance: true, description: 'Provide a descriptive label prop so the thumbnail and its remove button are accessible to screen readers.' },
+ { guidance: true, description: 'Use the isLoading state to show upload progress rather than displaying a broken or missing image.' },
+ { guidance: false, description: 'Use Thumbnail for non-image file types — use a file attachment component with an appropriate icon instead.' },
+ ],
+ },
p: {
src: 'Image source URL.',
alt: 'Alt text for image.',
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 8c70239598..3f4be73d13 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -143,25 +143,11 @@ export const docs = {
},
usage: {
description:
- 'TimeInput is a time input field with free-text entry, text parsing, and arrow-key navigation. Use it when users need to input a time, such as in scheduling or form fields.',
- features: [
- 'Accepts free-text time entry and parses common formats (e.g. "2:30 PM", "14:30")',
- 'Supports 12-hour and 24-hour display formats',
- 'Arrow-up / arrow-down adjust the time by a configurable minute increment',
- 'Optional seconds display via hasSeconds',
- 'Optional clear button via hasClear',
- 'Min / max range constraints reject out-of-range values',
- 'Async action support via onChangeAction with optimistic UI and loading spinner',
- ],
- accessibility: [
- 'The visible label is associated with the input via htmlFor / id.',
- 'isLabelHidden visually hides the label while keeping it in the accessibility tree.',
- 'description and status.message are linked to the input via aria-describedby.',
- 'aria-required is set when isRequired is true.',
- 'aria-invalid is set when status.type is "error".',
- 'aria-busy reflects the loading / optimistic-pending state.',
- 'The clear button has an explicit aria-label of "Clear time".',
- 'Keyboard: ArrowUp/ArrowDown adjust the current time by the configured increment in minutes; typing a time string in common formats is parsed on blur; pressing the clear button returns focus to the input.',
+ 'TimeInput is a time entry field with free-text parsing and arrow-key navigation. Use it in forms, scheduling interfaces, or anywhere users need to specify a time of day.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\'s locale and expectations.'},
+ {guidance: true, description: 'Set min and max constraints to prevent users from selecting invalid times for the context.'},
+ {guidance: false, description: 'Use TimeInput for date-and-time selection — pair it with DateInput for combined date-time fields.'},
],
},
};
@@ -309,26 +295,11 @@ export const docsZh = {
},
usage: {
description:
- '支持自由文本输入、文本解析和方向键导航的时间输入组件。',
- features: [
- '接受自由文本时间输入并解析常见格式(例如 "2:30 PM"、"14:30")',
- '支持 12 小时和 24 小时显示格式',
- '上/下方向键按可配置的分钟增量调整时间',
- '通过 hasSeconds 可选显示秒',
- '通过 hasClear 可选清除按钮',
- '最小/最大范围约束拒绝超出范围的值',
- '通过 onChangeAction 支持异步操作,带乐观 UI 和加载旋转器',
- '无障碍 — 标签、描述和状态消息通过 aria-describedby 关联;aria-required 和 aria-invalid 反映字段状态',
- ],
- accessibility: [
- '可见标签通过 htmlFor / id 与输入框关联。',
- 'isLabelHidden 视觉上隐藏标签,同时保持在无障碍树中。',
- 'description 和 status.message 通过 aria-describedby 与输入框关联。',
- '当 isRequired 为 true 时设置 aria-required。',
- '当 status.type 为 "error" 时设置 aria-invalid。',
- 'aria-busy 反映加载/乐观更新挂起状态。',
- '清除按钮具有明确的 aria-label "Clear time"。',
- 'Keyboard: 上/下方向键按配置的分钟增量调整当前时间。以常见格式(例如 "2:30 PM"、"14:30")输入时间字符串会在失焦时解析。按清除按钮将焦点返回到输入框。',
+ 'TimeInput is a time entry field with free-text parsing and arrow-key navigation. Use it in forms, scheduling interfaces, or anywhere users need to specify a time of day.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\'s locale and expectations.'},
+ {guidance: true, description: 'Set min and max constraints to prevent users from selecting invalid times for the context.'},
+ {guidance: false, description: 'Use TimeInput for date-and-time selection — pair it with DateInput for combined date-time fields.'},
],
},
};
@@ -336,26 +307,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Time input w/ free-text entry, text parsing, arrow-key navigation.',
- features: [
- 'Accepts free-text time entry; parses common formats (e.g. "2:30 PM", "14:30")',
- 'Supports 12-hour+24-hour display formats',
- 'ArrowUp/ArrowDown adjust time by configurable minute increment',
- 'Optional seconds display via hasSeconds',
- 'Optional clear button via hasClear',
- 'Min/max range constraints reject out-of-range values',
- 'Async action support via onChangeAction w/ optimistic UI+loading spinner',
- 'Accessible; label, description, status message wired to aria-describedby; aria-required+aria-invalid reflect field state',
- ],
- accessibility: [
- 'Visible label associated w/ input via htmlFor/id.',
- 'isLabelHidden hides label visually; keeps in a11y tree.',
- 'description+status.message linked to input via aria-describedby.',
- 'aria-required set when isRequired is true.',
- 'aria-invalid set when status.type is "error".',
- 'aria-busy reflects loading/optimistic-pending state.',
- 'Clear button has aria-label "Clear time".',
- ],
- keyboard: 'ArrowUp/ArrowDown adjust time by configured increment in minutes. Typing common formats (e.g. "2:30 PM", "14:30") parsed on blur. Clear button press returns focus to input.',
+ usage: {
+ description:
+ 'TimeInput is a time entry field with free-text parsing and arrow-key navigation. Use it in forms, scheduling interfaces, or anywhere users need to specify a time of day.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\'s locale and expectations.'},
+ {guidance: true, description: 'Set min and max constraints to prevent users from selecting invalid times for the context.'},
+ {guidance: false, description: 'Use TimeInput for date-and-time selection — pair it with DateInput for combined date-time fields.'},
+ ],
+ },
propDescriptions: {
label: 'Label text (required for a11y).',
isLabelHidden: 'Visually hides label; keeps screen reader access.',
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index 8ad7002f8b..ef966aef15 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -76,19 +76,11 @@ export const docs = {
},
usage: {
description:
- 'Timestamp displays a formatted timestamp as human-readable text with optional tooltip and live updates, rendering via XDSText for consistent typography. Choose a format that fits the context — absolute for precision, relative for recency — and ensure consistent formatting within the same view.',
- features: [
- "Formats: 'relative', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time', 'auto'",
- 'Live updates: opt-in timer that adjusts frequency based on age',
- 'Tooltip: shows full date/time on hover for relative timestamps',
- 'Semantic HTML: renders <time> with ISO 8601 datetime attribute',
- 'Typography: delegates to XDSText for consistent sizing and color',
- "System formats: ISO-style dates/times for databases and logs",
- ],
- accessibility: [
- 'Renders as <time datetime="..."> with ISO 8601 datetime attribute for machines.',
- 'Sets aria-label with full absolute time when displaying relative format.',
- 'Tooltip is keyboard accessible via focus.',
+ 'Timestamp displays a date or time value as human-readable text with optional tooltip and live updates. Use it to show when content was created, updated, or is scheduled, choosing a format that fits the context — relative for recency, absolute for precision.',
+ bestPractices: [
+ { guidance: true, description: 'Use the auto format to let the component switch between relative and absolute based on recency.' },
+ { guidance: true, description: 'Keep timestamp formatting consistent within the same view or list to avoid confusion.' },
+ { guidance: false, description: 'Display raw Unix timestamps or ISO strings directly — use Timestamp to format them for users.' },
],
anatomy: [
{name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
@@ -113,19 +105,17 @@ export const docsZh = {
weight: '字体粗细覆盖。',
},
usage: {
- description: '以人类可读文本显示格式化时间戳,可选工具提示和实时更新。',
- features: [
- "格式:'relative'、'date'、'date_time'、'time'、'system_date'、'system_date_time'、'system_time'、'auto'",
- '实时更新:根据时间戳年龄自适应频率的计时器',
- '工具提示:悬停时显示相对时间戳的完整日期/时间',
- '语义化 HTML:使用 ISO 8601 datetime 属性渲染 <time>',
- '排版:委托给 XDSText 以保持一致的大小和颜色',
- "系统格式:数据库和日志的 ISO 风格日期/时间",
+ description:
+ 'Timestamp displays a date or time value as human-readable text with optional tooltip and live updates. Use it to show when content was created, updated, or is scheduled, choosing a format that fits the context — relative for recency, absolute for precision.',
+ bestPractices: [
+ { guidance: true, description: 'Use the auto format to let the component switch between relative and absolute based on recency.' },
+ { guidance: true, description: 'Keep timestamp formatting consistent within the same view or list to avoid confusion.' },
+ { guidance: false, description: 'Display raw Unix timestamps or ISO strings directly — use Timestamp to format them for users.' },
],
- accessibility: [
- '作为带有 ISO 8601 datetime 属性的 <time datetime="..."> 渲染,供机器读取。',
- '显示相对格式时,设置带有完整绝对时间的 aria-label。',
- '工具提示可通过焦点访问键盘。',
+ anatomy: [
+ {name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
+ {name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},
+ {name: 'Hover Card', required: false, description: 'Floating card showing timezone, full date, or additional details on hover.'},
],
},
};
@@ -133,6 +123,20 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'formatted timestamp display with relative/absolute/auto modes via XDSText',
+ usage: {
+ description:
+ 'Timestamp displays a date or time value as human-readable text with optional tooltip and live updates. Use it to show when content was created, updated, or is scheduled, choosing a format that fits the context — relative for recency, absolute for precision.',
+ bestPractices: [
+ { guidance: true, description: 'Use the auto format to let the component switch between relative and absolute based on recency.' },
+ { guidance: true, description: 'Keep timestamp formatting consistent within the same view or list to avoid confusion.' },
+ { guidance: false, description: 'Display raw Unix timestamps or ISO strings directly — use Timestamp to format them for users.' },
+ ],
+ anatomy: [
+ {name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},
+ {name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},
+ {name: 'Hover Card', required: false, description: 'Floating card showing timezone, full date, or additional details on hover.'},
+ ],
+ },
propDescriptions: {
value: 'date/time as unix seconds or ISO string',
format: "display mode: 'relative', 'auto', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time'",
diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs
index 17d6250148..a49c4b5c0b 100644
--- a/packages/core/src/Toast/Toast.doc.mjs
+++ b/packages/core/src/Toast/Toast.doc.mjs
@@ -57,20 +57,12 @@ export const docs = {
usage: {
description:
- 'Toast is a transient notification that appears briefly to confirm actions or surface non-critical information, such as save confirmations or undo opportunities. It provides auto-dismiss, stacking, deduplication, and smooth animations with inverted surface theming via XDSMediaTheme. For critical information requiring user action or persistent messages, use Banner instead.',
- features: [
- "Types: 'info' (default), 'error'",
- 'Auto-dismiss: info toasts dismiss after 5s, error toasts persist',
- 'Pause on hover/focus: timer pauses during interaction',
- 'Stacking: multiple toasts stack with smooth enter/exit animations',
- 'Deduplication: uniqueID with ignore or overwrite collision behavior',
- 'Programmatic dismiss: show() returns a dismiss function',
- 'End content slot: trailing actions (buttons, links)',
- 'Fallback viewport: works without a provider via document.body fallback',
- 'Inverted surface: uses XDSMediaTheme for correct colors on dark/light backgrounds',
- ],
- accessibility: [
- 'Uses role=status for info toasts and role=alert for error toasts, with aria-live=polite and aria-live=assertive respectively.',
+ 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',
+ bestPractices: [
+ { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },
+ { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },
+ { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },
+ { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },
],
},
};
@@ -95,20 +87,12 @@ export const docsZh = {
},
usage: {
description:
- '短暂通知,出现片刻以确认操作或显示非关键信息(如保存确认或撤销机会)。支持自动关闭、堆叠、去重和平滑动画,使用 XDSMediaTheme 进行反转表面主题。对于需要用户操作的关键信息或持久性消息,请使用 Banner。',
- features: [
- "类型:'info'(默认)、'error'",
- '自动关闭:info toast 5秒后关闭,error toast 持续显示',
- '悬停/聚焦暂停:交互时计时器暂停',
- '堆叠:多个 toast 以平滑进出动画堆叠',
- '去重:uniqueID 支持 ignore 或 overwrite 碰撞行为',
- '程序化关闭:show() 返回关闭函数',
- '尾部内容插槽:尾随操作(按钮、链接)',
- '回退视口:无需 provider,通过 document.body 回退',
- '反转表面:使用 XDSMediaTheme 在深色/浅色背景上显示正确颜色',
- ],
- accessibility: [
- 'info toast 使用 role=status 和 aria-live=polite,error toast 使用 role=alert 和 aria-live=assertive。',
+ 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',
+ bestPractices: [
+ { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },
+ { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },
+ { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },
+ { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },
],
},
};
@@ -117,18 +101,16 @@ export const docsZh = {
export const docsDense = {
description:
'toast notification w/ auto-dismiss, stacking, dedup, smooth animations; XDSMediaTheme inverted surface',
- features: [
- "types: info (default), error",
- 'auto-dismiss: info 5s, error persists',
- 'pause on hover/focus',
- 'stacking w/ smooth enter/exit animations',
- 'dedup: uniqueID w/ ignore|overwrite collision',
- 'programmatic dismiss: show() returns dismiss fn',
- 'end content slot: trailing actions',
- 'fallback viewport: works w/o provider via document.body',
- 'inverted surface: XDSMediaTheme for dark/light bg colors',
- 'a11y: role=status/alert, aria-live=polite/assertive',
- ],
+ usage: {
+ description:
+ 'Toast is a transient notification that appears briefly to confirm an action or surface non-critical information. Use it for save confirmations, undo opportunities, or status updates that do not require user interaction.',
+ bestPractices: [
+ { guidance: true, description: 'Keep toast messages short and actionable so users can read them before they auto-dismiss.' },
+ { guidance: true, description: 'Include an undo action in the endContent slot for reversible operations.' },
+ { guidance: false, description: 'Use a toast for critical errors or information that requires user acknowledgment — use Banner instead.' },
+ { guidance: false, description: 'Stack multiple toasts for the same event — use uniqueID to deduplicate.' },
+ ],
+ },
propDescriptions: {
body: 'primary message content',
type: 'toast type; controls bg color; error persists until dismissed',
@@ -139,18 +121,4 @@ export const docsDense = {
collisionBehavior: 'behavior when matching uniqueID exists',
onHide: 'callback when toast removed',
},
- usage: {
- summary: 'transient notification confirming action or surfacing non-critical info',
- content: `## When to use
-
-- confirm completed action
-- non-critical time-sensitive info
-- undo opportunities for reversible actions
-
-## When NOT to use
-
-- critical info requiring action (use Banner)
-- persistent messages (use Banner)
-- form field validation errors (use Field status)`,
- },
};
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index e31a6e99e0..2bd3db97d9 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -46,21 +46,12 @@ export const docs = {
],
usage: {
description:
- 'ToggleButton is a button that switches between two persistent states (active/inactive), with optional icon swap and group integration for single or multi-select behavior. Use a group of toggle buttons for multiple independent two-state actions, or a toggle button group for mutually exclusive states. Convey state through color change, bolded text, or a filled icon, and keep the label the same between states.',
- features: [
- 'Controlled toggle via isPressed/onPressedChange',
- 'Icon swap between pressed and unpressed states via pressedIcon',
- 'Font weight emphasis on press with width reservation to prevent layout shift',
- 'Async action support via onPressedChangeAction with loading spinner',
- 'Group integration via XDSToggleButtonGroup for single or multi-select',
- 'Discriminated union on type: single (string | null) or multiple (string[])',
- 'Horizontal and vertical group orientation',
- 'Built on XDSButton with all its size, disabled, and tooltip support',
- ],
- accessibility: [
- 'Uses aria-pressed on the toggle button for screen reader state announcement.',
- 'Group uses role="group" with aria-label from the label prop.',
- 'Keyboard: Space/Enter toggles pressed state; Tab moves between buttons in a group.',
+ 'ToggleButton is a button that switches between pressed and unpressed states to represent a persistent on/off choice. Use it standalone for binary actions like bold or mute, or within a ToggleButtonGroup for single-select or multi-select toolbar options.',
+ bestPractices: [
+ { guidance: true, description: 'Convey the pressed state through a filled icon, bold text, or color change so users can see the current state at a glance.' },
+ { guidance: true, description: 'Keep the label the same between pressed and unpressed states — let the visual treatment communicate the change.' },
+ { guidance: false, description: 'Use a ToggleButton for actions that navigate to another page or trigger a one-time event — use Button instead.' },
+ { guidance: false, description: 'Mix ToggleButtons with regular Buttons in the same group.' },
],
},
};
@@ -106,21 +97,12 @@ export const docsZh = {
],
usage: {
description:
- '在按下和未按下状态之间切换的按钮,支持图标切换和分组集成,用于单选或多选行为。',
- features: [
- '通过 isPressed/onPressedChange 实现受控切换',
- '通过 pressedIcon 在按下和未按下状态之间切换图标',
- '按下时字重加粗,并预留宽度防止布局偏移',
- '通过 onPressedChangeAction 支持异步操作,显示加载动画',
- '通过 XDSToggleButtonGroup 实现分组集成,支持单选或多选',
- 'type 判别联合类型:single (string | null) 或 multiple (string[])',
- '支持水平和垂直方向的分组布局',
- '基于 XDSButton 构建,继承其尺寸、禁用和提示功能',
- ],
- accessibility: [
- '使用 aria-pressed 向屏幕阅读器宣告切换按钮状态。',
- '分组使用 role="group" 并通过 label 属性设置 aria-label。',
- 'Keyboard: Space/Enter 切换按下状态;Tab 在分组中的按钮间移动焦点',
+ 'ToggleButton is a button that switches between pressed and unpressed states to represent a persistent on/off choice. Use it standalone for binary actions like bold or mute, or within a ToggleButtonGroup for single-select or multi-select toolbar options.',
+ bestPractices: [
+ { guidance: true, description: 'Convey the pressed state through a filled icon, bold text, or color change so users can see the current state at a glance.' },
+ { guidance: true, description: 'Keep the label the same between pressed and unpressed states — let the visual treatment communicate the change.' },
+ { guidance: false, description: 'Use a ToggleButton for actions that navigate to another page or trigger a one-time event — use Button instead.' },
+ { guidance: false, description: 'Mix ToggleButtons with regular Buttons in the same group.' },
],
},
};
@@ -128,21 +110,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'toggle btn w/ pressed/unpressed states, icon swap, group integration for single/multi-select',
- features: [
- 'controlled toggle via isPressed/onPressedChange',
- 'icon swap pressed/unpressed via pressedIcon',
- 'font weight emphasis on press w/ width reservation (no layout shift)',
- 'async action via onPressedChangeAction w/ loading spinner',
- 'group integration via XDSToggleButtonGroup for single/multi-select',
- 'discriminated union on type: single (string|null) or multiple (string[])',
- 'horizontal+vertical group orientation',
- 'built on XDSButton w/ size, disabled, tooltip support',
- ],
- accessibility: [
- 'aria-pressed on toggle btn for screen reader state',
- 'group uses role="group" w/ aria-label from label prop',
- ],
- keyboard: 'Space/Enter toggles; Tab moves between btns in group',
+ usage: {
+ description:
+ 'ToggleButton is a button that switches between pressed and unpressed states to represent a persistent on/off choice. Use it standalone for binary actions like bold or mute, or within a ToggleButtonGroup for single-select or multi-select toolbar options.',
+ bestPractices: [
+ { guidance: true, description: 'Convey the pressed state through a filled icon, bold text, or color change so users can see the current state at a glance.' },
+ { guidance: true, description: 'Keep the label the same between pressed and unpressed states — let the visual treatment communicate the change.' },
+ { guidance: false, description: 'Use a ToggleButton for actions that navigate to another page or trigger a one-time event — use Button instead.' },
+ { guidance: false, description: 'Mix ToggleButtons with regular Buttons in the same group.' },
+ ],
+ },
components: [
{
name: 'XDSToggleButton',
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
index e3ad22f93f..79a44dbe71 100644
--- a/packages/core/src/Token/Token.doc.mjs
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -84,23 +84,12 @@ export const docs = {
},
usage: {
description:
- 'Token is a chip/tag component for displaying entities inline, rendering as a <span> by default, <a> when href is provided, or a <span> with an invisible <button> when onClick is used. It is ideal for concise metadata display such as tags, names, or colored indicators. For static indicators without interaction, use Badge instead.',
- features: [
- 'Polymorphic — renders as <span>, <a>, or interactive <span>+<button> based on props',
- 'Invisible button pattern for onClick preserves real button semantics while allowing focus-within outline on the full token',
- 'Remove button with expanded 14px hit-area tap target via ::after pseudo-element',
- 'Eleven color variants including a neutral default',
- 'Leading icon and trailing endContent slots',
- 'Label can be visually hidden while remaining accessible to screen readers',
- 'Disabled state reduces opacity and blocks pointer events',
- ],
- accessibility: [
- 'When isLabelHidden is true, the label is clipped visually but exposed via aria-label on the root element so screen readers still announce it.',
- 'The description prop maps to aria-description on the root element for supplementary context.',
- 'When onClick is provided, the clickable content is wrapped in a real <button> so keyboard users can activate it with Enter or Space.',
- 'The remove button has an automatic aria-label of "Remove <label>" and an expanded touch target via a ::after pseudo-element.',
- 'When href is provided, aria-disabled is set on the <a> element when isDisabled is true.',
- 'Keyboard: Tab focuses the token (or its inner button when onClick is used); Enter/Space activate a clickable token or the remove button; Remove button is reachable as a separate Tab stop.',
+ 'Token is a compact chip component for displaying entities like tags, names, or status indicators inline within content. Use a Token to represent metadata, categorization, or removable selections. For static status indicators without interaction, use Badge instead.',
+ bestPractices: [
+ {guidance: true, description: 'Use color variants to distinguish different categories or entity types at a glance.'},
+ {guidance: true, description: 'Provide an onRemove callback when users need the ability to dismiss or deselect a token.'},
+ {guidance: false, description: 'Avoid using tokens for primary actions or navigation — use Button or Link instead.'},
+ {guidance: false, description: 'Avoid hiding the label unless an icon provides sufficient visual meaning on its own.'},
],
anatomy: [
{name: 'Color', required: false, description: 'Background color indicator.'},
@@ -197,23 +186,19 @@ export const docsZh = {
},
usage: {
description:
- '用于内联显示实体的标签/标记组件。默认渲染为 <span>,提供 href 时渲染为 <a>,提供 onClick 时渲染为包含不可见 <button> 的 <span>。',
- features: [
- '多态渲染 — 根据属性渲染为 <span>、<a> 或交互式 <span>+<button>',
- '不可见按钮模式用于 onClick,保留真实按钮语义,同时允许 focus-within 轮廓显示在整个标记上',
- '移除按钮通过 ::after 伪元素扩展了 14px 的点击目标区域',
- '十一种颜色变体,包括中性默认色',
- '前置图标和尾部 endContent 插槽',
- '标签可以视觉隐藏,同时保持对屏幕阅读器的可访问性',
- '禁用状态降低透明度并阻止指针事件',
+ 'Token is a compact chip component for displaying entities like tags, names, or status indicators inline within content. Use a Token to represent metadata, categorization, or removable selections. For static status indicators without interaction, use Badge instead.',
+ bestPractices: [
+ {guidance: true, description: 'Use color variants to distinguish different categories or entity types at a glance.'},
+ {guidance: true, description: 'Provide an onRemove callback when users need the ability to dismiss or deselect a token.'},
+ {guidance: false, description: 'Avoid using tokens for primary actions or navigation — use Button or Link instead.'},
+ {guidance: false, description: 'Avoid hiding the label unless an icon provides sufficient visual meaning on its own.'},
],
- accessibility: [
- '当 isLabelHidden 为 true 时,标签在视觉上被裁剪,但通过根元素上的 aria-label 暴露给屏幕阅读器,使其仍然可以播报。',
- 'description 属性映射到根元素上的 aria-description,用于提供补充上下文。',
- '当提供 onClick 时,可点击内容被包裹在真实的 <button> 中,使键盘用户可以通过 Enter 或 Space 激活。',
- '移除按钮自动具有 "Remove <label>" 的 aria-label,并通过 ::after 伪元素扩展触摸目标。',
- '当提供 href 时,如果 isDisabled 为 true,则在 <a> 元素上设置 aria-disabled。',
- 'Keyboard: Tab 聚焦标记(或使用 onClick 时聚焦其内部按钮)。Enter/Space 激活可点击标记或移除按钮。移除按钮作为单独的 Tab 停靠点可达。',
+ anatomy: [
+ {name: 'Color', required: false, description: 'Background color indicator.'},
+ {name: 'Label', required: true, description: 'Text label for the token.'},
+ {name: 'Icon', required: false, description: '16px icon displayed in the token.'},
+ {name: 'Remove button', required: false, description: 'Shown when onRemove is provided.'},
+ {name: 'Description', required: false, description: 'Additional descriptive text.'},
],
},
};
@@ -221,23 +206,23 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Chip/tag for displaying entities inline. Renders as <span> default, <a> w/ href, or <span> w/ invisible <button> when onClick provided.',
- features: [
- 'Polymorphic; renders as <span>, <a>, or interactive <span>+<button> based on props',
- 'Invisible button pattern for onClick preserves real button semantics w/ focus-within outline on full token',
- 'Remove button w/ expanded 14px hit-area tap target via ::after pseudo-element',
- 'Eleven color variants including neutral default',
- 'Leading icon+trailing endContent slots',
- 'Label can be visually hidden; remains accessible to screen readers',
- 'Disabled state reduces opacity, blocks pointer events',
- ],
- accessibility: [
- 'isLabelHidden clips label visually but exposes via aria-label so screen readers announce it.',
- 'description maps to aria-description for supplementary context.',
- 'onClick wraps content in real <button> so keyboard users activate w/ Enter/Space.',
- 'Remove button has auto aria-label "Remove <label>"+expanded touch target via ::after pseudo-element.',
- 'href w/ isDisabled sets aria-disabled on <a>.',
- ],
- keyboard: 'Tab focuses token (or inner button w/ onClick). Enter/Space activate clickable token or remove button. Remove button is separate Tab stop.',
+ usage: {
+ description:
+ 'Token is a compact chip component for displaying entities like tags, names, or status indicators inline within content. Use a Token to represent metadata, categorization, or removable selections. For static status indicators without interaction, use Badge instead.',
+ bestPractices: [
+ {guidance: true, description: 'Use color variants to distinguish different categories or entity types at a glance.'},
+ {guidance: true, description: 'Provide an onRemove callback when users need the ability to dismiss or deselect a token.'},
+ {guidance: false, description: 'Avoid using tokens for primary actions or navigation — use Button or Link instead.'},
+ {guidance: false, description: 'Avoid hiding the label unless an icon provides sufficient visual meaning on its own.'},
+ ],
+ anatomy: [
+ {name: 'Color', required: false, description: 'Background color indicator.'},
+ {name: 'Label', required: true, description: 'Text label for the token.'},
+ {name: 'Icon', required: false, description: '16px icon displayed in the token.'},
+ {name: 'Remove button', required: false, description: 'Shown when onRemove is provided.'},
+ {name: 'Description', required: false, description: 'Additional descriptive text.'},
+ ],
+ },
propDescriptions: {
label: 'Text label inside token.',
size: "Token size; 'sm' or 'md'.",
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index 6df33c9116..fd040489d2 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -169,23 +169,12 @@ export const docs = {
},
usage: {
description:
- 'Tokenizer is a multi-select typeahead that converts text into token chips for selected items, enabling users to filter content and make selections from a data source. It composes XDSBaseTypeahead for search and XDSToken for chips. Avoid applying colored backgrounds to tokens within a tokenizer.',
- features: [
- 'Token chips for each selected item with remove buttons',
- 'Filtered search that automatically excludes already-selected items',
- 'Max entries to limit number of selections — input hides when limit is reached',
- 'Clear all button for bulk removal of all tokens',
- 'Custom token and item rendering via renderToken and renderItem',
- 'Backspace on empty input removes the last token',
- "Change metadata: onChange receives a second argument with type ('add' | 'create' | 'remove' | 'reorder')",
- 'Free-text token creation via hasCreate prop — shows a "Create" option in the dropdown for new values',
- ],
- accessibility: [
- 'Wrapped in XDSField for label, description, and status message association.',
- 'Token container has role="group" with aria-label.',
- 'Clear all button has aria-label="Clear all".',
- 'Combobox pattern provided by XDSBaseTypeahead with aria-expanded and aria-autocomplete.',
- 'Keyboard: Backspace on empty input removes last token; Arrow keys navigate dropdown; Enter selects highlighted item; Escape closes dropdown.',
+ 'Tokenizer is a multi-select input that lets users search and select multiple items displayed as removable token chips. Use Tokenizer when users need to build a set of selections from a searchable data source, such as adding recipients or applying multiple filters.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a clear placeholder that communicates what users can search for.'},
+ {guidance: true, description: 'Set a maxEntries limit when the number of selections should be bounded.'},
+ {guidance: false, description: 'Avoid applying colored backgrounds to tokens within a Tokenizer — use the default color for consistency.'},
+ {guidance: false, description: 'Avoid using Tokenizer for single-item selection — use Typeahead instead.'},
],
},
};
@@ -352,23 +341,12 @@ export const docsZh = {
},
usage: {
description:
- '带有标记芯片的多选预输入组件,用于显示已选项目。组合使用 XDSBaseTypeahead 进行搜索和 XDSToken 显示芯片。',
- features: [
- '每个已选项目显示带移除按钮的标记芯片',
- '过滤搜索自动排除已选项目',
- '最大条目数限制选择数量 — 达到限制时输入框隐藏',
- '全部清除按钮用于批量移除所有标记',
- '通过 renderToken 和 renderItem 自定义标记和项目渲染',
- '在空输入框上按退格键移除最后一个标记',
- "变更元数据:onChange 接收第二个参数,包含类型('add' | 'create' | 'remove' | 'reorder')",
- '通过 hasCreate 属性支持自由文本令牌创建 — 在下拉列表中为新值显示 "Create" 选项',
- ],
- accessibility: [
- '包裹在 XDSField 中,用于标签、描述和状态消息的关联。',
- '标记容器具有 role="group" 和 aria-label。',
- '全部清除按钮具有 aria-label="Clear all"。',
- 'XDSBaseTypeahead 提供组合框模式,包含 aria-expanded 和 aria-autocomplete。',
- 'Keyboard: 在空输入框上按退格键移除最后一个标记;方向键导航下拉列表;Enter 选择高亮项目;Escape 关闭下拉列表',
+ 'Tokenizer is a multi-select input that lets users search and select multiple items displayed as removable token chips. Use Tokenizer when users need to build a set of selections from a searchable data source, such as adding recipients or applying multiple filters.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a clear placeholder that communicates what users can search for.'},
+ {guidance: true, description: 'Set a maxEntries limit when the number of selections should be bounded.'},
+ {guidance: false, description: 'Avoid applying colored backgrounds to tokens within a Tokenizer — use the default color for consistency.'},
+ {guidance: false, description: 'Avoid using Tokenizer for single-item selection — use Typeahead instead.'},
],
},
};
@@ -376,23 +354,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Multi-select typeahead w/ token chips for selected items. Composes XDSBaseTypeahead for search+XDSToken for chips.',
- features: [
- 'Token chips for each selected item w/ remove buttons',
- 'Filtered search auto-excludes already-selected items',
- 'Max entries limits selections; input hides at limit',
- 'Clear all button for bulk removal of all tokens',
- 'Custom token+item rendering via renderToken+renderItem',
- 'Backspace on empty input removes last token',
- "Change metadata: onChange receives second arg w/ type ('add'|'create'|'remove'|'reorder')",
- 'Free-text token creation via hasCreate — "Create" option in dropdown for new values',
- ],
- accessibility: [
- 'Wrapped in XDSField for label, description, status message association.',
- 'Token container has role="group" w/ aria-label.',
- 'Clear all button has aria-label="Clear all".',
- 'Combobox pattern via XDSBaseTypeahead w/ aria-expanded+aria-autocomplete.',
- ],
- keyboard: 'Backspace on empty input removes last token. Arrow keys navigate dropdown. Enter selects highlighted item. Escape closes dropdown.',
+ usage: {
+ description:
+ 'Tokenizer is a multi-select input that lets users search and select multiple items displayed as removable token chips. Use Tokenizer when users need to build a set of selections from a searchable data source, such as adding recipients or applying multiple filters.',
+ bestPractices: [
+ {guidance: true, description: 'Provide a clear placeholder that communicates what users can search for.'},
+ {guidance: true, description: 'Set a maxEntries limit when the number of selections should be bounded.'},
+ {guidance: false, description: 'Avoid applying colored backgrounds to tokens within a Tokenizer — use the default color for consistency.'},
+ {guidance: false, description: 'Avoid using Tokenizer for single-item selection — use Typeahead instead.'},
+ ],
+ },
propDescriptions: {
label: 'Accessible label for input.',
searchSource: 'Data source w/ search+bootstrap methods for populating dropdown.',
diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjs
index fcf21bed00..35e6c3d9e2 100644
--- a/packages/core/src/Toolbar/Toolbar.doc.mjs
+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -71,32 +71,11 @@ export const docs = {
],
usage: {
description:
- 'Toolbar is a general-purpose container with start, center, and end content slots for grouping related actions or controls in a horizontal bar. Built on XDSSection with roving tabindex keyboard navigation, it is ideal for providing contextual actions above content areas like tables or editors.',
- features: [
- 'Slot-based layout — startContent, centerContent, and endContent for flexible organization',
- 'Three-column centering — centerContent switches to CSS grid (1fr auto 1fr) for true centering',
- 'Roving tabindex — arrow key navigation via useListFocus with orientation support',
- 'Density variants — default (40px) and compact (32px) minimum heights',
- 'Configurable gap — spacing scale gap between items within each slot',
- 'Built on XDSSection — inherits variant, theming, and nesting behavior',
- 'Composable overflow — use XDSOverflowList within slots for responsive collapsing',
- ],
- accessibility: [
- 'Inner element renders role="toolbar" with aria-label from label prop.',
- 'aria-orientation reflects the orientation prop (horizontal or vertical).',
- 'Roving tabindex via useListFocus — arrow keys move focus between focusable items (buttons, inputs, [tabindex="0"]).',
- 'Home/End keys jump to first/last focusable item.',
- 'Keyboard: ArrowLeft/ArrowRight (horizontal) or ArrowUp/ArrowDown (vertical) to move between items; Home/End for first/last item.',
- ],
- notes: [
- 'Built on XDSSection — variant prop controls background (default: transparent)',
- 'Two-slot layout (no centerContent): flex row with space-between',
- 'Three-slot layout (with centerContent): CSS grid 1fr auto 1fr for true centering',
- 'startContent only: fills width; endContent only: aligns to end',
- 'centerContent has min-width:0 and overflow:hidden for graceful truncation',
- 'No built-in overflow — compose with XDSOverflowList for responsive collapsing',
- 'Density controls minimum height — compact: 32px, default: 40px',
- 'Gap prop controls spacing between items within slots (default: --spacing-2 / 8px)',
+ '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.',
+ 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.'},
],
},
};
@@ -122,33 +101,11 @@ export const docsZh = {
],
usage: {
description:
- '通用工具栏,提供起始、居中和结束内容插槽。基于 XDSSection 构建,支持循环 Tab 键盘导航。',
- features: [
- '插槽式布局 — startContent、centerContent 和 endContent 灵活组织',
- '三列居中 — centerContent 切换为 CSS grid(1fr auto 1fr)实现真正居中',
- '循环 Tab — 通过 useListFocus 实现方向键导航',
- '密度变体 — default(40px)和 compact(32px)最小高度',
- '可配置间距 — 使用间距尺度设置插槽内项目间距',
- '基于 XDSSection — 继承变体、主题化和嵌套行为',
- '可组合溢出 — 在插槽中使用 XDSOverflowList 实现响应式折叠',
- ],
- accessibility: [
- '内部元素渲染 role="toolbar",从 label 属性设置 aria-label',
- 'aria-orientation 反映 orientation 属性(horizontal 或 vertical)',
- '通过 useListFocus 实现循环 Tab — 方向键在可聚焦项之间移动焦点',
- 'Home/End 键跳转到第一个/最后一个可聚焦项',
- '水平方向:ArrowLeft/ArrowRight 导航;垂直方向:ArrowUp/ArrowDown 导航',
- 'Keyboard: ArrowLeft/ArrowRight(水平)或 ArrowUp/ArrowDown(垂直)移动项目;Home/End 跳转首/末项',
- ],
- notes: [
- '基于 XDSSection — variant 属性控制背景(默认:transparent)',
- '两插槽布局(无 centerContent):flex 行 + space-between',
- '三插槽布局(有 centerContent):CSS grid 1fr auto 1fr 实现真正居中',
- 'startContent 独占:填充宽度;endContent 独占:靠右对齐',
- 'centerContent 设置 min-width:0 和 overflow:hidden 以优雅截断',
- '无内置溢出 — 组合 XDSOverflowList 实现响应式折叠',
- '密度控制最小高度 — compact: 32px,default: 40px',
- 'gap 属性控制插槽内项目间距(默认:--spacing-2 / 8px)',
+ '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.',
+ 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.'},
],
},
};
@@ -156,33 +113,15 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'General-purpose toolbar w/ start/center/end slots. Built on XDSSection w/ roving tabindex.',
- features: [
- 'Slot-based layout; startContent, centerContent, endContent',
- 'Three-column centering; centerContent switches to CSS grid (1fr auto 1fr)',
- 'Roving tabindex; arrow key nav via useListFocus w/ orientation',
- 'Density variants; default (40px) + compact (32px) min-height',
- 'Configurable gap; spacing scale gap between slot items',
- 'Built on XDSSection; inherits variant, theming, nesting',
- 'Composable overflow; use XDSOverflowList for responsive collapsing',
- ],
- accessibility: [
- 'role="toolbar" w/ aria-label from label prop.',
- 'aria-orientation reflects orientation prop.',
- 'Roving tabindex via useListFocus; arrows move focus between items.',
- 'Home/End jump to first/last item.',
- 'Horizontal: Left/Right; Vertical: Up/Down.',
- ],
- keyboard: 'Left/Right (horiz) or Up/Down (vert) between items; Home/End for first/last.',
- notes: [
- 'Built on XDSSection; variant controls bg (default: transparent).',
- 'Two-slot (no center): flex row w/ space-between.',
- 'Three-slot (w/ center): CSS grid 1fr auto 1fr.',
- 'startOnly fills width; endOnly aligns right.',
- 'centerContent: min-width:0 + overflow:hidden for truncation.',
- 'No built-in overflow; compose w/ XDSOverflowList.',
- 'Density: compact=32px, default=40px min-height.',
- 'Gap: spacing between slot items (default: --spacing-2/8px).',
- ],
+ 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.',
+ 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.'},
+ ],
+ },
components: [
{
name: 'XDSToolbar',
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index 43b16e8d38..b6ec41480a 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -134,28 +134,12 @@ export const docs = {
},
usage: {
description:
- 'Tooltip provides non-interactive hints that display additional information in the context of a specific UI element, triggered by hover or focus. It is ideal for progressive disclosure, non-interruptive education, or showing full text for truncated labels. For interactive content, use HoverCard instead; limit tooltip content to approximately 140 characters.',
- features: [
- 'CSS Anchor Positioning for automatic placement relative to trigger elements',
- 'Popover API for top-layer rendering — no React portals needed',
- 'Hover triggers with configurable show and hide delays',
- 'Focus triggers with auto-detection for focusable elements',
- 'Inverted color palette (dark background, light text) for high contrast',
- 'display:contents wrapper preserves children refs',
- 'Hover indication (dashed underline) for text-only triggers',
- 'Sibling mode via anchorRef for external trigger elements',
- ],
- accessibility: [
- 'Links the tooltip content to the trigger via aria-describedby.',
- 'When composing multiple aria-describedby sources, merge them with a utility.',
- 'Keyboard: Focus on the trigger shows the tooltip; blur hides it.',
- ],
- notes: [
- 'Unlike HoverCard, tooltips don\'t stay open when hovering the tooltip content.',
- 'Tooltips have shorter delays and use inverted colors for high contrast.',
- 'Tooltips are for short, non-interactive text. For interactive content, use XDSHoverCard or XDSPopover.',
- 'In sibling mode (anchorRef prop), XDSTooltip attaches to an external ref rather than wrapping children.',
- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',
+ 'Tooltip displays a short, non-interactive text hint anchored to a trigger element on hover or focus. Use Tooltip for progressive disclosure of supplementary information, such as describing an icon-only button or showing the full text of a truncated label.',
+ bestPractices: [
+ {guidance: true, description: 'Keep tooltip content concise — aim for under 140 characters of plain text.'},
+ {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
+ {guidance: false, description: 'Avoid placing interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.'},
+ {guidance: false, description: 'Avoid using tooltips for essential information that users must see to complete a task.'},
],
},
};
@@ -295,28 +279,12 @@ export const docsZh = {
},
usage: {
description:
- '悬停/聚焦触发的工具提示,用于显示锚定在触发元素上的简短、非交互式文本。',
- features: [
- 'CSS 锚点定位,自动相对于触发元素放置',
- 'Popover API 实现顶层渲染 — 无需 React 传送门',
- '悬停触发,支持可配置的显示和隐藏延迟',
- '聚焦触发,自动检测可聚焦元素',
- '反转色调(深色背景、浅色文字)以实现高对比度',
- 'display:contents 包装器保留子元素引用',
- '悬停指示(虚线下划线)用于纯文本触发器',
- '通过 anchorRef 的兄弟模式用于外部触发元素',
- ],
- accessibility: [
- '通过 aria-describedby 将工具提示内容链接到触发器。',
- '当组合多个 aria-describedby 来源时,使用工具函数合并它们。',
- 'Keyboard: 聚焦触发器显示工具提示。失焦隐藏工具提示。',
- ],
- notes: [
- '与 HoverCard 不同,悬停工具提示内容时工具提示不会保持打开状态。',
- '工具提示具有更短的延迟,并使用反转颜色以实现高对比度。',
- '工具提示用于简短的非交互式文本。对于交互式内容,请使用 XDSHoverCard 或 XDSPopover。',
- '在兄弟模式下(anchorRef 属性),XDSTooltip 附加到外部引用而不是包裹子元素。',
- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',
+ 'Tooltip displays a short, non-interactive text hint anchored to a trigger element on hover or focus. Use Tooltip for progressive disclosure of supplementary information, such as describing an icon-only button or showing the full text of a truncated label.',
+ bestPractices: [
+ {guidance: true, description: 'Keep tooltip content concise — aim for under 140 characters of plain text.'},
+ {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
+ {guidance: false, description: 'Avoid placing interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.'},
+ {guidance: false, description: 'Avoid using tooltips for essential information that users must see to complete a task.'},
],
},
};
@@ -324,28 +292,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
- features: [
- 'CSS Anchor Positioning for automatic placement relative to trigger',
- 'Popover API for top-layer rendering; no React portals needed',
- 'Hover triggers w/ configurable show+hide delays',
- 'Focus triggers w/ auto-detection for focusable elements',
- 'Inverted color palette (dark bg, light text) for high contrast',
- 'display:contents wrapper preserves children refs',
- 'Hover indication (dashed underline) for text-only triggers',
- 'Sibling mode via anchorRef for external trigger elements',
- ],
- notes: [
- "Unlike HoverCard, tooltips don't stay open when hovering tooltip content.",
- 'Shorter delays+inverted colors for high contrast.',
- 'For interactive content use XDSHoverCard or XDSPopover.',
- 'Sibling mode (anchorRef) attaches to external ref instead of wrapping children.',
- 'LayerPlacement: above|below|start|end. LayerAlignment: start|center|end.',
- ],
- accessibility: [
- 'Links tooltip content to trigger via aria-describedby.',
- 'When composing multiple aria-describedby sources, merge w/ utility.',
- ],
- keyboard: 'Focus on trigger shows tooltip. Blur hides it.',
+ usage: {
+ description:
+ 'Tooltip displays a short, non-interactive text hint anchored to a trigger element on hover or focus. Use Tooltip for progressive disclosure of supplementary information, such as describing an icon-only button or showing the full text of a truncated label.',
+ bestPractices: [
+ {guidance: true, description: 'Keep tooltip content concise — aim for under 140 characters of plain text.'},
+ {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
+ {guidance: false, description: 'Avoid placing interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.'},
+ {guidance: false, description: 'Avoid using tooltips for essential information that users must see to complete a task.'},
+ ],
+ },
components: [
{
name: 'XDSTooltip',
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index aadacecdba..4b96969d96 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -299,32 +299,12 @@ export const docs = {
],
usage: {
description:
- 'TopNav is a horizontal navigation bar for product-level navigation in application headers, featuring a slot-based layout with heading, startContent, centerContent, and endContent slots, plus companion nav item and menu components. Use for 5 or fewer always-visible nav items or minimal navigation paired with controls. Do not use for complex navigation hierarchies or to filter content—use tabs or filter buttons instead.',
- features: [
- 'Slot-based layout — heading, startContent, centerContent, and endContent slots for flexible organization',
- 'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering',
- 'Companion components — XDSTopNavHeading, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu',
- 'Themeable via className — target .xds-top-nav and sub-component classes',
- 'Link customization — XDSTopNavItem accepts an as prop to swap the anchor element (e.g. for React Router)',
- ],
- accessibility: [
- 'XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop.',
- 'XDSTopNavItem sets aria-current="page" when isSelected is true.',
- 'XDSTopNavItem sets aria-label when isIconOnly is true, keeping the item accessible.',
- 'XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true.',
- 'XDSTopNavMenu sets aria-haspopup="true" on the trigger button.',
- 'XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button.',
- 'XDSTopNavMegaMenu menu items are unreachable by keyboard (tabIndex=-1) when the panel is closed.',
- 'Escape key closes the XDSTopNavMegaMenu panel.',
- 'Keyboard: Tab to navigate between items; Escape closes XDSTopNavMegaMenu panels.',
- ],
- notes: [
- 'Default height is 48px (--spacing-12) with 16px horizontal padding',
- 'Without centerContent: heading and startContent grow to push endContent right (flex layout)',
- 'With centerContent: switches to CSS grid (gridTemplateColumns: 1fr auto 1fr) — the right column is always rendered even when endContent is absent to maintain the three-column structure',
- 'Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself',
- 'Dividers are controlled by the layout system (e.g. XDSLayoutHeader hasDivider), not TopNav',
- 'XDSTopNavMegaMenu panels position relative to the nearest positioned ancestor — wrap XDSTopNav in a container with position: relative for correct full-width behavior',
+ 'TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.',
+ bestPractices: [
+ {guidance: true, description: 'Include a product logo and name in the heading slot to clearly identify the application.'},
+ {guidance: true, description: 'Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load.'},
+ {guidance: false, description: 'Avoid using TopNav to filter page content — use Tabs or filter controls instead.'},
+ {guidance: false, description: 'Avoid deeply nested navigation hierarchies — keep menus to one level of depth.'},
],
anatomy: [
{name: 'Product icon and name', required: true, description: 'Identifies the product in the navigation bar.'},
@@ -628,33 +608,18 @@ export const docsZh = {
],
usage: {
description:
- '应用程序头部的顶部导航栏组件,采用插槽式布局和配套的导航项组件。',
- features: [
- '插槽式布局 — heading、startContent、centerContent 和 endContent 插槽实现灵活组织',
- '三列居中 — 提供 centerContent 时,切换为 CSS grid(1fr auto 1fr)实现真正的水平居中',
- '配套组件 — XDSTopNavHeading、XDSTopNavItem、XDSTopNavMenu、XDSTopNavMegaMenu',
- '无障碍 — 使用 role="navigation" 和 aria-label,选中项设置 aria-current="page"',
- '通过 className 支持主题化 — 可定位 .xds-top-nav 和子组件类',
- '链接自定义 — XDSTopNavItem 接受 as 属性来替换锚点元素(例如用于 React Router)',
- ],
- accessibility: [
- 'XDSTopNav 渲染一个 <nav> 元素,包含 role="navigation" 和从 label 属性设置的 aria-label',
- '当 isSelected 为 true 时,XDSTopNavItem 设置 aria-current="page"',
- 'XDSTopNavItem 为仅图标项设置 aria-label(当提供图标且没有子元素或可见标签文本时)',
- '当 isDisabled 为 true 时,XDSTopNavItem 设置 aria-disabled 和 tabIndex=-1',
- 'XDSTopNavMenu 在触发按钮上设置 aria-haspopup="true"',
- 'XDSTopNavMegaMenu 在触发按钮上设置 aria-haspopup="true" 和 aria-expanded',
- '当面板关闭时,XDSTopNavMegaMenu 菜单项对键盘不可达(tabIndex=-1)',
- 'Escape 键关闭 XDSTopNavMegaMenu 面板',
- 'Keyboard: Tab 在项目之间导航;Escape 关闭 XDSTopNavMegaMenu 面板',
+ 'TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.',
+ bestPractices: [
+ {guidance: true, description: 'Include a product logo and name in the heading slot to clearly identify the application.'},
+ {guidance: true, description: 'Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load.'},
+ {guidance: false, description: 'Avoid using TopNav to filter page content — use Tabs or filter controls instead.'},
+ {guidance: false, description: 'Avoid deeply nested navigation hierarchies — keep menus to one level of depth.'},
],
- notes: [
- '默认高度为 48px(--spacing-12),水平内边距 16px',
- '无 centerContent 时:heading 和 startContent 增长以将 endContent 推向右侧(flex 布局)',
- '有 centerContent 时:切换为 CSS grid(gridTemplateColumns: 1fr auto 1fr)— 即使 endContent 不存在,右列也始终渲染以维持三列结构',
- '定位(sticky/fixed)由布局系统处理(例如 XDSAppShell),而非 TopNav 本身',
- '分隔线由布局系统控制(例如 XDSLayoutHeader hasDivider),而非 TopNav',
- 'XDSTopNavMegaMenu 面板相对于最近的定位祖先定位 — 将 XDSTopNav 包裹在具有 position: relative 的容器中以获得正确的全宽行为',
+ anatomy: [
+ {name: 'Product icon and name', required: true, description: 'Identifies the product in the navigation bar.'},
+ {name: 'Navigation items', required: true, description: 'Primary links for product-level destinations.'},
+ {name: 'More menu', required: false, description: 'Overflow menu for additional navigation items.'},
+ {name: 'Flex area', required: false, description: 'Flexible region for search, primary action buttons, or other controls.'},
],
},
};
@@ -662,33 +627,22 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Top navigation bar for app headers w/ slot-based layout+companion nav item components.',
- features: [
- 'Slot-based layout; heading, startContent, centerContent, endContent slots',
- 'Three-column centering; centerContent switches to CSS grid (1fr auto 1fr) for true horizontal centering',
- 'Companion components; XDSTopNavHeading, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu',
- 'Accessible; role="navigation" w/ aria-label, aria-current="page" on selected items',
- 'Themeable via className; target .xds-top-nav+sub-component classes',
- 'Link customization; XDSTopNavItem accepts as prop to swap anchor element (e.g. React Router)',
- ],
- notes: [
- 'Default height 48px (--spacing-12) w/ 16px horizontal padding.',
- 'W/o centerContent: heading+startContent grow to push endContent right (flex layout).',
- 'W/ centerContent: CSS grid (1fr auto 1fr); right column always rendered for 3-col structure.',
- 'Positioning (sticky/fixed) handled by layout system (e.g. XDSAppShell), not TopNav.',
- 'Dividers controlled by layout system (e.g. XDSLayoutHeader hasDivider), not TopNav.',
- 'XDSTopNavMegaMenu panels position relative to nearest positioned ancestor; wrap in position:relative container for full-width.',
- ],
- accessibility: [
- 'XDSTopNav renders <nav> w/ role="navigation"+aria-label from label prop.',
- 'XDSTopNavItem sets aria-current="page" when isSelected.',
- 'XDSTopNavItem sets aria-label when isIconOnly is true.',
- 'XDSTopNavItem sets aria-disabled+tabIndex=-1 when isDisabled.',
- 'XDSTopNavMenu sets aria-haspopup="true" on trigger button.',
- 'XDSTopNavMegaMenu sets aria-haspopup="true"+aria-expanded on trigger button.',
- 'XDSTopNavMegaMenu items unreachable by keyboard (tabIndex=-1) when panel closed.',
- 'Escape closes XDSTopNavMegaMenu panel.',
- ],
- keyboard: 'Tab navigates between items. Escape closes XDSTopNavMegaMenu panels.',
+ usage: {
+ description:
+ 'TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.',
+ bestPractices: [
+ {guidance: true, description: 'Include a product logo and name in the heading slot to clearly identify the application.'},
+ {guidance: true, description: 'Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load.'},
+ {guidance: false, description: 'Avoid using TopNav to filter page content — use Tabs or filter controls instead.'},
+ {guidance: false, description: 'Avoid deeply nested navigation hierarchies — keep menus to one level of depth.'},
+ ],
+ anatomy: [
+ {name: 'Product icon and name', required: true, description: 'Identifies the product in the navigation bar.'},
+ {name: 'Navigation items', required: true, description: 'Primary links for product-level destinations.'},
+ {name: 'More menu', required: false, description: 'Overflow menu for additional navigation items.'},
+ {name: 'Flex area', required: false, description: 'Flexible region for search, primary action buttons, or other controls.'},
+ ],
+ },
components: [
{
name: 'XDSTopNav',
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 0e63aa11c3..c7027eca6f 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -44,31 +44,11 @@ export const docs = {
],
usage: {
description:
- 'TreeList is a data-driven component for displaying hierarchical information with expandable and collapsible nodes. It uses a flat items array with recursive children for rendering hierarchical data with branch lines and interactive items—no composition, no cloneElement. Use for file system navigators or visualizing hierarchical data.',
- features: [
- 'Data-driven API — items array with recursive children',
- 'Internal expansion state — seed via isExpanded on each item',
- 'Branch connector lines with center/top alignment',
- 'Density variants: compact, balanced, spacious',
- 'Interactive items via invisible button or anchor pattern',
- 'Start and end content slots (icon, avatar, badge)',
- 'Optional header associated via aria-labelledby',
- 'No context for positional data — computed at render time',
- ],
- accessibility: [
- 'Semantic <ul role="tree"> with <li role="treeitem"> elements',
- '<ul role="group"> for nested children',
- 'aria-expanded on items with children',
- 'aria-labelledby links the header element to the tree',
- 'aria-selected on selected items',
- 'aria-disabled on disabled items',
- 'Chevron toggle button with aria-label="Toggle children"',
- 'Interactive items are keyboard-focusable via Tab',
- ],
- notes: [
- 'Data-driven pattern: Unlike XDSList which uses children composition, XDSTreeList accepts an items array. This avoids cloneElement and enables the component to compute positional data (nestedLevel, isLast, ancestorsIsLast) at render time.',
- 'Expansion control: Expansion state is managed internally. Seed initial state by setting isExpanded: true on individual items in the data.',
- 'Performance: React reconciliation via key={id} means expanding a node only causes DOM updates in that subtree. Siblings with stable keys and same props are skipped by React.',
+ 'TreeList displays hierarchical data as an expandable and collapsible tree structure with branch connector lines. Use TreeList for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
+ bestPractices: [
+ {guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
+ {guidance: true, description: 'Pre-expand important branches using isExpanded so users see key content immediately.'},
+ {guidance: false, description: 'Avoid deeply nesting more than 4-5 levels — flatten the structure or use a different pattern for very deep hierarchies.'},
],
},
};
@@ -124,31 +104,11 @@ export const docsZh = {
],
usage: {
description:
- '数据驱动的树列表组件,用于渲染层级数据,支持展开/折叠、分支线条和交互式项目。使用扁平 items 数组配合递归 children,无需组合模式,无需 cloneElement。',
- features: [
- '数据驱动 API — items 数组配合递归 children',
- '内部展开状态 — 通过每项的 isExpanded 设置初始值',
- '分支连接线,支持居中/顶部对齐',
- '密度变体:compact、balanced、spacious',
- '交互式项目,通过不可见按钮或锚点模式',
- '起始和结束内容插槽(图标、头像、徽章)',
- '可选标题,通过 aria-labelledby 关联',
- '无需位置数据上下文 — 渲染时计算',
- ],
- accessibility: [
- '语义化 <ul role="tree"> 配合 <li role="treeitem"> 元素',
- '嵌套子项使用 <ul role="group">',
- '有子项的元素设置 aria-expanded',
- 'aria-labelledby 将标题元素与树关联',
- '选中项设置 aria-selected',
- '禁用项设置 aria-disabled',
- '折叠切换按钮带有 aria-label="Toggle children"',
- '交互式项目可通过 Tab 键获得焦点',
- ],
- notes: [
- '数据驱动模式:与使用 children 组合的 XDSList 不同,XDSTreeList 接受 items 数组。这避免了 cloneElement,使组件能在渲染时计算位置数据(nestedLevel、isLast、ancestorsIsLast)。',
- '展开控制:展开状态在内部管理。通过在数据中设置 isExpanded: true 来设定初始状态。',
- '性能:通过 key={id} 进行 React 协调意味着展开节点只会导致该子树的 DOM 更新。具有稳定 key 和相同 props 的兄弟节点会被 React 跳过。',
+ 'TreeList displays hierarchical data as an expandable and collapsible tree structure with branch connector lines. Use TreeList for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
+ bestPractices: [
+ {guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
+ {guidance: true, description: 'Pre-expand important branches using isExpanded so users see key content immediately.'},
+ {guidance: false, description: 'Avoid deeply nesting more than 4-5 levels — flatten the structure or use a different pattern for very deep hierarchies.'},
],
},
};
@@ -157,31 +117,15 @@ export const docsZh = {
export const docsDense = {
description:
'Data-driven tree list for hierarchical data w/ expand/collapse, branch lines, interactive items. Flat items array w/ recursive children, no composition, no cloneElement.',
- features: [
- 'Data-driven API; items array w/ recursive children',
- 'Internal expansion state; seed via isExpanded per item',
- 'Branch connector lines w/ center/top alignment',
- 'Density variants: compact, balanced, spacious',
- 'Interactive items via invisible button or anchor pattern',
- 'Start + end content slots (icon, avatar, badge)',
- 'Optional header via aria-labelledby',
- 'No context for positional data; computed at render time',
- ],
- accessibility: [
- 'Semantic <ul role="tree"> w/ <li role="treeitem">',
- '<ul role="group"> for nested children',
- 'aria-expanded on items w/ children',
- 'aria-labelledby links header to tree',
- 'aria-selected on selected items',
- 'aria-disabled on disabled items',
- 'Chevron toggle btn w/ aria-label="Toggle children"',
- 'Interactive items keyboard-focusable via Tab',
- ],
- notes: [
- 'Data-driven: accepts items array (not children composition), avoids cloneElement, computes positional data at render time.',
- 'Expansion managed internally. Seed initial state via isExpanded: true on items.',
- 'Perf: key={id} reconciliation means expanding node only updates that subtree.',
- ],
+ usage: {
+ description:
+ 'TreeList displays hierarchical data as an expandable and collapsible tree structure with branch connector lines. Use TreeList for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
+ bestPractices: [
+ {guidance: true, description: 'Provide meaningful labels and icons for each node to make the hierarchy easy to scan.'},
+ {guidance: true, description: 'Pre-expand important branches using isExpanded so users see key content immediately.'},
+ {guidance: false, description: 'Avoid deeply nesting more than 4-5 levels — flatten the structure or use a different pattern for very deep hierarchies.'},
+ ],
+ },
propDescriptions: {
items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
density: 'Spacing density for items.',
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 65fe3bf24f..eca206a87b 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -300,29 +300,12 @@ export const docs = {
},
usage: {
description:
- 'Typeahead is a searchable dropdown for single-item selection with keyboard navigation and async/sync data support via a searchSource interface. Use when selecting from a large or dynamic dataset where search-as-you-type helps users find options. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
- features: [
- 'Async and sync search via a searchSource interface with search() and bootstrap() methods',
- 'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',
- 'Edit mode: clicking selected token enters edit mode with text pre-populated and selected',
- 'Combobox ARIA pattern for full accessibility',
- 'Debounced search with configurable delay (default 150ms, set to 0 for synchronous sources)',
- 'Two-layer architecture: XDSBaseTypeahead provides the engine, XDSTypeahead adds field chrome',
- ],
- accessibility: [
- 'Uses combobox ARIA pattern with role="combobox", aria-expanded, aria-autocomplete="list".',
- 'Dropdown uses role="listbox" with role="option" on each item.',
- 'aria-activedescendant tracks the highlighted option.',
- 'Selected item has aria-selected="true".',
- 'Loading state has role="status" with aria-label="Loading".',
- 'XDSTypeahead wraps in XDSField for label and description association.',
- 'Keyboard: Arrow keys navigate dropdown items; Enter selects highlighted item; Escape closes dropdown or restores previous value in edit mode; Home/End jump to first/last item.',
- ],
- notes: [
- 'XDSSearchSource requires items to implement XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).',
- 'Edit mode in XDSTypeahead: clicking the selected token removes it visually, populates the input with the label text, and selects all. Blurring without selecting restores the original token.',
- 'XDSBaseTypeahead renders only the <input> and dropdown popover — consumers provide their own wrapper.',
- 'If item has an element property, XDSTypeaheadItem renders it directly instead of the standard layout.',
+ 'Typeahead is a searchable dropdown for selecting a single item from a large or dynamic dataset. Use Typeahead when users benefit from search-as-you-type to quickly find and select an option. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
+ bestPractices: [
+ {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
+ {guidance: true, description: 'Enable hasEntriesOnFocus when users benefit from seeing popular or recent options before typing.'},
+ {guidance: false, description: 'Avoid using Typeahead for short, static option lists — use Selector for better discoverability.'},
+ {guidance: false, description: 'Avoid placing multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
};
@@ -628,29 +611,12 @@ export const docsZh = {
},
usage: {
description:
- '可搜索的下拉组件,用于单项选择并支持键盘导航。通过 searchSource 接口支持异步和同步搜索。',
- features: [
- '通过 searchSource 接口支持异步和同步搜索,包含 search() 和 bootstrap() 方法',
- '聚焦时在输入前显示引导结果(通过 hasEntriesOnFocus)',
- '编辑模式:点击已选标记进入编辑模式,文本已预填并选中',
- '组合框 ARIA 模式,实现完整的无障碍支持',
- '防抖搜索,延迟可配置(默认 150ms,同步数据源设置为 0)',
- '双层架构:XDSBaseTypeahead 提供引擎,XDSTypeahead 添加字段外观',
- ],
- accessibility: [
- '使用组合框 ARIA 模式,包含 role="combobox"、aria-expanded、aria-autocomplete="list"。',
- '下拉列表使用 role="listbox",每个项使用 role="option"。',
- 'aria-activedescendant 追踪高亮选项。',
- '选中项具有 aria-selected="true"。',
- '加载状态具有 role="status" 和 aria-label="Loading"。',
- 'XDSTypeahead 包裹在 XDSField 中,用于标签和描述的关联。',
- 'Keyboard: 方向键导航下拉列表项目;Enter 选择高亮项目;Escape 关闭下拉列表或在编辑模式中恢复之前的值;Home/End 跳转到第一个/最后一个项目',
- ],
- notes: [
- 'XDSSearchSource 要求项目实现 XDSSearchableItem({ id: string; label: string; [key: string]: unknown })。',
- 'XDSTypeahead 中的编辑模式:点击已选标记会视觉移除它,将标签文本填入输入框并全选。在未选择的情况下失焦会恢复原始标记。',
- 'XDSBaseTypeahead 仅渲染 <input> 和下拉弹出框 — 使用者需提供自己的包装器。',
- '如果项目具有 element 属性,XDSTypeaheadItem 会直接渲染它而不是标准布局。',
+ 'Typeahead is a searchable dropdown for selecting a single item from a large or dynamic dataset. Use Typeahead when users benefit from search-as-you-type to quickly find and select an option. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
+ bestPractices: [
+ {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
+ {guidance: true, description: 'Enable hasEntriesOnFocus when users benefit from seeing popular or recent options before typing.'},
+ {guidance: false, description: 'Avoid using Typeahead for short, static option lists — use Selector for better discoverability.'},
+ {guidance: false, description: 'Avoid placing multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
};
@@ -658,29 +624,16 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',
- features: [
- 'Async+sync search via searchSource w/ search()+bootstrap() methods',
- 'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',
- 'Edit mode: clicking selected token enters edit w/ text pre-populated+selected',
- 'Combobox ARIA pattern for full a11y',
- 'Debounced search w/ configurable delay (default 150ms, 0 for sync)',
- 'Two-layer architecture: XDSBaseTypeahead provides engine, XDSTypeahead adds field chrome',
- ],
- notes: [
- 'XDSSearchSource requires items implementing XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).',
- 'Edit mode: clicking selected token removes it visually, populates input w/ label text, selects all. Blur w/o selecting restores original.',
- 'XDSBaseTypeahead renders only <input>+dropdown popover; consumers provide wrapper.',
- 'If item has element property, XDSTypeaheadItem renders it directly instead of standard layout.',
- ],
- accessibility: [
- 'Combobox ARIA: role="combobox", aria-expanded, aria-autocomplete="list".',
- 'Dropdown role="listbox" w/ role="option" on each item.',
- 'aria-activedescendant tracks highlighted option.',
- 'Selected item has aria-selected="true".',
- 'Loading state has role="status" w/ aria-label="Loading".',
- 'XDSTypeahead wraps in XDSField for label+description association.',
- ],
- keyboard: 'Arrow keys navigate dropdown items. Enter selects highlighted item. Escape closes dropdown or restores previous value in edit mode. Home/End jump to first/last item.',
+ usage: {
+ description:
+ 'Typeahead is a searchable dropdown for selecting a single item from a large or dynamic dataset. Use Typeahead when users benefit from search-as-you-type to quickly find and select an option. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
+ bestPractices: [
+ {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
+ {guidance: true, description: 'Enable hasEntriesOnFocus when users benefit from seeing popular or recent options before typing.'},
+ {guidance: false, description: 'Avoid using Typeahead for short, static option lists — use Selector for better discoverability.'},
+ {guidance: false, description: 'Avoid placing multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+ ],
+ },
components: [
{
name: 'XDSTypeahead',
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index 49cbebc317..24e2fe53b9 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -160,32 +160,63 @@ export interface AnatomyElement {
}
/**
- * Unified documentation for a component — what it is, what it can do,
- * accessibility, implementation notes, and visual anatomy.
+ * A single do/don't best practice for a component.
+ * Rendered as a table row with a colored "Do" or "Don't" badge
+ * in the Guidance column and the description in the Practices column.
*
- * All prose about a component lives here. The only fields that stay on
- * BaseDoc are `name`, `keywords`, and `theming` (identity/discovery/styling).
+ * @example
+ * ```
+ * {guidance: true, description: 'Convey clear action hierarchy. Each surface should only have 1 primary button.'}
+ * {guidance: false, description: 'Overuse primary or special buttons. Overusing colored buttons creates visual confusion.'}
+ * ```
+ */
+export interface BestPractice {
+ /** `true` renders a green "Do" badge; `false` renders a red "Don't" badge. */
+ guidance: boolean;
+ /** 1-2 short sentences of design guidance. Focus on how a designer
+ * would USE the component, not how it's built.
+ *
+ * NEVER start with "Do" or "Don't" — the badge handles that.
+ *
+ * Good: `"Convey clear action hierarchy. Each surface should only have 1 primary button."`
+ * Bad: `"Do use clear action hierarchy."` */
+ description: string;
+}
+
+/**
+ * Component usage documentation — a concise summary, design guidance
+ * best practices, and optional visual anatomy.
+ *
+ * ## description
+ * Exactly 2-3 short sentences:
+ * - Sentence 1: What the component is and does.
+ * - Sentence 2-3: When to use it, or what context it belongs in.
+ *
+ * Reference tone: "Buttons provide visual cues for actions and events.
+ * These fundamental components allow users to commit actions and navigate
+ * a page flow. Use a Button when a user needs to submit a form, start a
+ * new task or action, or trigger a new UI element to appear on the page."
+ *
+ * ## bestPractices
+ * Array of 3-4 items. Usually 2 Do items, then 1-2 Don't items.
+ * Each item is design guidance — not implementation details.
+ * Never start the description with "Do" or "Don't".
*/
export interface UsageDoc {
- /** What the component is and when to use it. 1-3 sentences combining
- * the developer summary with design guidance.
- * e.g. `"Buttons provide visual cues for actions and events. XDSButton
- * supports primary, secondary, ghost, and destructive variants with
- * built-in loading states. Use secondary for most actions, reserve
- * primary for a single emphasized action per layout."` */
+ /** What the component is and when to use it. 2-3 short sentences.
+ *
+ * Sentence 1: What the component is and does.
+ * Sentence 2-3: When to use it, or what context it belongs in.
+ *
+ * e.g. `"Buttons provide visual cues for actions and events. These
+ * fundamental components allow users to commit actions and navigate
+ * a page flow. Use a Button when a user needs to submit a form,
+ * start a new task or action, or trigger a new UI element to appear
+ * on the page."` */
description: string;
- /** Key capabilities as short bullet points. Each string is one feature.
- * Focus on what the component CAN DO, not how it's implemented.
- * e.g. `"Variants: 'primary', 'secondary', 'ghost', 'destructive'"` */
- features?: string[];
- /** Accessibility notes including keyboard interaction. Each string is
- * one self-contained note. Keyboard bindings use the format
- * `"Keyboard: Enter/Space activates; Tab/Shift+Tab moves focus"`.
- * e.g. `"Uses native <dialog> with showModal() for correct ARIA modal semantics."` */
- accessibility?: string[];
- /** Technical implementation notes — architecture decisions, performance
- * considerations, caveats. Only internal details, not usage guidance. */
- notes?: string[];
+ /** 3-4 do/don't design guidance items. Usually 2 Do's then 1-2 Don'ts.
+ * Focus on how a designer would USE the component, not how it's built. */
+ bestPractices?: BestPractice[];
/** Structural/visual anatomy of the component. Each entry describes one
* element that makes up the component (icon slot, label, container, etc.).
* Order entries in the visual reading order (leading → trailing, top → bottom). */
@@ -226,8 +257,8 @@ interface BaseDoc {
* internal variables must not be listed here. */
cssProperties?: CSSPropertyDoc[];
};
- /** All component documentation — description, features, accessibility,
- * implementation notes, and visual anatomy. */
+ /** Component usage documentation — concise summary, best practices,
+ * and optional visual anatomy. */
usage: UsageDoc;
}
@@ -276,39 +307,17 @@ export type ComponentDoc = SingleComponentDoc | MultiComponentDoc;
* types, defaults, and code all come from `docs`.
*
* Used by both `docsZh` (Chinese translation) and `docsDense` (compressed format).
- *
- * @example
- * ```
- * export const docsDense = {
- * description: 'multi-variant btn w/ loading',
- * features: ['4 variants: primary secondary ghost destructive'],
- * propDescriptions: { label: 'a11y label; aria-label for icon-only' },
- * notes: ['prefer over div onClick for a11y'],
- * };
- * ```
*/
export interface TranslationDoc {
- /** Compressed/translated component description.
- * Can also be provided via usage.description. */
+ /** Compressed/translated component description. */
description?: string;
- /** Compressed/translated feature strings. Must match docs.features length and order. */
- features?: string[];
- /** Compressed/translated note strings. Must match docs.notes length and order. */
- notes?: string[];
- /** Compressed/translated accessibility strings. Must match docs.accessibility length and order. */
- accessibility?: string[];
- /** Compressed/translated keyboard string. */
- keyboard?: string;
/** Prop descriptions keyed by prop name. Only include props that have descriptions. */
propDescriptions?: Record<string, string>;
/** Translated/compressed usage overlay. Mirrors UsageDoc fields. */
usage?: {
description?: string;
- features?: string[];
- accessibility?: string[];
- notes?: string[];
- summary?: string;
- content?: string;
+ bestPractices?: BestPractice[];
+ anatomy?: AnatomyElement[];
};
/** Sub-component translations. Must match docs.components length and order (if present). */
components?: Array<{