zenit UI dev SkillThe zenit UI dev Skill

一份给 Claude Code 等 AI Agent 的开发说明书。装上之后，Agent 写 zenit 界面时会先选现成组件、用 token 和样式配方、按 zenit 的生命周期管理状态，并在交付前构建、截图自验。A development manual for Claude Code and other AI agents. With it installed, an agent writing zenit UI reaches for existing components first, styles with tokens and recipes, manages state on zenit’s lifetimes, and builds and screenshots its own work before handing it over.

下载Download

压缩包内是一个标准的 Agent Skill 目录：入口 SKILL.md 很短，只放规则和决策表；细节拆在 references/ 里，Agent 按需读取，不占上下文。The archive is a standard Agent Skill folder: a short SKILL.md entry point holding rules and decision tables, with details split into references/ that the agent reads only when needed.

安装Install

1. 1
   放进 Skill 目录Put it in a skills folder

   个人使用放 ~/.claude/skills/，对所有项目生效；团队共享放仓库里的 .claude/skills/ 并提交，克隆仓库的人自动获得。For yourself, use ~/.claude/skills/ (every project). For a team, commit it to the repo’s .claude/skills/ so everyone who clones gets it.

2. 2
   重启 Agent 会话Restart the agent session

   Claude Code 在会话开始时扫描 Skill。新开会话后，输入 /skills 能看到 zenit-ui-dev 即安装成功。Claude Code scans skills at session start. Open a new session; /skills should list zenit-ui-dev.

3. 3
   像平时一样提需求Ask as usual

   涉及 zenit 界面的任务会自动加载它，也可以显式说「用 zenit-ui-dev skill」。Any zenit UI task loads it automatically; you can also say “use the zenit-ui-dev skill”.

下载后解压到个人目录（所有项目生效）：After downloading, unzip it into your user folder (every project):

~/.claude/skills/
└── zenit-ui-dev/
    ├── SKILL.md
    ├── references/
    └── tools/

或解压到项目目录并提交（团队共享）：Or unzip it into the project and commit it (shared with the team):

.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

里面有什么What’s inside

推荐：搭配 Pencil 设计Recommended: design in Pencil

Pencilpen.dev

推荐工作流 · PENCIL + SKILLRECOMMENDED WORKFLOW · PENCIL + SKILL

推荐搭配 Pencil，设计 + AI 一起开发Pair it with Pencil: design, then build with AI

我们推荐用 Pencil 画界面，再让 Agent 结合本 Skill 实现。.pen 的 Flex 布局、间距、圆角、字号和 lucide 图标与 zenit 的模型很接近；Skill 里附了字段映射表和 design_diff 比对工具，方便 Agent 按数值而不是凭感觉还原。We recommend designing in Pencil and letting your agent build it with this Skill. Flex layout, spacing, radii, type sizes and lucide icons in a .pen file sit close to zenit’s model; the Skill includes a field mapping and a design_diff tool so the agent ports by the numbers rather than by eye.

了解 PencilAbout Pencil

1. 01.penPencil 设计稿Pencil design
2. 02MCPAgent 读取精确数值Agent reads exact values
3. 03zig组件 + token 写出 zenit 代码zenit code from widgets + tokens
4. 04diff截图与设计稿数值比对Numeric diff against the design

1. 1
   连接 Pencil MCPConnect the Pencil MCP

   在 Agent 里启用 Pencil 的 MCP server 并打开 .pen 文件。Skill 规定 .pen 只能通过 MCP 读取：MCP 会展开设计变量、给出解析后的真实尺寸，这两样是还原最需要的。Enable Pencil’s MCP server in your agent and open the .pen file. The Skill only reads .pen through the MCP, which resolves design variables and computed sizes — the two things a faithful port needs.

2. 2
   读数值，不看图Read values, not pixels

   Agent 先用 Get(nodeId, { resolveVariables: true }) 拿到 gap、padding、圆角、字号和颜色，再按映射表写成 zenit：fill_container → .fill()，chevron-down → ui.icons.chevron_down。The agent first pulls gap, padding, radius, type size and color with Get(nodeId, { resolveVariables: true }), then maps them onto zenit: fill_container → .fill(), chevron-down → ui.icons.chevron_down.

3. 3
   数值比对到对齐Diff until it matches

   导出设计稿（scale 2），用 tools/shot.ts 截取真实窗口，tools/design_diff.ts 给出位移、尺寸差、热力图与配色偏差，Agent 按提示修改；每轮约 5 秒。Export the design at scale 2, capture the real window with tools/shot.ts, and tools/design_diff.ts reports offset, size delta, a heat map and palette drift; the agent fixes from the hints, about 5 s per round.

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

怎么用Using it

不需要特殊语法。描述你要的界面或问题即可，下面是几个效果较好的提法：No special syntax. Describe the UI or the problem; here are a few prompts that work well:

用 Pencil MCP 读取当前 .pen 里的「Settings」画板，用 zenit 还原成设置窗口，design_diff 分数到 90 以上再交给我。
用 zenit 给这个 app 加一个设置窗口：左侧分类列表，右侧表单，改动实时生效。
把 src/views/sidebar.zig 里手写的样式迁移到 styles.zig + recipe。
文件树 5 万个节点时滚动卡顿，帮我查原因并修掉，修完截图给我看。

内容来源Where it comes from

Skill 的规则来自两个项目：zenit 框架本身（公开 API、示例、组件目录、测试工具），以及一个基于 zenit 开发的生产级 macOS 编辑器（大型应用的分层方式、原生集成和修复记录）。示例代码尽量取自这两个仓库中可编译的代码，并与本手册保持一致。The rules come from two projects: the zenit framework itself (public API, examples, component catalog, test tooling) and a production macOS editor built on zenit (large-app layering, native integration and fix history). Code samples are taken from compiling code in those repos where possible and match this manual.

源文件在官网仓库的 skill/zenit-ui-dev/，构建时由 scripts/pack-skill.mjs 打包。也可以直接阅读 SKILL.md。Sources live in the site repo under skill/zenit-ui-dev/ and are packed at build time by scripts/pack-skill.mjs. You can also read SKILL.md directly.