ux-polaris-antipatternslisted

# 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 th