---
version: alpha
name: Polaris Admin Commerce Interface
description: "A commerce-admin design system derived from Shopify Polaris principles for merchant operations, embedded apps, inventory, orders, payments, and workflow consoles. It uses neutral admin surfaces, compact typography, semantic status color, dense cards, index tables, banners, badges, and task-first actions. The system is intended for research and abstract interface generation only: use official Polaris Web Components for Shopify apps, and avoid copying Shopify proprietary product identity in unrelated products."

colors:
  primary: "#303030"
  primary-hover: "#1a1a1a"
  on-primary: "#ffffff"
  canvas: "#f1f1f1"
  surface-card: "#ffffff"
  surface-soft: "#f7f7f7"
  surface-inset: "#f3f3f3"
  surface-selected: "#ebf5ff"
  ink: "#1a1a1a"
  body: "#303030"
  muted: "#616161"
  subdued: "#8a8a8a"
  hairline: "#d4d4d4"
  hairline-strong: "#8a8a8a"
  success: "#047b5d"
  success-surface: "#e4f7ef"
  warning: "#ffb800"
  warning-surface: "#fff4d6"
  critical: "#c70a24"
  critical-surface: "#fee9eb"
  info: "#006bb7"
  info-surface: "#e5f3ff"
  magic: "#8051ff"
  inverse-canvas: "#111111"
  inverse-surface: "#1b1b1b"
  inverse-ink: "#f7f7f7"

typography:
  display-xl:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 42px
    fontWeight: 650
    lineHeight: 1.1
    letterSpacing: 0
  display-lg:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 32px
    fontWeight: 650
    lineHeight: 1.14
    letterSpacing: 0
  heading-md:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 20px
    fontWeight: 650
    lineHeight: 1.3
    letterSpacing: 0
  heading-sm:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 16px
    fontWeight: 650
    lineHeight: 1.35
    letterSpacing: 0
  body:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 14px
    fontWeight: 450
    lineHeight: 1.45
    letterSpacing: 0
  body-sm:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 13px
    fontWeight: 450
    lineHeight: 1.4
    letterSpacing: 0
  caption:
    fontFamily: "Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 12px
    fontWeight: 600
    lineHeight: 1.35
    letterSpacing: 0
  mono:
    fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1.45
    letterSpacing: 0
    fontVariantNumeric: "tabular-nums"

rounded:
  xs: 4px
  sm: 6px
  md: 8px
  lg: 12px
  xl: 16px
  pill: 9999px

spacing:
  base: 4px
  xxs: 4px
  xs: 8px
  sm: 12px
  md: 16px
  lg: 20px
  xl: 28px
  xxl: 40px
  section: 72px

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.md}"
    padding: 8px 12px
  button-secondary:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.ink}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.md}"
    padding: 8px 12px
  admin-card:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    rounded: "{rounded.lg}"
    padding: 16px
  index-table:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.body}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.lg}"
    padding: 0
  banner:
    backgroundColor: "{colors.info-surface}"
    textColor: "{colors.body}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.md}"
    padding: 12px
  status-badge:
    backgroundColor: "{colors.success-surface}"
    textColor: "{colors.success}"
    typography: "{typography.caption}"
    rounded: "{rounded.sm}"
    padding: 3px 7px
  compact-field:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.ink}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.md}"
    padding: 7px 10px

layout:
  content-width: "1120px maximum for embedded admin pages; 720px to 860px for focused edit flows."
  grid: "12-column desktop grid. Use 3/4/6/12 column card spans for metrics, tasks, tables, and detail sidebars."
  density: "High density is appropriate for index pages and operational dashboards. Lower density is appropriate for editing one object."
  surfaces: "Neutral grey page floor, white cards, nested inset surfaces, fine hairlines, and semantic status panels."

guidance:
  do:
    - "Use neutral surfaces as the default, then reserve color for semantic state, risk, and progress."
    - "Choose density by task: data-rich index pages can be compact; single-object edit flows need more breathing room."
    - "Make the first screen action-driven with orders, inventory, payouts, alerts, or merchant tasks visible."
    - "Use badges, banners, filters, tables, and popovers to show status without overwhelming the page."
    - "Use official Polaris Web Components for real Shopify apps when available."
  dont:
    - "Do not turn a merchant workflow into a marketing landing page."
    - "Do not use green, red, or yellow as decoration; they must keep their semantic meaning."
    - "Do not make two components look the same if they behave differently."
    - "Do not copy Shopify product branding, iconography, or proprietary layouts into unrelated products."
    - "Do not hide primary merchant actions behind decorative hero copy."

caseStudy:
  source: "Shopify Polaris design guidance, tokens, and Polaris Web Components"
  urls:
    - "https://polaris-react.shopify.com/design"
    - "https://polaris-react.shopify.com/design/pro-design-language"
    - "https://polaris-react.shopify.com/design/layout"
    - "https://polaris-react.shopify.com/design/typography"
    - "https://polaris-react.shopify.com/tokens/color"
    - "https://shopify.dev/docs/api/app-home/web-components"
    - "https://github.com/Shopify/polaris-react/blob/main/LICENSE.md"
  analysis: "Polaris treats admin UI as daily merchant software rather than a website. Its most reusable lessons are semantic color discipline, density control, predictable component behavior, compact data surfaces, and action-oriented pages. This resource abstracts those lessons for commerce-admin research while preserving the boundary that real Shopify apps should use official Web Components and unrelated products should not copy Shopify identity."
---

# Polaris Admin Commerce Interface

Use this system for merchant operations, commerce admin tools, marketplace back offices, inventory consoles, payment review, fulfillment workflows, and embedded app surfaces where users compare status, make changes, and resolve operational tasks.

The design posture is practical and restrained. A merchant should be able to scan orders, notice risk, choose an action, and trust that every repeated control behaves consistently.

## Overview

The core idea is dense operational clarity. The page floor is neutral grey, cards are white, text is compact, and color carries meaning rather than mood. Tables, filters, badges, banners, popovers, and forms are first-class components because merchant work is usually repetitive, stateful, and time-sensitive.

The interface should feel like software. Avoid oversized hero compositions, ornamental gradients, and brand theatrics. A good first viewport shows the objects under management: orders, products, inventory, payouts, tasks, alerts, or automations.

## Colors

### Brand & Accent

- `primary` (#303030) is the main action color for save, publish, create, and resolve.
- `magic` (#8051ff) is optional and only for AI-assisted or automation affordances.
- Brand color is deliberately quiet so semantic status remains legible.

### Surface

- `canvas` (#f1f1f1) is the admin page floor.
- `surface-card` (#ffffff) is the default component and panel surface.
- `surface-soft` (#f7f7f7) and `surface-inset` (#f3f3f3) are for nested panels, table headers, and grouped metadata.
- `surface-selected` (#ebf5ff) is for selected rows or active filters, not decoration.

### Text

- `ink` (#1a1a1a) is for headings and primary labels.
- `body` (#303030) is the default reading color.
- `muted` (#616161) and `subdued` (#8a8a8a) are for helper copy, counts, timestamps, and secondary metadata.

### Hairlines & Borders

- `hairline` (#d4d4d4) separates table rows, card sections, controls, and nested surfaces.
- `hairline-strong` (#8a8a8a) is for focus outlines, active filters, or high-importance dividers.

### Semantic

- `success` (#047b5d) means completed, paid, in stock, verified, or go.
- `warning` (#ffb800) means attention, pending, low stock, or partially blocked.
- `critical` (#c70a24) means destructive, failed, overdue, chargeback, or risk.
- `info` (#006bb7) means neutral guidance, system notice, or help.

Do not reuse these colors as decorative fills. Their value is predictability.

## Typography

### Font Family

Use `Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif`. If matching a platform shell, map to that shell's system type while preserving compact sizes, medium weights, and clear hierarchy.

### Hierarchy

- Page title: 42px/46px for dashboard-level pages; use 32px/36px for embedded app headers.
- Section heading: 20px/26px.
- Card title: 16px/22px.
- Body: 14px/20px.
- Small body and metadata: 13px/18px.
- Mono: 12px/17px with tabular numerals for money, SKU, counts, IDs, and log-like values.

### Principles

Use typography to support scanning, not drama. Most hierarchy comes from card grouping, proximity, dividers, labels, and status badges. Do not rely on color alone to mark priority or interactivity.

### Note on Font Substitutes

If Inter is unavailable, use the system sans stack. Keep letter spacing at `0` and avoid display faces in dense admin contexts.

## Layout

### Spacing System

The working rhythm is 4px-based:

- 4px for icon and badge internal gaps.
- 8px for compact stack gaps and control padding.
- 12px for field groups, filters, and table toolbar gaps.
- 16px for card padding.
- 20px to 28px for card groups.
- 40px to 72px for major page divisions.

### Grid & Container

Use a maximum content width around 1120px for embedded admin pages. Dashboard sections can use 12 columns with 3, 4, 6, and 12 column spans. Focused edit pages should use a narrower content column with a supporting sidebar for status, publication, and metadata.

### Whitespace Philosophy

Whitespace is a task tool. Increase density when users compare many rows or statuses. Increase spacing when users edit one product, configure a payment setting, or make an irreversible choice.

## Elevation & Depth

Keep depth shallow. Use background contrast, borders, and nested inset surfaces more often than shadows. Shadows are reserved for menus, popovers, and modal surfaces that sit above the admin plane.

Button interaction can feel tactile through a subtle pressed translation, border change, or tonal shift. Do not introduce glass, glow, or large decorative blur.

## Shapes

Use tight but friendly radii:

- 4px for badges and small controls.
- 6px to 8px for buttons, inputs, filters, and menus.
- 12px for cards, tables, and banners.
- 16px only for large panels or modal surfaces.
- Full pills only for tags, not for structural cards.

Nested surfaces should usually have an equal or smaller radius than their parent.

## Components

### Buttons

Primary buttons are dark neutral and compact. Secondary buttons are white or soft grey with visible borders. Destructive actions should use text, icon, or confirmation patterns before showing a critical fill.

### Cards & Containers

Cards group one task or one object. A card should not mix unrelated workflows. Use section headers, metadata rows, and nested inset panels to prevent card sprawl.

### Inputs & Forms

Inputs are compact but must keep visible labels, help text, error text, and focus state. Money fields, SKU fields, and quantity fields should use tabular numerals and clear units.

### Navigation

Admin navigation should be predictable: page title, primary action, secondary actions, filters, table, and detail drill-in. If a workflow is embedded in another platform, the local navigation should not fight the host shell.

### Signature Components

- Index table with filters, saved views, row selection, and bulk actions.
- Banner for system guidance and urgent merchant attention.
- Badge for fulfillment, payment, inventory, risk, and publication status.
- Popover or action menu for contextual row actions.
- Modal for confirmation, policy text, and destructive choices.

## Do's and Don'ts

Do:

- Show real merchant objects in the first viewport.
- Pair every badge color with text.
- Let table density vary by task complexity.
- Use banners for actionable guidance, not generic announcements.
- Keep repeated component appearances tied to repeated behavior.

Don't:

- Do not use semantic colors as decoration.
- Do not make an unrelated product look like Shopify Admin.
- Do not hide operational tasks under oversized hero headlines.
- Do not invent custom control shapes for every section.
- Do not rely on hover-only actions for critical merchant workflows.

## Responsive Behavior

### Breakpoints

- Desktop: 1024px and above, use grid cards and full tables.
- Tablet: 720px to 1023px, collapse secondary panels below the main content and keep filters accessible.
- Mobile: below 720px, convert table rows into stacked object cards with visible status, amount, date, and primary action.

### Touch Targets

Keep interactive targets at least 44px tall on touch devices even if desktop controls are visually compact.

### Collapsing Strategy

Collapse columns by task value, not by arbitrary order. Preserve identifier, status, amount, date, and next action before secondary metadata.

### Image Behavior

Product thumbnails should remain inspectable. Do not crop merchandise, variant swatches, or fulfillment evidence so tightly that users lose context.

## Iteration Guide

1. Start with a task inventory: what objects does the merchant need to manage?
2. Decide the density tier: index, dashboard, edit, confirmation, or support.
3. Map semantic states before choosing decorative color.
4. Define table columns, badge states, filters, bulk actions, and empty states.
5. Add interaction states for hover, focus, pressed, selected, loading, disabled, warning, and critical.
6. Test mobile by converting tables into object cards and verifying the next action remains visible.

## Known Gaps

- Exact Polaris token values and component behavior change over time; confirm against current official Web Components for production Shopify apps.
- The legacy Polaris React repository is archived and carries a custom Shopify-oriented license boundary. Treat this resource as design research, not a copyable UI kit.
- Dark preview is an intentional internal-operations variant for Interface Lab, not a claim that Shopify Admin uses this exact dark mode.
- Proprietary Shopify branding, app chrome, icons, and merchant content are not included.