Skip to content

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

TypeScript

docs(dense): restore dropped Icon and Carousel dense/zh best-practice bullets (#4676)

Joeya52220664649
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 29eb79a63e..600738ec8d 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -66,8 +66,10 @@ export const docsZh = {
'Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表,或任何希望无需占据整页即可浏览的项目集合。',
bestPractices: [
{guidance: true, description: '当每个项目应精确对齐到起始边缘时启用滚动吸附,例如画廊或产品列表。'},
+ {guidance: true, description: '在小型可循环的集合(如照片画廊)上使用 hasLoop,此时从最后一项绕回第一项的滚动更自然。'},
{guidance: true, description: '始终提供描述轮播内容的 aria-label,例如"精选产品"或"团队成员"。'},
{guidance: true, description: '使用一致的间距和项目宽度,让轮播看起来是有意为之,而不是内容意外溢出。'},
+ {guidance: true, description: '信任内置导航:触控板用户可水平滑动,鼠标用户可按住 Shift 滚动滚轮来浏览项目。'},
{guidance: false, description: '将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动,关键内容应放在首屏。'},
{guidance: false, description: '自动轮播项目。让用户按自己的节奏滚动。'},
{guidance: false, description: '嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。'},
@@ -94,6 +96,7 @@ export const docsDense = {
'Carousel scrolls items horizontally when they overflow. Use for card grids, galleries, product lists.',
bestPractices: [
{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge: gallery, product list.'},
+ {guidance: true, description: 'Reach for hasLoop on small cyclable sets (photo gallery) where wrapping past the last item back to the first feels natural.'},
{guidance: true, description: 'Always provide an aria-label describing what the carousel contains: "Featured products", "Team members".'},
{guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
{guidance: true, description: 'Trust built-in navigation: trackpad users swipe horizontally, mouse users hold Shift + wheel to move through items.'},
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index b418723dfc..78e710000b 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -55,7 +55,7 @@ export const docs = {
description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
bestPractices: [
{ guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
- { guidance: true, description: "Libraries can augment the icon map with their own keys: registerIcons({'richtext:bold': <MyIcon />}) accepts arbitrary extension keys (not just the built-in IconName set). Resolve them with getExtendedIcon(key, fallback), which prefers a theme-registered icon and falls back to a bundled default — the seam that makes library-shipped icons theme-overridable." },
+ { guidance: true, description: "Override icons through the theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>, and extends shallow-merges it into derived themes. registerIcons() mutates a process-wide registry and warns in dev, so keep it for app bootstrap rather than making it a library's theming seam." },
{ guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
{ guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.' },
{ guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
@@ -133,6 +133,7 @@ export const docsDense = {
description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
bestPractices: [
{ guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+ { guidance: true, description: "Override icons via theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>; extends shallow-merges into derived themes. registerIcons() mutates a global registry and warns in dev: app bootstrap only, not a library theming seam." },
{ guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
{ guidance: true, description: 'For a meaningful standalone icon (no adjacent text), set an accessible name via `label`: sets role="img" + aria-label, unhides icon.' },
{ guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },