Skip to content

Comments

Improve examples for components Image Thumbnail#3927

Open
sordaz00 wants to merge 11 commits into2026-01from
uiext-polaris-examples-batch3
Open

Improve examples for components Image Thumbnail#3927
sordaz00 wants to merge 11 commits into2026-01from
uiext-polaris-examples-batch3

Conversation

@sordaz00
Copy link
Contributor

@sordaz00 sordaz00 commented Feb 19, 2026 •
edited
Loading

Updating examples only for App Home polaris components: Image and Thumbnail.

Updates:

  • Improves examples descriptions to 2-sentence structure: What this pattern helps merchants accomplish + What this specific example demonstrates beginning with "This example shows..."
  • Update to action-oriented titles
  • Removes redundant examples

Relates to:
https://github.com/Shopify/shopify-dev/issues/67432
https://github.com/Shopify/shopify-dev/issues/67433

Test plan

  • Run yarn docs:admin 2026-01 to verify docs build
  • Verify Image and Thumbnail pages render correctly

@github-actions

This comment has been minimized.

Sign in to view
mcvinci
mcvinci reviewed Feb 19, 2026
View reviewed changes
Copy link
Contributor

@mcvinci mcvinci left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for these updates, @sordaz00! I've added some comments and suggestions throughout, some of which could also be applied to your other code example PRs:

Let me know if you'd like to chat through any of these areas!

SteveSill
SteveSill reviewed Feb 20, 2026
View reviewed changes
Copy link
Contributor

@SteveSill SteveSill left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey! Nice work on these. 😄 I left some comments / suggestions, but most of them are around the code in the examples. I'm not sure if that's in scope for you guys, but I thought I'd leave them there anyway.

packages/ui-extensions/src/surfaces/admin/components/Image/Image.doc.ts Outdated
{
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 shows a 16:9 image with cover fit and lazy loading for performance.',
Copy link
Contributor

@SteveSill SteveSill Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Little confused by 'cover fit'. What is a cover fit?

mcvinci
mcvinci approved these changes Feb 20, 2026
View reviewed changes
Copy link
Contributor

@mcvinci mcvinci left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice updates, @sordaz00! Again, I'll leave it up to you if you want to revisit any descriptions in a follow-up PR to add some more specifics about certain props / attributes that are referenced in the code examples (related comment).

packages/ui-extensions/src/surfaces/admin/components/Image/Image.doc.ts Outdated
@@ -37,21 +41,17 @@ const data: AdminReferenceEntityTemplateSchema = {
Copy link
Contributor

@mcvinci mcvinci Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
'The image component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).',

packages/ui-extensions/src/surfaces/admin/components/Image/Image.doc.ts Outdated
{
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/app-home/polaris-web-components/s-grid). This example arranges three product photos in a row, each constrained to a square with rounded corners so they line up evenly.',
Copy link
Contributor

@mcvinci mcvinci Feb 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
'Build a product image gallery with consistent sizing using [Grid](/docs/api/app-home/polaris-web-components/s-grid). This example arranges three product photos in a row, each constrained to a square with rounded corners so they line up evenly.',
'Build a product image gallery with consistent sizing using a [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.',

packages/ui-extensions/src/surfaces/admin/components/Thumbnail/Thumbnail.doc.ts Outdated
Copy link
Contributor

@mcvinci mcvinci Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
'The thumbnail component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).',

@sordaz00 sordaz00 changed the title Improve App Home Polaris examples - Batch 3 (Image, Thumbnail) Improve examples for components Image Thumbnail Feb 23, 2026
Stephanie Ordaz and others added 10 commits February 24, 2026 14:18
@sordaz00
Improve App Home Polaris examples - Batch 3 (Image, Thumbnail)
d4761a6 
Updates example documentation for Image and Thumbnail components:

Image (8 examples):
- Swapped default to show simplest usage (src + alt)
- Added "Combine aspect ratio and sizing" for advanced usage
- Updated all descriptions to 3-sentence pattern
- Action-oriented titles throughout

Thumbnail (4 examples, was 5):
- Added description to default example
- Removed redundant "Basic usage" (identical to default)
- Updated all descriptions to 3-sentence pattern
- Action-oriented titles throughout
@sordaz00 @mcvinci
Update packages/ui-extensions/src/surfaces/admin/components/Image/Ima…
4d0bf69 
…ge.doc.ts

Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>
@sordaz00 @mcvinci
Update packages/ui-extensions/src/surfaces/admin/components/Image/Ima…
5ac6f82 
…ge.doc.ts

Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>
@sordaz00 @mcvinci
Update packages/ui-extensions/src/surfaces/admin/components/Thumbnail…
4a08a35 
…/Thumbnail.doc.ts

Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>
@sordaz00
Simplify examples for Image and Thumbnail components
855c595 
- Collapse code examples to HTML only, removing duplicate JSX tabs
- Remove "Click to interact with the preview." from all descriptions
- Add backticks to property names in descriptions (srcSet, sizes, alt, etc.)
- Delete unused .jsx example files
@sordaz00
Remove 'html' tab title from code blocks
bda5484
@sordaz00
Update code block language to 'preview' for Image and Thumbnail
0408555
@sordaz00
Fix Events link to use correct polaris URL format
8aa40c5
@sordaz00
Improve Image and Thumbnail examples based on PR feedback
f88b345 
- Update basic Image example to show realistic product thumbnail with metadata
- Remove redundant auto-sized image example
- Clarify descriptions for objectFit and responsive images
- Fix Thumbnail alt texts to follow "Image of" convention
- Fix event handling example to use proper addEventListener pattern
  instead of React-style onLoad attribute
- Add both load and error handlers to match description
@sordaz00 @cursoragent
Address PR feedback for Image and Thumbnail docs
78327e3 
- Replace "This example shows" with active verbs
- Add periods to all bullet points
- Lowercase component names in prose (image, thumbnail)
- Fix Grid link to use proper URL format with API placeholders

Co-authored-by: Cursor <cursoragent@cursor.com>
@sordaz00 sordaz00 force-pushed the uiext-polaris-examples-batch3 branch from 38825ba to a7c1f87 Compare February 24, 2026 20:20
@sordaz00 @cursoragent
Add empty changeset for docs-only changes
0cc8a15 
Co-authored-by: Cursor <cursoragent@cursor.com>
@sordaz00 sordaz00 force-pushed the uiext-polaris-examples-batch3 branch from 55f1dac to 0cc8a15 Compare February 24, 2026 20:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@SteveSill SteveSill SteveSill left review comments

@mcvinci mcvinci mcvinci approved these changes

Assignees

No one assigned

Labels

cla-needed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@sordaz00 @mcvinci @SteveSill