Improve examples for components Image Thumbnail

.changeset/clear-symbols-hear.md

@@ -0,0 +1,2 @@
+---
+---

packages/ui-extensions/src/surfaces/admin/components/Image/Image.doc.ts

@@ -6,28 +6,32 @@ const data: AdminReferenceEntityTemplateSchema = {
   thumbnail: '/assets/templated-apis-screenshots/admin/components/image.png',
   isVisualComponent: true,
   subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Adding illustrations and photos.`,
+    },
     {
       title: 'Best practices',
       type: 'Generic' as const,
       anchorLink: 'best-practices',
-      sectionContent: `- **Always provide descriptive alternative text:** Write alt text that describes what's in the image, not what the image is for. Use "Blue cotton t-shirt with crew neck" instead of "Product image." For decorative images that don't add information, use an empty alt attribute.
-- **Use images for meaningful content, not decoration:** Display product photos, diagrams, charts, or instructional screenshots. For icons or decorative elements, use the [icon](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/media-and-visuals/icon) component instead.
-- **Ensure images are accessible and performant:** Use appropriate image formats (WebP for photos, PNG for graphics with transparency, SVG for logos). Ensure images load from reliable sources with proper CORS configuration if cross-origin.
-- **Consider the image's purpose and context:** Use images to help merchants understand products, visualize data, or follow instructions. Every image should serve a clear purpose in your interface.`,
+      sectionContent: `- Use high-resolution, optimized images.
+- Use intentionally to add clarity and guide users.`,
     },
     {
-      title: 'Limitations',
+      title: 'Content guidelines',
       type: 'Generic' as const,
-      anchorLink: 'limitations',
-      sectionContent: `- Images can be loaded from remote URLs or local file resources. Cross-origin images require proper CORS headers from the image host.
-- The component displays images at their intrinsic aspect ratio. Use \`aspectRatio\` (for example, \`'16/9'\`) to set a fixed ratio, and \`objectFit\` (\`'cover'\` or \`'contain'\`) to control how the image resizes within its container.
-- The component provides a basic placeholder while images load but doesn't include built-in loading skeletons or progressive loading features.`,
+      anchorLink: 'content-guidelines',
+      sectionContent: `Alt text should be accurate, concise, and descriptive:
+- Indicate it's an image: "Image of", "Photo of".
+- Focus on description: "Image of a woman with curly brown hair smiling".`,
     },
   ],
   definitions: [
     {
       title: 'Properties',
-      description: 'Configure the following properties on the image component.',
+      description: '',
       type: 'Image',
     },
     {
@@ -37,21 +41,17 @@ const data: AdminReferenceEntityTemplateSchema = {
       type: 'ImageEvents',
     },
   ],
-  category: 'Polaris web components',
-  subCategory: 'Media and visuals',
   defaultExample: {
     image: 'image-default.png',
+    description:
+      'Display a product thumbnail with metadata in a grid layout. This example demonstrates how to control image sizing with `aspectRatio`, `objectFit`, and `inlineSize`, and round corners with `borderRadius`.',
     codeblock: {
-      title: 'Code',
+      title: 'Display a product thumbnail',
       tabs: [
         {
-          code: './examples/default.html',
-          language: 'html',
-        },
-
-        {
-          code: './examples/default.jsx',
-          language: 'preview-jsx',
+          title: '',
+          code: './examples/basic-usage.html',
+          language: 'preview',
         },
       ],
     },
@@ -60,130 +60,74 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     exampleGroups: [
       {
-        title: 'Basic usage',
+        title: '',
         examples: [
           {
             description:
-              'Demonstrates the simplest implementation of an image component with a source and alt text.',
+              'Control image proportions with a fixed aspect ratio. This example displays a 16:9 image that scales to fill its container using `objectFit="cover"`, with lazy loading for performance.',
             codeblock: {
-              title: 'Basic usage',
-              tabs: [
-                {
-                  code: './examples/basic-usage.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/basic-usage.jsx',
-                  language: 'preview-jsx',
-                },
-              ],
-            },
-          },
-          {
-            description:
-              'Shows how to create a responsive image with a fixed 16:9 aspect ratio, set to cover the container, and loaded lazily.',
-            codeblock: {
-              title: 'Responsive layout with aspect ratio',
+              title: 'Set an aspect ratio',
               tabs: [
                 {
+                  title: '',
                   code: './examples/responsive-layout-with-aspect-ratio.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/responsive-layout-with-aspect-ratio.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Illustrates how to provide multiple image sources for different screen sizes and resolutions using srcSet and sizes attributes.',
+              'Set up responsive image sources using `srcSet` and `sizes`. This example demonstrates how to configure the browser to select appropriate image sources based on viewport width.',
             codeblock: {
-              title: 'Responsive images with srcset',
+              title: 'Use responsive images',
               tabs: [
                 {
+                  title: '',
                   code: './examples/responsive-images-with-srcset.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/responsive-images-with-srcset.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Demonstrates how to apply border styling to an image, including width, style, color, and radius, using border-related properties.',
+              'Add visual emphasis with border styling. This example displays an image with border width, color, and rounded corners.',
             codeblock: {
-              title: 'With border styling',
+              title: 'Add border styling',
               tabs: [
                 {
+                  title: '',
                   code: './examples/with-border-styling.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/with-border-styling.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Shows how to mark an image as decorative, which will make screen readers ignore the image by setting an empty alt text and presentation role.',
+              'Hide images from screen readers when purely decorative. This example presents an image with empty `alt` text and `presentation` role for accessibility.',
             codeblock: {
-              title: 'Decorative image',
+              title: 'Mark as decorative',
               tabs: [
                 {
+                  title: '',
                   code: './examples/decorative-image.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/decorative-image.jsx',
-                  language: 'preview-jsx',
-                },
-              ],
-            },
-          },
-          {
-            description:
-              "Demonstrates an image with auto-sizing, which allows the image to adjust its size based on its container's width.",
-            codeblock: {
-              title: 'Auto-sized image',
-              tabs: [
-                {
-                  code: './examples/auto-sized-image.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/auto-sized-image.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Shows how to use images within a grid layout, creating a consistent grid of images with equal size, aspect ratio, and styling.',
+              'Build a product image gallery with consistent sizing using [grid](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/grid). This example arranges three product photos in a row, each constrained to a square with rounded corners so they line up evenly.',
             codeblock: {
-              title: 'Within layout components',
+              title: 'Use in a grid layout',
               tabs: [
                 {
+                  title: '',
                   code: './examples/within-layout-components.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/within-layout-components.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },

packages/ui-extensions/src/surfaces/admin/components/Image/examples/basic-usage.html

@@ -1,4 +1,15 @@
-<s-image
-  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
-  alt="Product image"
-></s-image>
+<s-grid gridTemplateColumns="80px 1fr" gap="base" alignItems="center">
+  <s-image
+    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
+    alt="Indoor plant"
+    aspectRatio="1/1"
+    objectFit="cover"
+    borderRadius="base"
+    inlineSize="fill"
+  />
+  <s-stack gap="small">
+    <s-text type="strong">Indoor Plant</s-text>
+    <s-text color="subdued">SKU: PLT-001</s-text>
+    <s-text tone="success">In stock</s-text>
+  </s-stack>
+</s-grid>