zenit UI dev Skill
一份给 Claude Code 等 AI Agent 的开发说明书。装上之后，Agent 写 zenit 界面时会先选现成组件、用 token 和样式配方、按 zenit 的生命周期管理状态，并在交付前构建、截图自验。
下载
压缩包内是一个标准的 Agent Skill 目录：入口 SKILL.md 很短，只放规则和决策表；细节拆在 references/ 里，Agent 按需读取，不占上下文。
安装
- 1放进 Skill 目录
个人使用放
~/.claude/skills/，对所有项目生效；团队共享放仓库里的.claude/skills/并提交，克隆仓库的人自动获得。 - 2重启 Agent 会话
Claude Code 在会话开始时扫描 Skill。新开会话后，输入
/skills能看到zenit-ui-dev即安装成功。 - 3像平时一样提需求
涉及 zenit 界面的任务会自动加载它，也可以显式说「用 zenit-ui-dev skill」。
下载后解压到个人目录（所有项目生效）：
~/.claude/skills/
└── zenit-ui-dev/
├── SKILL.md
├── references/
└── tools/或解压到项目目录并提交（团队共享）：
.claude/skills/
└── zenit-ui-dev/
├── SKILL.md
├── references/
└── tools/# Codex and other agents that read AGENTS.md: unpack into the repo and reference it
unzip -oq zenit-ui-dev.zip -d .agents/skills
echo '- zenit UI: read .agents/skills/zenit-ui-dev/SKILL.md before writing UI code' >> AGENTS.md里面有什么
SKILL.md入口：触发条件、工作流、硬规则、决策表，以及何时读哪份 referencereferences/app-architecture.md以一个生产级编辑器为例的大型应用分层：状态、视图、命令、服务references/components.mdui.widgets 目录、两种 mount 形态、「设计元素 → 组件」选型表references/macos-native.md菜单、快捷键、文件对话框、剪贴板、拖拽、多窗口、IMEreferences/pencil-design.mdPencil（pen.dev）设计稿还原：MCP 读数值、字段映射、截图数值比对references/performance.md虚拟列表、脏标记、大文本、后台线程与主线程通信references/pitfalls.md从 zenit 与生产项目修复记录整理的「现象 → 原因 → 正确做法」references/project-setup.md新建项目、build.zig / build.zig.zon、打包 .app、构建选项转发references/state-reactivity.mdbindState / cx.on、Signal / Memo / Effect、Scope 生命周期与清理references/styling.mdToken → styles.zig → recipe 三层、主题、ui.arb 逃生舱references/ui-tree-layout.md节点、Flex 布局、尺寸、更新节点、显隐、坐标references/verification.mdAgent 自验闭环：构建、截图、E2E harness、DevTools、日志tools/design_diff.ts设计稿 PNG 与应用截图的数值比对，输出可执行的修改提示tools/png.tsdesign_diff 使用的零依赖 PNG 解码器tools/shot.ts通过文件 RPC 给任意 zenit 应用截图（Retina）把设计稿里的每个元素映射到 ui.widgets 里的现成组件，避免 Agent 用 box 重新拼一个 Button。
bindState、pub deinit、Scope 清理与页面切换的规则，直接对应最常见的泄漏、重复释放和悬垂指针。
要求 Agent 构建、运行、截图并对照需求检查，而不是只看编译通过。
从真实生产项目的修复记录里整理出的问题清单，每条都有原因和正确做法。
推荐：搭配 Pencil 设计
Pencilpen.dev我们推荐用 Pencil 画界面，再让 Agent 结合本 Skill 实现。.pen 的 Flex 布局、间距、圆角、字号和 lucide 图标与 zenit 的模型很接近；Skill 里附了字段映射表和 design_diff 比对工具，方便 Agent 按数值而不是凭感觉还原。
- 01.penPencil 设计稿
- 02MCPAgent 读取精确数值
- 03zig组件 + token 写出 zenit 代码
- 04diff截图与设计稿数值比对
- 1连接 Pencil MCP
在 Agent 里启用 Pencil 的 MCP server 并打开 .pen 文件。Skill 规定 .pen 只能通过 MCP 读取：MCP 会展开设计变量、给出解析后的真实尺寸，这两样是还原最需要的。
- 2读数值，不看图
Agent 先用
Get(nodeId, { resolveVariables: true })拿到 gap、padding、圆角、字号和颜色，再按映射表写成 zenit：fill_container → .fill()，chevron-down → ui.icons.chevron_down。 - 3数值比对到对齐
导出设计稿（scale 2），用
tools/shot.ts截取真实窗口，tools/design_diff.ts给出位移、尺寸差、热力图与配色偏差，Agent 按提示修改；每轮约 5 秒。
SKILL=~/.claude/skills/zenit-ui-dev
bun $SKILL/tools/design_diff.ts --self-test
ZENIT_E2E_FILE_RPC_DIR=$RPCDIR bun $SKILL/tools/shot.ts /tmp/actual.png
bun $SKILL/tools/design_diff.ts /tmp/design/<nodeId>.png /tmp/actual.png怎么用
不需要特殊语法。描述你要的界面或问题即可，下面是几个效果较好的提法：
用 Pencil MCP 读取当前 .pen 里的「Settings」画板，用 zenit 还原成设置窗口，design_diff 分数到 90 以上再交给我。
用 zenit 给这个 app 加一个设置窗口：左侧分类列表，右侧表单，改动实时生效。
把 src/views/sidebar.zig 里手写的样式迁移到 styles.zig + recipe。
文件树 5 万个节点时滚动卡顿，帮我查原因并修掉，修完截图给我看。内容来源
Skill 的规则来自两个项目：zenit 框架本身（公开 API、示例、组件目录、测试工具），以及一个基于 zenit 开发的生产级 macOS 编辑器（大型应用的分层方式、原生集成和修复记录）。示例代码尽量取自这两个仓库中可编译的代码，并与本手册保持一致。
源文件在官网仓库的 skill/zenit-ui-dev/，构建时由 scripts/pack-skill.mjs 打包。也可以直接阅读 SKILL.md。