shopify-polaris-design

这项技能可确保界面使用 Shopify 的 Polaris Design System 构建，为 Shopify 商家提供原生、易用且专业的外观和体验。

核心原则

1. 以商家为中心：设计应注重效率和清晰度。商家使用这些工具来经营业务。
2. 原生体验：应用应如同 Shopify 管理后台的自然延伸。除非绝对必要，否则不要引入陌生的设计模式（例如 Material Design 阴影、明显带有 bootstappy 风格的按钮）。
3. 易用性：Polaris 的设计充分考虑了易用性。使用语义化组件（例如 Button、Link、TextField），而不是自定义的 div 实现，以保持这一点。
4. 可预测性：遵循 Shopify 的标准模式。保存按钮放在上下文保存栏中。页面操作放在右上角。主要内容居中显示。

技术实现

依赖项

• @shopify/polaris
• @shopify/polaris-icons
• @shopify/app-bridge-react（用于导航、标题栏、提示消息和保存栏）

基础组件

• AppProvider：所有 Polaris 应用都必须包裹在 <AppProvider i18n={enTranslations}> 中。
• Page：路由的顶层容器。始终设置 title 和 primaryAction（如适用）。

  <Page title="Products" primaryAction={{content: 'Add product', onAction: handleAdd}}>
  

• Layout：使用 Layout 和 Layout.Section 来组织内容。
  • Layout.AnnotatedSection：用于设置页面（左侧为标题/描述，右侧为卡片）。
  • Layout.Section：标准全宽（默认）、1/2 宽（variant="oneHalf"）或 1/3 宽（variant="oneThird"）列。
• Card：内容块的主要容器。将相关信息归类到同一张卡片中。
  • 在卡片内部使用 BlockStack（垂直）或 InlineStack（水平）进行布局。
  • 不要在较新版本中使用已弃用的 Card.Section；请改用带有 gap 的 BlockStack。

数据展示

• IndexTable：用于显示对象列表（产品、订单），支持批量操作和筛选。对于复杂表格场景，它取代了旧版 ResourceList。
• LegacyCard + ResourceList：对于不需要表头的简单列表，仍然适用。
• DataTable：用于简单的非交互式数据网格（例如分析数据）。
• Text：使用 <Text as="h2" variant="headingMd">，而不是 <h2>。严格控制排版至关重要。

表单设计

• 使用 FormLayout 自动处理表单字段的间距和对齐。
• 使用 TextField、Select、Checkbox、RadioButton。
• 验证：向表单字段传入 error 属性（字符串或布尔值），以在行内显示验证消息。
• ContextualSaveBar：对于编辑现有数据的表单，使用 App Bridge 的 useSaveBar 或 <ContextualSaveBar> 组件，在顶部显示专用的保存/放弃更改栏。

设计令牌与 CSS

• 避免自定义 CSS：95% 的样式应通过 Polaris 属性（gap、padding、align、justify）处理。
• 设计令牌：如果必须使用自定义 CSS，请使用 Polaris CSS 自定义属性（令牌）。
  • 背景：var(--p-color-bg-surface)
  • 文本：var(--p-color-text-default)
  • 间距：var(--p-space-400)（16px）
  • 边框：var(--p-border-radius-200)

代码风格示例

import { Page, Layout, Card, BlockStack, Text, Button, InlineStack, Badge } from '@shopify/polaris';

export default function Dashboard() {
  return (
    <Page 
        title="Dashboard" 
        primaryAction={{content: 'Create Campaign', onAction: () => {}}}
        secondaryActions={[{content: 'View Logs', onAction: () => {}}]}
    >
      <Layout>
        <Layout.Section>
          <Card>
            <BlockStack gap="400">
              <InlineStack align="space-between">
                <Text as="h2" variant="headingMd">Recent Activity</Text>
                <Badge tone="success">Active</Badge>
              </InlineStack>
              <Text as="p" tone="subdued">Everything is running smoothly.</Text>
            </BlockStack>
          </Card>
        </Layout.Section>
        
        <Layout.Section variant="oneThird">
            <Card>
                <BlockStack gap="200">
                    <Text as="h3" variant="headingSm">Quick Helper</Text>
                    <Button variant="plain">Read Documentation</Button>
                </BlockStack>
            </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

应避免的反模式

• 切勿手动添加阴影或边框。卡片会处理这些样式。
• 切勿使用 style={{ margin: 10 }}。请使用 <Box padding="400"> 或 <BlockStack gap="400">。
• 切勿在表单底部创建“保存”按钮。请在视口顶部使用 ContextualSaveBar。
• 切勿使用通用加载旋转图标。加载时请使用 <SkeletonPage> 或 <SkeletonBodyText>。