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. 运行：

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/：仅在相关任务中加载的详细契约与质量检查说明。