Polaris code example updates for Action components by timtrevor-shopify · Pull Request #3944 · Shopify/ui-extensions

timtrevor-shopify · 2026-02-20T22:27:04Z

Background

As part of an overall update to the App Home / App Bridge docs, we're improving the titles and descriptions of code examples for Polaris components, as well as removing any redundant examples, and adding new examples for missing use cases.

Solution

This PR makes updates to the following component pages:
ButtonGroup
Clickable
ClickableChip
Link
Menu

The following code examples have been added and removed:

ButtonGroup
Removed example files:
basic-usage.html / .jsx — Redundant with the default example; both showed a Cancel + Save button pair using the primary-action and secondary-actions slots.
form-action-buttons.html / .jsx — Redundant with the default example; same Cancel + Save pattern with only the label text changed to "Save product".

Clickable
Removed example files:
basic-button-usage.html / .jsx — Redundant with the default example; showed a single clickable with border and padding, which is a strict subset of the default that already demonstrates two clickable elements with those same props.

ClickableChip
Removed example files:
multiple-chips-with-proper-spacing.html / .jsx — Redundant composite of concepts already covered individually by the color variants, icon/removable, and subdued/icon examples. The title focused on layout spacing which is an s-stack concern, not a ClickableChip concept.

Link
Removed example files:
links-with-auto-tone.html / .jsx — Redundant with "Basic Links in Paragraph"; both showed links inside a regular paragraph with no new concept.
links-in-banner-context.html / .jsx — Redundant with "Links in Banner"; same pattern of a link inside a banner, just a different tone value (warning vs info).
links-in-subdued-paragraph.html / .jsx — Redundant with "Links with Different Tones" which comprehensively covers links inheriting tone from six different paragraph tones.
critical-context-links.html / .jsx — Redundant with "Links with Different Tones" which includes a critical tone example among others.

Menu
Removed example files:
basic-menu.html / .jsx — Redundant with the default example; both showed a trigger button with three icon buttons in the menu.
menu-with-icons.html / .jsx — Redundant with the default example; the only new element was a caret-down icon on the trigger button, which didn't warrant a separate example.

Added example files:
icon-only-trigger.html / .jsx — Added to fill a gap; no existing example showed the common "three-dot menu" pattern where an icon-only button triggers the menu, which is one of the most frequent menu patterns in real apps.

🎩

To TopHat these changes, checkout the branch PolarisCodeExampleUpdates2 and run yarn docs:admin 2026-01.
In the shopify-dev repo, confirm the db/data/docs/templated_apis/app_home/generated_docs_data.json has been updated and run dev s for a local preview.

Checklist

I have 🎩'd these changes
I have updated relevant documentation

…. Basic Usage)

github-actions · 2026-02-20T22:27:55Z

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

Nice improvements, @timtrevor-shopify! I added a few suggestions, and happy to chat through any feedback, too.

mcvinci · 2026-02-21T00:12:40Z

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

-              ],
+        image: 'button-default.png',
+        description:
+          'Group related buttons together with a primary action and secondary options. This example shows a button group with a save button and a cancel button using the slot layout.',


I'm not sure if this is a locally previewing issue, or an actual issue, but I'm not seeing the html title in the codeblock, and the preview seems collapsed. Might be worthwhile double-checking?

Doesn't look like any of the default html files were added to this PR

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

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

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

…/Clickable.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

…Chip/ClickableChip.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

….doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Fionoble

Need to add the missing html files

SteveSill

Looking good @timtrevor-shopify ! Added a few suggestions to take a look at before merging.

Claude and I also did a quick pass on the example code. But I couldn't track down a PR with any examples in them. So I'll note them here:

Code review (.html + .jsx example files)

Link

links-with-different-tones.html vs .jsx: HTML labels don't match tones. HTML says "Neutral tone" for tone="success" and "Subdued tone" for tone="caution". JSX correctly says "Success tone" and "Caution tone".

Files: Link/examples/links-with-different-tones.html L6, Link/examples/links-with-different-tones.jsx L6

links-with-different-tones.html: Zero href attributes across all 6 <s-link> elements. Links without href don't navigate.

File: Link/examples/links-with-different-tones.html

links-with-language-attribute.html: No href attribute on the <s-link>.

File: Link/examples/links-with-language-attribute.html

default.html and default.jsx: On the base branch (not changed in this PR). HTML uses href="#beep", JSX uses href="javascript:void(0)". Both have typo "fufilling" (should be "fulfilling"). Worth flagging for whoever owns the base.

Files: Link/examples/default.html, Link/examples/default.jsx

menu-with-links-and-disabled-items.html vs .jsx: Different download button behavior. HTML: <s-button download href="javascript:void(0)"> (bare boolean download, placeholder href). JSX: <s-button download="sales-report.csv" href="/reports/sales-report.csv"> (filename + real path). HTML and JSX should match.

Files: Menu/examples/menu-with-links-and-disabled-items.html L8, Menu/examples/menu-with-links-and-disabled-items.jsx L9

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

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

+      },
+      {
+        description:
+          'Embed links within paragraph text so merchants can navigate to related content inline. This example shows two links inside a paragraph that inherit the surrounding text tone.',


The "basic-links-in-paragraph" example demonstrates inline links within a Paragraph. I'd consider adding a link to the Paragraph component in the description.

SteveSill · 2026-02-23T23:34:51Z

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

-              ],
+        image: 'button-default.png',
+        description:
+          'Group related buttons together with a primary action and secondary options. This example shows a button group with a save button and a cancel button using the slot layout.',


Do we define what a slot layout is on the page or code? Not sure what that is.

SteveSill · 2026-02-23T23:37:28Z

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

+      },
+      {
+        description:
+          'Add icons to grouped buttons to help merchants quickly identify each action. This example shows duplicate, archive, and delete buttons with icons.',


Suggested change

'Add icons to grouped buttons to help merchants quickly identify each action. This example shows duplicate, archive, and delete buttons with icons.',

'Add icons to grouped buttons to identify each action. This example shows duplicate, archive, and delete buttons with icons.',

I'm not fond of my rewrite. But I don't think we need to say 'help merchants quickly".

SteveSill · 2026-02-23T23:40:37Z

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

+      },
+      {
+        description:
+          'Embed a clickable component within a content section to provide an interactive action alongside text. This example shows a styled clickable button inside a box with a heading and description.',


"to provide an interactive action alongside text" feels a lttle vague to me. We could be more specific.

SteveSill · 2026-02-23T23:42:07Z

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

-                },
-              ],
+        description:
+          'Create an interactive chip that merchants can click to trigger an action. This example shows a clickable chip component with default styling.',


"that merchants can click to trigger an action" -- restates what "interactive" and "clickable" mean. The second sentence isn't adding much besides 'default styling'.

SteveSill · 2026-02-23T23:45:24Z

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

+      },
+      {
+        description:
+          'Add an icon and a remove button so merchants can see status at a glance and dismiss the chip. This example shows a removable chip with a check circle icon in the graphic slot.',


Suggested change

'Add an icon and a remove button so merchants can see status at a glance and dismiss the chip. This example shows a removable chip with a check circle icon in the graphic slot.',

'Add an icon and a remove button so merchants can see the status and dismiss the chip. This example shows a removable chip with a check circle icon in the graphic slot.',

SteveSill · 2026-02-23T23:57:53Z

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

-              ],
+        image: 'link-default.png',
+        description:
+          'Add an inline link to let merchants navigate to another page. This example shows a basic text link with an `href` property.',


The code behind this example has a typo.

Current: fufilling orders
Fix: fulfilling orders

We could also show it in context:

<s-paragraph> Your product catalog is empty. Start by <s-link href="javascript:void(0)">adding your first product</s-link> or <s-link href="javascript:void(0)">importing existing inventory</s-link>. </s-paragraph>

<s-paragraph> Your product catalog is empty. Start by <s-link href="javascript:void(0)">adding your first product</s-link> or <s-link href="javascript:void(0)">importing existing inventory</s-link>. </s-paragraph>

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

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

+      },
+      {
+        description:
+          'Configure links to inherit the tone of their parent paragraph to match the surrounding context. This example shows links inside paragraphs with six different tones.',


"Configure links to inherit" is passive/abstract. Could rephrase this one.

Suggested change

'Configure links to inherit the tone of their parent paragraph to match the surrounding context. This example shows links inside paragraphs with six different tones.',

'Configure links that inherit the tone of their parent paragraph and match the surrounding context. This example shows links inside paragraphs with six different tones.',

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

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

+      },
+      {
+        description:
+          'Organize menu items into labeled groups so merchants can quickly find related actions. This example shows two sections with headings separating product actions from export options.',


Suggested change

'Organize menu items into labeled groups so merchants can quickly find related actions. This example shows two sections with headings separating product actions from export options.',

'Organize menu items into labeled groups so merchants can find related actions. This example shows two sections with headings separating product actions from export options.',

chadwcarlson · 2026-02-24T15:37:21Z

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

+      },
+      {
+        description:
+          'Use the `color` property to visually distinguish chips by importance or category. This example shows three chips with base, subdued, and strong color variants.',


Suggested change

'Use the `color` property to visually distinguish chips by importance or category. This example shows three chips with base, subdued, and strong color variants.',

'Use the `color` property to visually distinguish chips by importance or category. This example shows three chips with `base`, `subdued`, and `strong` color variants.',

chadwcarlson · 2026-02-24T15:39:55Z

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

+      },
+      {
+        description:
+          'Configure links to inherit the tone of their parent paragraph to match the surrounding context. This example shows links inside paragraphs with six different tones.',


Suggested change

'Configure links to inherit the tone of their parent paragraph to match the surrounding context. This example shows links inside paragraphs with six different tones.',

'Configure links that inherit the tone of their parent paragraph and match the surrounding context. This example shows links inside paragraphs with six different tones.',

timtrevor-shopify added 7 commits February 20, 2026 14:22

Flatten examples into a single array removing default and groups (e.g…

4f8194b

…. Basic Usage)

Delete redundant examples from ButtonGroup page

980676b

Delete redundant examples from Clickable

2a9cada

Delete redundant examples from ClickableChip

263ff4a

Delete redundant code examples for Link component

7bb68f5

Delete redundant code examples and add new example for Menu component

341d721

Update titles and descriptions for code examples

9870327

timtrevor-shopify force-pushed the PolarisCodeExampleUpdates2 branch from abf6706 to 9870327 Compare February 20, 2026 22:27

timtrevor-shopify requested review from Fionoble, chadwcarlson, davejcameron, mcvinci and sordaz00 February 20, 2026 22:28

mcvinci approved these changes Feb 21, 2026

View reviewed changes

timtrevor-shopify and others added 8 commits February 20, 2026 16:28

Update packages/ui-extensions/src/surfaces/admin/components/Clickable…

ec9f0a7

…/Clickable.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Clickable…

72f6890

…/Clickable.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Clickable…

32b1d11

…/Clickable.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Clickable…

0bf22fc

…/Clickable.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Clickable…

a766839

…Chip/ClickableChip.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Clickable…

f7ad445

…Chip/ClickableChip.doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Link/Link…

306e8ea

….doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Update packages/ui-extensions/src/surfaces/admin/components/Link/Link…

86dcf48

….doc.ts Co-authored-by: Michelle Vinci <michelle.vinci@shopify.com>

Fionoble requested changes Feb 23, 2026

View reviewed changes

SteveSill approved these changes Feb 24, 2026

View reviewed changes

chadwcarlson approved these changes Feb 24, 2026

View reviewed changes

	'Add icons to grouped buttons to help merchants quickly identify each action. This example shows duplicate, archive, and delete buttons with icons.',
	'Add icons to grouped buttons to identify each action. This example shows duplicate, archive, and delete buttons with icons.',

	'Add an icon and a remove button so merchants can see status at a glance and dismiss the chip. This example shows a removable chip with a check circle icon in the graphic slot.',
	'Add an icon and a remove button so merchants can see the status and dismiss the chip. This example shows a removable chip with a check circle icon in the graphic slot.',

	'Configure links to inherit the tone of their parent paragraph to match the surrounding context. This example shows links inside paragraphs with six different tones.',
	'Configure links that inherit the tone of their parent paragraph and match the surrounding context. This example shows links inside paragraphs with six different tones.',

	'Organize menu items into labeled groups so merchants can quickly find related actions. This example shows two sections with headings separating product actions from export options.',
	'Organize menu items into labeled groups so merchants can find related actions. This example shows two sections with headings separating product actions from export options.',

	'Use the `color` property to visually distinguish chips by importance or category. This example shows three chips with base, subdued, and strong color variants.',
	'Use the `color` property to visually distinguish chips by importance or category. This example shows three chips with `base`, `subdued`, and `strong` color variants.',

Comments

Conversation

timtrevor-shopify commented Feb 20, 2026

Background

Solution

🎩

Checklist

Uh oh!

github-actions bot commented Feb 20, 2026

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Fionoble left a comment

Choose a reason for hiding this comment

Uh oh!

SteveSill 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

Code review (.html + .jsx example files)

Link

Menu

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

SteveSill left a comment •

edited

Loading