Communitygithub.com

pencil-generate-library

從程式碼建立或更新 Pencil (pen.dev) 中的真實設計系統工作流程:變數、主題、元件及 .lib.pen 設計庫。需搭配 pencil-use 使用。

pencil-generate-library 是什麼?

此技能提供一個結構化工作流程,用於在 Pencil (pen.dev) 中從現有程式碼庫(CSS、Tailwind、DTCG 代幣等)建立或更新真實的設計系統。它不僅僅是匯入代幣,而是指導 AI 代理逐步完成發現、基礎建設(變數和主題)、檔案佈局、逐個元件建立以及品質保證階段,在每個階段之間的檢查點尋求使用者批准。該技能詳細解釋了 Pencil 的獨特模型——例如使用帶有主題值的變數、無文字/陰影樣式、每個變體一個元件以及插槽和圖示覆蓋機制——以確保設計系統在平台上能正常運作。輸出是一個功能性的 `.pen` 檔案,包含綁定到變數的基礎板、一組遵循依賴順序的程式碼匹配元件,以及可選擇的 `.lib.pen` 庫檔案。它支援 Claude Code、Cursor 和任何可執行自訂代理技能的 AI 編碼工具,主要用於前端開發人員和設計工程師,以保持設計與程式碼之間的同步。

相容平台~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"
文字樣式無。使用字體變數(系列、大小、行高、粗細作為字串或數字),如有需要可使用小型文字元件
陰影樣式無。陰影效果接受顏色、模糊和偏移的變數
元件任何帶有 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 變體 x 尺寸   Button/Primary、Button/Secondary、Button/Outline、Button/Ghost(尺寸透過主題軸)   新增

當程式碼和檔案不一致時,詢問哪個優先。不要獨自決定。

檢查點:顯示計畫,等待批准。

階段 1. 基礎

命名。 保留程式碼的名稱,以便設計和程式碼可以來回轉換:CSS 變數 --muted-foreground 變成 Pencil 變數 --muted-foreground,以 $--muted-foreground 方式引用。永遠不要以 $ 開頭命名。避免在名稱中使用 :。如果程式碼沒有名稱,請根據角色使用簡短的 kebab 名稱: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. 元件,一次一個

按依賴關係排序:原子先(圖示包裝器、Badge、Avatar、Button、Input、Checkbox、Toggle),然後分子(帶標籤和提示的輸入群組、選單項目、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"} 服務於每個大小。已測試並可正常運作。當程式碼以相同方式工作時使用它;否則,也請為大小建立元件。
  • 一個全域開關(在模型圖中顯示或隱藏每個 Badge)可以是綁定到 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 可作為幽靈變體的透明填充)。
  • 呼叫的 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.

相關技能