# Polaris — Design Style Reference

> **Unofficial, community-authored reference.** Compiled by [designsystems.one](https://www.designsystems.one). Not affiliated with, endorsed by, or sponsored by Shopify. "Polaris" and related marks belong to their respective owners. This document describes publicly observable style attributes in original words — it contains no copied documentation, logos, icon artwork, or original token files. Always defer to the official source for canonical, current values.

**System:** Polaris
**Owner:** Shopify
**Official documentation:** https://polaris.shopify.com/
**Visual character:** Merchant-workbench pragmatism: quiet grays, one decisive dark action button, and type tuned for forms and data, not marketing.

---

## Summary

Merchant-first design system shipping a real product surface.

_Confidence: high. Values are drawn from well-documented public token references._

## Color tokens

| Color | Value | CSS variable | Role |
| --- | --- | --- | --- |
| Surface | `#ffffff` | `--p-color-bg-surface` | Page surface |
| Background App | `#f1f1f1` | `--p-color-bg` | App background behind surfaces |
| Text | `#202223` | `--p-color-text` | Default body text |
| Text Secondary | `#6d7175` | `--p-color-text-secondary` | Secondary text |
| Interactive / Link | `#005bd3` | `--p-color-text-link` | Links and interactive text |
| Primary Button | `#303030` | `--p-color-bg-fill-brand` | Primary action fill (v12 dark button) |
| Critical | `#d72c0d` | `--p-color-text-critical` | Destructive emphasis |
| Success | `#29845a` | `--p-color-text-success` | Positive states |
| Border | `#e3e3e3` | `--p-color-border` | Hairlines and input borders |

## Typography

- **Body:** Inter — weights 400, 450, 550, 650 — `Inter, -apple-system, 'San Francisco', 'Segoe UI', Roboto, sans-serif`
- **Mono:** SF Mono — weights 400 — `ui-monospace, SFMono-Regular, Menlo, monospace`

## Type scale

| Step | Size | Line height |
| --- | --- | --- |
| heading-2xl | `30px` | `32px` |
| heading-xl | `24px` | `28px` |
| heading-lg | `20px` | `24px` |
| heading-md | `16px` | `20px` |
| body-md | `14px` | `20px` |
| body-sm | `12px` | `16px` |

## Spacing

Base unit: `4px`

Scale: `4px` · `8px` · `12px` · `16px` · `20px` · `24px` · `32px`

## Corner radius

| Name | Value |
| --- | --- |
| radius-100 | `4px` |
| radius-200 | `8px` |
| radius-300 | `12px` |
| radius-full | `9999px` |

## Elevation / shadows

| Name | Value |
| --- | --- |
| shadow-200 | `0 1px 2px rgba(0,0,0,0.06)` |
| shadow-300 | `0 4px 6px -2px rgba(26,26,26,0.20)` |

## Motion

| Name | Value |
| --- | --- |
| duration-100 | `100ms` |
| duration-200 | `200ms` |
| ease | `cubic-bezier(0.25, 0.1, 0.25, 1)` |

## Quick start (CSS)

```css
/* Polaris — illustrative tokens, restated as CSS custom properties.
   Unofficial reference by designsystems.one; values are indicative, not
   canonical. Official reference: https://polaris.shopify.com/ */

:root {
  /* Color */
  --p-color-bg-surface: #ffffff; /* Page surface */
  --p-color-bg: #f1f1f1; /* App background behind surfaces */
  --p-color-text: #202223; /* Default body text */
  --p-color-text-secondary: #6d7175; /* Secondary text */
  --p-color-text-link: #005bd3; /* Links and interactive text */
  --p-color-bg-fill-brand: #303030; /* Primary action fill (v12 dark button) */
  --p-color-text-critical: #d72c0d; /* Destructive emphasis */
  --p-color-text-success: #29845a; /* Positive states */
  --p-color-border: #e3e3e3; /* Hairlines and input borders */

  /* Typography */
  --font-body: Inter, -apple-system, 'San Francisco', 'Segoe UI', Roboto, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;

  /* Type scale */
  --text-heading-2xl: 30px /* line-height 32px */;
  --text-heading-xl: 24px /* line-height 28px */;
  --text-heading-lg: 20px /* line-height 24px */;
  --text-heading-md: 16px /* line-height 20px */;
  --text-body-md: 14px /* line-height 20px */;
  --text-body-sm: 12px /* line-height 16px */;

  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-7: 32px;

  /* Radius */
  --radius-radius-100: 4px;
  --radius-radius-200: 8px;
  --radius-radius-300: 12px;
  --radius-radius-full: 9999px;

  /* Elevation */
  --shadow-shadow-200: 0 1px 2px rgba(0,0,0,0.06);
  --shadow-shadow-300: 0 4px 6px -2px rgba(26,26,26,0.20);

  /* Motion */
  --motion-duration-100: 100ms;
  --motion-duration-200: 200ms;
  --motion-ease: cubic-bezier(0.25, 0.1, 0.25, 1);
}
```

## Origin

Polaris launched in 2017 to unify the merchant-facing surfaces of Shopify Admin. It has matured through multiple major versions while remaining unusually grounded in the realities of merchant workflows — long forms, complex tables, error recovery, asynchronous bulk operations.

## Governance

Centralized core team owns the canonical components and tokens; product teams contribute through a public contribution model. Token decisions go through internal RFCs; component changes ship behind versioning with deprecation periods.

## Known for

- Industry-leading content guidelines — Polaris's voice & tone documentation is widely cited beyond Shopify.
- Mature data-table and form patterns built for genuinely complex merchant flows.
- Public, opinionated guidance on accessibility for transactional interfaces.

## Underrated

- The empty-state and error-state catalog — better thought through than most public design systems acknowledge.
- Detailed admin UI patterns (bulk actions, async results) that most design systems duck.

## Watch out for

- Polaris is built for Shopify Admin, not for marketing surfaces — applying it to a content site without adaptation produces a tool-shaped marketing site.
- Heavy on patterns specific to commerce; you will inherit assumptions you may not want.

## Components worth studying

- **ResourceList / IndexTable** — Bulk-action data grids that are genuinely usable at scale.
- **FormLayout** — Field grouping that handles long forms and inline validation cleanly.
- **Banner** — The reference example for inline status messaging in admin UIs.

## When to choose Polaris

Pick Polaris if you're building merchant- or operator-facing tools with form-heavy interactions. Don't pick it as a marketing or storytelling system — its patterns assume a logged-in user doing real work.

## Apply this style with an AI tool

Paste this into your AI coding assistant as a direction, then iterate:

> Design in the spirit of Polaris by Shopify — Merchant-first design system shipping a real product surface. Character: Merchant-workbench pragmatism: quiet grays, one decisive dark action button, and type tuned for forms and data, not marketing. Use a primary colour near #303030, the typeface "Inter" (or a close equivalent), corner radius around 4px, a spacing rhythm on a 4px base. Lean into what it's known for: Industry-leading content guidelines — Polaris's voice & tone documentation is widely cited beyond Shopify. Match the intent, not the pixels; adapt it to my product rather than cloning it.

## Official references

- [Polaris docs](https://polaris.shopify.com/)
- [Polaris on GitHub](https://github.com/Shopify/polaris)
- [Tokens reference](https://polaris.shopify.com/tokens/colors)

---

_Generated by [designsystems.one](https://www.designsystems.one/design-systems/polaris) — a catalogue of public design systems. Style facts are reported for reference and education; adapt them to your own product. Report issues or takedown requests via the site._