Shopify Polaris

---
name: shopify-polaris
description: Apply the Shopify Polaris visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Shopify Polaris, mentions Polaris, Shopify admin style, Polaris design system, or describes near-black primary buttons, white cards on light-gray canvas, blue only for links and focus — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Shopify Polaris Design System

The design system of the Shopify merchant admin: ink-on-light neutrals with near-black #303030 primary buttons (green CTAs are long gone), blue #005bd3 reserved for links and focus, white cards on a #f1f1f1 canvas, a tight 4px spacing scale, small 8px card radii, and a fast, utilitarian, system-font voice.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Shopify Polaris.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (Polaris, Shopify admin style, Polaris design system), or describes its traits: near-black primary buttons; white cards on light-gray canvas; blue only for links and focus; system font stack; resource lists and index tables; status badges.

## Design tokens

### Color palette

- color-bg — admin canvas background: `#f1f1f1` (--color-bg)
- color-bg-surface — cards and sheets: `#ffffff` (--color-surface)
- color-bg-surface-secondary — subdued zones and table headers: `#f7f7f7` (--color-surface-secondary)
- color-text — primary ink: `#303030` (--color-text)
- color-text-secondary — supporting text: `#616161` (--color-text-muted)
- color-text-link / focus ring — interactive blue: `#005bd3` (--color-accent)
- color-bg-fill-brand — primary button fill (near-black, not green): `#303030` (--color-fill-brand)
- color-border — card and control borders: `#e3e3e3` (--color-border)
- color-bg-inverse — top bar and dark chrome: `#1a1a1a` (--color-inverse)

### Typography

- Display / headings: system-ui (fallback: -apple-system, BlinkMacSystemFont, San Francisco, Segoe UI, Roboto, Helvetica Neue, sans-serif)
- Body: system-ui (fallback: -apple-system, BlinkMacSystemFont, San Francisco, Segoe UI, Roboto, Helvetica Neue, sans-serif)
- Mono / data: ui-monospace (fallback: SFMono-Regular, Consolas, Menlo, monospace)
- Type scale: 1.15 ratio, base 13px — computed steps: 13px / 15px / 17px / 20px / 23px / 26px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 600, line-height 1.3, letter-spacing 0
- Body: line-height 1.54, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 12, 16, 20, 24, 32 — Merchant-task density on a 4px scale (space-100 = 4px, space-400 = 16px): 16px card padding, 8px gaps between stacked controls, 16px page gutters — compact enough for daily operational work without feeling cramped.
- Border radius: sm 4px, md 8px, lg 12px, full 9999px — radius-100 4px on inputs and buttons, radius-200 8px on cards, full round for badges and avatars.
- Border treatment: 1px solid #e3e3e3 — Hairline #e3e3e3 borders define cards and table rows; inputs use a slightly darker border with a strong bottom edge for an inset feel.

### Shadows

- card: `0 1px 0 rgba(26, 26, 26, 0.07)` — Resting cards — a single hairline drop
- button: `inset 0 -1px 0 rgba(26, 26, 26, 0.2), 0 1px 0 rgba(26, 26, 26, 0.07)` — Buttons — bottom inset edge gives a pressed-metal tactility
- popover: `0 4px 6px -2px rgba(26, 26, 26, 0.2)` — Popovers, dropdown menus, tooltips
- modal: `0 20px 20px -8px rgba(26, 26, 26, 0.28)` — Modal dialogs

### Layout

- Max content width: 998px
- Admin frame: dark #1a1a1a top bar, light left nav, content column capped near 998px (fullWidth for index tables)
- Pages are vertical stacks of white cards, each one job
- Index tables / resource lists with sticky bulk-action headers are the core browsing pattern
- Primary page action lives in the page header, top right

### Effects

- Subtle top-light gradient on filled buttons (lighter top edge) for a tactile, physical-control feel
- Status badges in soft tinted fills: green success, yellow attention, red critical

### Motion

- Easing: cubic-bezier(0.25, 0.1, 0.25, 1); durations 100ms / 200ms / 300ms
- Fast, unobtrusive fades and height expansions — merchants are here to work
- Skeleton pages load structure-first while data streams in
- No decorative or celebratory motion outside onboarding moments

## CSS variables (drop-in)

```css
:root {
  --color-bg: #f1f1f1;
  --color-surface: #ffffff;
  --color-surface-secondary: #f7f7f7;
  --color-text: #303030;
  --color-text-muted: #616161;
  --color-accent: #005bd3;
  --color-fill-brand: #303030;
  --color-border: #e3e3e3;
  --color-inverse: #1a1a1a;
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;
  --shadow-card: 0 1px 0 rgba(26, 26, 26, 0.07);
  --shadow-button: inset 0 -1px 0 rgba(26, 26, 26, 0.2), 0 1px 0 rgba(26, 26, 26, 0.07);
  --shadow-popover: 0 4px 6px -2px rgba(26, 26, 26, 0.2);
  --shadow-modal: 0 20px 20px -8px rgba(26, 26, 26, 0.28);
  --border-default: 1px solid #e3e3e3;
  --font-display: system-ui, -apple-system, BlinkMacSystemFont, "San Francisco", "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
  --font-body: system-ui, -apple-system, BlinkMacSystemFont, "San Francisco", "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, Consolas, Menlo, monospace;
  --text-base: 13px;
  --leading-heading: 1.3;
  --leading-body: 1.54;
  --tracking-heading: 0;
  --tracking-body: 0;
  --ease: cubic-bezier(0.25, 0.1, 0.25, 1);
  --duration-fast: 100ms;
  --duration-base: 200ms;
  --duration-slow: 300ms;
}
```

All fonts are system fonts — nothing to load.

## Component recipes

- **Nav:** Dark #1a1a1a top bar with search; light sidebar with 32px rows, 13px labels, selected item gets a #ebebeb pill and bolder ink
- **Hero:** Admin-first: a page header with back arrow, 20px/600 title, primary #303030 button top-right; marketing surfaces reuse the card language at larger scale
- **Card:** White surface, 8px radius, hairline card shadow plus 1px #e3e3e3 border, 16px padding; section headings 13px/600
- **Button (primary):** Near-black #303030 fill with subtle top-lit gradient, white 600-weight 13px label, 4px radius, 28–32px tall, inset bottom edge; hover #1a1a1a
- **Button (secondary):** White fill, 1px #e3e3e3 border, #303030 text, same geometry; pressed state darkens to #f7f7f7
- **Form fields:** 13px label above; 32px input, 4px radius, 1px border with darker bottom edge; focus draws a 2px #005bd3 ring offset 1px

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The near-black #303030 CTA button with a subtle top-lit gradient and hairline shadow — a deliberately unbranded, ink-like primary action sitting inside white cards on the #f1f1f1 admin canvas. Spend boldness here; keep everything else quiet.

## Do

- Keep primary actions near-black — Polaris moved off green CTAs; ink is the brand
- Reserve #005bd3 strictly for links and focus rings so interactivity stays legible
- Compose pages as stacks of single-purpose cards with 16px padding
- Use tinted badges, not raw color text, for order/product status

## Don't

- Don't reintroduce the legacy Shopify green as a button color inside admin surfaces
- Don't load a webfont — Polaris intentionally rides the OS system stack for speed
- Don't exceed 12px radii; soft-rounded cards break the utilitarian tone
- Don't scatter primary buttons — one per page header, secondary actions inside cards

## Accessibility notes

- Ink pairs pass comfortably: #303030 on #f1f1f1 is about 10.9:1 and #616161 secondary text stays above 4.5:1 on both white and the canvas gray
- Link blue #005bd3 passes AA on white and #f1f1f1; keep it off the #f7f7f7-adjacent tinted badge fills without checking
- The 13px base size is small — never reduce secondary text below 12px, and preserve the 2px offset focus ring on all controls

## Reference sites

- Polaris design system: https://polaris.shopify.com
- Polaris design tokens: https://polaris.shopify.com/tokens/color
- Polaris components: https://polaris.shopify.com/components

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip shopify-polaris.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/shopify-polaris.json

Settings → Capabilities → Skills → Upload skill → shopify-polaris.zip