pencil-design

Pencil 设计技能

在 Pencil 中设计可用于生产环境的高质量 UI，并据此生成整洁、易维护的代码。此技能强调设计系统复用、变量使用、布局正确性、视觉验证以及设计转代码工作流方面的最佳实践。

何时使用此技能

• 在 .pen 文件中设计屏幕、页面或组件
• 根据 Pencil 设计生成代码（React、Next.js、Vue、Svelte、HTML/CSS）
• 在 Pencil 中构建或扩展设计系统
• 在 Pencil 和代码之间同步设计令牌（Tailwind v4 @theme、shadcn/ui 令牌）
• 将现有代码导入 Pencil 设计
• 使用任何 Pencil MCP 工具（pencil_batch_design、pencil_batch_get 等）

关键规则

这些规则针对 Agent 最常犯的错误。违反规则会导致设计不一致、难以维护，并生成质量不佳的代码。

规则 1：始终复用设计系统组件

如果设计文件中已有组件，切勿从头重新创建。

插入任何元素之前，必须：

1. 调用 pencil_batch_get，并使用 patterns: [{ reusable: true }] 列出所有可用的可复用组件
2. 在结果中搜索符合需求的组件（按钮、卡片、输入框、导航等）
3. 如果找到匹配项，将其作为 ref 实例插入，使用 I(parent, { type: "ref", ref: "<componentId>" })
4. 通过更新实例的后代节点来自定义实例，使用 U(instanceId + "/childId", { ... })
5. 仅当不存在合适的可复用组件时，才从头创建新组件

详细工作流请参阅 references/design-system-components.md。

规则 2：始终使用变量，而非硬编码值

如果存在变量，切勿硬编码颜色、边框圆角、间距或字体排版值。

应用任何样式值之前，必须：

1. 调用 pencil_get_variables 读取所有已定义的设计令牌
2. 将预期值映射到现有变量（例如，使用 primary，而非 #3b82f6；使用 radius-md，而非 6）
3. 使用变量引用应用值，而不是直接填写原始值
4. 生成代码时，使用 Tailwind v4 语义化实用类（例如 bg-primary、text-foreground、rounded-md）。切勿使用任意值语法（bg-[#3b82f6]、text-[var(--primary)]、rounded-[6px]）

详细工作流请参阅 references/variables-and-tokens.md。

规则 3：防止文本和内容溢出

切勿让文本或子元素溢出其父元素或画板。

对每个文本元素和容器：

1. 设置合适的文本换行和截断方式
2. 将宽度限制在父元素边界内，尤其是在移动屏幕上（通常宽 375px）
3. 对自动布局框架内文本元素的宽度使用 "fill_container"
4. 插入内容后，调用 pencil_snapshot_layout 并设置 problemsOnly: true，以检测裁切或溢出
5. 继续操作前，先修复所有报告的问题

详细工作流请参阅 references/layout-and-text-overflow.md。

规则 4：对每个区域进行视觉验证

完成一个区域或屏幕后，切勿跳过视觉验证。

完成每个逻辑区域（页眉、主视觉区、侧边栏、表单、卡片网格等）后：

1. 对该区域或整个屏幕节点调用 pencil_get_screenshot
2. 检查截图中是否存在对齐问题、间距不一致、文本溢出、视觉异常或内容缺失
3. 调用 pencil_snapshot_layout 并设置 problemsOnly: true，检查裁切和重叠
4. 前往下一个区域之前，修复发现的所有问题
5. 整个设计完成后，截取一张最终的全屏截图

详细工作流请参阅 references/visual-verification.md。

规则 5：复用现有资源（徽标、图标、图像）

如果文档中已有徽标或资源，绝对不要生成新的徽标或重复资源。

生成任何图像或徽标之前：

1. 调用 pencil_batch_get，按名称模式搜索现有图像／徽标节点（例如：patterns: [{ name: "logo|brand|icon" }]）
2. 如果文档中的其他位置（另一画板／屏幕）存在匹配资源，使用 C()（复制）操作将其复制过来
3. 只有对于文档中确实不存在的全新图像，才使用 G()（生成）操作
4. 对于徽标：始终从现有实例复制，绝不重新生成

详细工作流请参阅 references/asset-reuse.md。

规则 6：始终加载 frontend-design 技能

未先加载 frontend-design 技能，绝对不要在 Pencil 中进行设计，也不要从 Pencil 生成代码。

frontend-design 技能提供美学方向和设计质量标准，避免生成千篇一律、缺乏特色的 UI。你必须：

1. 在任何 Pencil 设计或代码生成任务开始时加载 frontend-design 技能
2. 遵循其设计思考流程：理解用途、确定鲜明的美学方向，并考虑如何体现差异化
3. 在 Pencil 中进行设计和从 Pencil 设计生成代码时，都应用其关于排版、色彩、动效、空间构图和视觉细节的准则
4. 绝不采用千篇一律的 AI 美学（过度使用的字体、陈腐的配色方案、可预测的布局）

这适用于以下两种情况：

• Pencil 设计任务：运用该技能的美学准则，指导 .pen 文件中的布局、排版、色彩和构图选择
• 从 Pencil 生成代码：运用该技能的准则，确保生成的代码包含鲜明的排版、有意设计的主题色、动效／动画和精致的视觉细节，而非仅仅机械地转换设计树

设计工作流

开始新设计

0. Load `frontend-design` skill   -> Get aesthetic direction and design quality standards
1. pencil_get_editor_state        -> Understand file state, get schema
2. pencil_batch_get (reusable)    -> Discover design system components
3. pencil_get_variables           -> Read design tokens
4. pencil_get_guidelines          -> Get relevant design rules
5. pencil_get_style_guide_tags    -> (optional) Get style inspiration
6. pencil_get_style_guide         -> (optional) Apply style direction
7. pencil_find_empty_space_on_canvas -> Find space for new screen
8. pencil_batch_design            -> Build the design (section by section)
9. pencil_get_screenshot          -> Verify each section visually
10. pencil_snapshot_layout        -> Check for layout problems

逐个构建区块

对于屏幕的每个区块（页眉、内容区域、页脚、侧边栏等）：

1. 规划 - 确定要复用哪些设计系统组件
2. 构建 - 将组件作为 ref 实例插入，并应用变量设置样式
3. 验证 - 截取该区块的屏幕截图，并检查布局是否存在问题
4. 修复 - 解决溢出、对齐或间距问题
5. 继续 - 仅在验证通过后再进入下一个区块

设计到代码工作流

完整工作流请参阅 references/design-to-code-workflow.md。 完整的 Pencil 到 Tailwind 映射表请参阅 references/tailwind-shadcn-mapping.md。 多画板响应式代码生成请参阅 references/responsive-breakpoints.md。

摘要：

1. 加载 frontend-design 技能以确定美学方向
2. 使用主题 "code" 和 "tailwind" 调用 pencil_get_guidelines
3. 调用 pencil_get_variables，将设计令牌映射到 Tailwind @theme 声明
4. 使用 pencil_batch_get 读取设计树
5. 将可复用的 Pencil 组件映射到 shadcn/ui 组件（Button、Card、Input 等）
6. 使用语义化 Tailwind 类（bg-primary、rounded-md）生成代码，绝不使用任意值
7. 应用 frontend-design 准则：鲜明的排版、有意设计的色彩、动效和空间构图
8. 对自定义组件变体使用 CVA，使用 cn() 合并类，并使用 Lucide 图标

MCP 工具速查表

工具	使用时机
pencil_get_editor_state	首次调用——了解文件状态并获取 .pen 架构
pencil_batch_get	读取节点、搜索组件（reusable: true）、检查结构
pencil_batch_design	插入、复制、更新、替换、移动、删除元素；生成图像
pencil_get_variables	读取设计令牌（颜色、圆角、间距、字体）
pencil_set_variables	创建或更新设计令牌
pencil_get_screenshot	对任意节点进行视觉验证
pencil_snapshot_layout	检测裁切、溢出、元素重叠
pencil_get_guidelines	获取以下方面的设计规则：code、table、tailwind、landing-page、design-system
pencil_find_empty_space_on_canvas	为新屏幕/画板查找空白区域
pencil_get_style_guide_tags	浏览可用的风格方向
pencil_get_style_guide	获取特定的风格灵感
pencil_search_all_unique_properties	审查整个文档中的属性值
pencil_replace_all_matching_properties	批量更新属性（例如，替换颜色）
pencil_open_document	打开 .pen 文件或创建新文档

应避免的常见错误

错误	正确做法
从头创建按钮	搜索现有按钮组件，并以 ref 形式插入
使用 fill: "#3b82f6"	使用变量：引用 primary 或对应的变量
使用 cornerRadius: 8	使用变量：引用 radius-md 或对应的变量
在代码中生成 bg-[#3b82f6]	使用语义化 Tailwind 类：bg-primary
在代码中生成 text-[var(--primary)]	使用语义化 Tailwind 类：text-primary
在代码中生成 rounded-[6px]	使用语义化 Tailwind 类：rounded-md
在 className 中使用 var(--primary)	使用语义化 Tailwind 类：bg-primary 或 text-primary
未检查溢出	每完成一个部分后，调用 pencil_snapshot_layout(problemsOnly: true)
跳过截图	每完成一个部分后，调用 pencil_get_screenshot
生成新 Logo	使用 C() 从其他画板复制现有 Logo
构建完整屏幕后再检查	按部分构建并逐一验证
忽略 pencil_get_guidelines	开始前，务必针对相关主题调用此工具
使用 tailwind.config.ts	使用 CSS @theme 块（Tailwind v4）
在代码中使用 Material Icons	映射为 Lucide 图标（<Search />、<ArrowRight /> 等）
跳过 frontend-design 技能	在 Pencil 中进行设计或生成代码前，务必先加载该技能
使用泛化的 AI 审美（Inter 字体、紫色渐变）	遵循 frontend-design 指南，打造独特且经过精心设计的作品

资源

• Pencil 文档
• Pencil 提示词库
• 设计即代码
• 变量
• 组件
• 设计转代码
• 样式和 UI 套件