Shopify Polaris Design System
Before writing code
Fetch live docs:
- Fetch
https://polaris.shopify.com/ for Polaris component documentation and examples
- Web-search
site:shopify.dev polaris app design guidelines for design guidelines
- Web-search
site:shopify.dev polaris web components migration for migration status
- Web-search
site:polaris.shopify.com components for current component APIs and props
- Web-search
site:polaris.shopify.com tokens for current design token values
What Is Polaris
Shopify's design system for building admin app UIs:
- Component library with consistent Shopify admin look and feel
- Design tokens for colors, spacing, typography
- App Design Guidelines for embedded apps
- Accessibility-first design patterns
IMPORTANT: Polaris React is in maintenance mode. Shopify is transitioning to Polaris Web Components. Check current migration status before choosing components.
Component Categories
Layout
Page — top-level page container with title and actions
Layout — two-column annotated layout
Card — content container with sections
Box — flexible container with spacing/color
InlineStack — horizontal layout
BlockStack — vertical layout
Divider — visual separator
Grid — CSS grid layout
Actions
Button — primary, secondary, destructive actions
ButtonGroup — group related actions
ActionList — dropdown menu of actions
Popover — dropdown container
Navigation
Navigation — sidebar navigation
Tabs — tabbed content
Pagination — page navigation
Forms
TextField — text input
Select — dropdown select
Checkbox — boolean input
RadioButton — single selection
ChoiceList — radio/checkbox groups
DatePicker — date selection
DropZone — file upload
Form — form container
FormLayout — form field arrangement
Feedback
Banner — info, success, warning, critical messages
Toast — temporary notifications
Badge — status indicators
Spinner — loading state
SkeletonPage / SkeletonBodyText — loading placeholders
ProgressBar — progress indicator
Data Display
IndexTable — resource list with bulk actions (primary list component)
DataTable — simple tabular data
ResourceList — list of resources (legacy, prefer IndexTable)
ResourceItem — individual resource entry
DescriptionList — key-value pairs
EmptyState — no-content placeholder
Thumbnail — small image
Overlays
Modal — dialog overlay
Sheet — side panel (deprecated in React, check Web Components)
Fetch live docs for current component APIs and props — components are updated frequently. Always check https://polaris.shopify.com/components before using any component.
Minimal Usage Patterns
Page with Card Layout
// Pattern: standard Polaris page layout
// Fetch live docs for current Page, Card, and BlockStack props
<Page title="Products" primaryAction={{ content: "Add product", onAction: handleAdd }}>
<Layout>
<Layout.Section>
<Card>
<BlockStack gap="300">
<Text variant="headingMd">Product List</Text>
{/* IndexTable or content here */}
</BlockStack>
</Card>
</Layout.Section>
<Layout.Section variant="oneThird">
<Card>
<Text variant="headingMd">Filters</Text>
</Card>
</Layout.Section>
</Layout>
</Page>
Form Pattern
// Pattern: form with validation
// Fetch live docs for current TextField, Select, and Form props
<Form
<FormLayout>
<TextField label="Product name" value={name} autoComplete="off" />
<Select label="Status" options={statusOptions} value={status} />
<Button submit variant="primary">Save</Button>
</FormLayout>
</Form>
Feedback Pattern
// Pattern: Banner for persistent messages, Toast for transient
<Banner title="Order shipped" tone="success"
<p>Tracking number: {trackingNumber}</p>
</Banner>
// Toast via App Bridge (not Polaris component in embedded apps)
shopify.toast.show("Product saved");
Design Tokens
Consistent design values used across all Polaris components:
| Category |
Token Pattern |
Examples |
| Colors |
--p-color-bg-*, --p-color-text-* |
--p-color-bg-surface, --p-color-text-critical |
| Spacing |
--p-space-* |
--p-space-100 (4px) through --p-space-1200 (48px) |
| Typography |
--p-font-size-*, --p-font-weight-* |
--p-font-size-300, --p-font-weight-bold |
| Border |
--p-border-radius-* |
--p-border-radius-200 |
| Shadow |
--p-shadow-* |
--p-shadow-100, --p-shadow-200 |
Fetch live docs for current token values and names — token naming conventions change across Polaris versions. Check https://polaris.shopify.com/tokens.
@shopify/draggable
Shopify's drag-and-drop library:
- Draggable, Sortable, Swappable, Droppable
- Touch and mouse support
- Accessible with keyboard support
- Used for reorderable lists, kanban boards, custom interfaces
Fetch live docs: Web-search site:github.com shopify draggable for current API and examples.
App Design Guidelines
Embedded Apps Must
- Use Polaris components for consistent admin experience
- Use App Bridge for navigation and titles
- Follow Shopify's color, typography, and spacing tokens
- Implement loading states (skeleton screens)
- Handle errors with Banner components
- Support responsive layouts
Do NOT
- Use custom CSS that overrides Polaris styles
- Build custom navigation chrome (use App Bridge)
- Use non-Polaris modals or toasts in embedded apps
- Mix design systems (e.g., Material UI with Polaris)
Accessibility
Polaris components are built with accessibility:
- ARIA attributes included by default
- Keyboard navigation support
- Focus management in modals and popovers
- Color contrast meets WCAG AA
- Screen reader announcements for dynamic content
Fetch live docs: Web-search site:polaris.shopify.com accessibility for current accessibility guidelines and component-specific a11y notes.
Best Practices
- Check Polaris Web Components status before starting — prefer Web Components if available
- Use
IndexTable for resource lists (not DataTable for CRUD interfaces)
- Use
Banner for persistent messages, Toast (via App Bridge) for transient confirmations
- Use skeleton components (
SkeletonPage, SkeletonBodyText) for loading states
- Follow the
Page → Layout → Card → content hierarchy
- Use
BlockStack and InlineStack for layout (not CSS flex/grid directly)
- Apply design tokens for custom styles instead of hardcoded values
- Test keyboard navigation and screen reader output
- Always fetch live docs for component props before implementation — APIs change frequently
Fetch the Polaris documentation for exact component APIs, design tokens, prop types, and Web Components migration status before implementing.
1---2name: shopify-polaris3description: Build Shopify app UIs with Polaris — component categories, Web Components transition, React legacy components, App Design Guidelines, accessibility, @shopify/draggable, and design tokens. Use when building Shopify admin app interfaces.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/shopify-polaris7---89# Shopify Polaris Design System1011## Before writing code1213**Fetch live docs**:141. Fetch `https://polaris.shopify.com/` for Polaris component documentation and examples152. Web-search `site:shopify.dev polaris app design guidelines` for design guidelines163. Web-search `site:shopify.dev polaris web components migration` for migration status174. Web-search `site:polaris.shopify.com components` for current component APIs and props185. Web-search `site:polaris.shopify.com tokens` for current design token values1920## What Is Polaris2122Shopify's design system for building admin app UIs:23- Component library with consistent Shopify admin look and feel24- Design tokens for colors, spacing, typography25- App Design Guidelines for embedded apps26- Accessibility-first design patterns2728> **IMPORTANT:** Polaris React is in maintenance mode. Shopify is transitioning to Polaris Web Components. Check current migration status before choosing components.2930## Component Categories3132### Layout33- `Page` — top-level page container with title and actions34- `Layout` — two-column annotated layout35- `Card` — content container with sections36- `Box` — flexible container with spacing/color37- `InlineStack` — horizontal layout38- `BlockStack` — vertical layout39- `Divider` — visual separator40- `Grid` — CSS grid layout4142### Actions43- `Button` — primary, secondary, destructive actions44- `ButtonGroup` — group related actions45- `ActionList` — dropdown menu of actions46- `Popover` — dropdown container4748### Navigation49- `Navigation` — sidebar navigation50- `Tabs` — tabbed content51- `Pagination` — page navigation5253### Forms54- `TextField` — text input55- `Select` — dropdown select56- `Checkbox` — boolean input57- `RadioButton` — single selection58- `ChoiceList` — radio/checkbox groups59- `DatePicker` — date selection60- `DropZone` — file upload61- `Form` — form container62- `FormLayout` — form field arrangement6364### Feedback65- `Banner` — info, success, warning, critical messages66- `Toast` — temporary notifications67- `Badge` — status indicators68- `Spinner` — loading state69- `SkeletonPage` / `SkeletonBodyText` — loading placeholders70- `ProgressBar` — progress indicator7172### Data Display73- `IndexTable` — resource list with bulk actions (primary list component)74- `DataTable` — simple tabular data75- `ResourceList` — list of resources (legacy, prefer IndexTable)76- `ResourceItem` — individual resource entry77- `DescriptionList` — key-value pairs78- `EmptyState` — no-content placeholder79- `Thumbnail` — small image8081### Overlays82- `Modal` — dialog overlay83- `Sheet` — side panel (deprecated in React, check Web Components)8485> **Fetch live docs** for current component APIs and props — components are updated frequently. Always check `https://polaris.shopify.com/components` before using any component.8687## Minimal Usage Patterns8889### Page with Card Layout9091```tsx92// Pattern: standard Polaris page layout93// Fetch live docs for current Page, Card, and BlockStack props94<Page title="Products" primaryAction={{ content: "Add product", onAction: handleAdd }}>95 <Layout>96 <Layout.Section>97 <Card>98 <BlockStack gap="300">99 <Text variant="headingMd">Product List</Text>100 {/* IndexTable or content here */}101 </BlockStack>102 </Card>103 </Layout.Section>104 <Layout.Section variant="oneThird">105 <Card>106 <Text variant="headingMd">Filters</Text>107 </Card>108 </Layout.Section>109 </Layout>110</Page>111```112113### Form Pattern114115```tsx116// Pattern: form with validation117// Fetch live docs for current TextField, Select, and Form props118<Form onSubmit={handleSubmit}>119 <FormLayout>120 <TextField label="Product name" value={name} onChange={setName} autoComplete="off" />121 <Select label="Status" options={statusOptions} value={status} onChange={setStatus} />122 <Button submit variant="primary">Save</Button>123 </FormLayout>124</Form>125```126127### Feedback Pattern128129```tsx130// Pattern: Banner for persistent messages, Toast for transient131<Banner title="Order shipped" tone="success" onDismiss={handleDismiss}>132 <p>Tracking number: {trackingNumber}</p>133</Banner>134135// Toast via App Bridge (not Polaris component in embedded apps)136shopify.toast.show("Product saved");137```138139## Design Tokens140141Consistent design values used across all Polaris components:142143| Category | Token Pattern | Examples |144|----------|--------------|---------|145| Colors | `--p-color-bg-*`, `--p-color-text-*` | `--p-color-bg-surface`, `--p-color-text-critical` |146| Spacing | `--p-space-*` | `--p-space-100` (4px) through `--p-space-1200` (48px) |147| Typography | `--p-font-size-*`, `--p-font-weight-*` | `--p-font-size-300`, `--p-font-weight-bold` |148| Border | `--p-border-radius-*` | `--p-border-radius-200` |149| Shadow | `--p-shadow-*` | `--p-shadow-100`, `--p-shadow-200` |150151> **Fetch live docs** for current token values and names — token naming conventions change across Polaris versions. Check `https://polaris.shopify.com/tokens`.152153## @shopify/draggable154155Shopify's drag-and-drop library:156- Draggable, Sortable, Swappable, Droppable157- Touch and mouse support158- Accessible with keyboard support159- Used for reorderable lists, kanban boards, custom interfaces160161> **Fetch live docs**: Web-search `site:github.com shopify draggable` for current API and examples.162163## App Design Guidelines164165### Embedded Apps Must166167- Use Polaris components for consistent admin experience168- Use App Bridge for navigation and titles169- Follow Shopify's color, typography, and spacing tokens170- Implement loading states (skeleton screens)171- Handle errors with Banner components172- Support responsive layouts173174### Do NOT175176- Use custom CSS that overrides Polaris styles177- Build custom navigation chrome (use App Bridge)178- Use non-Polaris modals or toasts in embedded apps179- Mix design systems (e.g., Material UI with Polaris)180181## Accessibility182183Polaris components are built with accessibility:184- ARIA attributes included by default185- Keyboard navigation support186- Focus management in modals and popovers187- Color contrast meets WCAG AA188- Screen reader announcements for dynamic content189190> **Fetch live docs**: Web-search `site:polaris.shopify.com accessibility` for current accessibility guidelines and component-specific a11y notes.191192## Best Practices193194- Check Polaris Web Components status before starting — prefer Web Components if available195- Use `IndexTable` for resource lists (not `DataTable` for CRUD interfaces)196- Use `Banner` for persistent messages, `Toast` (via App Bridge) for transient confirmations197- Use skeleton components (`SkeletonPage`, `SkeletonBodyText`) for loading states198- Follow the `Page` → `Layout` → `Card` → content hierarchy199- Use `BlockStack` and `InlineStack` for layout (not CSS flex/grid directly)200- Apply design tokens for custom styles instead of hardcoded values201- Test keyboard navigation and screen reader output202- Always fetch live docs for component props before implementation — APIs change frequently203204Fetch the Polaris documentation for exact component APIs, design tokens, prop types, and Web Components migration status before implementing.