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. 尋找程式碼中的代幣,按此順序:
- CSS 自訂屬性(
:root { --background: ... }、.dark { ... }或[data-theme="dark"])。 - Tailwind 設定檔或 Tailwind v4
@theme區塊。 - 代幣檔案(DTCG
.tokens.json、Style Dictionary)。 - 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-sm14、text-base16...)、行高作為比率(leading-normal1.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. 品質保證和庫
- 代幣審計:元件使用的每個變數都存在;每個有主題的變數都有每個主題值。
- 綁定審計:元件內部沒有十六進制顏色或原始間距,除非是刻意列出的值。
- 對比度:文字在其背景上的對比度,兩種主題下均需檢查(正文文字為 4.5:1,大文字為 3:1 ...
[為翻譯而截斷]