Skip to content

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

TypeScript

docs(core): correct Carousel doc drift and translate zh usage block (#3532)

Md Shahrier Islam Arham1f25f2593f4d
diff --git a/.changeset/carousel-docs-accuracy.md b/.changeset/carousel-docs-accuracy.md
new file mode 100644
index 0000000000..ce6daa75e0
--- /dev/null
+++ b/.changeset/carousel-docs-accuracy.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Correct Carousel doc drift and translate its Chinese usage block (#3532)
+
+The Carousel docs described behaviors the component doesn't have: there is no scroll-driven scale effect on items, and the prev/next buttons are driven by per-edge overflow (each appears when the content can scroll in that direction), not by hover or platform. Descriptions now match the source. Also translates the docsZh usage block, which was still in English.
+@arham766
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index ca2c455b04..5c45aa2409 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -20,15 +20,15 @@ export const docs = {
],
anatomy: [
{name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
- {name: 'Items', required: true, description: 'The children rendered in a row. Each item is animated with a scroll-driven scale effect.'},
+ {name: 'Items', required: true, description: 'The children rendered in a row inside the scroll container. With hasSnap, each item snaps to the start edge.'},
{name: 'Fade edges', required: false, description: 'Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.'},
- {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
+ {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear when the content can scroll in that direction. Enabled by default, disable with hasButtons={false}.'},
],
},
props: [
{name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
{name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
- {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+ {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons when content is scrollable.', default: 'true'},
{name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
{name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
{name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
@@ -59,20 +59,20 @@ export const docs = {
export const docsZh = {
usage: {
description:
- 'Carousel scrolls a row of items horizontally when they overflow the available width. Use it for card grids, image galleries, product lists, or any set of items that should be browsable without taking up the full page.',
+ 'Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表,或任何希望无需占据整页即可浏览的项目集合。',
bestPractices: [
- {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
- {guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
- {guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
- {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
- {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
- {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
+ {guidance: true, description: '当每个项目应精确对齐到起始边缘时启用滚动吸附,例如画廊或产品列表。'},
+ {guidance: true, description: '始终提供描述轮播内容的 aria-label,例如"精选产品"或"团队成员"。'},
+ {guidance: true, description: '使用一致的间距和项目宽度,让轮播看起来是有意为之,而不是内容意外溢出。'},
+ {guidance: false, description: '将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动,关键内容应放在首屏。'},
+ {guidance: false, description: '自动轮播项目。让用户按自己的节奏滚动。'},
+ {guidance: false, description: '嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。'},
],
},
propDescriptions: {
children: '在水平滚动容器中渲染的轮播项目。',
gap: '使用间距令牌比例的项目间距。',
- hasButtons: '悬停时显示上一个/下一个导航按钮(仅桌面端)。',
+ hasButtons: '内容可滚动时显示上一个/下一个导航按钮。',
hasEdgeFade: '内容溢出时显示渐变边缘遮罩,提示屏幕外还有更多项目。',
hasSnap: '启用滚动吸附,使每个子元素吸附到起始边缘。',
padding: '滚动容器内的内联内边距,并设置匹配的 scroll-padding,使吸附点与内容边缘对齐。',
@@ -98,7 +98,7 @@ export const docsDense = {
propDescriptions: {
children: 'carousel items in horizontal scroll',
gap: 'item spacing via spacing token scale',
- hasButtons: 'prev/next buttons on hover (desktop)',
+ hasButtons: 'prev/next buttons when content is scrollable',
hasEdgeFade: 'gradient edge-fade mask on overflow',
hasSnap: 'scroll-snap; children snap to start edge',
padding: 'inline padding; scroll-padding keeps snap points on content edge',