Polaris code example updates

[timtrevor-shopify]

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:
Button
ChoiceList
DateField
DatePicker
EmailField
NumberField
SearchField
TextArea
TextField

The following code examples have been removed and added:

Button
Removed example files:
toolbar-icon-buttons.html / .jsx — Redundant with the icon-only button example; same concept (icon-only + accessibilityLabel) repeated multiple times. The icon-only button example was updated to absorb the toolbar pattern.
navigation-to-admin-sections.html / .jsx — Redundant; just a combination of the "with icon" and "link buttons" examples with no new concept.
bulk-actions.html / .jsx — Redundant with the delete confirmation example; both showed a secondary + critical primary button pair.
product-save-form.html / .jsx — Redundant with form states and delete confirmation; the only new element was justifyContent="end", which is a layout concern rather than a button concept.

Updated example files:
icon-only-button.html / .jsx — Updated from a single icon-only button to a toolbar pattern with three icon-only buttons, absorbing the content from the removed toolbar-icon-buttons example.

ChoiceList
Removed example files:
multiple-choices-with-details.html / .jsx — Redundant with the "multiple selections" example; both demonstrated multiple + slot="details" with the same prop pattern.

Added example files:
disabled-state.html / .jsx — Added to fill a gap; no existing example covered the disabled prop.

DateField
Removed example files:
date-fields-with-validation.html / .jsx — Redundant with the "form integration" example; both showed date fields in a composite form with other elements.

DatePicker
No example files were added or removed.

EmailField
Removed example files:
basic-usage.html / .jsx — Redundant with the default example; the only unique prop was required, which is already demonstrated in other examples.
optional-field-with-placeholder.html / .jsx — Redundant with the default example; both used the same props (placeholder + details) with only different label text.

Added example files:
disabled-state.html / .jsx — Added to fill a gap; no existing example covered the disabled prop.

NumberField
Removed example files:
basic-usage.html / .jsx — Redundant with the default example; both showed the same props (min, max, step) with slightly different values.
multiple-examples.html / .jsx — Redundant composite that combined concepts already shown by the default and "with prefix and suffix" examples without introducing new props.

Added example files:
with-error-state.html / .jsx — Added to fill a gap; no existing example covered the error or required props.
disabled-and-read-only.html / .jsx — Added to fill a gap; no existing example covered the disabled or readOnly props.

SearchField
Removed example files:
basic-usage.html / .jsx — Redundant with the default example; both showed a search field with label and placeholder.

TextArea
Removed example files:
product-care-instructions.html / .jsx — Redundant with the "SEO meta description" example; both used details + placeholder + rows + autocomplete. The only difference was a larger rows value.

Added example files:
disabled-and-read-only.html / .jsx — Added to fill a gap; no existing example covered the disabled or readOnly props.

TextField
Removed example files:
basic-usage.html / .jsx — Redundant with the default example; the only unique prop was autocomplete="off".
required-field-with-validation.html / .jsx — Trivial single-prop example (required); the error messages example already demonstrates validation more thoroughly.

Added example files:
disabled-and-read-only.html / .jsx — Added to fill a gap; no existing example covered the disabled or readOnly props.

🎩

To TopHat these changes, checkout the branch PolarisCodeExampleUpdates 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

[github-actions]

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.

[chadwcarlson]

Few nits

[mcvinci]

Nice work, @timtrevor-shopify! I did a light skim, as I know @chadwcarlson already reviewed. ❤️

[SteveSill]

Hey @timtrevor-shopify - Nice work on these! I added a few questions / suggestions.

Also came across some odd things in the examples that we should verify:

Code review (.html + .jsx example files)

ChoiceList

with-error-state.html vs with-error-state.jsx: Different error messages. HTML: error="Product visibility cannot be hidden at this time". JSX: error="Please select an option". Also HTML has name="visibility" and selected on "Required" choice, JSX has neither.

• Files: ChoiceList/examples/with-error-state.html, ChoiceList/examples/with-error-state.jsx

TextArea

seo-meta-description-with-character-limit.jsx: Uses max-length={160} (kebab-case). In JSX context, this should be maxLength={160}. Verify whether Polaris web components accept kebab-case attributes in JSX/Preact.

• File: TextArea/examples/seo-meta-description-with-character-limit.jsx

[timtrevor-shopify]

Thanks @SteveSill, some great catches in the code example there. Appreciate the thoroughness!