App Home-only Polaris updates: Modal, Page, Popover, and DropZone by sordaz00 · Pull Request #3920 · Shopify/ui-extensions

sordaz00 · 2026-02-18T14:21:24Z

Updating full page content for App Home-only polaris components.

Updates completed in World and sync'd where relevant.
Improves descriptions
Updates naming convention
Improves examples descriptions to 3-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
Add complete examples
Removes unnecessary sections for ui extension alignment
Updates/adds best practices/limitations aligned to BFS

Relates to:
https://github.com/Shopify/shopify-dev/issues/67273
https://github.com/Shopify/shopify-dev/issues/67272
https://github.com/Shopify/shopify-dev/issues/67274
https://github.com/Shopify/shopify-dev/issues/67275

Test plan

Run yarn docs:admin to regenerate documentation
Verify changes appear correctly in shopify-dev preview
Check that component names render without code styling in prose
Confirm example descriptions are clear and follow the two-sentence pattern

mcvinci

Thanks for these updates, @sordaz00! I went pretty deep on the intros, best practices, limitations, and code examples. Let me know if you have any questions or want to chat through anything. ❤️

I didn't review the prop descriptions, as I think you might need to do another rebase of the shared.d.ts and components.d.ts files. They currently have many revisions unrelated to your changes, so we might need to clean those up first. I'm happy to review those after that!

packages/ui-extensions/src/docs/shared/components/DropZone.ts

packages/ui-extensions/src/docs/shared/components/Modal.ts

packages/ui-extensions/src/docs/shared/components/Page.ts

packages/ui-extensions/src/docs/shared/components/Popover.ts

...es/ui-extensions/src/surfaces/admin/components/DropZone/examples/upload-with-validation.html

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

packages/ui-extensions/src/surfaces/admin/components/shared.d.ts

packages/ui-extensions/src/surfaces/admin/components.d.ts

- Add Best practices and Limitations sections - Update descriptions with clearer language - Add complete workflow examples - Use interactive preview language for examples

- Modal: Replace repeated "The Modal component" with "This component", add link to App Window for complex workflows - Popover: Add second paragraph with link to Modal for larger interactions - DropZone: Restructure intro to lead with use cases, move technical details to second paragraph

- Rewrite descriptions to follow goal-focused pattern: user goal + specific implementation - Remove backticks from component names in Properties descriptions - Vary sentence structure to avoid repetitive phrasing

- Change PascalCase component names to lowercase (modal, page, popover, drop zone) - Remove backticks from component name references in descriptions - Keep code references (type fields, imports) unchanged

- Update name field from 'DropZone' to 'Drop zone'

- Generalize shared descriptions (remove prop-specific content) - Remove App Bridge-specific paragraph from Modal shared description - Add "Shopify" before "admin's" in Page description - Add MDN link for commandFor in Popover description - Update Events/Slots descriptions to match component pattern - Remove JSX tabs, keep HTML-only with language: 'preview' - Delete 28 unreferenced JSX example files

mcvinci

Added a couple more suggestions! Your updates to examples are looking 🔥!

I noticed that the updates to field / prop descriptions for modal, page, popover, and drop zone were removed from your PR (shared.ts and components.d.ts). Are you thinking to tackle those updates in a separate PR (or maybe no further updates are necessary for prop descriptions)?

mcvinci · 2026-02-20T20:47:49Z

packages/ui-extensions/src/docs/shared/components/DropZone.ts

+  name: 'Drop zone',
  description:
-    'Lets users upload files through drag-and-drop functionality into a designated area on a page, or by activating a button.',
+    'The drop zone component lets users upload files through drag-and-drop or by clicking to browse. Use for file uploads such as images, documents, or CSV imports.',


In comparison to the descriptions for the page and popover components, it feels like drop zone and modal are a bit thin on details. Not sure if there's more that we can say about drop zone and modal?

mcvinci · 2026-02-20T20:48:49Z

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

+      sectionContent: `- Set clear file type and size restrictions using the \`accept\` property
+- Use the \`droprejected\` event to display meaningful error messages when uploads fail validation
+- Consider using \`disabled\` to prevent uploads during processing`,


If we do end up keeping these here, let's just add periods at the end of each statement. 😄

mcvinci · 2026-02-20T21:10:54Z

@sordaz00 Re: CI errors, you should be able to feed the linting errors into Cursor for quick fixes. With the CLA, I think you can just re-run that check, and it should pass the next time.

mcvinci

One non-blocking thought to ponder, and can definitely be considered in a follow-up PR:

With the richer example code, should we also have richer descriptions that refer to specific props? I'm comparing to some of the API example descriptions that @SteveSill has written (example, which share a lot of context about what's going on in the code.

- Remove Usage/Useful for sections from Modal and Popover - Add periods to all bullet points for consistency - Update example descriptions with active verbs and prop references - Expand shared component descriptions with implementation details - Fix Page subCategory to match live docs URL structure - Sync prop descriptions from world Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions bot added the cla-needed label Feb 18, 2026

sordaz00 force-pushed the uiext-polaris-modal-page-popover-dropzone branch from 9b1d2de to dc510fd Compare February 18, 2026 15:34

sordaz00 changed the base branch from 2026-04-rc to 2026-01 February 18, 2026 15:43

sordaz00 changed the title ~~Improve documentation for Modal, Page, Popover, and DropZone components~~ App Home-only Polaris updates: Modal, Page, Popover, and DropZone Feb 18, 2026

This comment has been minimized.

Sign in to view

mcvinci reviewed Feb 19, 2026

View reviewed changes

sordaz00 added 8 commits February 20, 2026 07:17

Improve Polaris component docs: Page, DropZone, Modal, Popover

44a3859

- Add Best practices and Limitations sections - Update descriptions with clearer language - Add complete workflow examples - Use interactive preview language for examples

Update Polaris component docs: descriptions, titles, and intros

ddd9270

Improve example descriptions for Modal, Page, Popover, and DropZone

5b2bb17

- Rewrite descriptions to follow goal-focused pattern: user goal + specific implementation - Remove backticks from component names in Properties descriptions - Vary sentence structure to avoid repetitive phrasing

Use lowercase component names in documentation prose

809f698

- Change PascalCase component names to lowercase (modal, page, popover, drop zone) - Remove backticks from component name references in descriptions - Keep code references (type fields, imports) unchanged

Change DropZone page title to sentence case

e0b7f7c

- Update name field from 'DropZone' to 'Drop zone'

Use API_NAME/API_VERSION variables in shared docs links

b8bef38

sordaz00 force-pushed the uiext-polaris-modal-page-popover-dropzone branch from e0dfa93 to 71747d6 Compare February 20, 2026 13:26

mcvinci approved these changes Feb 20, 2026

View reviewed changes

mcvinci reviewed Feb 20, 2026

View reviewed changes

This was referenced Feb 20, 2026

Improve examples for Avatar, Checkbox, ColorField, ColorPicker, and Icon #3926

Open

Improve examples for components Image Thumbnail #3927

Open

sordaz00 and others added 2 commits February 24, 2026 10:50

Add empty changeset for docs-only changes

4b69208

Co-authored-by: Cursor <cursoragent@cursor.com>

sordaz00 force-pushed the uiext-polaris-modal-page-popover-dropzone branch from 3730887 to 4b69208 Compare February 24, 2026 20:29

github-actions bot removed the cla-needed label Feb 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

App Home-only Polaris updates: Modal, Page, Popover, and DropZone#3920

App Home-only Polaris updates: Modal, Page, Popover, and DropZone#3920
sordaz00 wants to merge 10 commits into2026-01from
uiext-polaris-modal-page-popover-dropzone

sordaz00 commented Feb 18, 2026 •

edited

Loading

Uh oh!

This comment has been minimized.

mcvinci left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcvinci left a comment

Uh oh!

mcvinci Feb 20, 2026

Uh oh!

mcvinci Feb 20, 2026

Uh oh!

mcvinci commented Feb 20, 2026

Uh oh!

mcvinci left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

sordaz00 commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test plan

Uh oh!

This comment has been minimized.

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

mcvinci Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

mcvinci Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

mcvinci commented Feb 20, 2026

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sordaz00 commented Feb 18, 2026 •

edited

Loading