Communitygithub.com

pencil-generate-library:按顺序生成令牌、主题和组件

用于在 Pencil (pen.dev) 中构建或更新真实设计系统的工作流,通常从代码库生成:变量(颜色、间距、半径、字体)、亮色和暗色主题、可复用组件及其变体、状态、插槽、基础面板,以及可选的 .lib.pen 设计库。与 pencil-use 配合使用,当用户希望在 .pen 文件中获取令牌或组件时,即使是单个组件,也建议使用此技能,因为组件需要令牌基础和变体才能可用。触发词:“在 Pencil 中创建设计系统”、“将我的令牌导入 pen.dev”、“同步 CSS 变量 / Tailwind 主题到 Pencil”、“为 .pen 文件添加暗黑模式”、“在 Pencil 中构建按钮组件”、“创建组件库”、“为此组件制作变体”、“将此文件转换为库”、“使 Pencil 与代码保持一致”。它说明了要构建的内容和顺序(发现、令牌、文件布局、逐个组件、质量检查),并在各阶段之间设置了用户检查点。pencil-use 说明了如何调用工具。

pencil-generate-library:按顺序生成令牌、主题和组件 是什么?

此 AI 技能“pencil-generate-library”提供了一种结构化的、多阶段的工作流,用于在 Pencil (pen.dev) 中基于现有代码库(如 CSS 变量、Tailwind 配置或 DTCG 令牌文件)创建或更新设计系统。其核心原则是“这不是一次调用就能完成的”,而是将构建过程分解为 15 到 40 次甚至更多次的原子操作,确保设计系统的可构建性和可维护性。它遵循一个清晰的四阶段流程:发现(0 阶段):只读分析代码和现有 .pen 文件以识别令牌和组件;基础(1 阶段):创建结构化的变量(原始值、语义值)和主题(亮色/暗色模式);文件布局(2 阶段):在画布上组织区域,包括一个绑定到变量的动态基础面板;组件(3 阶段):逐个构建可复用组件,强调原子设计原则(原子、分子、有机体),并正确使用实例、变体(每个变体一个组件)、布尔值、图标切换和插槽。最后,质量检查与库(4 阶段)环节会执行令牌和绑定审计。每个阶段后都会有一个用户检查点,以便在继续之前验证进度。该技能擅长将代码中的设计决策映射到 Pencil 的独特模型,例如:使用主题轴实现亮/暗模式、通过变量实现别名、使用“/”命名约定实现变体、以及使用插槽实现可交换内容。它提供了详细的命令行界面 (CLI) 调用示例,例如使用 `SetVariables` 创建令牌和使用 `Insert`、`FindEmptySpace` 构建组件。该技能与“pencil-use”技能配对,后者保存着执行规则。所有主要平台(如 Claude Code、Cursor、Copilot、Codex 以及任何支持多步骤代理工作流的通用 AI 编码助手)都支持,因为其核心是 AI 代理可以执行的原子化、基于 shell 和 API 的调用序列。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/alekpixel/pencil-skills/tree/main/skills/pencil-generate-library

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

pencil-generate-library:按顺序生成令牌、主题和组件 是做什么的?

在 .pen 文件中构建与代码匹配的设计系统。先加载 pencil-use:它包含 execute 规则。此技能包含工作顺序和设计系统决策。

1. 最重要的规则

这从来不是一次调用就能完成的。 一个小型系统需要 15 到 40 次 execute 调用,更大的系统则需要更多。以最小的有用单元为单位工作,检查它,展示它,然后继续。一次性生成的系统会出错且难以修复。

2. Pencil 与其他工具的不同之处

使用 Pencil 的真实模型进行规划,而不是借用其他地方的模型:

需求在 Pencil 中
令牌类型为 color、number、string、boolean 的文档 variables,以 $name 形式引用
模式(亮色、暗色)主题轴。变量值是一个 {value, theme: {mode: "dark"}} 列表;框架通过其 theme 属性选择一个值
别名(语义到原始)一个值指向另一个变量的变量:value: "$gray-900"
文本样式无。使用字体变量(将 family、size、line height、weight 作为字符串或数字),并且如果适用,使用小的文本组件
阴影样式无。阴影效果接受用于颜色、模糊和偏移的变量
组件任何带有 reusable: true 的节点
变体无变体集。每个变体一个组件,使用斜杠命名:Button/Primary、Button/Outline
布尔选项(显示图标)在该部分的实例覆盖 enabled: false
可替换的图标在图标节点上的实例覆盖:{icon: "plus"}
可替换的内容组件内部的 slot 框架,带有推荐的组件 id
共享库在应用内转换为 .lib.pen 的文件(单向,不可撤销),由屏幕文件导入

3. 工作流

阶段 0  发现            读取代码和文件,不写入          -> 检查点:计划已批准
阶段 1  基础            变量和主题                     -> 检查点:令牌摘要已批准
阶段 2  文件布局        画布上的区域,基础面板          -> 检查点:面板截图已批准
阶段 3  组件            一次一个,原子先于分子          -> 每个组件后的检查点
阶段 4  质量检查与库    审核,修复,可选的 .lib.pen     -> 检查点:签署

在每个检查点命名下一个阶段。仅凭“看起来不错”的令牌评价并不能作为开始组件的批准。

阶段 0. 发现(只读)

0a. 在代码中找到令牌,按此顺序:

  1. CSS 自定义属性(:root { --background: ... }、.dark { ... } 或 [data-theme="dark"])。
  2. Tailwind 配置或 Tailwind v4 @theme 块。
  3. 令牌文件(DTCG .tokens.json、Style Dictionary)。
  4. CSS-in-JS 中的主题对象,或原生主题文件(iOS 资源目录、Android colors.xml)。

注意暗色模式机制、间距和半径比例、字体及类型比例,以及阴影。

0b. 在代码中找到组件:UI 原语列表(Button、Input、Checkbox、Badge、Avatar、Card...),它们的 props,哪些 props 是变体(variant、size、state),哪些是布尔值,哪些接受子元素。

0c. 读取文件:

Print(GetVariables())
Get(n => n.reusable && Print(n.id, "|", n.name))
Get(document, (n, c) => { if (c.depth === 1) { Print(n.id, "|", n.type, "|", n.name); c.skipChildren() } })

还要检查 get_app_state 以获取导入的库。匹配文件中已有的任何命名。

0d. 与用户锁定范围:此轮的确切令牌列表和确切组件列表。第一轮包含六到十个组件是一个不错的大小。

0e. 将代码映射到 Pencil 并解决冲突。 呈现一个表格:

代码令牌            Pencil 变量          亮色       暗色       状态
--background          --background          #FFFFFF    #0A0A0A    新建
--primary             --primary             #1D4ED8    #3B82F6    存在,值不同(询问)
组件                 Pencil 组件                                 状态
Button variant x size Button/Primary, Button/Secondary, Button/Outline, Button/Ghost (size via theme axis)   新建

当代码和文件不一致时,询问哪个获胜。不要独自决定。

检查点:显示计划,等待批准。

阶段 1. 基础

命名。 保持代码的名称以便设计和代码来回转换:CSS 变量 --muted-foreground 变为 Pencil 变量 --muted-foreground,以 $--muted-foreground 形式引用。永远不要以 $ 开头命名。避免在名称中使用 :。如果代码没有名称,请按角色使用短横线命名:surface、text、text-muted、border、accent、space-4、radius-md。

层级。

  • 原始值:原始值,无主题(gray-50 ... gray-950、blue-500、space-1 ... space-16)。
  • 语义值:角色名称,带主题,指向原始值(--background:亮色 $white,暗色 $gray-950)。
  • 组件仅使用语义值。直接引用 $gray-900 的组件将不随主题切换。

系统大小。

  • 少于约 50 个令牌:一个扁平集合,一个带有 light 和 dark 的 mode 轴。
  • 更大:如上所述的原始值加语义值,并且仅在代码确实具有时才添加额外的主题轴(density: comfortable, compact;brand: a, b)。

分批写入,每次调用写入一个系列(原始颜色,然后是语义颜色,然后间距和半径,然后字体),并读回:

SetVariables({
  "gray-50": {type: "color", value: "#FAFAFA"},
  "gray-900": {type: "color", value: "#171717"},
  "gray-950": {type: "color", value: "#0A0A0A"},
  "white": {type: "color", value: "#FFFFFF"}
})
SetVariables({
  "--background": {type: "color", value: [{value: "$white", theme: {mode: "light"}}, {value: "$gray-950", theme: {mode: "dark"}}]},
  "--foreground": {type: "color", value: [{value: "$gray-900", theme: {mode: "light"}}, {value: "$gray-50", theme: {mode: "dark"}}]}
})
const v = GetVariables()
Print(Object.keys(v.variables).length, "variables", "|", JSON.stringify(v.themes))
  • 检查 mode 轴的第一个值是否是产品使用的默认值(通常是 light)。
  • 为你使用的每个主题值给每个主题变量提供一个值。缺失的值会静默地显示错误的颜色。
  • 对于不应更改的值(间距、半径),在各主题之间保持相同的值。
  • 排版:--font-sans(字符串),大小(text-sm 14,text-base 16...),行高作为比率(leading-normal 1.5),字重作为字符串("400","600")。
  • 阴影:一个用于阴影颜色的主题颜色变量,以及如果代码有阴影比例,用于模糊和偏移的数字变量。
  • 永远不要在没有明确同意的情况下对现有文件使用 SetVariables(..., true):它会清除每个变量。

退出标准:计划中的每个令牌都已存在且类型正确,每个主题令牌都具有每个主题值,别名指向现有变量。

检查点:显示每个系列的数量、主题轴以及你不得不猜测的任何值。

阶段 2. 文件布局和基础面板

保持画布清晰易读:

  • 一个基础框架位于左上角:色板、字体样本、间距条、半径示例。
  • 一个组件区域位于其右侧或下方,每个组件系列一个框架(Buttons、Inputs、Cards),包含带有标题和简短用法说明的组件。
  • 屏幕放在更下方和右侧,切勿与组件混合。
  • 每个根框架使用 FindEmptySpace。

色板和样本必须绑定到变量,这样令牌更改时面板才会更新。使用循环构建色板:

boardId = Insert(document, {type: "frame", name: "Foundations / Color", layout: "vertical", gap: 16, padding: 32, fill: "$--background", x: 0, y: 0})
rowId = Insert(boardId, {type: "frame", name: "Semantic colors", gap: 16})
for (const name of ["--background", "--foreground", "--primary", "--muted", "--border"]) {
  const s = Insert(rowId, {type: "frame", name: "Swatch " + name, layout: "vertical", gap: 8})
  Insert(s, {type: "rectangle", name: "Chip", width: 96, height: 64, cornerRadius: 8, fill: "$" + name, stroke: "$--border", strokeWidth: 1})
  Insert(s, {type: "text", name: "Label", content: name, fontSize: 12, fill: "$--foreground"})
}
TakeScreenshot([boardId])

然后在旁边复制一个带有 theme: {mode: "dark"} 的面板:如果任何部分保持亮色,则表示某个令牌缺少其暗色值。

检查点:两种主题下面板的截图。

阶段 3. 组件,一次一个

按依赖关系排序:先原子(Icon 包装器、Badge、Avatar、Button、Input、Checkbox、Toggle),然后是分子(带有标签和提示的 Input 组、菜单项、Tab),然后是有机体(Card、Dialog、Sidebar、Table row)。包含另一个组件的组件必须在其之后构建,并且必须包含其实例,而不是重新绘制的副本。

对于每个组件:

3a. 在绘制之前设计 API。 来自代码 props:

  • 改变颜色或结构的变体轴成为单独的组件:Button/Primary、Button/Secondary、Button/Outline、Button/Ghost、Button/Destructive。
  • 仅改变令牌值的轴(大小、密度)可以成为主题轴而不是更多组件:带主题的数字变量,如 button-padding-y 和 button-padding-x,具有 size: md, sm, lg(第一个值是默认值)。然后一个组件通过实例上的 theme: {size: "sm"} 服务于每种大小。业经验证且有效。当代码以相同方式工作时使用它;否则也要制作大小组件。
  • 全局开关(在模拟中显示或隐藏每个徽章)可以是一个绑定到 enabled: "$show-badge" 的布尔变量。它会一次更改每个实例,因此将其保留用于演示切换,而不是用于每个实例的选项。
  • 保持计数合理。如果变体乘以大小乘以状态超过大约 30 个组件,则拆分系列或将一个轴移动到主题。
  • 状态:仅当用户想要显示它们时,才创建 Disabled 或 Focus 组件;悬停和按下状态通常只记录。
  • 布尔值(带图标,带提示)不是变体:构建完整组件,并使用 enabled: false 隐藏每个实例的部分。
  • 图标不是变体:一个图标节点,使用 icon 覆盖进行交换。
  • 自由内容区域是插槽:一个带有 slot: [recommendedComponentIds]、width: "fill_container" 和固定高度(例如 height: 40)的框架。一个由 fit_content 确定大小的空插槽会收缩到零并消失。

3b. 在一次调用中构建基础组件:一个带有 reusable: true、布局、填充、间距、半径和填充全部来自变量的框架,命名子元素(Label、Icon、Content)。将其 id 及其子 id 捕获到全局变量中。

const pos = FindEmptySpace({width: 600, height: 200, direction: "right", padding: 80})
buttonsId = Insert(document, {type: "frame", name: "Buttons", layout: "vertical", gap: 24, padding: 32, x: pos.x, y: pos.y})
btnPrimaryId = Insert(buttonsId, {type: "frame", name: "Button/Primary", reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill: "$--primary", alignItems: "center", justifyContent: "center"})
btnIconId = Insert(btnPrimaryId, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: "$--primary-foreground"})
btnLabelId = Insert(btnPrimaryId, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: "$--primary-foreground"})
TakeScreenshot([btnPrimaryId])

3c. 构建其他变体。 组件的 Copy 生成一个实例,而不是新组件。要获得独立的变体组件,请在一次调用中使用一个小型辅助函数,遍历变体表来重建每个组件:

const make = (name, fill, fg, stroke) => {
  const id = Insert(buttonsId, {type: "frame", name, reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill, alignItems: "center", justifyContent: "center", ...(stroke ? {stroke, strokeWidth: 1} : {})})
  Insert(id, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: fg})
  Insert(id, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: fg})
  return id
}
btnSecondaryId = make("Button/Secondary", "$--secondary", "$--secondary-foreground")
btnOutlineId = make("Button/Outline", "$--background", "$--foreground", "$--border")
btnGhostId = make("Button/Ghost", "#00000000", "$--foreground")

保持子元素名称在各变体之间相同(Label、Icon),以便可以按名称覆盖实例,并且变体交换保持可用。

3d. 在其系列框架内以可读的网格布局该系列:每个变体一行,每个大小或状态一列,带有小文本标题。使用带有 gap 的行框架,永远不要使用绝对位置。

3e. 记录它:在系列框架中放置一个标题和两到三行用法说明(何时使用哪个变体,一个主要操作规则)。

3f. 检查它:

  • 对系列框架进行硬编码检查:没有十六进制填充,除非是有意的透明填充(#00000000 作为 ghost 变体的透明填充是有效的)。
  • 调用的 issues detected 块(折叠的框架,空的插槽)。在当前版本中,ctx.problems 裁剪检查会给出误报:通过截图确认。
  • 实例测试:在草稿框架中插入每个变体的一个实例,用长文本覆盖标签并隐藏图标,然后在亮色和暗色下(在草稿框架上使用 theme)截图。之后删除草稿框架。

每个组件的检查点:截图、变体列表和 id。未经批准,不要开始下一个组件。

阶段 4. 质量检查与库

  1. 令牌审计:组件使用的每个变量都存在;每个主题变量都具有每个主题值。
  2. 绑定审计:组件内没有十六进制颜色或原始间距,除非是列为有意的值。
  3. 对比度:文本在两种主题下与其背景的对比度(正文文本为 4.5:1,大文本为 3:1)

...

[为翻译而截断]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能