---
name: pancli-design
description: 专业的设计技能,用于使用 pancli (pencil tools) 创建现代化、一致的 EmailBill 移动端 UI 设计
license: MIT
compatibility: Requires pencil_* tools (batch_design, batch_get, etc.)
metadata:
  author: EmailBill Design Team
  version: "2.0.0"
  generatedBy: opencode
  lastUpdated: "2026-02-03"
  source: ".pans/v2.pen 日历设计 (亮色/暗色)"
---

# pancli-design - EmailBill UI 设计系统

> 专业的设计技能,用于使用 pancli (pencil tools) 创建现代化、一致的移动端 UI 设计。

## 何时使用此技能

**总是使用此技能当:**
- 使用 pancli 创建新的 UI 界面或组件
- 修改现有的 .pen 设计文件
- 处理亮色/暗色主题设计
- 为 EmailBill 项目设计移动端优先的界面

**触发条件:**
- 用户提到 "画设计图"、"设计"、"UI"、"界面"、"pancli"、".pen"
- 任务涉及 `pencil_*` 工具
- 创建视觉原型或模型

## 核心设计原则

### 1. 现代移动端优先设计

**核心规范:**
- 移动视口: 375px 宽度 (iPhone SE 基准)
- 安全区域: 尊重 iOS/Android 安全区域边距
- 交互元素最小触摸目标: 44x44px
- 间距基于 8px 网格: 4px, 8px, 12px, 16px, 24px, 32px
- 卡片阴影: `0 2px 12px rgba(0,0,0,0.08)` (亮色模式)

**反 AI 设计痕迹检查清单:**
- ❌ 使用 "Dashboard", "Lorem Ipsum" 等通用占位符
- ❌ 使用过饱和的颜色或生硬的渐变
- ❌ 使用装饰性字体 (Comic Sans, Papyrus)
- ✅ 使用代码库中的真实中文业务术语
- ✅ 使用克制的配色和柔和的阴影
- ✅ 使用专业的系统字体

### 2. 统一色彩系统

**色彩分层:**
- **背景层**: 页面背景 → 卡片背景 → 强调背景 (三层递进)
- **文本层**: 主文本 → 次要文本 → 三级文本 (三级层次)
- **语义色**: 红色(支出/危险) → 黄色(警告) → 绿色(收入/成功) → 蓝色(主操作/信息)

**颜色使用规则:**
- 始终使用语义颜色变量,避免硬编码十六进制值
- 支出/负数统一使用红色 `#FF6B6B`,收入/正数使用绿色系
- 主操作按钮统一使用蓝色 `#3B82F6`
- 避免纯黑 (#000000) 或纯白 (#FFFFFF) 文本,使用柔和的色调
- 暗色模式下减少阴影强度或完全移除
- 详细色值参见文末"快速参考"表格

### 3. 排版系统

**字体栈:**
- **标题**: `'Bricolage Grotesque'` - 用于大数值、章节标题
- **正文**: `'DM Sans'` - 用于界面文本、说明
- **数字**: `'DIN Alternate'` - 用于金额、数据显示
- **备选**: `-apple-system, 'PingFang SC'` - 系统默认字体

**排版原则:**
- 使用真实中文业务术语,避免 Lorem Ipsum
- 行高: 1.4-1.6 保证可读性
- 数字数据使用等宽字体 (tabular-nums)
- 字号遵循比例系统,避免任意数值
- 详细字号比例参见文末"快速参考"表格

### 4. 组件库

**设计原则:**
- 所有尺寸和间距基于 8px 网格系统
- 圆角: 12px (小按钮), 16px/20px (卡片), 22px/28px (圆形按钮)
- 交互元素最小触摸目标: 44x44px
- 详细组件规格参见文末"快速参考"表格

**卡片设计 (基于 statsCard, tCard):**
```
统计卡片 (大卡片):
  - 背景: #F6F7F8 (亮色), #18181B (暗色)
  - 内边距: 20px
  - 圆角: 20px
  - 间距: 12px (元素之间)
  - 布局: 垂直

交易卡片 (列表卡片):
  - 背景: #F6F7F8 (亮色), #18181B (暗色)  
  - 内边距: 16px
  - 圆角: 16px
  - 间距: 14px (水平元素)
  - 高度: 自适应内容
```

**按钮 (基于实际设计):**
```
图标按钮 (通知按钮):
  - 尺寸: 44x44px
  - 圆角: 22px (完全圆形)
  - 背景: #F5F5F5 (亮色), #27272A (暗色)
  - 图标大小: 20px
  
标签按钮:
  - 内边距: 6px 10px / 6px 12px
  - 圆角: 12px
  - 字体: DM Sans 13px/500
  - 颜色:
    - 温暖色: #FFFBEB (亮色), #451A03 (暗色)
    - 绿色: #F0FDF4 (亮色), #064E3B (暗色)
    - 蓝色: #E0E7FF (亮色), #312E81 (暗色)

悬浮按钮 (FAB):
  - 尺寸: 56x56px
  - 圆角: 28px
  - 背景: #3B82F6
  - 描边: 4px 白色边框
  - 阴影: 提升效果
```

**图标与文字:**
```
图标容器:
  - 尺寸: 44x44px
  - 圆角: 22px
  - 背景: #FFFFFF (亮色), #27272A (暗色)
  - 图标: 20px (lucide 字体)
  - 颜色: #FF6B6B (星标), #FCD34D (咖啡)

章节标题:
  - 字体: Bricolage Grotesque 18px/700
  - 颜色: #1A1A1A (亮色), #F4F4F5 (暗色)
  
大数值:
  - 字体: Bricolage Grotesque 32px/800
  - 颜色: #1A1A1A (亮色), #F4F4F5 (暗色)
```

**布局模式 (基于 Calendar 结构):**
```
页面容器: 402px (设计视口), 垂直布局, 24px 内边距
头部区域: 水平布局, 两端对齐, 8px 24px 内边距
内容区域: 垂直布局, 24px 内边距, 12-16px 间距
```

**关键布局原则:**
- 遵循 Flex 容器模式 (见下方"5. 布局模式")
- 导航栏背景必须透明 (`:deep(.van-nav-bar) { background: transparent !important; }`)
- 尊重安全区域 (`env(safe-area-inset-bottom)`)

### 5. 布局模式

**页面结构 (Flex 容器):**
```
.page-container-flex:
  - display: flex
  - flex-direction: column
  - height: 100%
  - overflow: hidden
  
  结构:
    1. van-nav-bar (固定高度)
    2. van-tabs 或 sticky-header
    3. scroll-content (flex: 1, overflow-y: auto)
    4. bottom-button 或 van-tabbar (固定)
```

**导航栏背景透明化 (项目标准模式):**
```css
/* 所有页面统一设置 */
:deep(.van-nav-bar) {
  background: transparent !important;
}
```
**关键要求:**
- 页面容器必须有明确的背景色
- 必须使用 `:deep()` 选择器覆盖 Vant 样式
- 必须添加 `!important` 标记
- 在 `<style scoped>` 块中添加此规则

**安全区域处理:**
```css
/* iPhone 刘海底部内边距 */
padding-bottom: env(safe-area-inset-bottom, 0px);

/* 状态栏顶部内边距 */
padding-top: max(0px, calc(env(safe-area-inset-top, 0px) * 0.75));
```

**固定元素:**
```css
.sticky-header {
  position: sticky;
  top: 0;
  z-index: 10;
  background: var(--van-background-2);
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.04);
  margin: 12px;
  padding: 12px 16px;
}
```

### 6. 交互模式

**触摸反馈:**
- 激活状态: 点击时 scale(0.95)
- 涟漪效果: 使用 Vant 内置触摸反馈
- 悬停状态: 12% 透明度叠加 (网页端)

**加载状态:**
```
van-pull-refresh:
  - 用于顶层可滚动内容
  - 最小高度: calc(100vh - nav - tabbar)
  
van-loading:
  - 容器内居中
  - 尺寸: 内联 24px, 页面 32px
```

**空状态:**
```
van-empty:
  - 图标: 60px 大小
  - 描述: 14px, var(--van-text-color-2)
  - 内边距: 垂直 48px
```

**悬浮操作:**
```
van-floating-bubble:
  - 图标大小: 24px
  - 位置: 右下角, 距底部 100px (避开 tabbar)
  - 磁吸: 贴靠 x 轴边缘
```

### 7. 数据可视化

**预算进度条:**
```
渐变逻辑:
  支出 (0% → 100%):
    - 0%:  #40a9ff (安全蓝)
    - 40%: #36cfc9 (青色过渡)
    - 70%: #faad14 (警告黄)
    - 100%: #ff4d4f (危险红)
  
  收入 (0% → 100%):
    - 0%:  #f5222d (深红 - 未开始)
    - 45%: #ffcccc (浅红)
    - 50%: #f0f2f5 (中性灰)
    - 55%: #bae7ff (浅蓝)
    - 100%: #1890ff (深蓝 - 达成)
```

**金额显示:**
```css
.amount {
  font-family: 'DIN Alternate', system-ui;
  font-weight: 600;
  font-variant-numeric: tabular-nums;
}

.expense { color: var(--van-danger-color); }
.income { color: var(--van-success-color); }
```

**图表 (如果使用):**
- 折线图: 2px 笔画, 圆角连接
- 柱状图: 8px 圆角, 4px 间距
- 颜色: 使用语义色阶
- 网格线: 1px, 8% 透明度

### 8. 主题切换 (亮色/暗色)

**实现策略:**
```javascript
// 自动检测系统偏好
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches
theme.value = isDark ? 'dark' : 'light'
document.documentElement.setAttribute('data-theme', theme.value)
```

**设计文件要求:**
- **必须同时创建亮色和暗色变体**
- 使用 Vant 的主题变量 (自动切换)
- 测试对比度: WCAG AA 最低标准 (文本 4.5:1)
- 暗色模式适配:
  - 减少卡片阴影至 0 2px 8px rgba(0,0,0,0.24)
  - 增加边框对比度
  - 白色文本柔化至 #e5e5e5

**pancli 工作流:**
```
1. 先创建亮色主题设计
2. 复制帧用于暗色模式
3. 使用 replace_all_matching_properties 批量更新:
   - 背景颜色
   - 文本颜色
   - 边框颜色
4. 手动调整阴影和叠加
5. 命名帧: "[屏幕名称] - Light" / "[屏幕名称] - Dark"
```

### 9. 命名约定

**帧名称:**
```
格式: [模块] - [屏幕] - [变体]

示例:
  ✅ Budget - List View - Light
  ✅ Budget - Edit Dialog - Dark
  ✅ Transaction - Card Component
  ✅ Statistics - Chart Section
  
  ❌ Screen1
  ❌ Frame_Copy_2
  ❌ New Design
```

**组件层级:**
```
可复用组件:
  - 前缀 "Component/"
  - 示例: "Component/BudgetCard"
  
屏幕:
  - 按模块分组
  - 示例: "Budget/ListView", "Budget/EditForm"
```

### 10. 质量检查清单

**设计完成前必检项:**
- [ ] 同时创建亮色和暗色主题
- [ ] 使用真实中文业务术语 (无占位文本)
- [ ] 交互元素 ≥ 44x44px
- [ ] 间距遵循 8px 网格
- [ ] 使用语义颜色变量 (非硬编码)
- [ ] 导航栏背景透明 (`:deep(.van-nav-bar)`)
- [ ] 帧命名: 模块-屏幕-变体 格式
- [ ] 可复用组件标记 `reusable: true`
- [ ] 两种主题截图验证

**无障碍标准:**
- [ ] 正文对比度 ≥ 4.5:1
- [ ] 大文本对比度 ≥ 3:1 (18px+)
- [ ] 触摸目标间距 ≥ 8px

## PANCLI 工作流程

### 阶段 1: 设置与风格选择

```typescript
// 1. 获取编辑器状态
pencil_get_editor_state(include_schema: true)

// 2. 获取设计指南
pencil_get_guidelines(topic: "landing-page") // 或 "design-system"

// 3. 选择合适的风格指南
pencil_get_style_guide_tags() // 获取可用标签

// 4. 使用标签获取风格指南
pencil_get_style_guide(tags: [
  "mobile",        // 必需
  "webapp",        // 类应用界面
  "modern",        // 简洁, 现代
  "minimal",       // 避免杂乱
  "professional",  // 商业环境
  "blue",          // 主色提示
  "fintech"        // 如果可用
])
```

### 阶段 2: 创建亮色主题设计

```typescript
// 5. 读取现有组件 (如果有)
pencil_batch_get(
  filePath: "designs/emailbill.pen",
  patterns: [{ reusable: true }],
  readDepth: 2
)

// 6. 创建亮色主题屏幕
pencil_batch_design(
  filePath: "designs/emailbill.pen",
  operations: `
    screen=I(document, {
      type: "frame",
      name: "Budget - List View - Light",
      width: 375,
      height: 812,
      fill: "#FFFFFF",
      layout: "vertical",
      placeholder: true
    })
    
    navbar=I(screen, {
      type: "frame",
      name: "Navbar",
      width: "fill_container",
      height: 44,
      fill: "transparent",
      layout: "horizontal",
      padding: [12, 16, 12, 16]
    })
    
    title=I(navbar, {
      type: "text",
      content: "预算管理",
      fontSize: 16,
      fontWeight: "600",
      textColor: "#1A1A1A"
    })
    
    // ... 更多操作
  `
)
```

### 阶段 3: 创建暗色主题变体

```typescript
// 7. 复制亮色主题帧
pencil_batch_design(
  operations: `
    darkScreen=C("light-screen-id", document, {
      name: "Budget - List View - Dark",
      positionDirection: "right",
      positionPadding: 48
    })
  `
)

// 8. 批量替换暗色主题颜色
pencil_replace_all_matching_properties(
  parents: ["dark-screen-id"],
  properties: {
    fillColor: [
      { from: "#FFFFFF", to: "#09090B" },   // 页面背景
      { from: "#F6F7F8", to: "#18181B" },   // 卡片背景
      { from: "#F5F5F5", to: "#27272A" }    // 边框
    ],
    textColor: [
      { from: "#1A1A1A", to: "#F4F4F5" },   // 主文本
      { from: "#6B7280", to: "#A1A1AA" },   // 次要
      { from: "#9CA3AF", to: "#71717A" }    // 三级
    ]
  }
)

// 9. 手动调整暗色模式阴影 (如需要)
pencil_batch_design(
  operations: `
    U("dark-card-id", {
      shadow: {
        x: 0,
        y: 2,
        blur: 8,
        color: "rgba(0,0,0,0.24)"
      }
    })
  `
)
```

### 阶段 4: 验证

```typescript
// 10. 对两种主题截图
pencil_get_screenshot(nodeId: "light-screen-id")
pencil_get_screenshot(nodeId: "dark-screen-id")

// 11. 检查布局问题
pencil_snapshot_layout(
  parentId: "light-screen-id",
  problemsOnly: true
)

// 12. 验证所有唯一属性
pencil_search_all_unique_properties(
  parents: ["light-screen-id"],
  properties: ["fillColor", "textColor", "fontSize"]
)
```

## 代码库实际示例

### 示例 1: 预算卡片组件

```
组件结构:
  BudgetCard (375x120px)
    ├─ CardBackground (#ffffff, 16px 圆角, 阴影)
    ├─ HeaderRow (水平布局)
    │   ├─ CategoryName (16px, 600 粗细)
    │   └─ PeriodLabel (12px, 次要颜色)
    ├─ ProgressBar (基于比例渐变)
    │   └─ ProgressFill (高度: 8px, 圆角: 4px)
    ├─ AmountRow (水平布局, 两端对齐)
    │   ├─ CurrentAmount (DIN, 18px, 危险色)
    │   ├─ LimitAmount (DIN, 14px, 次要)
    │   └─ RemainingAmount (DIN, 14px, 成功色)
    └─ FooterActions (可选, 储蓄按钮)
```

**pancli 实现:**
```typescript
card=I(parent, {
  type: "frame",
  name: "BudgetCard",
  width: "fill_container",
  height: 120,
  fill: "#ffffff",
  cornerRadius: [16, 16, 16, 16],
  shadow: { x: 0, y: 2, blur: 12, color: "rgba(0,0,0,0.08)" },
  stroke: { color: "#ebedf0", thickness: 1 },
  padding: [16, 16, 16, 16],
  layout: "vertical",
  gap: 12,
  placeholder: true
})

header=I(card, {
  type: "frame",
  layout: "horizontal",
  width: "fill_container",
  height: "hug_contents"
})

categoryName=I(header, {
  type: "text",
  content: "日常开销",
  fontSize: 16,
  fontWeight: "600",
  textColor: "#323233"
})

// 带渐变的进度条
progressBar=I(card, {
  type: "frame",
  width: "fill_container",
  height: 8,
  fill: "#f0f0f0",
  cornerRadius: [4, 4, 4, 4]
})

progressFill=I(progressBar, {
  type: "frame",
  width: "75%", // 75% 进度示例
  height: 8,
  fill: "linear-gradient(90deg, #40a9ff 0%, #faad14 100%)",
  cornerRadius: [4, 4, 4, 4]
})
```

### 示例 2: 带日期选择器的固定头部

```
固定头部模式 (来自 BudgetView):
  ├─ 位置: sticky, top: 0
  ├─ 背景: var(--van-background-2)
  ├─ 圆角: 12px
  ├─ 阴影: 0 2px 8px rgba(0,0,0,0.04)
  ├─ 内边距: 12px 16px
  ├─ 内容: "2024年1月" + 下拉箭头图标
```

### 示例 3: 滑动删除列表项

```
van-swipe-cell 模式:
  ├─ 内容: BudgetCard 组件
  ├─ 右侧操作: 删除按钮
  │   ├─ 宽度: 60px
  │   ├─ 背景: var(--van-danger-color)
  │   ├─ 文本: "删除"
  │   └─ 全高 (100%)
```

## 避免的反模式

**❌ 不要这样做:**
```
// 通用 AI 生成内容
title=I(navbar, {
  type: "text",
  content: "Dashboard", // ❌ 使用 "预算管理" 代替
  fontSize: 20,         // ❌ 按字号比例使用 16px
  fontWeight: "bold"    // ❌ 使用数字值 600
})

// 不一致的间距
card=I(parent, {
  padding: [15, 13, 17, 14] // ❌ 使用 8px 网格: [16, 16, 16, 16]
})

// 硬编码颜色而非语义
amount=I(card, {
  textColor: "#ff0000" // ❌ 使用 var(--van-danger-color) 或 "#ee0a24"
})

// 缺少暗色模式
// ❌ 只创建亮色主题没有暗色变体

// 糟糕的命名
frame=I(document, {
  name: "Frame_123" // ❌ 使用 "Budget - List View - Light"
})
```

**✅ 应该这样做:**
```typescript
// 真实业务术语
title=I(navbar, {
  type: "text",
  content: "预算管理",
  fontSize: 16,
  fontWeight: "600",
  textColor: "#323233"
})

// 一致的 8px 网格间距
card=I(parent, {
  padding: [16, 16, 16, 16],
  gap: 12
})

// 语义颜色变量
amount=I(card, {
  textColor: "#ee0a24", // 一致的危险色
  fontFamily: "DIN Alternate"
})

// 总是创建两种主题
lightScreen=I(document, { name: "Budget - List - Light" })
darkScreen=C(lightScreen, document, { 
  name: "Budget - List - Dark",
  positionDirection: "right"
})

// 清晰的描述性名称
card=I(parent, {
  name: "BudgetCard",
  reusable: true
})
```

## 委派与任务管理

**使用此技能时:**

```typescript
// 委派设计任务时加载此技能
delegate_task(
  category: "visual-engineering",
  load_skills: ["pancli-design", "frontend-ui-ux"],
  description: "创建预算列表屏幕设计",
  prompt: `
    任务: 为 EmailBill 应用创建移动端预算列表屏幕设计
    
    预期结果:
    - 375x812px 亮色主题设计
    - 暗色主题变体 (复制并适配)
    - 可复用的 BudgetCard 组件
    - 两种主题的截图验证
    
    必需工具:
    - pencil_get_style_guide_tags
    - pencil_get_style_guide
    - pencil_batch_design
    - pencil_batch_get
    - pencil_replace_all_matching_properties
    - pencil_get_screenshot
    
    必须做:
    - 严格遵循 pancli-design 技能指南
    - 使用真实中文业务术语 (预算, 账单, 分类)
    - 创建亮色和暗色两种主题
    - 使用 8px 网格间距系统
    - 遵循 Vant UI 组件模式
    - 使用 模块-屏幕-变体 格式命名帧
    - 使用语义颜色变量
    - 数字显示应用 DIN Alternate
    - 导航栏背景必须设置为透明 (:deep(.van-nav-bar) { background: transparent !important; })
    - 截图验证
    
    不得做:
    - 使用 Lorem Ipsum 或占位文本
    - 只创建亮色主题没有暗色变体
    - 使用任意间距 (必须遵循 8px 网格)
    - 硬编码颜色 (使用语义变量)
    - 使用通用 "Dashboard" 标签
    - 跳过截图验证
    - 创建名为 "Frame_1", "Copy" 等的帧
    
    上下文:
    - 移动视口: 375px 宽度
    - 设计系统: 基于 Vant UI
    - 配色方案: #1989fa 主色, #ee0a24 危险, #07c160 成功
    - 字体: 中文系统默认, 数字 DIN Alternate
    - designs/emailbill.pen 中的现有组件 (用 batch_get 检查)
  `,
  run_in_background: false
)
```

## 快速参考

**颜色面板 (基于实际 v2.pen 设计):**

| 名称 | 亮色 | 暗色 | 用途 |
|------|------|------|------|
| 页面背景 | #FFFFFF | #09090B | 页面背景 |
| 卡片背景 | #F6F7F8 | #18181B | 卡片表面 |
| 强调背景 | #F5F5F5 | #27272A | 按钮, 图标容器 |
| 主文本 | #1A1A1A | #F4F4F5 | 主要文本 |
| 次要文本 | #6B7280 | #A1A1AA | 次要文本 |
| 三级文本 | #9CA3AF | #71717A | 三级文本 |
| 主色 | #3B82F6 | #3B82F6 | 操作, FAB |
| 红色 | #FF6B6B | #FF6B6B | 支出, 警告 |
| 黄色 | #FCD34D | #FCD34D | 警告 |
| 绿色 | #F0FDF4 | #064E3B | 收入标签 |
| 蓝色 | #E0E7FF | #312E81 | 信息标签 |

**排版比例:**

| 用途 | 字体 | 大小 | 粗细 |
|------|------|------|------|
| 大数值 | Bricolage Grotesque | 32px | 800 |
| 页面标题 | DM Sans | 24px | 500 |
| 章节标题 | Bricolage Grotesque | 18px | 700 |
| 正文 | DM Sans | 15px | 600 |
| 说明 | DM Sans | 13px | 500 |
| 微型标签 | DM Sans | 12px | 600 |

**组件规格:**

- **容器内边距**: 24px (主区域), 20px (卡片), 16px (小卡片)
- **间距比例**: 2px, 4px, 8px, 12px, 14px, 16px
- **圆角**: 12px (标签), 16px/20px (卡片), 22px/28px (圆形按钮)
- **图标**: 20px
- **图标按钮**: 44x44px
- **FAB 按钮**: 56x56px
- **触摸目标**: 最小 44x44px
- **设计视口**: 402px 宽度

---

**版本:** 2.0.0  
**最后更新:** 2026-02-04  
**维护者:** EmailBill 设计团队