agykit 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