Shopify Polaris Design

Shopify Polaris Design

Apply Polaris design principles to create efficient, accessible admin interfaces optimized for data-heavy workflows.

Core Principles

Color Has Purpose

• Use neutral backgrounds (black/​white) to make colored elements stand out
• Red for critical errors, green for success, blue for tips/​offers
• Never use color purely for decoration in the UI (only in illustrations)
• Use color WITH other elements (icons, text) - never alone to convey meaning

Typography Defines Hierarchy

• Use weight, size, and positioning to establish hierarchy
• Never rely only on color for hierarchy
• Mono for code; tabular numbers for currency/​amounts
• Consistently style similar or repeating type

Space Defines Relationships

• Closer objects = stronger perceived relationship
• Group related items in the same card
• Larger/​heavier elements attract attention; smaller/​lighter for details
• Avoid nesting shapes; avoid divider lines outside of tables

Design Tokens

For complete token values, see references/​design-tokens.md.

Color Palette

/​* Neutral Backgrounds */
--p-color-bg: #ffffff;
--p-color-bg-surface: #f1f1f1;
--p-color-bg-surface-secondary: #f7f7f7;
--p-color-bg-surface-hover: #f0f0f0;
--p-color-bg-surface-active: #e8e8e8;

/​* Text Colors */
--p-color-text: #1a1a1a;
--p-color-text-secondary: #616161;
--p-color-text-disabled: #8c8c8c;

/​* Primary (Interactive) */
--p-color-bg-fill-brand: #008060;
--p-color-text-brand: #008060;

/​* Status Colors */
--p-color-bg-fill-success: #008060; /​* Green */
--p-color-bg-fill-critical: #d72c0d; /​* Red */
--p-color-bg-fill-warning: #ffc453; /​* Yellow */
--p-color-bg-fill-info: #0070f3;    /​* Blue */

Typography

/​* Font Family */
--p-font-family-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
--p-font-family-mono: 'SF Mono', Consolas, 'Liberation Mono', Menlo, monospace;

/​* Font Sizes */
--p-font-size-75: 0.75rem;   /​* 12px - Caption */
--p-font-size-100: 0.8125rem; /​* 13px - Body small */
--p-font-size-200: 0.875rem;  /​* 14px - Body */
--p-font-size-300: 1rem;      /​* 16px - Body large */
--p-font-size-400: 1.25rem;   /​* 20px - Heading */
--p-font-size-500: 1.5rem;    /​* 24px - Display */

/​* Font Weights */
--p-font-weight-regular: 400;
--p-font-weight-medium: 500;
--p-font-weight-semibold: 600;
--p-font-weight-bold: 700;

/​* Line Heights */
--p-font-line-height-1: 1;
--p-font-line-height-2: 1.25;
--p-font-line-height-3: 1.5;

Spacing (4px base unit)

--p-space-050: 0.125rem; /​* 2px */
--p-space-100: 0.25rem;  /​* 4px */
--p-space-150: 0.375rem; /​* 6px */
--p-space-200: 0.5rem;   /​* 8px */
--p-space-300: 0.75rem;  /​* 12px */
--p-space-400: 1rem;     /​* 16px */
--p-space-500: 1.25rem;  /​* 20px */
--p-space-600: 1.5rem;   /​* 24px */
--p-space-800: 2rem;     /​* 32px */
--p-space-1000: 2.5rem;  /​* 40px */

Border & Shadow

/​* Border Radius */
--p-border-radius-100: 0.25rem; /​* 4px */
--p-border-radius-200: 0.5rem;  /​* 8px */
--p-border-radius-300: 0.75rem; /​* 12px */
--p-border-radius-full: 9999px;

/​* Shadows */
--p-shadow-100: 0 1px 0 rgba(0, 0, 0, 0.05);
--p-shadow-200: 0 1px 2px rgba(0, 0, 0, 0.1);
--p-shadow-300: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
--p-shadow-400: 0 10px 15px -3px rgba(0, 0, 0, 0.1);

/​* Borders */
--p-border-width-1: 1px;
--p-color-border: #e1e1e1;
--p-color-border-secondary: #d1d1d1;

Component Patterns

For complete component examples, see references/​component-patterns.md.

Cards

.polaris-card {
  background: var(--p-color-bg-surface);
  border-radius: var(--p-border-radius-200);
  padding: var(--p-space-400);
  box-shadow: var(--p-shadow-200);
}

Buttons

.polaris-button {
  font-size: var(--p-font-size-200);
  font-weight: var(--p-font-weight-medium);
  padding: var(--p-space-200) var(--p-space-400);
  border-radius: var(--p-border-radius-100);
  transition: background 0.15s ease;
}
.polaris-button--primary {
  background: var(--p-color-bg-fill-brand);
  color: #ffffff;
}

Data Tables

.polaris-table {
  width: 100%;
  border-collapse: collapse;
  font-size: var(--p-font-size-200);
}
.polaris-table th {
  text-align: left;
  font-weight: var(--p-font-weight-semibold);
  padding: var(--p-space-300) var(--p-space-400);
  border-bottom: var(--p-border-width-1) solid var(--p-color-border);
  color: var(--p-color-text-secondary);
}
.polaris-table td {
  padding: var(--p-space-300) var(--p-space-400);
  border-bottom: var(--p-border-width-1) solid var(--p-color-border);
}
.polaris-table tr:hover {
  background: var(--p-color-bg-surface-hover);
}

Form Inputs

.polaris-input {
  font-size: var(--p-font-size-200);
  padding: var(--p-space-200) var(--p-space-300);
  border: var(--p-border-width-1) solid var(--p-color-border);
  border-radius: var(--p-border-radius-100);
  background: var(--p-color-bg);
  transition: border-color 0.15s ease;
}
.polaris-input:focus {
  outline: none;
  border-color: var(--p-color-bg-fill-brand);
  box-shadow: 0 0 0 1px var(--p-color-bg-fill-brand);
}

Best Practices

Data Density

• Use 13-14px base font for data-heavy interfaces
• Reduce padding in table cells for scannability
• Group related metrics in cards

Interaction States

• Always provide visual feedback: hover, focus, active, disabled
• Use consistent timing: 150ms for micro-interactions
• Focus states must be visible (never remove outline without alternative)

Accessibility

• Maintain minimum 4.5:1 contrast ratio for text
• Use color WITH icons/​text, never alone
• All interactive elements must be keyboard accessible