Skip to content

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

TypeScript

Improve Carousel docs page and block examples (#1557)

rubyycheung8a88eadf1e7f
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselCards.doc.mjs b/packages/cli/templates/blocks/components/Carousel/CarouselCards.doc.mjs
index d72cf37841..62e0ec4b4b 100644
--- a/packages/cli/templates/blocks/components/Carousel/CarouselCards.doc.mjs
+++ b/packages/cli/templates/blocks/components/Carousel/CarouselCards.doc.mjs
@@ -1,10 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Carousel — Card Content',
- description:
- 'Horizontally scrollable carousel of card components with snap scrolling.',
+ name: 'Carousel — Cards',
+ description: 'A horizontally scrollable row of cards with snap scrolling enabled. Use for feature grids, product lists, or any set of cards that overflows the available width. The carousel adds fade edges and navigation buttons automatically.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Carousel', 'Card'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Carousel', 'Card', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselCards.tsx b/packages/cli/templates/blocks/components/Carousel/CarouselCards.tsx
index fbf3533197..cb5724fed5 100644
--- a/packages/cli/templates/blocks/components/Carousel/CarouselCards.tsx
+++ b/packages/cli/templates/blocks/components/Carousel/CarouselCards.tsx
@@ -2,31 +2,44 @@
import {XDSCarousel} from '@xds/core/Carousel';
import {XDSCard} from '@xds/core/Card';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
-const CARDS = [
- {id: 1, title: 'Design System', desc: 'Component library'},
- {id: 2, title: 'Documentation', desc: 'API reference'},
- {id: 3, title: 'Storybook', desc: 'Visual testing'},
- {id: 4, title: 'Theme Config', desc: 'Token overrides'},
- {id: 5, title: 'CLI Tools', desc: 'Code generation'},
- {id: 6, title: 'Accessibility', desc: 'ARIA patterns'},
+const FEATURES = [
+ {
+ title: 'Design System',
+ desc: 'Tokens, components, and patterns',
+ },
+ {
+ title: 'Documentation',
+ desc: 'API reference and usage guides',
+ },
+ {
+ title: 'Storybook',
+ desc: 'Visual testing and previews',
+ },
];
export default function CarouselCards() {
return (
- <div style={{maxWidth: 500}}>
+ <XDSStack direction="vertical" gap={3} style={{maxWidth: 520, padding: 8}}>
+ <XDSText type="body" weight="bold">
+ Browse features
+ </XDSText>
<XDSCarousel gap={2} hasSnap aria-label="Feature cards">
- {CARDS.map(card => (
- <XDSCard key={card.id} width={160}>
- <p style={{margin: 0, fontSize: 14, fontWeight: 600}}>
- {card.title}
- </p>
- <p style={{margin: '4px 0 0', fontSize: 12, color: '#666'}}>
- {card.desc}
- </p>
+ {FEATURES.map(item => (
+ <XDSCard key={item.title} width={200} minHeight={100}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="body" weight="bold">
+ {item.title}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {item.desc}
+ </XDSText>
+ </XDSStack>
</XDSCard>
))}
</XDSCarousel>
- </div>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselColorSwatches.doc.mjs b/packages/cli/templates/blocks/components/Carousel/CarouselColorSwatches.doc.mjs
deleted file mode 100644
index 9cee282abe..0000000000
--- a/packages/cli/templates/blocks/components/Carousel/CarouselColorSwatches.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Carousel — Custom Content',
- description:
- 'Carousel with arbitrary content (color swatches) showing it works with any children.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Carousel'],
-};
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselColorSwatches.tsx b/packages/cli/templates/blocks/components/Carousel/CarouselColorSwatches.tsx
deleted file mode 100644
index 8f67e320ab..0000000000
--- a/packages/cli/templates/blocks/components/Carousel/CarouselColorSwatches.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-'use client';
-
-import {XDSCarousel} from '@xds/core/Carousel';
-
-const COLORS = [
- '#e74c3c',
- '#e67e22',
- '#f1c40f',
- '#2ecc71',
- '#1abc9c',
- '#3498db',
- '#9b59b6',
- '#34495e',
- '#e84393',
- '#00cec9',
- '#6c5ce7',
- '#fdcb6e',
-];
-
-export default function CarouselColorSwatches() {
- return (
- <div style={{maxWidth: 360}}>
- <XDSCarousel gap={1.5} aria-label="Color swatches">
- {COLORS.map(color => (
- <div
- key={color}
- style={{
- width: 80,
- height: 80,
- borderRadius: 8,
- backgroundColor: color,
- flexShrink: 0,
- }}
- title={color}
- />
- ))}
- </XDSCarousel>
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselScrollSnap.doc.mjs b/packages/cli/templates/blocks/components/Carousel/CarouselScrollSnap.doc.mjs
deleted file mode 100644
index 52c2a4a6dd..0000000000
--- a/packages/cli/templates/blocks/components/Carousel/CarouselScrollSnap.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Carousel — Scroll Snap',
- description:
- 'Thumbnail carousel with scroll-snap enabled for precise item alignment.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Carousel', 'Thumbnail'],
-};
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselScrollSnap.tsx b/packages/cli/templates/blocks/components/Carousel/CarouselScrollSnap.tsx
deleted file mode 100644
index 359c495bfe..0000000000
--- a/packages/cli/templates/blocks/components/Carousel/CarouselScrollSnap.tsx
+++ /dev/null
@@ -1,32 +0,0 @@
-'use client';
-
-import {XDSCarousel} from '@xds/core/Carousel';
-import {XDSThumbnail} from '@xds/core/Thumbnail';
-
-const IMAGES = [
- {id: 1, src: 'https://picsum.photos/id/1042/200/200', label: 'dark.jpg'},
- {id: 2, src: 'https://picsum.photos/id/1043/200/200', label: 'light.jpg'},
- {id: 3, src: 'https://picsum.photos/id/1044/200/200', label: 'warm.jpg'},
- {id: 4, src: 'https://picsum.photos/id/1047/200/200', label: 'mixed.jpg'},
- {id: 5, src: 'https://picsum.photos/id/1050/200/200', label: 'nature.jpg'},
- {id: 6, src: 'https://picsum.photos/id/1055/200/200', label: 'city.jpg'},
- {id: 7, src: 'https://picsum.photos/id/1060/200/200', label: 'ocean.jpg'},
- {id: 8, src: 'https://picsum.photos/id/1069/200/200', label: 'forest.jpg'},
-];
-
-export default function CarouselScrollSnap() {
- return (
- <div style={{maxWidth: 400}}>
- <XDSCarousel gap={2} hasSnap aria-label="Snapping gallery">
- {IMAGES.map(img => (
- <XDSThumbnail
- key={img.id}
- src={img.src}
- alt={img.label}
- label={img.label}
- />
- ))}
- </XDSCarousel>
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselSnap.doc.mjs b/packages/cli/templates/blocks/components/Carousel/CarouselSnap.doc.mjs
new file mode 100644
index 0000000000..c2ff70716a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Carousel/CarouselSnap.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Carousel — Snap',
+ description: 'Scroll-snap carousel with navigation buttons and team member cards. Each card snaps to the start edge on scroll. Use when items should be viewed one at a time rather than as a continuous strip.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Carousel', 'Avatar', 'Badge', 'Card', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Carousel/CarouselSnap.tsx b/packages/cli/templates/blocks/components/Carousel/CarouselSnap.tsx
new file mode 100644
index 0000000000..85922d86de
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Carousel/CarouselSnap.tsx
@@ -0,0 +1,39 @@
+'use client';
+
+import {XDSCarousel} from '@xds/core/Carousel';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSCard} from '@xds/core/Card';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const TEAM = [
+ {name: 'Alice Chen', role: 'Engineering Lead', color: 'blue' as const},
+ {name: 'Bob Smith', role: 'Product Designer', color: 'purple' as const},
+ {name: 'Carol Davis', role: 'Product Manager', color: 'green' as const},
+];
+
+export default function CarouselSnap() {
+ return (
+ <XDSStack direction="vertical" gap={3} style={{maxWidth: 520, padding: 8}}>
+ <XDSText type="body" weight="bold">
+ Team members
+ </XDSText>
+ <XDSCarousel gap={2} hasSnap hasButtons aria-label="Team members">
+ {TEAM.map(person => (
+ <XDSCard key={person.name} width={180} minHeight={140}>
+ <XDSStack direction="vertical" gap={3} hAlign="center">
+ <XDSAvatar name={person.name} size="medium" />
+ <XDSStack direction="vertical" gap={1} hAlign="center">
+ <XDSText type="body" weight="bold">
+ {person.name}
+ </XDSText>
+ <XDSBadge variant={person.color} label={person.role} />
+ </XDSStack>
+ </XDSStack>
+ </XDSCard>
+ ))}
+ </XDSCarousel>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 803a9654cf..3e8a71a205 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -5,12 +5,20 @@ export const docs = {
keywords: ['carousel', 'slider', 'scroll', 'gallery', 'filmstrip', 'swiper', 'horizontal', 'overflow', 'snap'],
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.',
+ '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.',
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.'},
+ {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. 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.'},
+ ],
+ 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: 'Fade edges', required: true, description: 'Gradient fades on the left and right edges that indicate more content is available.'},
+ {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
],
},
props: [
@@ -36,12 +44,14 @@ export const docs = {
export const docsZh = {
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.',
+ '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.',
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.'},
+ {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. 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.'},
],
},
propDescriptions: {
@@ -55,15 +65,13 @@ 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',
+ description: 'horizontal scroll container w/ fade edges, nav buttons, scroll-snap',
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.',
+ '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 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.'},
+ {guidance: true, description: 'Scroll-snap for precise alignment. Always set aria-label. Consistent gap and item width.'},
+ {guidance: false, description: 'Critical content in carousels. Auto-advance. Nested carousels.'},
],
},
propDescriptions: {