Improve examples for MoneyField, PasswordField, Select, Switch, URLField by sordaz00 · Pull Request #3923 · Shopify/ui-extensions

sordaz00 · 2026-02-18T22:24:34Z

Updating examples only for App Home polaris components: MoneyField, PasswordField, Select, Switch URLField.

Updates:

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 any redundant examples

Relates to:
https://github.com/Shopify/shopify-dev/issues/67273
https://github.com/Shopify/shopify-dev/issues/67423
https://github.com/Shopify/shopify-dev/issues/67426
https://github.com/Shopify/shopify-dev/issues/67421
https://github.com/Shopify/shopify-dev/issues/67429

Test plan

Verify descriptions render correctly on docs pages

github-actions · 2026-02-18T22:24:44Z

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.

mcvinci

Hey @sordaz00! I tried running yarn docs:admin 2026-01 to preview these doc changes, but it looks like there are some build errors you might need to sort through. I can review these again once CI is passing!

Let me know if have any questions. Happy to pair up! ❤️

…witch, URLField Apply consistent 3-sentence pattern to all example descriptions: - Purpose statement explaining why to use this pattern - "This example shows..." describing specific implementation - "Click to interact with the preview." CTA Also corrected descriptions to accurately match example code.

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

mcvinci

Nice updates, @sordaz00! I'm still seeing a combination of JSX and HTML examples, which are very similar. We might still need to do a bit of clean up so that only the HTML examples render.

mcvinci · 2026-02-24T00:41:16Z

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

  defaultExample: {
-    image: 'moneyfield-default.png',
+    description:
+      'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details. Click to interact with the preview.',


Suggested change

'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details. Click to interact with the preview.',

'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details.',

mcvinci · 2026-02-24T00:41:32Z

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

          {
            description:
-              'Demonstrates a simple money field with a label, initial value, and numeric constraints.',
+              'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range. Click to interact with the preview.',


Suggested change

'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range. Click to interact with the preview.',

'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range.',

mcvinci · 2026-02-24T00:42:09Z

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

          {
            description:
-              'Showcases a money field with explicit minimum and maximum value limits, and a detailed description for user guidance.',
+              'Communicate input problems clearly to users. This example shows an error message displayed when the entered value is invalid. Click to interact with the preview.',


I won't add suggestions for all of these descriptions, but recommend removing the "Click to interact with the preview" from all of them. Let's get a better UX treatment for this instead of trying to solve with content.

mcvinci · 2026-02-24T00:45:45Z

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

@@ -42,9 +42,10 @@ const data: AdminReferenceEntityTemplateSchema = {
    },
  ],
  defaultExample: {


For some of these examples, I'm seeing codeblocks only in jsx (such as "Validate input in real time"). For others, I'm seeing both jsx and html tabs. I think we aligned to only show html?

It might be worthwhile doing another run-through of all the examples across these components to make sure we only have the html examples displaying.

mcvinci · 2026-02-24T00:51:03Z

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

          {
            description:
-              'Shows a URL field in a disabled state, displaying a pre-filled URL that cannot be edited by the user.',
+              'Display a URL that users can view but not change. This example shows a disabled field with a pre-filled value that prevents editing.',


I think there might be a misplaced modifier here.

"That prevents editing" is meant to describe the disabled field, but it's attached to "a pre-filled value", making it sound like the value is what prevents editing.

Perhaps: "This example shows a pre-filled, disabled field that prevents editing."? Not wedded to that suggestion though!

SteveSill

Hey! Great work on these. I added some suggestions + comments andor/questions.

I also took a dive through the code behind these. We might need to follow up on these once the GSD project ends.

Some findings:

Code review (.html + .jsx example files)

MoneyField

default.html: Uses placeholder prop -- not listed in Polaris skill for s-money-field. Verify this prop exists.

basic-field.html: Has both value="29.99" and error="Product cost is required" -- showing an error on a field that already has a value is contradictory.

validation-example.jsx: Uses onInput event -- verify this is a valid event for s-money-field. Also uses e.currentTarget.max and e.currentTarget.min which assumes DOM properties exist on the web component.

PasswordField

password-strength-validation.jsx vs with-password-strength-requirements.html: The JSX is dynamic (checks in real-time), the HTML is static (hardcoded checklist). The doc.ts has two separate descriptions for these, but the HTML version (L113) says "static checklist" while the JSX version (L131) says "real-time validation." These are the same example in two different states. Is it supposed to be that way?

disabled-switch.html: Uses checked="true" and disabled="true" as string attributes. For Polaris web components, boolean attributes should be just checked and disabled without ="true". Verify whether string booleans work.

Select

with-error-state.html: Country names not capitalized ("United states", "United kingdom"). Should be "United States", "United Kingdom".

with-option-groups.html: Same capitalization issue ("North america", "United states", "Asia pacific").

Switch

disabled-switch.html: Uses checked="true" and disabled="true" as string values instead of boolean attributes.

form-integration.html: Uses a raw <form> element. Polaris may have its own form pattern. The description says "batch submission with a save action" but there's no submit button in the code.

URLField

with-default-value.html: Wrapped in s-stack but contains only one child. Unnecessary wrapper.

default.html: placeholder="https://shopify.com/partner" -- uses a real Shopify URL as placeholder. Use https://example.com per style guide. I'd double check if this applies here tho'

SteveSill · 2026-02-19T23:17:57Z

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

          {
            description:
-              'Demonstrates a simple money field with a label, initial value, and numeric constraints.',
+              'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range. Click to interact with the preview.',


Hey! Nice work on these descriptions!

Few quick suggestions:

All of the example descriptions, second sentence:

"This example shows..."

We could change the verb to match what the code is actually doing. Few examples from one of my branches:

"This example maps order states to corresponding tones..."

"This example collects a warehouse SKU and location assignment..."

"This example wraps content in a Box with padding..."

"This example pairs a base-sized indicator with a status message..."

SteveSill · 2026-02-19T23:23:10Z

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

+              title: 'Validate password strength',
+              tabs: [
+                {
+                  code: './examples/password-strength-validation.jsx',


Do you have these files in a different PR? I'm getting build errors, so I can't tophat them. I think it relates to these ./examples/ links. Can't find these in the repo.

I see it for these:

PasswordField | ./examples/password-strength-validation.jsx
Select | ./examples/handle-selection-change.jsx
Switch | ./examples/toggle-with-feedback.jsx
URLField | ./examples/validate-url-input.jsx

SteveSill · 2026-02-20T01:33:43Z

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

          {
            description:
-              'Demonstrates a password field with dynamic password strength validation, showing real-time feedback on password complexity requirements.',
+              'Show users exactly what their password needs. This example shows a static checklist of requirements like character length and case requirements. Click to interact with the preview.',


"Show users exactly what their password needs." This sounds a bit off to me. I don't think a password needs something? 😄

Something like: "Display a password requirements checklist alongside the field."

"static checklist" -- the HTML version is static, but the JSX version is dynamic. Mismatch.

SteveSill · 2026-02-24T00:31:59Z

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

  defaultExample: {
-    image: 'moneyfield-default.png',
+    description:
+      'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details. Click to interact with the preview.',


Just assuming "Click to interact with the preview" is being removed?

Could also say something like "Set a regional product price with placeholder text and helper details."

SteveSill · 2026-02-24T00:34:14Z

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

          {
            description:
-              'Demonstrates a simple money field with a label, initial value, and numeric constraints.',
+              'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range. Click to interact with the preview.',


'Guide users' is a bit awkward for me. What are we guiding them to?

SteveSill · 2026-02-24T00:45:17Z

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

          {
            description:
-              'Select dropdown with helpful placeholder text guiding category selection.',
+              'Guide users before they make a selection. This example shows placeholder text that describes what the user should choose. Click to interact with the preview.',


What are we guiding users to?

SteveSill · 2026-02-24T00:46:13Z

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

          {
            description:
-              'Select dropdown with sort icon for filtering order management views.',
+              'Visually indicate the purpose of a select field. This example shows a sort icon that signals filtering functionality. Click to interact with the preview.',


"Visually indicate" feels a bit vague to me.

SteveSill · 2026-02-24T00:47:13Z

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

  ],
  defaultExample: {
+    description:
+      'Give users a clear way to turn a feature on or off. This example shows a labeled toggle switch for enabling a preference.',


Restates the component definition ("Give users a clear way to toggle options on or off" is the Polaris description)

"shows a labeled toggle switch" - this one should be pretty clear from the code.

SteveSill · 2026-02-24T00:48:45Z

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

          {
            description:
-              'Multiple switches within a form for notification preferences submission. This example illustrates how switches can be used together in a form to allow merchants to configure multiple related settings simultaneously.',
+              'Apply changes instantly without a save button. This example shows switches arranged in a panel where each toggle takes effect immediately.',


"Apply changes instantly" -- is that what the code does? The code has a s-stack with settings and a display area showing current values. Not "instant" I don't think. iit's reactive state.

SteveSill · 2026-02-24T00:56:09Z

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

          {
            description:
-              'Shows a URL field in a disabled state, displaying a pre-filled URL that cannot be edited by the user.',
+              'Display a URL that users can view but not change. This example shows a disabled field with a pre-filled value that prevents editing.',


Almost identical to L77-78 above. Two examples showing essentially the same thing (read-only vs disabled) with nearly identical descriptions.

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

Doc file updates (MoneyField, PasswordField, Select, Switch, URLField): - Replace "This example shows" with specific verbs (pairs, configures, displays, groups, etc.) - Fix awkward phrasing in descriptions - Clarify readOnly vs disabled behavior in URLField examples - Update password requirements checklist description HTML example fixes: - Use boolean attributes without ="true" (checked, disabled, required) - Fix country/region capitalization (United States, North America, etc.) - Remove contradictory value from MoneyField error example - Add submit button to Switch form-integration example - Remove unnecessary s-stack wrapper from URLField example - Change placeholder to example.com in URLField Co-authored-by: Cursor <cursoragent@cursor.com>

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

sordaz00 changed the title ~~Improve example descriptions for MoneyField, PasswordField, Select, Switch, URLField~~ Improve examples for MoneyField, PasswordField, Select, Switch, URLField Feb 19, 2026

mcvinci mentioned this pull request Feb 19, 2026

Improve examples for components Image Thumbnail #3927

Open

2 tasks

mcvinci reviewed Feb 20, 2026

View reviewed changes

sordaz00 force-pushed the uiext-batch1-descriptions branch from 060a59f to 3d64377 Compare February 23, 2026 22:11

sordaz00 and others added 2 commits February 23, 2026 17:53

Fix prettier formatting errors (curly quotes)

6a3bd35

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

sordaz00 force-pushed the uiext-batch1-descriptions branch from 3d64377 to 6a3bd35 Compare February 23, 2026 23:53

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

Remove references to non-existent JSX example files

5b2b9ee

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

mcvinci approved these changes Feb 24, 2026

View reviewed changes

SteveSill approved these changes Feb 24, 2026

View reviewed changes

sordaz00 and others added 4 commits February 24, 2026 06:50

Remove JSX tabs, collapse to HTML-only examples

c6057f2

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

Remove 'Click to interact with the preview' from descriptions

1cb1874

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

Fix misplaced modifier in URLField description

0d002ee

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

sordaz00 merged commit 1d79307 into 2026-01 Feb 24, 2026
6 checks passed

	'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details. Click to interact with the preview.',
	'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details.',

	'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range. Click to interact with the preview.',
	'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range.',

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!

github-actions bot commented Feb 18, 2026

Uh oh!

mcvinci left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SteveSill left a comment

Choose a reason for hiding this comment

Code review (.html + .jsx example files)

MoneyField

PasswordField

Select

Switch

URLField

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sordaz00 commented Feb 18, 2026 •

edited

Loading

mcvinci left a comment •

edited

Loading