# Pencil Cupertino Web Workflow

> 使用 Pencil .pen 文件和 React Cupertino UI 构建并维护 Apple/Cupertino 风格的网页界面。适用于创建 Pencil 组件库、建立 Pencil 组件与 React 组件映射、同步 CSS 设计令牌、将 Pencil 页面实现为 React、在 Pencil 中还原现有 React 页面、使用已映射组件组合新页面，以及审计设计与代码的偏差和视觉一致性。

- Skill: `rayekry777/pencil-cupertino-web-workflow` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add rayekry777/pencil-cupertino-web-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rayekry777/pencil-cupertino-web-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Rayekry777 (https://skillmd.com/u/rayekry777)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rayekry777/pencil-cupertino-web-workflow

---


# Pencil Cupertino 网页工作流

让 Pencil 设计与 React 实现遵循同一套明确契约：共享设计令牌、稳定的组件名称、已记录的属性/变体映射，以及可重复执行的视觉质量检查。

## 操作规则

- 将当前检出的项目作为已安装包名、版本、导出项、属性和 CSS 的事实来源。不得凭记忆虚构 React Cupertino UI API。
- 在 `src/design-system/` 中建立项目自有的封装层。业务页面应导入封装组件，不要在整个应用中散布第三方导入。
- 将可复用控件建成 Pencil 组件，将页面中的使用方式建成组件实例。不要在每个页面中重复绘制已映射控件。
- 将项目专属产物保存在项目内，不要放入本 skill。
- 使用 Pencil 或其连接的 MCP/插件修改 `.pen` 文件。不要手工编辑未公开的 `.pen` 内部结构。
- 当项目既有约定与下方建议路径冲突时，遵循项目约定，并将最终路径记录到 `design/workflow.config.json`。
- 保留用户已有的可用代码和无关改动，只做最小且完整的修改。

## 选择工作流

根据请求选择对应入口：

- **新项目或缺少设计系统**：先执行“初始化契约”，再执行“设计转代码”。
- **现有 React 页面转 Pencil**：执行“代码转设计”。
- **现有 Pencil 页面转 React**：执行“设计转代码”。
- **组件库升级或视觉不一致**：执行“偏差审计”。
- **只要求一个组件**：对该组件应用同一套契约，不要无谓地初始化整套组件库。

## 阶段 1：前置检查

1. 检查包管理器、框架、构建命令、测试命令、React Cupertino UI 版本及现有设计系统目录。
2. 定位 `.pen` 文件、CSS 变量、主题文件、截图、Storybook stories 和现有组件目录。
3. 判断 Pencil 是否已连接。若不可用，继续完成代码侧清单和契约文件，然后只报告被阻塞的设计操作，不要伪造 `.pen` 结果。
4. 编辑前检查仓库说明。
5. 只读取与任务相关的参考文档：
   - 项目布局和文件结构：`references/project-contract.md`
   - 组件清单或映射：`references/component-mapping.md`
   - Pencil 组件库或页面：`references/pencil-conventions.md`
   - 实现和视觉一致性验证：`references/visual-qa.md`

## 阶段 2：初始化契约

若等价文件已存在，则跳过创建。

1. 创建或确认项目封装层，例如 `src/design-system/`。
2. 如果项目没有更明确的约定，创建 `design/`，并将页面文件放在 `design/pages/` 下。
3. 按需复制并调整以下模板：
   - `assets/workflow.config.template.json` → `design/workflow.config.json`
   - `assets/component-map.template.json` → `design/component-map.json`
   - 仅当项目没有令牌文件时，才将 `assets/tokens.template.css` 复制为配置指定的 CSS 令牌文件
4. 在契约中固定每个实际使用的 UI 包及其版本，不要填写 `latest`。
5. 运行：

```bash
python <skill-dir>/scripts/validate_workflow.py --project <project-root>
```

当所有已配置产物都应存在时，在最终交付前加上 `--strict`。

## 阶段 3：盘点并封装组件

1. 从已安装源码/类型、官方包文档或仓库 stories 中确认导出项和属性。
2. 按语义角色建立清单：操作、输入、导航、容器、浮层、反馈和数据展示。
3. 优先复用现有封装。仅当封装能稳定以下一项或多项内容时才新建：
   - 第三方导入路径；
   - 属性名称或默认值；
   - 无障碍行为；
   - 设计令牌和视觉状态；
   - 应用专属组合方式。
4. 使用稳定的 PascalCase 名称命名封装组件。除非某种组合反复出现，否则将页面专属组合留在基础组件库之外。
5. 为所有需要在 Pencil 中复现的状态添加 stories 或小型组件目录页。

不要为了获得代码所有权而把第三方组件库的实现复制进项目，应对其进行封装。

## 阶段 4：同步设计令牌

除非项目已有正式的令牌流水线，否则使用 CSS 自定义属性作为代码侧令牌来源。

1. 盘点语义颜色、字体排版、间距、圆角、阴影、模糊、动效和断点。
2. 优先使用 `--ui-color-accent`、`--ui-radius-card` 等语义名称；避免 `--dashboard-card-3-green` 之类的组件实例名称。
3. 将语义令牌同步到 Pencil 变量和主题中。按模式映射明暗值，不要为不同模式复制组件。
4. 在 `component-map.json` 的 `tokens` 下记录映射。
5. 如果某个视觉值无法在网页端完全一致地实现，记录降级方案并进行视觉验证。

## 阶段 5：构建 Pencil 组件库

1. 创建或更新配置指定的 `.lib.pen` 组件库。
2. 先构建基础层，再构建组件：变量、主题、文本样式、效果和布局基础。
3. 按从简单到组合的顺序构建组件族：基础元素、控件、导航、浮层，最后是应用级组件。
4. 只暴露有意义的变体和插槽，并尽量与封装组件的属性语义保持一致。
5. 除非项目已有命名体系，否则使用 `Cupertino/<Category>/<Component>` 命名组件。
6. 添加组件目录页，展示必要状态和响应式行为。
7. 将每个可复用 Pencil 组件加入 `component-map.json`；明确标记尚未完成的映射，不要悄悄用近似实现代替。

写入 Pencil 时遵循 `references/pencil-conventions.md`。

## 阶段 6A：设计转代码

1. 检查目标 Pencil 页面、组件实例、变量、层级、约束和目标视口。
2. 编写 JSX 前，先通过 `component-map.json` 解析每个设计组件。
3. 使用项目封装组件组合页面。只对确实未映射的页面结构或图稿编写原始 CSS/HTML。
4. 不得用视觉仿制品替换已映射组件。
5. 使用现有令牌；只有在确实可以复用时才新增语义令牌。
6. 根据约束和已记录的断点实现响应式行为，不要只依据一张截图推断。
7. 保留无障碍能力：语义元素、标签、焦点状态、键盘操作、对比度、减少动态效果和触控目标尺寸。
8. 运行项目检查，然后完成视觉质量检查。

## 阶段 6B：代码转设计

1. 检查渲染后的代码、封装组件、stories、CSS 令牌和响应式状态。
2. 复用已映射的 Pencil 组件。只有当某个可复用代码组件缺少映射时，才新建 Pencil 组件。
3. 绑定 Pencil 变量，不要复制计算后的颜色或间距值。
4. 对布局差异明显的响应式形态使用独立页面画框；不要把一个桌面画框拉伸成失真的移动端稿。
5. 立即记录新增的组件、属性、插槽或令牌映射。
6. 使用真实浏览器截图验证 Pencil 组合结果。

## 阶段 7：偏差审计

按以下顺序审计：

1. 已安装依赖版本与配置版本；
2. 封装导出项与映射的代码组件；
3. Pencil 组件及变体与映射的设计名称；
4. CSS 令牌名称与令牌映射；
5. 页面实例用法与封装组件用法；
6. 约定视口下的截图。

将发现分类为 `missing`（缺失）、`stale`（过时）、`approximate`（近似）或 `verified`（已验证）。先修复稳定的基础组件，再处理页面级像素差异。

## 阶段 8：验证与交付

完成任务前，必须通过所有适用检查：

- 配置的映射和令牌文件校验通过；
- 项目构建和相关测试通过；
- 批准的封装边界之外没有新增直接导入第三方包的代码；
- 代码与 Pencil 中都包含所需组件状态；
- 目标截图在相同视口、缩放、字体环境和数据状态下完成比较；
- 剩余差异已记录原因和负责人；
- 清晰报告修改文件和验证命令。

比较顺序和容差遵循 `references/visual-qa.md`。仅生成截图不能证明像素级一致。

## 内置资源

- `scripts/validate_workflow.py`：校验工作流配置、组件映射、令牌引用、重名项和配置路径。
- `assets/workflow.config.template.json`：项目路径和验证配置模板。
- `assets/component-map.template.json`：组件与令牌映射模板。
- `assets/tokens.template.css`：供尚无令牌系统的项目使用的最小语义令牌起始模板。
- `references/`：仅在相关任务中加载的详细契约与质量检查说明。