ux-polaris-antipatterns

Polaris UI Anti-Patterns (v12+)

A field guide to the 20 most common ways Shopify app teams break the Polaris contract — and the exact fix for each. Use this when reviewing a PR, writing a new screen, or auditing an app pre-submission for Built for Shopify.

The principle behind every rule: Shopify admin is a shared design surface. Merchants have already learned its patterns. The closer your app feels to the rest of admin, the higher your install-to-activation rate. The further you drift, the more your app feels like a third-party graft — and the more support tickets you get from confused merchants.

---

1. When to use

Pull this skill in when you are:

• Reviewing a pull request that touches @shopify/polaris components
• Writing a new screen and unsure whether a custom component is warranted
• Migrating from Polaris 10 or 11 to 12+
• Preparing an app for App Store submission or Built for Shopify certification
• Debugging "why does our app look off-brand?" complaints
• Diagnosing accessibility audit failures
• Deciding between <Modal>, <Banner>, <Toast>, or inline error
• Choosing between custom CSS and design tokens

If the user mentions Polaris, Stack, BlockStack, design tokens, --p-color-*, className on Polaris components, Modal overuse, or "this feels off-brand" — trigger this skill.

---

2. The 20 anti-patterns, ranked by severity

Ranked by how badly each one degrades the merchant experience (1 = catastrophic, 20 = nit). Fixes are in the "do this instead" column.

#	Anti-pattern	Severity	Do this instead
1	Using <Stack> / <LegacyStack> / <VerticalStack> / <HorizontalStack>	Build-breaking on v12+	<BlockStack> (vertical) or <InlineStack> (horizontal). Run npx @shopify/polaris-migrator
2	Wrapping Polaris components in custom className for styling	High — most Polaris components do not accept className	Use the component's built-in props (tone, variant, padding, gap). For exceptions, use <Box> with token props
3	Hex codes (color: #008060) instead of design tokens	High — instantly off-brand on theme changes	var(--p-color-bg-fill-success) or a tone prop
4	Modal for non-blocking errors or confirmations	High — blocks the merchant; high abandonment	<Banner> for in-context info, <Toast> for transient confirmations, inline error for forms
5	Toast for errors that need explanation	High — disappears in 3s, easily missed	<Banner tone="critical"> with title + body + recovery action
6	Using tone="success" for neutral or informational	Medium — semantic noise	tone="info" for info, no tone for neutral
7	Using tone="critical" for warnings	Medium — desensitizes the merchant to real errors	tone="warning" for cautionary, tone="critical" only for destructive/error
8	Missing <FormLayout> around form fields	Medium — inconsistent spacing	Always wrap related fields in <FormLayout> inside <Form>
9	Blocking validation on every keystroke	Medium — feels hostile, breaks flow	Validate on blur or on submit; clear errors on next change
10	Missing helpText on non-obvious fields	Medium — drives support tickets	helpText describing format, examples, or constraints
11	Forgetting to import @shopify/polaris/build/esm/styles.css	High — entire app looks unstyled	Import once in the app root, before <AppProvider>
12	More than 2 filled/shaped buttons in one Card	Medium — destroys hierarchy	One primary, one secondary, rest as plain or inside <ActionList>
13	<IndexTable> on mobile without responsive plan	Medium — horizontal scroll hell on phones	Hide columns or switch to <ResourceList> below the mobile breakpoint
14	Modal sized larger than the mobile viewport	Medium — content clipped on phones	size="small" for mobile flows; never assume desktop
15	Icon-only buttons missing accessibilityLabel	Medium — screen readers see nothing	Always pass accessibilityLabel to icon-only <Button>
16	Error states relying on color alone	Medium — fails WCAG, fails colorblind users	Pair red border with text error message and icon
17	Importing old icon names (DeleteMinor, EditMajor)	Medium — works on v10–11, gone in v12+	Use new icon names (DeleteIcon, EditIcon)
18	Custom focus styles that override Polaris focus rings	Medium — keyboard users get lost	Leave focus rings alone, or use --p-focused tokens
19	Card with no padding wrapper	Low — content touches Card edge	<Box padding="400"> inside, or use <Card padding="400"> (v12+)
20	Mixing tone="subdued" with low-contrast text on top	Low — fails AA contrast	Don't stack subdued tones; use one level of de-emphasis