pencil-skill

pencil-skill

1）概述

Pencil 是一款使用基于 JSON 的 .pen 格式的设计工具。 由于 .pen 适合 Git 管理，因此非常适合 Agent 直接创建和修改。 关键不在于通用 JSON 语法，而在于 Pencil 特有的规则（ref、slot、textGrowth、变量绑定）。

2）核心文档结构

{
  "version": "2.8",
  "themes": {
    "mode": [
      "light",
      "dark"
    ]
  },
  "variables": {
    "color.surface": {
      "type": "color",
      "value": [
        {
          "theme": {
            "mode": "light"
          },
          "value": "#FFFFFF"
        },
        {
          "theme": {
            "mode": "dark"
          },
          "value": "#111827"
        }
      ]
    }
  },
  "children": []
}

• 必须包含 version 和 children
• themes 和 variables 是可选项，但对于设计系统而言实际上必不可少

3）对象类型列表

• rectangle：基本矩形
• ellipse：圆形／弧形
• line：线条
• polygon：多边形
• path：路径几何图形
• text：文本
• frame：布局容器，也可以声明插槽
• group：分组容器
• note：注释
• prompt：提示词备忘
• context：上下文备忘
• icon_font：基于图标字体的矢量图标
• ref：可复用组件实例

4）布局（摘要）

只需记住这些核心属性：

• layout：none | vertical | horizontal
• gap、padding
• justifyContent：start | center | end | space_between | space_around
• alignItems：start | center | end

注意事项：

• 在 flex（vertical／horizontal）容器中，子项的 x、y 值实际上会被忽略

实用的 frame 属性

属性	类型	说明
clip	boolean	当值为 true 时，裁剪超出 frame 边界的内容。默认为 false

通用实体属性（适用于所有节点类型）

属性	类型	说明
enabled	boolean	当值为 false 时隐藏节点（适用于所有实体，而非仅适用于 frame）

[
  {
    "type": "frame",
    "id": "modal-overlay",
    "clip": true,
    "layout": "vertical"
  },
  {
    "type": "frame",
    "id": "hidden-panel",
    "enabled": false,
    "layout": "vertical"
  }
]

5）SizingBehavior

• fit_content
• fill_container
• fit_content(${number})

width 和 height 可以使用数字、变量或上述 SizingBehavior 值。

6）图形基础

• fill：颜色／渐变／图像／mesh_gradient
• stroke：align、thickness、join、cap、dashPattern、fill
• effect：blur、background_blur、shadow

建议使用十六进制格式的颜色值（#RGB、#RRGGBB、#RRGGBBAA）。

7）文本规则（重要）

• 对 text，请先设置 textGrowth
• textGrowth：auto | fixed-width | fixed-width-height
• 如果不设置 textGrowth 就设置 width／height，相关行为可能会被忽略或表现不一致

8）组件（reusable + ref + descendants + slot）

定义组件

• 在 frame（或其他实体）中添加 reusable: true
• 其 id 将作为组件键

创建实例

• type: "ref"
• ref: "<reusable id>"

descendants 覆盖

• 键为子项的 id 值
• 使用斜杠路径访问深层子项："container/button/label"

slot 模式

• 在组件中声明 slot: ["body"]
• 创建一个内部 frame，并设置 name: "body"
• 通过 ref.children 注入内容

9）变量

绑定格式：

• "$variable.name"

示例：

{
  "fill": "$color.surface",
  "padding": "$space.card.padding"
}

验证要点：

• $ 后面的键必须存在于 variables 中
• 使用基于主题的变量值时，必须与 themes 的轴和值匹配

10）IconFont

支持的系列：

• lucide
• feather
• Material Symbols Outlined
• Material Symbols Rounded
• Material Symbols Sharp
• phosphor

11）禁止的模式

模式	结果
id 中包含 /（例如 "a/b"）	❌ 无效
同一文件中存在重复的 id 值	❌ 无效
ref 指向不存在的 reusable id	❌ 无效
文本未设置 textGrowth 却设置 width/height	⚠️ 警告（可能会被忽略）
引用 "$unknown.var"	⚠️ 警告（变量未解析）

关键规则

这些规则可以避免 Agent 最常犯的错误。

规则 1：必须复用组件

如果存在匹配的可复用组件，必须使用 ref 复用它。

1. 使用 search-nodes.mjs --reusable 检查可用组件
2. 如果存在匹配的组件，将其作为 ref 实例插入
3. 使用 descendants 自定义
4. 仅在不存在匹配组件时才创建新组件

规则 2：变量是必需的

禁止硬编码。 颜色、间距和排版必须使用变量。

1. 使用 get-variables.mjs 检查现有变量
2. 以 "$variable.name" 格式引用值
3. 如果需要新变量，先使用 set-variables.mjs 注册

规则 3：防止文本溢出

对于每个文本节点：

1. 先设置 textGrowth（auto 或 fixed-width）
2. 如果父级 frame 有布局，宽度使用 fill_container
3. 编辑后使用 validate-pen.mjs 验证

规则 4：更改后始终验证

每次修改后：

1. 使用 validate-pen.mjs 验证结构和 lint
2. 使用 read-tree.mjs --depth 2 检查结构

规则 5：重复利用资源

对于 logo、图片和图标：

1. 使用 search-nodes.mjs --name "logo|brand|icon" 搜索现有资源
2. 如果找到，使用 batch-design.mjs 的 copy 操作复制
3. 仅在没有现有资源时创建新资源

12）创建必需检查清单

• 根节点存在 version 和 children
• id 唯一且不使用斜杠
• 每个 ref 对应的目标可复用组件均存在
• variables 引用与实际键（$...）一致
• 在对文本使用 width/height 前设置 textGrowth
• 使用 slot 时，确认 slot 声明、name frame 和 ref.children 注入关系
• 根据需要检查主题轴／值的一致性

属性别名

架构在 $defs 中定义了单数和复数形式。 在节点属性中，标准键为单数：

• fill（值可以是单个填充或数组）
• stroke（值可以是单个描边或数组）
• effect（值可以是单个效果或数组）

脚本接受复数形式（fills、strokes、effects），并在写入时将其规范化为单数键。

AGENTS.md（Agent 指南）

AGENTS.md 是一份简明指南，包含规则摘要以及指向各个 rules/*.md 文件的详细说明链接。编辑规则后重新生成：node scripts/compile-agents.mjs

CLI 工具

这些脚本可直接操作 .pen 文件，无需 MCP。

读取工具

脚本	用途	用法
read-tree.mjs	打印节点树结构	node scripts/read-tree.mjs file.pen [--depth 2] [--id nodeId]
search-nodes.mjs	搜索节点	node scripts/search-nodes.mjs file.pen --type frame [--reusable] [--name regex]
get-variables.mjs	查看变量／主题	node scripts/get-variables.mjs file.pen [--format json]
find-space.mjs	查找空白区域坐标	node scripts/find-space.mjs file.pen --width 300 --height 200

写入工具

脚本	用途	用法
batch-design.mjs	插入／更新／删除／移动／复制节点	node scripts/batch-design.mjs file.pen --ops '[{"op":"update","id":"node1","props":{"name":"Header"}}]'
replace-props.mjs	批量替换属性	node scripts/replace-props.mjs file.pen --match '{"fill":"#FF0000"}' --replace '{"fill":"$color.primary"}'
set-variables.mjs	添加／更新变量	node scripts/set-variables.mjs file.pen --var 'name=type:value'

set-variables.mjs 主题语法（@theme）：

# Single value
node scripts/set-variables.mjs file.pen --var 'color.primary=color:#0D9488'

# Per-theme variable setting — @theme syntax
node scripts/set-variables.mjs file.pen --var 'color.bg=color:#FFFFFF@light,#0F172A@dark'
node scripts/set-variables.mjs file.pen --var 'space.md=number:12'

验证工具

脚本	用途	用法
validate-pen.mjs	结构验证 + 值类型检查 + lint	node scripts/validate-pen.mjs file.pen

batch-design 操作

batch-design.mjs 接受 JSON 数组形式的操作：

insert — 插入新节点

{
  "op": "insert",
  "parentId": "frame-1",
  "node": {
    "type": "text",
    "id": "title",
    "content": "Hello",
    "textGrowth": "auto"
  }
}

update — 更新属性（深度合并）

{
  "op": "update",
  "id": "title",
  "props": {
    "content": "Updated",
    "fill": "$color.primary"
  }
}

delete — 删除节点

{
  "op": "delete",
  "id": "title"
}

move — 移动到其他父级

{
  "op": "move",
  "id": "title",
  "toParentId": "frame-2",
  "index": 0
}

copy — 复制节点

{
  "op": "copy",
  "id": "card-1",
  "newId": "card-2",
  "toParentId": "grid"
}

注意：

• toParentId 为可选项。若省略，复制的节点将插入根级别。
• 复制时，所有内部子节点 id 必须保持唯一 → 建议使用 newId 前缀
• 一次不要发送过多操作（建议不超过 25 个）
• 自动创建备份（.pen.bak）

标准工作流

1. read-tree.mjs          → Inspect current structure
2. search-nodes.mjs       → Search reusable components
3. get-variables.mjs      → Check variables/themes
4. find-space.mjs         → Calculate frame placement coordinates
5. batch-design.mjs       → Create/modify nodes
6. validate-pen.mjs       → Validate results

设计规则

生产级设计的必备规则。共 41 条规则，分为 8 个类别。

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	布局与溢出	CRITICAL	layout-	8
2	设计令牌	CRITICAL	token-	5
3	反 AI 美学	HIGH	aesthetic-	6
4	组件系统	HIGH	component-	5
5	字体排版	MEDIUM	typo-	5
6	色彩系统	MEDIUM	color-	4
7	间距系统	MEDIUM	spacing-	4
8	展示与样式指南	MEDIUM	showcase-	4

快速参考

1. 布局与溢出（CRITICAL）

• layout-auto-layout — 所有容器都必须使用自动布局
• layout-sizing — 根据场景设置宽度和高度规则
• layout-overflow — 防止溢出的检查清单
• layout-responsive — 响应式模拟（单独的画框）
• layout-spacing-consistency — 保持间距和内边距一致
• layout-z-order — Z 顺序与叠加元素的放置
• layout-no-overlap — 防止元素重叠
• layout-canvas-placement — 顶层画布的放置，不得与图层重叠

2. 设计令牌（CRITICAL）

• token-naming — 命名格式：$category.purpose.variant
• token-semantic-colors — 必须使用语义化色彩系统
• token-theme-required — 必须提供浅色和深色主题
• token-no-hardcode — 禁止硬编码
• token-workflow — 令牌设置工作流

3. 反 AI 美学（HIGH）

• aesthetic-layout — 避免看起来像 AI 生成的布局
• aesthetic-typography — 避免看起来像 AI 生成的字体选择
• aesthetic-color — 避免看起来像 AI 生成的配色
• aesthetic-decoration — 避免看起来像 AI 生成的装饰
• aesthetic-content — 避免看起来像 AI 生成的内容
• aesthetic-checklist — 自查清单

4. 组件系统（HIGH）

• component-atomic — 应用原子设计
• component-naming — 遵循 Figma 标准命名
• component-variant — 变体模式
• component-slot — 插槽模式
• component-reuse-first — 优先复用组件

5. 字体排版（MEDIUM）

• typo-scale — 定义字体比例
• typo-weight — 字重使用规则
• typo-pairing — 字体搭配指南
• typo-line-height — 行高规则
• typo-text-rules — 文本布局规则

6. 色彩系统（MEDIUM）

• color-semantic — 语义化色彩系统
• color-accessibility — WCAG 2.1 AA 无障碍要求
• color-ratio — 60-30-10 色彩比例
• color-dark-mode — 深色模式规则

7. 间距系统（MEDIUM）

• spacing-8pt-grid — 8pt 网格系统
• spacing-proximity — 接近性原则
• spacing-padding — 内边距系统
• spacing-forbidden — 禁止使用的模式

8. 展示与样式指南（MEDIUM）

• showcase-pre-design — 必须遵循的设计前流程
• showcase-design-system — 设计系统优先原则
• showcase-frame — 展示画框模式
• showcase-final-checklist — 最终 QA 检查清单

使用方法

查看各规则文件，了解详细说明和代码示例：

rules/layout-auto-layout.md
rules/token-naming.md
rules/aesthetic-layout.md

包含规则摘要的 Agent 指南：AGENTS.md — 完整规则见 rules/*.md

参考资料

架构与类型

• pen-schema.json：官方 JSON Schema（v2.8）
• pen-types.ts：TypeScript 类型定义

转换指南

• pen-to-tailwind.md：.pen → Tailwind CSS 转换表
• component-patterns.md：UI 组件模式

示例

• example-card.pen：完整的 .pen 文件示例
• reddit-ui.pen：采用可复用组件的 Reddit 风格三栏 UI 布局