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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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: {