Pencil Pro
主要解析規則
此技能必須在首次使用前進行設定。
如果使用者說「執行 PencilPlaybook 設定精靈」或要求設定或配置 PencilPlaybook:
→ 請閱讀 .claude/skills/pencilplaybook/setup.md 並確實遵循當中的指示。
如果使用者說「用 PencilPlaybook 建立我的第一個畫面」或要求開始設計:
→ 請閱讀 .claude/skills/pencilplaybook/onboarding.md 並確實遵循當中的指示。
設定好的解析度:(執行設定以設定此項)
如果現有 .pen 檔案中的畫面根節點與您設定的解析度不符,請在編輯前先註明。請勿忽略此偏差而在錯誤尺寸的畫布上繼續建構。
常見例外——行銷頁面: 無論應用程式的解析度為何,一律以 1440px 進行設計。行銷頁面會在各種瀏覽器寬度下被瀏覽——以 1440px 設計,並以 390px 驗證。
工作階段啟動(每個 Pencil 工作階段)
1. get_editor_state() — 檢查使用中的文件和選取範圍
2. open_document("path/to/your-file.pen") — 開啟目標檔案
3. get_guidelines(topic="web-app") — 載入設計指南
4. set_variables(<token map below>) — 注入品牌 Token
5. get_variables() — 確認 Token 已儲存
6. snapshot_layout() — 驗證畫布尺寸
您的 Token 對應表 — 請在每次工作階段開始時使用此物件執行 set_variables。Token 可能在 Claude Code 工作階段之間無法持續保留。
{
"color-primary": "YOUR_HEX",
"color-primary-dark": "YOUR_HEX",
"color-accent": "YOUR_HEX",
"color-background": "YOUR_HEX",
"color-surface": "YOUR_HEX",
"color-border": "YOUR_HEX",
"color-text": "YOUR_HEX",
"color-text-muted": "YOUR_HEX",
"color-success": "YOUR_HEX",
"color-warning": "YOUR_HEX",
"color-error": "YOUR_HEX",
"font-sans": "YOUR_FONT",
"font-mono": "YOUR_FONT",
"font-serif": "YOUR_FONT",
"spacing-card": "24",
"spacing-gap-sm": "8",
"spacing-gap-md": "16",
"spacing-gap-lg": "24",
"spacing-gap-xl": "32",
"content-max-width": "YOUR_VALUE",
"sidebar-width": "YOUR_VALUE"
}
在執行 set_variables 後,請呼叫 get_variables() 以確認所有 Token 都已儲存。
鷹架腳本
九個涵蓋最常見佈局原型的鷹架腳本。請執行設定精靈來填入下方的尺寸與顏色值,然後再使用。
鷹架 A — 應用程式儀表板
指標、KPI、活動饋送、監控
sidebar=I("root", {name:"Sidebar", width:SCAFFOLD_SIDEBAR_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"SIDEBAR_BG", display:"flex", flexDirection:"column"})
pageArea=I("root", {name:"PageArea", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, x:SCAFFOLD_SIDEBAR_WIDTH, bg:"PAGE_BG"})
pageHeader=I("pageArea", {name:"PageHeader", width:SCAFFOLD_PAGE_AREA_WIDTH, height:64, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", px:32})
statsBar=I("pageArea", {name:"StatsBar", y:64, width:SCAFFOLD_PAGE_AREA_WIDTH, height:80, bg:"STATS_BG", display:"flex", alignItems:"center", gap:24, px:32})
contentWrap=I("pageArea", {name:"ContentWrap", y:144, width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CONTENT_HEIGHT_A, display:"flex", justifyContent:"center", p:32})
contentInner=I("contentWrap", {name:"ContentInner", width:SCAFFOLD_CONTENT_MAX, display:"flex", flexDirection:"column", gap:24})
鷹架建立後:執行 snapshot_layout() — 驗證 pageArea.width 和 contentInner.width 是否正確。
鷹架 B — 應用程式列表/佇列
表格、資產庫、佇列、使用者管理
sidebar=I("root", {name:"Sidebar", width:SCAFFOLD_SIDEBAR_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"SIDEBAR_BG"})
pageArea=I("root", {name:"PageArea", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, x:SCAFFOLD_SIDEBAR_WIDTH, bg:"PAGE_BG"})
pageHeader=I("pageArea", {name:"PageHeader", width:SCAFFOLD_PAGE_AREA_WIDTH, height:64, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", px:32})
commandStrip=I("pageArea", {name:"CommandStrip", y:64, width:SCAFFOLD_PAGE_AREA_WIDTH, height:52, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", gap:16, px:32})
tableWrap=I("pageArea", {name:"TableWrap", y:116, width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CONTENT_HEIGHT_B, display:"flex", justifyContent:"center", px:32, pt:24})
tableInner=I("tableWrap", {name:"TableInner", width:SCAFFOLD_CONTENT_MAX, display:"flex", flexDirection:"column", gap:0})
tableHeader=I("tableInner", {name:"TableHeader", width:SCAFFOLD_CONTENT_MAX, height:40, bg:"TABLE_HEADER_BG", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center"})
鷹架 C — 應用程式詳細資料/審閱
雙面板詳細資料檢視、審閱流程、並排佈局
sidebar=I("root", {name:"Sidebar", width:SCAFFOLD_SIDEBAR_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"SIDEBAR_BG"})
pageArea=I("root", {name:"PageArea", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, x:SCAFFOLD_SIDEBAR_WIDTH, bg:"PAGE_BG"})
pageHeader=I("pageArea", {name:"PageHeader", width:SCAFFOLD_PAGE_AREA_WIDTH, height:64, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR"})
actionBar=I("pageArea", {name:"ActionBar", y:64, width:SCAFFOLD_PAGE_AREA_WIDTH, height:56, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR"})
contentWrap=I("pageArea", {name:"ContentWrap", y:120, width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CONTENT_HEIGHT_C, display:"flex", justifyContent:"center"})
contentInner=I("contentWrap", {name:"ContentInner", width:SCAFFOLD_CONTENT_MAX, height:SCAFFOLD_CONTENT_HEIGHT_C, display:"flex", gap:0})
leftPanel=I("contentInner", {name:"LeftPanel", width:SCAFFOLD_LEFT_PANEL, height:SCAFFOLD_CONTENT_HEIGHT_C, bg:"SURFACE_COLOR", borderRight:"1px solid BORDER_COLOR"})
rightPanel=I("contentInner", {name:"RightPanel", width:SCAFFOLD_RIGHT_PANEL, height:SCAFFOLD_CONTENT_HEIGHT_C, bg:"PAGE_BG", p:24, display:"flex", flexDirection:"column", gap:20})
注意:左右分割預設為約 40/60。請根據功能調整——常見分割比例:40/60、38/62、50/50。
鷹架 D — 行銷頁面
登陸頁面、產品頁面——無論應用程式畫布為何,一律為 1440px 寬
navbar=I("root", {name:"Navbar", width:1440, height:72, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", px:80})
heroSection=I("root", {name:"HeroSection", y:72, width:1440, height:600, bg:"HERO_BG", display:"flex", flexDirection:"column", alignItems:"center", justifyContent:"center"})
heroContent=I("heroSection", {name:"HeroContent", width:SCAFFOLD_MARKETING_CONTENT_MAX, display:"flex", flexDirection:"column", alignItems:"center", gap:24})
section1=I("root", {name:"Section1", y:672, width:1440, height:480, bg:"SURFACE_COLOR", display:"flex", flexDirection:"column", alignItems:"center", py:80})
section1Content=I("section1", {name:"Section1Content", width:SCAFFOLD_MARKETING_CONTENT_MAX})
行銷頁面是手機優先的。請以 1440px 進行設計,並在交付前以 390px 寬度驗證佈局。
鷹架 E — 模態視窗/對話框
確認對話框、破壞性操作、快速編輯表單、側邊面板
請先執行鷹架 A、B 或 C。然後在 pageArea 上疊加此模態視窗——請勿插入到根節點。
backdrop=I("pageArea", {name:"ModalBackdrop", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"rgba(0,0,0,0.48)", display:"flex", alignItems:"center", justifyContent:"center"})
modal=I("backdrop", {name:"Modal", width:480, bg:"SURFACE_COLOR", borderRadius:8, border:"1px solid BORDER_COLOR", display:"flex", flexDirection:"column", overflow:"hidden"})
modalHeader=I("modal", {name:"ModalHeader", height:56, px:24, display:"flex", alignItems:"center", justifyContent:"space-between", borderBottom:"1px solid BORDER_COLOR"})
modalBody=I("modal", {name:"ModalBody", px:24, py:20, display:"flex", flexDirection:"column", gap:16})
modalFooter=I("modal", {name:"ModalFooter", height:60, px:24, display:"flex", alignItems:"center", justifyContent:"flex-end", gap:12, borderTop:"1px solid BORDER_COLOR"})
鷹架建立後:執行 snapshot_layout() — 確認模態視窗可見且置中。請根據使用案例調整模態視窗寬度:380px(緊湊確認對話框)、480px(標準表單)、600px(寬版表單)、720px(詳細資料/預覽)。
鷹架 F — 精靈/步驟流程
多步驟表單、入職流程、設定序列、結帳
sidebar=I("root", {name:"Sidebar", width:SCAFFOLD_SIDEBAR_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"SIDEBAR_BG"})
pageArea=I("root", {name:"PageArea", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, x:SCAFFOLD_SIDEBAR_WIDTH, bg:"PAGE_BG"})
pageHeader=I("pageArea", {name:"PageHeader", width:SCAFFOLD_PAGE_AREA_WIDTH, height:64, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", px:32})
stepperBar=I("pageArea", {name:"StepperBar", y:64, width:SCAFFOLD_PAGE_AREA_WIDTH, height:60, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", justifyContent:"center"})
contentWrap=I("pageArea", {name:"ContentWrap", y:124, width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CONTENT_HEIGHT_F, display:"flex", justifyContent:"center", px:32, pt:32})
contentInner=I("contentWrap", {name:"ContentInner", width:640, display:"flex", flexDirection:"column", gap:24})
actionFooter=I("pageArea", {name:"ActionFooter", y:SCAFFOLD_WIZARD_FOOTER_Y, width:SCAFFOLD_PAGE_AREA_WIDTH, height:72, bg:"SURFACE_COLOR", borderTop:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", justifyContent:"space-between", px:32})
注意:ContentInner 預設為 640px 寬——專注的單欄表單。ActionFooter 中,返回按鈕靠左,下一步/提交按鈕靠右(justifyContent:"space-between")。
鷹架 G — 行動畫面
390×844px(iPhone 14 標準尺寸)。所有行動畫面皆使用此鷹架——硬編碼,無需設定值。
statusBar=I("root", {name:"StatusBar", width:390, height:44, bg:"PAGE_BG"})
navBar=I("root", {name:"NavBar", y:44, width:390, height:56, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", px:16})
scrollContent=I("root", {name:"ScrollContent", y:100, width:390, height:688, bg:"PAGE_BG", display:"flex", flexDirection:"column", overflow:"hidden"})
contentPad=I("scrollContent", {name:"ContentPad", width:390, display:"flex", flexDirection:"column", gap:16, px:16, pt:16})
bottomNav=I("root", {name:"BottomNav", y:788, width:390, height:56, bg:"SURFACE_COLOR", borderTop:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", justifyContent:"space-around"})
注意:如果不顯示系統狀態列,請移除 statusBar 並將 navBar.y 設為 0。對於沒有分頁導覽的應用程式,請移除 bottomNav。此鷹架內部的觸控目標必須 ≥44×44px。
鷹架 H — 表單/資料輸入
設定頁面、個人資料編輯、大量資料輸入——單欄、置中表單
sidebar=I("root", {name:"Sidebar", width:SCAFFOLD_SIDEBAR_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"SIDEBAR_BG"})
pageArea=I("root", {name:"PageArea", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, x:SCAFFOLD_SIDEBAR_WIDTH, bg:"PAGE_BG"})
pageHeader=I("pageArea", {name:"PageHeader", width:SCAFFOLD_PAGE_AREA_WIDTH, height:64, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", justifyContent:"space-between", px:32})
formWrap=I("pageArea", {name:"FormWrap", y:64, width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CONTENT_HEIGHT_H, display:"flex", justifyContent:"center", px:32, pt:32})
formInner=I("formWrap", {name:"FormInner", width:600, display:"flex", flexDirection:"column", gap:28})
formSection=I("formInner", {name:"FormSection1", display:"flex", flexDirection:"column", gap:16})
formActions=I("formInner", {name:"FormActions", display:"flex", gap:12, justifyContent:"flex-end"})
注意:FormInner 寬度預設為 600px。簡單流程使用 480px,寬版雙欄佈局使用 800px。在 formInner 內部新增更多 FormSection 節點以分組相關欄位。
鷹架 I — 空狀態/入職步驟
零資料檢視、首次使用提示、功能探索、空白畫面
sidebar=I("root", {name:"Sidebar", width:SCAFFOLD_SIDEBAR_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, bg:"SIDEBAR_BG"})
pageArea=I("root", {name:"PageArea", width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CANVAS_HEIGHT, x:SCAFFOLD_SIDEBAR_WIDTH, bg:"PAGE_BG"})
pageHeader=I("pageArea", {name:"PageHeader", width:SCAFFOLD_PAGE_AREA_WIDTH, height:64, bg:"SURFACE_COLOR", borderBottom:"1px solid BORDER_COLOR"})
emptyCenter=I("pageArea", {name:"EmptyCenter", y:64, width:SCAFFOLD_PAGE_AREA_WIDTH, height:SCAFFOLD_CONTENT_HEIGHT_H, display:"flex", alignItems:"center", justifyContent:"center"})
emptyContent=I("emptyCenter", {name:"EmptyContent", width:400, display:"flex", flexDirection:"column", alignItems:"center", gap:20})
illustrationArea=I("emptyContent", {name:"IllustrationArea", width:200, height:160, borderRadius:12, bg:"SURFACE_COLOR", border:"1px solid BORDER_COLOR", display:"flex", alignItems:"center", justifyContent:"center"})
textStack=I("emptyContent", {name:"TextStack", width:400, display:"flex", flexDirection:"column", alignItems:"center", gap:8})
emptyActions=I("emptyContent", {name:"EmptyActions", display:"flex", gap:12})
注意:將 IllustrationArea 替換為 G("illustrationArea", "ai", "your prompt") 以生成插圖。保持空狀態文案簡短:一個標題(16–18px)、一行說明文字(14px muted)、一個主要 CTA。
核心工作流程
工作流程 1:畫布考古學
使用時機:「這個 .pen 檔裡有什麼?它為什麼這樣設計?」
1. snapshot_layout() — 凍結目前狀態
2. get_editor_state() — 讀取文件與選取範圍元資料
3. 檢查文件內所有 `I()` 和 `G()` 節點
- 每個根節點代表一個畫面、彈出視窗或重疊元件
- 每個子節點代表一個容器、文字區塊、按鈕或繪圖
4. 建立一份快速清單:
- 頁面結構(側邊欄、標頭、內容區域)
- 使用的間距模式(gap、padding、margin 值)
- 文字層級(字型、大小、粗細、顏色)
- 互動元素(按鈕、連結、表單欄位、懸停狀態)
5. 與指南中的品牌 12 字樣層級進行交叉比對
- 識別不一致之處:錯誤的間距、缺少的層級、超出品牌規範的顏色
6. 提出一個包含 3 項的改進計劃,每個項目都有「原因」與「作法」
7. 在進行任何編輯前,先獲得使用者的核准
重點:畫布考古學的目的不是批評——而是確保每個設計決策背後都有感知心理學的依據。始終要問「為什麼?」而不是「這樣可以嗎?」
工作流程 2:CSS 輸出模式
使用時機:「為這個畫面產生 React + CSS 或 Tailwind 程式碼」
1. snapshot_layout() — 凍結最終佈局的座標和尺寸
2. 對於每個 `I()` 或 `G()` 節點,轉換為對應的 HTML/CSS
- `x`, `y` → CSS `position: absolute` + `left`, `top`(或 flexbox,如適合)
- `width` → `width` 或 `max-width`
- `px`, `py`, `p` → `padding-left`, `padding-right`, `padding-top`, `padding-bottom`
- `gap` → `gap` 或子元素的 `margin`
- `display`, `flexDirection`, `alignItems`, `justifyContent` → 1:1 對應 CSS flexbox 屬性
- `borderRadius` → `border-radius`
- `border`, `borderTop`, `borderBottom`, `borderRight`, `borderLeft` → 1:1 對應 CSS border
3. 將品牌 Token 對應到專案的 CSS 變數或色板
4. 輸出帶有 Tailwind class 或 CSS-in-JS 樣式的 React 元件
重點:不要只給出程式碼——也要說明佈局邏輯和回應式行為,尤其是針對行銷頁面(在 1440/390 兩者驗證)。
感知心理學護欄
以下是 Claude 在設計任何 UI 時必須遵守的規則。這些不僅是偏好——更是基於人類視覺感知的硬性限制。
護欄 1:鄰近性法則
規則: 相關的元素必須群組在一起。無關的元素必須以視覺上明顯的間距分隔開來。
作法:
- 永遠使用
gap來定義元素之間的關係 - 群組內間距(
gap)= 8–16px。群組之間間距 = 24–48px - 如果您看到
gap: 24分散在整個畫面中,請質疑它——24px 應該是區塊間距,而不是通用間距 - 按鈕內部的間距 ≤12px(緊湊)。一個區塊與下一個區塊之間的間距 ≥24px
例外: 資料視覺化(圖表需要其自身的內部間距邏輯)、列印佈局(紙張出血限制了間距)
護欄 2:完形法則
規則: 使用者會先看到整體形狀,然後才是局部細節。建立清晰的矩形視覺層級,不要零散的浮動元素。
作法:
- 每個可點擊的群組都應該是感知得到的完整矩形——不是獨立的文字按鈕
- 卡片必須有明確的邊界(邊框、背景顏色、內部間距)
- 不要將按鈕放置在空白處——將它們錨定在容器邊緣或與其他群組對齊
- 如果一個區塊最寬的元素是 320px,就不要讓表單欄位寬 400px——保持對齊
例外: 頭像重疊、圖釘指示器、裝飾性背景元素
護欄 3:一致性與標準化
規則: 跨相同頁面類型的相同元素必須以相同方式呈現。沒有隨意的變化。
作法:
- 所有按鈕的內部間距、邊框半徑和字重都相同
- 所有輸入欄位都有相同的高度、邊框样式和焦點指示器
- 清單項目永遠以相同結構呈現:圖示 + 標籤 + 值(或整個清單中一致的三個元素)
- 懸停狀態必須在類型層級一致——不要讓一個按鈕變暗而另一個變亮
例外: 由內容驅動的佈局(部落格、饋送)可能因內容長度而有不同高度
護欄 4:顏色與對比度
規則: 文字的可讀性是首要任務。根據 WCAG 2.1 AA 標準,UI 中的對比度需要 ≥3:1,文字的對比度需要 ≥4.5:1。
作法:
- 永遠使用品牌的 Token 顏色——不要編造十六進位值
- 文字永遠不要使用低對比度的顏色。預設是
color-text(#1A1A1A),次要文字是color-text-muted(對比度 ≥4.5:1) - 不要將灰色文字放在灰色背景上,除非有足夠的對比度
- 按鈕狀態 = 不同的顏色或透明度——不僅僅是文字粗細的改變
例外: 裝飾性圖示(非互動式)、品牌標誌、禁用狀態(但即使如此,也需 ≥3:1 對比度)
護欄 5:費茲定律與觸控目標
規則: 可點擊元素的尺寸必須 ≥44×44px。它們之間的距離必須 ≥8px。目標越大,互動越容易。
作法:
- 按鈕永遠 ≥44px 高——即使文字只需要 36px
- 如果圖示本身不夠大,圖示按鈕需要至少 44×44px 的點擊區域
- 不要將兩個 ≥44px 的元素以 4px 的間距放置——最小為 8px
- 下拉式選單中的清單項目必須 ≥44px 高(「非互動式」選項除外)
例外: 滑鼠優先的桌面應用程式(企業軟體、設計工具)可能使用 32px 的較小目標
護欄 6:視覺重量與層級
規則: 使用者在 50 毫秒內掃視並決定什麼是重要的。您的層級必須符合他們的本能預期。
作法:
- 主要操作 = 填滿顏色、粗體文字、按鈕右側或底部
- 次要操作 = 外框樣式或線條樣式、正常粗體、按鈕次要位置
- 第三層操作 = 純文字、靜態位置、較小的尺寸
- CTA 永遠不應該是「次要的」——它必須是頁面上視覺重量最重的互動元素
- 錯誤:一個按鈕是填滿顏色,另一個是外框樣式——但兩者標示相同的權重
例外: 遊戲 UI 可能有不同的視覺重量慣例。請遵循遊戲的設計系統。
護欄 7:空白空間(留白)
規則: 空白空間不是浪費的——它是視覺呼吸的空間。目標是內容密度約 40–60%,不要用邊界填滿每個像素。
作法:
- 區塊之間的間距 = 24–48px(取決於頁面類型)
- 區塊內部的間距 = 16–24px
- 清單項目之間的間距 = 8–12px
- 不要僅為了填滿高度而延展內容——如果內容結束於 600px 但畫布高度是 900px,請新增一個裝飾元素或接受較低的內容密度
- 如果畫面感覺空曠,請在底部新增頁尾資訊或補充功能
例外: 儀表板(更高的密度是可以預期的)、行銷頁面(更多的空白空間是可以接受的)
護欄 8:錯誤預防與回饋
規則: 防止錯誤發生。當錯誤發生時,立即告訴使用者他們做了什麼以及如何修正。
作法:
- 表單送出之前——驗證所有欄位是否格式正確
- 內聯驗證:如果欄位失去焦點且格式不正確,在欄位下方顯示錯誤訊息
- 錯誤訊息格式:圖示 + 說明文字 + 解決方案(如果適用)
- 永遠讓使用者可以在不遺失資料的情況下復原和取消——確認對話框需要明確的退出路徑
- 不要只在頂部顯示 toast 通知——在使用者正在使用的欄位旁邊提供內聯回饋
例外: 系統層級的錯誤(網路中斷、伺服器錯誤)——這些資訊應顯示為橫幅或專用的錯誤畫面
設計系統整合
品牌 12 字樣層級
| 層級 | 標籤 | 尺寸 | 粗細 | 使用案例 |
|---|---|---|---|---|
| 1 | h1 | 32–48px | Bold | 頁面標題、英雄文字 |
| 2 | h2 | 24–36px | Bold | 區塊標題、模態視窗標題 |
| 3 | h3 | 20–28px | SemiBold | 卡片標題、區段標題 |
| 4 | h4 | 18–24px | SemiBold | 子區段、清單群組標題 |
| 5 | h5 | 16–20px | Medium | 重點項目、功能層級標題 |
| 6 | h6 | 14–18px | Medium | 小型標題、次要重點 |
| 7 | body-large | 16–18px | Regular | 內文、描述、長篇閱讀 |
| 8 | body | 14–16px | Regular | 標準內文、表格資料 |
| 9 | body-small | 12–14px | Regular | 輔助文字、提示、標籤 |
| 10 | caption | 11–12px | Regular | 圖說、時間戳、尺寸 |
| 11 | label | 12–14px | Medium | 表單標籤、清單項目標題 |
| 12 | button | 14–16px | Medium/SemiBold | 按鈕文字、連結 |
注意事項:
- 在特定層級範圍內選擇尺寸時,請考慮內容:詳細儀表板使用較小的尺寸;行銷頁面使用較大的尺寸
- Body 文字永遠不要小於 12px(可讀性底線)
- 按鈕文字應與其容器成比例——大按鈕使用 16px,標準按鈕使用 14px
品牌顏色映射
| Token | 用途 | 對比度備註 |
|---|---|---|
color-primary | 主要按鈕、重點、連結 | 文字 on 此色:需 ≥4.5:1 |
color-primary-dark | 主要懸停、標題 | 文字 on 此色:需 ≥4.5:1 |
color-accent | 次要動作、徽章、標籤 | 文字 on 此色:需 ≥4.5:1 |
color-background | 頁面背景 | — |
color-surface | 卡片、側邊欄、模態視窗、輸入欄位 | — |
color-border | 分隔線、輸入欄位邊框、表格行 | — |
color-text | 標題、主要內文 | on background:需 ≥4.5:1 |
color-text-muted | 次要文字、預留位置、說明 | on background:需 ≥4.5:1 |
color-success | 成功狀態、已驗證的輸入欄位 | on background:需 ≥3:1 |
color-warning | 警告狀態、非文字橫幅 | 文字 on 此色:需 ≥4.5:1 |
color-error | 錯誤狀態、必填欄位指示器、橫幅 | 文字 on 此色:需 ≥4.5:1 |
顏色使用規則:
- 永遠從此映射中選擇——不要從 Figma 設計中推導十六進位值
- 懸停狀態 = 具有 90% 不透明度的上層疊加層,或在調色盤中明度降低 10%
- 禁用狀態 = 具有 60% 不透明度 + 對比度減少
- 連結永遠使用
color-primary,且底線(底線或透過 2px 底部邊框)
Pencil 技能 API 參考
get_editor_state()
傳回編輯器狀態、使用中的文件和選取範圍元資料。
open_document(path)
使用提供的檔案路徑在 Pencil 中開啟文件。
get_guidelines(topic)
載入指定主題的設計指南。
set_variables(record)
為當前工作階段設定品牌變數(Token)。變數可能無法在 Claude Code 工作階段之間持續保留——請在每個工作階段重新設定。
get_variables()
確認所有品牌 Token 已正確儲存。如果某些 Token 為空值,請重新執行 set_variables。
snapshot_layout()
捕捉目前的畫布狀態。如果有任何節點不在預期位置(例如,因父層尺寸解析失敗而位於 [0,0]),傳回警告。
I(parent, config)
在指定父層內插入一個節點(圖層)。配置的可選屬性:name、x、y、width、height、bg、borderRadius、border、borderTop、borderBottom、borderRight、borderLeft、display、flexDirection、alignItems、justifyContent、gap、px、py、p、pt、pb、pl、pr、overflow。
G(parent, type, prompt)
在指定的父層內使用文字生成 prompt 插入一個生成式節點(影像、文字區塊、形狀)。type 可以是 "ai"(根據 prompt 生成任何內容)或 "text"(將 prompt 作為文字區塊插入)。