Skip to content

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

TypeScript

Improve Thumbnail docs page and block examples (#1607)

Kenton Quatmanf29024a9a2c6
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.doc.mjs
new file mode 100644
index 0000000000..036ef1fc17
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Thumbnail — Disabled',
+ description: 'Thumbnails in the disabled state with reduced opacity. The remove button and click handler are suppressed when disabled.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Thumbnail', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx
new file mode 100644
index 0000000000..70d5beb90f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailDisabled.tsx
@@ -0,0 +1,41 @@
+'use client';
+
+import {XDSThumbnail} from '@xds/core/Thumbnail';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ThumbnailDisabled() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Enabled
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSThumbnail
+ src="https://picsum.photos/id/1043/200/200"
+ alt="Bright landscape"
+ label="landscape.jpg"
+ onRemove={() => {}}
+ />
+ <XDSThumbnail label="document.pdf" onRemove={() => {}} />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Disabled
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ <XDSThumbnail
+ src="https://picsum.photos/id/1043/200/200"
+ alt="Bright landscape"
+ label="landscape.jpg"
+ onRemove={() => {}}
+ isDisabled
+ />
+ <XDSThumbnail label="document.pdf" onRemove={() => {}} isDisabled />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.doc.mjs
index 9cb7a59631..49beb84260 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.doc.mjs
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'Thumbnail — Gallery',
- description:
- 'Row of removable thumbnails forming an image gallery with a reset action when all are removed.',
+ description: 'A row of clickable thumbnails with labels that open a detail view. Use for image attachment lists where users need to preview and manage uploads.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Thumbnail'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Thumbnail', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx
index 3b5acb0ef7..7fcc5b26bf 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx
@@ -2,35 +2,44 @@
import {useState} from 'react';
import {XDSThumbnail} from '@xds/core/Thumbnail';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
-const initialItems = [
- {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'},
+const ATTACHMENTS = [
+ {id: 1, src: 'https://picsum.photos/id/1015/200/200', alt: 'River through a valley', label: 'valley.jpg'},
+ {id: 2, src: 'https://picsum.photos/id/1018/200/200', alt: 'Foggy mountain peak', label: 'mountain.jpg'},
+ {id: 3, src: 'https://picsum.photos/id/1025/200/200', alt: 'Golden retriever puppy', label: 'puppy.jpg'},
+ {id: 4, src: 'https://picsum.photos/id/1035/200/200', alt: 'Bridge at sunset', label: 'bridge.jpg'},
];
export default function ThumbnailGallery() {
- const [items, setItems] = useState(initialItems);
+ const [selected, setSelected] = useState<string | null>(null);
+ const [items, setItems] = useState(ATTACHMENTS);
return (
- <div style={{display: 'flex', gap: 8, alignItems: 'flex-start'}}>
- {items.map(item => (
- <XDSThumbnail
- key={item.id}
- src={item.src}
- alt={item.label}
- label={item.label}
- onRemove={() =>
- setItems(prev => prev.filter(i => i.id !== item.id))
- }
- />
- ))}
- {items.length === 0 && (
- <p style={{color: '#888', fontSize: 12}}>
- All removed.{' '}
- <button onClick={() => setItems(initialItems)}>Reset</button>
- </p>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Click to preview, dismiss to remove
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ {items.map(item => (
+ <XDSThumbnail
+ key={item.id}
+ src={item.src}
+ alt={item.alt}
+ label={item.label}
+ onClick={() => setSelected(item.label)}
+ onRemove={() =>
+ setItems(prev => prev.filter(i => i.id !== item.id))
+ }
+ />
+ ))}
+ </XDSStack>
+ {selected != null && (
+ <XDSText type="supporting" color="active">
+ Previewing: {selected}
+ </XDSText>
)}
- </div>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailLoading.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailLoading.doc.mjs
deleted file mode 100644
index dcf7849400..0000000000
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailLoading.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Thumbnail — Loading States',
- description:
- 'Thumbnails in loading state, both without a preview and with a blurred preview image.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Thumbnail'],
-};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailLoading.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailLoading.tsx
deleted file mode 100644
index 4cf38f9598..0000000000
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailLoading.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {XDSThumbnail} from '@xds/core/Thumbnail';
-
-export default function ThumbnailLoading() {
- return (
- <div style={{display: 'flex', gap: 8, alignItems: 'flex-start'}}>
- <XDSThumbnail isLoading label="uploading.jpg" />
- <XDSThumbnail
- src="https://picsum.photos/id/1044/200/200"
- alt="Uploading preview"
- isLoading
- label="vacation.jpg"
- />
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailPlaceholder.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailPlaceholder.doc.mjs
deleted file mode 100644
index ee44807d09..0000000000
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailPlaceholder.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Thumbnail — Placeholder',
- description:
- 'Thumbnail without an image source, showing a placeholder icon for non-image files.',
- isReady: true,
- aspectRatio: 1,
- componentsUsed: ['Thumbnail'],
-};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailPlaceholder.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailPlaceholder.tsx
deleted file mode 100644
index bf3948304b..0000000000
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailPlaceholder.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSThumbnail} from '@xds/core/Thumbnail';
-
-export default function ThumbnailPlaceholder() {
- const [visible, setVisible] = useState(true);
-
- if (!visible) {
- return (
- <p style={{color: '#888', fontSize: 12}}>
- Removed.{' '}
- <button onClick={() => setVisible(true)}>Undo</button>
- </p>
- );
- }
-
- return (
- <XDSThumbnail
- label="report.pdf"
- onRemove={() => setVisible(false)}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.doc.mjs
index b7615d82b0..f4c2926b95 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'Thumbnail — Removable',
- description:
- 'Thumbnail with a remove button that hides the image and offers an undo action.',
+ description: 'Thumbnails with a remove button overlay. The close button uses APCA luminance detection to stay visible on both dark and light images.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Thumbnail'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Thumbnail', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx
index d7da94f595..758fa6700c 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailRemovable.tsx
@@ -2,25 +2,41 @@
import {useState} from 'react';
import {XDSThumbnail} from '@xds/core/Thumbnail';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
-export default function ThumbnailRemovable() {
- const [visible, setVisible] = useState(true);
+const IMAGES = [
+ {id: 1, src: 'https://picsum.photos/id/1042/200/200', alt: 'Dark cityscape at night', label: 'dark-city.jpg'},
+ {id: 2, src: 'https://picsum.photos/id/1043/200/200', alt: 'Bright snowy landscape', label: 'snow.jpg'},
+ {id: 3, src: 'https://picsum.photos/id/1044/200/200', alt: 'Warm sunset over mountains', label: 'sunset.jpg'},
+];
- if (!visible) {
- return (
- <p style={{color: '#888', fontSize: 12}}>
- Removed.{' '}
- <button onClick={() => setVisible(true)}>Undo</button>
- </p>
- );
- }
+export default function ThumbnailRemovable() {
+ const [items, setItems] = useState(IMAGES);
return (
- <XDSThumbnail
- src="https://picsum.photos/id/1043/200/200"
- alt="Removable thumbnail"
- label="photo.png"
- onRemove={() => setVisible(false)}
- />
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Remove button adapts contrast to image luminance
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="center">
+ {items.map(item => (
+ <XDSThumbnail
+ key={item.id}
+ src={item.src}
+ alt={item.alt}
+ label={item.label}
+ onRemove={() =>
+ setItems(prev => prev.filter(i => i.id !== item.id))
+ }
+ />
+ ))}
+ {items.length === 0 && (
+ <XDSText type="supporting" color="secondary">
+ All removed.
+ </XDSText>
+ )}
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailShowcase.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailShowcase.doc.mjs
index 1cffcb1d4e..16bc19d45d 100644
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'Thumbnail',
isReady: true,
- aspectRatio: 1,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailStates.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailStates.doc.mjs
new file mode 100644
index 0000000000..a9a6c44761
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailStates.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Thumbnail — States',
+ description: 'All visual states side by side: image loaded, placeholder, skeleton loading, and upload overlay. Demonstrates the full lifecycle of a thumbnail from empty to loaded.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Thumbnail', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailStates.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailStates.tsx
new file mode 100644
index 0000000000..978ff74e40
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailStates.tsx
@@ -0,0 +1,52 @@
+'use client';
+
+import {XDSThumbnail} from '@xds/core/Thumbnail';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ThumbnailStates() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Lifecycle: empty → uploading → processing → loaded
+ </XDSText>
+ <XDSStack direction="horizontal" gap={3} vAlign="end">
+ <XDSStack direction="vertical" gap={1} hAlign="center">
+ <XDSThumbnail label="report.pdf" />
+ <XDSText type="supporting" color="secondary">
+ Placeholder
+ </XDSText>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1} hAlign="center">
+ <XDSThumbnail isLoading label="uploading.jpg" />
+ <XDSText type="supporting" color="secondary">
+ Skeleton
+ </XDSText>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1} hAlign="center">
+ <XDSThumbnail
+ src="https://picsum.photos/id/1044/200/200"
+ alt="Mountain landscape"
+ isLoading
+ label="landscape.jpg"
+ />
+ <XDSText type="supporting" color="secondary">
+ Uploading
+ </XDSText>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1} hAlign="center">
+ <XDSThumbnail
+ src="https://picsum.photos/id/1044/200/200"
+ alt="Mountain landscape"
+ label="landscape.jpg"
+ />
+ <XDSText type="supporting" color="secondary">
+ Loaded
+ </XDSText>
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailWithLabel.doc.mjs b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailWithLabel.doc.mjs
deleted file mode 100644
index 94cc178482..0000000000
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailWithLabel.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Thumbnail — With Label',
- description: 'Basic thumbnail with a filename label underneath the image.',
- isReady: true,
- aspectRatio: 1,
- componentsUsed: ['Thumbnail'],
-};
diff --git a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailWithLabel.tsx b/packages/cli/templates/blocks/components/Thumbnail/ThumbnailWithLabel.tsx
deleted file mode 100644
index dd41a21945..0000000000
--- a/packages/cli/templates/blocks/components/Thumbnail/ThumbnailWithLabel.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-'use client';
-
-import {XDSThumbnail} from '@xds/core/Thumbnail';
-
-export default function ThumbnailWithLabel() {
- return (
- <XDSThumbnail
- src="https://picsum.photos/id/1044/200/200"
- alt="Vacation photo"
- label="vacation.jpg"
- />
- );
-}
diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
index dea3d52776..39c44af07b 100644
--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs
+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
@@ -61,18 +61,28 @@ export const docs = {
type: 'string',
description: 'Test selector for automated testing frameworks.',
},
- ], theming: {
+ ],
+ theming: {
targets: [
{className: 'xds-thumbnail'},
],
},
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.',
+ 'Thumbnail displays a compact, square preview of an image attachment. It shows a shimmer effect while uploading, the image on success, and a placeholder icon when no source is set. Use it in chat composers, file upload lists, or anywhere you need a small image preview with optional remove and click actions.',
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.' },
+ {guidance: true, description: 'Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover.'},
+ {guidance: true, description: 'Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available.'},
+ {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image — the thumbnail adds button semantics and a hover shadow automatically.'},
+ {guidance: false, description: "Don't use Thumbnail for non-image file types like PDFs or spreadsheets — use a file attachment component with an appropriate icon instead."},
+ {guidance: false, description: "Don't omit alt text when a src is provided — screen readers need a description of the image content, not just the file name from label."},
+ ],
+ anatomy: [
+ {name: 'Image', required: false, description: 'The preview image, displayed as a square with cover fit.'},
+ {name: 'Placeholder', required: false, description: 'An image silhouette icon shown when no src is provided.'},
+ {name: 'Remove button', required: false, description: 'An overlaid close button in the top-right corner. Appears when onRemove is set. Uses APCA luminance detection to stay visible on any image.'},
+ {name: 'Upload overlay', required: false, description: 'A semi-transparent overlay with a spinner, shown when isLoading is true and a src preview is available.'},
+ {name: 'Skeleton', required: false, description: 'A shimmer animation shown when isLoading is true and no src is set.'},
],
},
};
@@ -80,25 +90,27 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
propDescriptions: {
- src: '图片源 URL。',
- alt: '图片的替代文本。',
- label: '无障碍标签(如文件名)。悬停时以提示工具显示。',
- onRemove: '覆盖层移除按钮的回调。',
- onClick: '点击处理器。添加按钮语义和悬停阴影。',
- isLoading: '显示骨架屏(无 src)或上传覆盖层(有 src)。',
- isDisabled: '是否禁用缩略图。',
- xstyle: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值,而非内联样式对象。',
- className: '根元素的 CSS 类名。建议使用 xstyle。',
- style: '根元素的内联样式。建议使用 xstyle。',
- 'data-testid': '用于自动化测试框架的测试选择器。',
+ src: '\u56FE\u7247\u6E90 URL\u3002',
+ alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002',
+ label: '\u65E0\u969C\u788D\u6807\u7B7E\uFF08\u5982\u6587\u4EF6\u540D\uFF09\u3002\u60AC\u505C\u65F6\u4EE5\u63D0\u793A\u5DE5\u5177\u663E\u793A\u3002',
+ onRemove: '\u8986\u76D6\u5C42\u79FB\u9664\u6309\u94AE\u7684\u56DE\u8C03\u3002',
+ onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002',
+ isLoading: '\u663E\u793A\u9AA8\u67B6\u5C4F\uFF08\u65E0 src\uFF09\u6216\u4E0A\u4F20\u8986\u76D6\u5C42\uFF08\u6709 src\uFF09\u3002',
+ isDisabled: '\u662F\u5426\u7981\u7528\u7F29\u7565\u56FE\u3002',
+ xstyle: '\u7528\u4E8E\u5E03\u5C40\u81EA\u5B9A\u4E49\u7684 StyleX \u6837\u5F0F\u3002\u5FC5\u987B\u662F stylex.create() \u7684\u503C\uFF0C\u800C\u975E\u5185\u8054\u6837\u5F0F\u5BF9\u8C61\u3002',
+ className: '\u6839\u5143\u7D20\u7684 CSS \u7C7B\u540D\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
+ style: '\u6839\u5143\u7D20\u7684\u5185\u8054\u6837\u5F0F\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
+ 'data-testid': '\u7528\u4E8E\u81EA\u52A8\u5316\u6D4B\u8BD5\u6846\u67B6\u7684\u6D4B\u8BD5\u9009\u62E9\u5668\u3002',
},
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.',
+ 'Thumbnail \u662F\u56FE\u7247\u9644\u4EF6\u7684\u65B9\u5F62\u9884\u89C8\u5361\u7247\u3002\u4E0A\u4F20\u65F6\u663E\u793A\u9AA8\u67B6\u5C4F\u52A8\u753B\uFF0C\u6210\u529F\u540E\u663E\u793A\u56FE\u7247\uFF0C\u672A\u8BBE\u7F6E\u6E90\u65F6\u663E\u793A\u5360\u4F4D\u56FE\u6807\u3002\u7528\u4E8E\u804A\u5929\u7F16\u8F91\u5668\u3001\u6587\u4EF6\u4E0A\u4F20\u5217\u8868\u6216\u4EFB\u4F55\u9700\u8981\u7D27\u51D1\u56FE\u7247\u9884\u89C8\u7684\u573A\u666F\u3002',
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.' },
+ {guidance: true, description: '\u59CB\u7EC8\u63D0\u4F9B label \u5C5E\u6027\u5E76\u586B\u5199\u6587\u4EF6\u540D\uFF0C\u4EE5\u4FBF\u5C4F\u5E55\u9605\u8BFB\u5668\u80FD\u591F\u8BC6\u522B\u7F29\u7565\u56FE\u53CA\u5176\u79FB\u9664\u6309\u94AE\uFF0C\u5E76\u5728\u60AC\u505C\u65F6\u663E\u793A\u63D0\u793A\u3002'},
+ {guidance: true, description: '\u4E0A\u4F20\u521D\u671F\u4F7F\u7528\u4E0D\u5E26 src \u7684 isLoading \u663E\u793A\u9AA8\u67B6\u5C4F\uFF1B\u83B7\u5F97\u9884\u89C8 URL \u540E\u4F7F\u7528\u5E26 src \u7684 isLoading \u663E\u793A\u65CB\u8F6C\u52A0\u8F7D\u8986\u76D6\u5C42\u3002'},
+ {guidance: true, description: '\u5C06 onClick \u4E0E\u706F\u7BB1\u6216\u8BE6\u60C5\u89C6\u56FE\u914D\u5BF9\uFF0C\u4EE5\u4FBF\u7528\u6237\u67E5\u770B\u5B8C\u6574\u56FE\u7247\u2014\u2014\u7EC4\u4EF6\u4F1A\u81EA\u52A8\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002'},
+ {guidance: false, description: '\u5BF9 PDF \u6216\u7535\u5B50\u8868\u683C\u7B49\u975E\u56FE\u7247\u6587\u4EF6\u7C7B\u578B\u4F7F\u7528 Thumbnail\u2014\u2014\u5E94\u4F7F\u7528\u5E26\u6709\u76F8\u5E94\u56FE\u6807\u7684\u6587\u4EF6\u9644\u4EF6\u7EC4\u4EF6\u3002'},
+ {guidance: false, description: '\u63D0\u4F9B src \u65F6\u7701\u7565 alt \u6587\u672C\u2014\u2014\u5C4F\u5E55\u9605\u8BFB\u5668\u9700\u8981\u56FE\u7247\u5185\u5BB9\u7684\u63CF\u8FF0\uFF0C\u800C\u4E0D\u4EC5\u662F label \u4E2D\u7684\u6587\u4EF6\u540D\u3002'},
],
},
};
@@ -109,11 +121,13 @@ export const docsDense = {
kw: ['thumbnail', 'attachment', 'preview', 'image', 'upload', 'dismiss', 'remove', 'loading'],
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.',
+ 'Compact square image preview. Shimmer while uploading, image on success, placeholder when empty. Use in chat composers, file lists, or small media previews.',
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.' },
+ {guidance: true, description: 'Always set label (file name) for a11y \u2014 powers screen reader announce + hover tooltip.'},
+ {guidance: true, description: 'isLoading w/o src \u2192 skeleton; isLoading w/ src \u2192 spinner overlay. Two distinct loading states.'},
+ {guidance: true, description: 'onClick adds button semantics + hover shadow \u2014 pair with lightbox for full preview.'},
+ {guidance: false, description: "Don't use for non-image files (PDF, xlsx) \u2014 use file attachment component with icon instead."},
+ {guidance: false, description: "Don't omit alt when src present \u2014 screen readers need image content description, not just label."},
],
},
p: {