Core Polaris Web Components fundamentals including component library structure, design tokens, responsive patterns, and SSR compatibility. Auto-invoked when working with Polaris components.
Provides foundational knowledge of Polaris Web Components, including setup, component categories, design tokens, and best practices.
Polaris Web Components are organized into six categories:
1. Actions - Interactive elements that trigger actions
2. Forms - Input and selection components
3. Feedback - Status and notification components
4. Media - Visual content components
5. Structure - Layout and organization components
6. Titles and Text - Typography components
gap="050" // 2px
gap="100" // 4px
gap="200" // 8px
gap="300" // 12px
gap="400" // 16px (default)
gap="500" // 20px
gap="600" // 24px
gap="800" // 32px
gap="1000" // 40px
gap="1600" // 64px
background="bg-surface" // Default surface
background="bg-surface-secondary" // Secondary surface
background="bg-surface-tertiary" // Tertiary surface
background="bg-surface-success" // Success state
background="bg-surface-warning" // Warning state
background="bg-surface-critical" // Error state
border="base" // Default border
border="success" // Success border
border="warning" // Warning border
border="critical" // Error border
borderRadius="base" // 4px
borderRadius="large" // 8px
borderRadius="full" // 50% (circular)
tone="subdued" // Secondary text
tone="success" // Success message
tone="warning" // Warning message
tone="critical" // Error message
variant="heading3xl" // Page titles
variant="heading2xl" // Section headers
variant="headingXl" // Card titles
variant="headingLg" // Subsection headers
variant="headingMd" // Card headers
variant="headingSm" // Small headers
variant="bodyLg" // Large body text
variant="bodyMd" // Default body text (default)
variant="bodySm" // Small body text
// Mobile first approach
columns="1" // Mobile (default)
sm-columns="2" // Small devices (≥577px)
md-columns="3" // Medium devices (≥769px)
lg-columns="4" // Large devices (≥1025px)
// Example usage
<s-grid columns="1" md-columns="2" lg-columns="4">
<div>Column 1</div>
<div>Column 2</div>
<div>Column 3</div>
<div>Column 4</div>
</s-grid>
NEVER use inline event handlers - they cause hydration mismatches in SSR apps.
// ❌ WRONG - Hydration mismatch
<s-button onclick={handleClick}>Click</s-button>
// ✅ CORRECT - Use data attributes + useEffect
<s-button data-my-button>Click</s-button>
useEffect(() => {
const button = document.querySelector('[data-my-button]');
if (button) {
button.addEventListener('click', handleClick);
}
return () => button?.removeEventListener('click', handleClick);
}, []);
<s-button>Default</s-button>
<s-button variant="primary">Primary</s-button>
<s-button variant="destructive">Delete</s-button>
<s-button variant="plain">Plain</s-button>
<s-button size="slim">Small</s-button>
<s-button loading>Loading</s-button>
<s-button disabled>Disabled</s-button>
<s-text-field
label="Product Title"
value={title}
error={errors.title} // Show error
disabled={isDisabled} // Disable input
required // Mark required
helpText="Customer-facing" // Help text
placeholder="Enter title" // Placeholder
/>
<s-card>
<s-stack gap="400" direction="vertical">
<s-heading>Card Title</s-heading>
<s-divider />
<s-text>Card content</s-text>
<s-divider />
<s-button-group>
<s-button variant="primary">Save</s-button>
<s-button>Cancel</s-button>
</s-button-group>
</s-stack>
</s-card>
{isLoading ? (
<s-card>
<s-stack gap="400" direction="vertical">
<s-skeleton-display-text />
<s-skeleton-display-text />
<s-skeleton-display-text />
</s-stack>
</s-card>
) : (
<s-card>{/* Actual content */}</s-card>
)}
{items.length === 0 ? (
<s-empty-state
heading="No items yet"
image="https://cdn.shopify.com/..."
>
<s-text>Get started by adding your first item</s-text>
<s-button variant="primary">Add Item</s-button>
</s-empty-state>
) : (
// Item list
)}
<s-page heading="Page Title">
<s-section>
{/* First section */}
</s-section>
<s-section>
{/* Second section */}
</s-section>
</s-page>
<s-page
heading="Products"
primaryAction={{
content: "Add Product",
url: "/products/new"
}}
>
{/* Page content */}
</s-page>
<s-heading as="h1">Main Title</s-heading>
<s-heading as="h2">Section Title</s-heading>
<s-text as="p">Paragraph text</s-text>
<s-icon-button
icon="delete"
aria-label="Delete product"
/>
<s-search-field
aria-label="Search products"
placeholder="Search..."
/>
as prop for proper HTML elements| Need | Component | Example |
|---|---|---|
| Primary action | <s-button variant="primary"> |
Save, Submit |
| Secondary action | <s-button> |
Cancel, Back |
| Destructive action | <s-button variant="destructive"> |
Delete, Remove |
| Page container | <s-page> |
All pages |
| Content container | <s-card> |
Forms, data displays |
| Text input | <s-text-field> |
Title, description |
| Selection | <s-select> |
Category, status |
| Multiple choices | <s-checkbox> |
Features, options |
| Success message | <s-banner tone="success"> |
Saved successfully |
| Error message | <s-banner tone="critical"> |
Failed to save |
| Status indicator | <s-badge> |
Active, Draft |
| Data table | <s-table> |
Products, orders |
| Vertical spacing | <s-stack direction="vertical"> |
Form fields |
| Horizontal layout | <s-grid> |
Dashboard cards |
For complete component documentation, see:
polaris-web-components/components/ - All component docspolaris-web-components/patterns/ - Composition patternspolaris-web-components/using-polaris-web-components.md - Setup guideRemember: Polaris ensures your app matches Shopify's design system and provides a consistent, accessible user experience.