---
title: "Polaris design system: designing a Shopify app that feels native"
description: "How to design an embedded Shopify app with Polaris: what to follow exactly, where to adapt, what to avoid, and how App Home and App Bridge fit together."
topic: "Design process and tickets"
date: 2026-10-13
updated: 2026-10-13
author: "Geetansh Saini"
url: https://www.geeetansh.com/guides/polaris-app-design
tags: ["polaris", "shopify apps", "design systems"]
---
# Polaris design system: designing a Shopify app that feels native

**In short:** Polaris is Shopify's design system for apps, and in its current form it is a library of web components that render inside your app's App Home iframe, while App Bridge draws the pieces of the admin around it: the navigation, the title bar, the save bar. Follow Polaris exactly for navigation, page structure, forms and index tables, because merchants move between your app and the admin all day and notice every difference. Adapt only where your app's core object has no equivalent in the admin, and build that piece from Polaris primitives so it still reads as Shopify.

## What is Polaris, and how does it relate to App Home and App Bridge?

Three names, three jobs. Shopify's [App Home reference](https://shopify.dev/docs/api/app-home) describes App Home as your app's dedicated space in the Shopify admin, where it renders its UI in an iframe using web components, and says Polaris components are built on the Web Components standard. App Bridge is the JavaScript SDK your app uses to talk to the admin, and its own web components add elements outside your iframe, such as the title bar and the navigation menu.

| Piece | What it is | What you design with it |
| --- | --- | --- |
| Polaris web components | Buttons, fields, tables, cards, badges, modals that match the admin | Everything inside the page |
| App Home | The iframe in the admin where your app lives | The page itself |
| App Bridge | The SDK that connects the iframe to the admin, plus its web components | Navigation, title bar, breadcrumbs, save bar, full-screen app window |

Two recent changes matter. The old polaris.shopify.com now redirects to shopify.dev, and the App Home docs, patterns and references are written for the web components. If your app was built on the React package, nothing I have read says it is deprecated, but every new pattern Shopify publishes for App Home is for the web components, so that is where I design. And there are now two ways to build App Home: Shopify's build docs recommend the iframe model for most apps and reserve the UI extension model for custom-distribution apps with no server-side logic. If you are shipping to the App Store, you are designing for the iframe.

One distinction to keep straight. Shopify's [app design guidelines](https://shopify.dev/docs/apps/design) recommend Polaris for embedded apps rather than require it: the wording is that Shopify recommends using the components and best practices of Polaris. The [Built for Shopify requirements](https://shopify.dev/docs/apps/launch/built-for-shopify/requirements) go further for apps that want the badge: your app generally looks and behaves like the Shopify admin, and should use App Bridge where appropriate. The guidelines are advice, the badge requirements are rules, and the fastest way to meet both is the same.

## What should you follow exactly?

Four areas where I do not deviate, because merchants learned them from the admin.

### Navigation

Shopify's [navigation guidelines](https://shopify.dev/apps/design-guidelines/navigation) say the app nav lives in the admin sidebar on desktop and in the header on Shopify mobile, drawn by the App Bridge app nav component, not by your page. The seventh item and above are truncated into a View more button, so plan for six at most. Use nouns, not verbs: Affiliates, Payouts, Settings, not Manage affiliates. Do not repeat the nav inside the page body, and do not put main navigation in the page header, which the guidelines reserve for in-page actions. Use tabs sparingly for secondary navigation, and never let them wrap. Merchants should be able to go back without the browser button, so the title bar carries breadcrumbs or a Back action. Last, do not send merchants outside the admin for key actions or primary workflows.

### Page structure

Shopify's [App Home page patterns](https://shopify.dev/docs/api/app-home/patterns) give four templates, and almost every screen in an e-commerce app is one of them.

| Template | Shopify's purpose | In an affiliate app |
| --- | --- | --- |
| Homepage | Quick access to key information and actions | Dashboard: affiliate revenue, pending payouts, setup guide |
| Index | Manage collections of resources and act on them | The affiliates table, the payouts table |
| Details | View and edit one resource in a dual-column layout | One affiliate: profile, commission, orders, notes |
| Settings | Configure how the app behaves | Commission defaults, payout schedule, integrations |

The title bar, set through App Bridge, holds the page title, the primary and secondary actions, and breadcrumbs. I hold to one primary action per page. If it seems to need two, it is two pages.

### Forms

The Built for Shopify requirements say form inputs should generally be saved using the App Bridge contextual save bar, the admin's own Save and Discard bar. Design every settings and details page around it: no Save button at the bottom of the card, no unsaved-changes modal of your own. The settings template pairs it with a modal to confirm destructive actions and a toast to confirm the save. Use the typed fields Polaris provides, the money field for commission amounts, the email field for affiliate contacts, the URL field for destination links, the date picker for payout windows, because their validation and formatting match the admin.

### Index tables

The index table composition in the same patterns is the answer for any list merchants manage: a scannable list with search, filtering, sorting and bulk actions, with checkboxes for bulk selection, row actions on hover, pagination for large data sets, and a modal to confirm destructive bulk actions. Your affiliates list, creators list and payouts list should all be this component with different columns. The design work is choosing the columns, default sort, saved filters and bulk actions a merchant with 2,000 affiliates needs.

## Where should you adapt?

Polaris describes Shopify's objects: products, orders, customers, discounts. Your app's core object is something else, an affiliate, a creator, a commission rule, a campaign. That is where adaptation belongs, and my rule is to adapt the content, not the structure.

- Use the index and details templates for your objects, but choose the columns, badges and status vocabulary for them. An affiliate is Active, Pending or Declined, shown with the badge component.
- Use the compositions for the jobs they name. The setup guide composition is a checklist with progress tracking, the right shape for first-week onboarding. The metrics card belongs at the top of the homepage. The account connection composition is for connecting Klaviyo or a payout provider. [Onboarding checklist design](/guides/onboarding-checklist-design) covers what the setup guide should contain.
- Use the admin's nouns for the admin's objects and your nouns for yours. "Orders" means Shopify orders. If you mean orders attributed to an affiliate, say that.
- Adapt density with columns and filters, not with smaller type or tighter spacing. A merchant with 2,000 affiliates needs a good default filter more than a denser table.

## What should you avoid?

- Restyled buttons and brand colours in the admin. The Built for Shopify requirements use Polaris buttons styled to not match the admin as their example of what fails the "familiar" requirement.
- Your own navigation inside the page. The nav is the admin's job through App Bridge. A sidebar inside the iframe gives the merchant two sidebars.
- The deprecated Polaris full-screen bar for modals. The badge requirements say not to use it and point to the app window and page components instead.
- Embedded external pages, or primary workflows that leave the admin. The requirements say apps should not embed external web pages and that merchants should be able to complete primary workflows inside the admin.
- Marketing-site typography, illustrations and animation. Merchants are there to do a task between two other tasks.
- Designing the whole app in Figma from an old kit and handing it off. The web components decide spacing, states and behaviour, and a drawing of them drifts. I design structure in Figma and check the real components in the browser before handoff, which also answers most of the questions a [developer-ready handoff](/guides/development-ready-design) must answer.

## How do you design a screen Polaris has no component for?

A tiered commission builder. An affiliate link preview. A creator pipeline with stages. A payout batch of 200 rows that can partially fail. None are in Polaris, and that is fine. Polaris is a vocabulary, not a template for your product. The order I work in:

1. Check the compositions first. Many "custom" screens turn out to be a callout card, a metrics card or a resource list with different content.
2. Find the admin's analogue. A commission rule builder is close to discount creation. A campaign is close to a marketing activity. A payout batch is close to a bulk fulfilment. Borrow the structure, change the nouns.
3. Compose from primitives. Page, section, box, stack and grid give you the layout, and heading, text, badge and banner give you the hierarchy. Keep every input a native Polaris field. The custom part, say a row-based tier editor, is usually one small region inside an otherwise standard details page.
4. Give the custom region the same states as everything else: empty, loading, error, partial, success.
5. If the merchant is customising something visual, show the result as they change it. The badge requirements say merchants must be able to see their changes in real time. A referral widget editor without a live preview does not pass.
6. Run the result through the same [design QA checklist](/guides/design-qa-checklist) as a standard page, with extra attention to keyboard behaviour, because that is what hand-built components lose first.

I spent two years designing a Shopify app from inside the admin, after close to two years in its support queue. Merchants' public reviews repeatedly call the app simple, and my view is that most of that came from following Polaris closely and keeping the custom parts small.

## Where to start

1. Open your app next to the admin's Orders page and list every place the two differ in navigation, title bar, save behaviour or table behaviour. That is your follow-exactly backlog.
2. Map each existing screen to one of the four templates. A screen that fits none is either a composition or a genuine custom region, and now you know which.
3. Move every save to the contextual save bar and remove your own Save buttons and unsaved-changes dialogs.
4. For the one custom screen you need most, write down its admin analogue and its five states before drawing anything.
5. Read the Built for Shopify design and performance requirements once, end to end, and decide whether you are aiming for the badge.

## Frequently asked questions

### Do I have to use Polaris to be listed in the Shopify App Store?

Not by the listing requirements I have read. Shopify's app design guidelines recommend Polaris for embedded apps. The Built for Shopify badge is stricter: your app should generally look and behave like the Shopify admin, use the latest App Bridge, and use the contextual save bar for forms, and Polaris is the practical way to meet that.

### Should I still design in Figma if the components live in code?

Yes, for flows, structure and the custom regions, because Figma is faster for exploring. But check every standard component in the browser before handoff. The web components carry their own spacing and states, and a drawn copy of them is where most handoff questions come from.

### What about apps built on Polaris React?

Nothing I have read on shopify.dev says the React package is deprecated, but the App Home references and page patterns are written for the web components, and the design guidance follows them. If you are starting a new screen, design it for the web components and let engineering decide the migration path.

### Does Polaris handle mobile for me?

Partly. The components are responsive and the app nav moves into the header on Shopify mobile. But Shopify's design guidelines say most online store traffic is on mobile and to design for mobile first, and the choices about which table columns hide and which actions move into a menu are still yours to make and to test.