zhongwei/gh-sarojpunde-shopify-dev-toolkit-claude-plugins-shopify-polaris

Fork 0

Files

Zhongwei Li 958dd5e6bc Initial commit

2025-11-30 08:54:03 +08:00

8.1 KiB

Raw Permalink Blame History

name, description, allowed-tools, documentation_path

name

description

allowed-tools

documentation_path

polaris-fundamentals

Core Polaris Web Components fundamentals including component library structure, design tokens, responsive patterns, and SSR compatibility. Auto-invoked when working with Polaris components.

Read

Grep

Glob

../../../polaris-web-components

Polaris Fundamentals Skill

Purpose

Provides foundational knowledge of Polaris Web Components, including setup, component categories, design tokens, and best practices.

When This Skill Activates

Working with Polaris Web Components
Building Shopify app UIs
Implementing design system patterns
Choosing components for specific use cases

Core Concepts

Component Categories

Polaris Web Components are organized into six categories:

1. Actions - Interactive elements that trigger actions

Buttons, links, icon buttons, button groups

2. Forms - Input and selection components

Text fields, checkboxes, selects, file uploads, color pickers

3. Feedback - Status and notification components

Banners, toasts, progress bars, spinners, skeletons

4. Media - Visual content components

Avatars, icons, thumbnails, video thumbnails

5. Structure - Layout and organization components

Pages, cards, sections, boxes, grids, stacks, tables

6. Titles and Text - Typography components

Headings, text, paragraphs, badges, chips

Design Tokens

Spacing Scale

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 Colors

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 Options

border="base"     // Default border
border="success"  // Success border
border="warning"  // Warning border
border="critical" // Error border

Border Radius

borderRadius="base"  // 4px
borderRadius="large" // 8px
borderRadius="full"  // 50% (circular)

Text Tones

tone="subdued"   // Secondary text
tone="success"   // Success message
tone="warning"   // Warning message
tone="critical"  // Error message

Typography Variants

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

Responsive Breakpoints

// 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>

React Hydration (SSR Apps)

⚠️ CRITICAL: Event Handler Pattern

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);
}, []);

Common Component Patterns

Button Variants

<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>

Text Field States

<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
/>

Card Structure

<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>

Loading Pattern

{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>
)}

Empty State Pattern

{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
)}

Page Structure

Standard Page Layout

<s-page heading="Page Title">
  <s-section>
    {/* First section */}
  </s-section>

  <s-section>
    {/* Second section */}
  </s-section>
</s-page>

Page with Primary Action

<s-page
  heading="Products"
  primaryAction={{
    content: "Add Product",
    url: "/products/new"
  }}
>
  {/* Page content */}
</s-page>

Accessibility

Semantic HTML

<s-heading as="h1">Main Title</s-heading>
<s-heading as="h2">Section Title</s-heading>
<s-text as="p">Paragraph text</s-text>

ARIA Labels

<s-icon-button
  icon="delete"
  aria-label="Delete product"
/>

<s-search-field
  aria-label="Search products"
  placeholder="Search..."
/>

All interactive elements are keyboard accessible
Use Tab to navigate
Enter/Space to activate buttons
Escape to close modals

Best Practices

Use Design Tokens - Never hardcode colors, spacing, or typography
Mobile First - Start with mobile layout, enhance for desktop
Semantic HTML - Use the as prop for proper HTML elements
Loading States - Always show skeleton loaders during data fetch
Empty States - Provide guidance when no data exists
Error Handling - Use inline errors for form validation
Accessibility - Ensure keyboard navigation and ARIA labels
Consistent Spacing - Use Polaris spacing scale (gap="400")
SSR Compatible - Use data attributes for event handlers
Follow Patterns - Use established Polaris patterns

Component Selection Guide

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

Documentation Reference

For complete component documentation, see:

polaris-web-components/components/ - All component docs
polaris-web-components/patterns/ - Composition patterns
polaris-web-components/using-polaris-web-components.md - Setup guide

Remember: Polaris ensures your app matches Shopify's design system and provides a consistent, accessible user experience.

8.1 KiB Raw Permalink Blame History