polaris-fundamentals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polaris Fundamentals Skill

Polaris基础技能

Purpose

用途

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

提供Polaris Web Components的相关基础知识，包括配置方式、组件分类、设计令牌和最佳实践。

When This Skill Activates

该技能激活场景

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

使用Polaris Web Components时
构建Shopify应用UI时
实现设计系统模式时
为特定使用场景选择组件时

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

Polaris Web Components共分为六大类别：

1. 操作类 - 触发动作的交互元素

按钮、链接、图标按钮、按钮组

2. 表单类 - 输入与选择组件

文本框、复选框、选择器、文件上传、颜色选择器

3. 反馈类 - 状态与通知组件

横幅、吐司提示、进度条、加载器、骨架屏

4. 媒体类 - 视觉内容组件

头像、图标、缩略图、视频缩略图

5. 结构类 - 布局与组织组件

页面、卡片、区块、盒子、网格、堆栈、表格

6. 标题与文本类 - 排版组件

标题、文本、段落、徽章、标签

Design Tokens

设计令牌

Spacing Scale

间距尺度

tsx

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

tsx

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

背景色

tsx

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

tsx

background="bg-surface"           // 默认表层
background="bg-surface-secondary" // 次级表层
background="bg-surface-tertiary"  // 三级表层
background="bg-surface-success"   // 成功状态
background="bg-surface-warning"   // 警告状态
background="bg-surface-critical"  // 错误状态

Border Options

边框选项

tsx

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

tsx

border="base"     // 默认边框
border="success"  // 成功边框
border="warning"  // 警告边框
border="critical" // 错误边框

Border Radius

边框圆角

tsx

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

tsx

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

Text Tones

文本色调

tsx

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

tsx

tone="subdued"   // 次要文本
tone="success"   // 成功消息
tone="warning"   // 警告消息
tone="critical"  // 错误消息

Typography Variants

排版变体

tsx

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

tsx

variant="heading3xl"  // 页面标题
variant="heading2xl"  // 区块头部
variant="headingXl"   // 卡片标题
variant="headingLg"   // 子区块头部
variant="headingMd"   // 卡片头部
variant="headingSm"   // 小型头部
variant="bodyLg"      // 大号正文
variant="bodyMd"      // 默认正文 (default)
variant="bodySm"      // 小号正文

Responsive Breakpoints

响应式断点

tsx

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

tsx

// 移动端优先方案
columns="1"          // 移动端 (默认)
sm-columns="2"       // 小型设备 (≥577px)
md-columns="3"       // 中型设备 (≥769px)
lg-columns="4"       // 大型设备 (≥1025px)

// 使用示例
<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)

React Hydration（SSR应用）

⚠️ CRITICAL: Event Handler Pattern

⚠️ 重要提示：事件处理模式

NEVER use inline event handlers - they cause hydration mismatches in SSR apps.

tsx

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

绝对不要使用内联事件处理函数 - 它们会在SSR应用中导致水合不匹配问题。

tsx

// ❌ 错误写法 - 水合不匹配
<s-button onclick={handleClick}>Click</s-button>

// ✅ 正确写法 - 使用data属性 + 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

按钮变体

tsx

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

tsx

<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

文本框状态

tsx

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

tsx

<s-text-field
  label="Product Title"
  value={title}
  error={errors.title}        // 显示错误
  disabled={isDisabled}       // 禁用输入
  required                    // 标记为必填
  helpText="Customer-facing"  // 帮助文本
  placeholder="Enter title"   // 占位符
/>

Card Structure

卡片结构

tsx

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

tsx

<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

加载模式

tsx

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

tsx

{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>{/* 实际内容 */}</s-card>
)}

Empty State Pattern

空状态模式

tsx

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

tsx

{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>
) : (
  // 项目列表
)}

Page Structure

页面结构

Standard Page Layout

标准页面布局

tsx

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

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

tsx

<s-page heading="Page Title">
  <s-section>
    {/* 第一个区块 */}
  </s-section>

  <s-section>
    {/* 第二个区块 */}
  </s-section>
</s-page>

Page with Primary Action

带主操作按钮的页面

tsx

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

tsx

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

Accessibility

可访问性

Semantic HTML

语义化HTML

tsx

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

tsx

<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

ARIA标签

tsx

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

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

tsx

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

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

Keyboard Navigation

键盘导航

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

所有交互元素都支持键盘访问
使用Tab键导航
回车/空格键激活按钮
ESC键关闭模态框

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

使用设计令牌 - 永远不要硬编码颜色、间距或排版样式
移动端优先 - 先完成移动端布局，再针对桌面端做增强
语义化HTML - 使用
```
as
```
属性指定正确的HTML元素
加载状态 - 数据请求过程中始终显示骨架加载屏
空状态 - 无数据时提供操作指引
错误处理 - 表单校验使用内联错误提示
可访问性 - 确保支持键盘导航并配置ARIA标签
间距统一 - 使用Polaris间距尺度（例如gap="400"）
SSR兼容 - 使用data属性绑定事件处理函数
遵循模式 - 使用成熟的Polaris设计模式

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

需求	组件	示例
主操作	`<s-button variant="primary">`	保存、提交
次操作	`<s-button>`	取消、返回
危险操作	`<s-button variant="destructive">`	删除、移除
页面容器	`<s-page>`	所有页面
内容容器	`<s-card>`	表单、数据展示
文本输入	`<s-text-field>`	标题、描述
选择器	`<s-select>`	分类、状态
多选	`<s-checkbox>`	功能、选项
成功消息	`<s-banner tone="success">`	保存成功
错误消息	`<s-banner tone="critical">`	保存失败
状态指示器	`<s-badge>`	已激活、草稿
数据表格	`<s-table>`	商品、订单
垂直间距	`<s-stack direction="vertical">`	表单字段
横向布局	`<s-grid>`	仪表盘卡片

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.

完整组件文档请查看：

```
polaris-web-components/components/
```
- 所有组件文档
```
polaris-web-components/patterns/
```
- 组合模式

polaris-web-components/using-polaris-web-components.md

- 配置指南

注意：Polaris可确保你的应用符合Shopify设计系统规范，提供一致、可访问的用户体验。