Communitygithub.com

stevembarclay/pencilplaybook

PencilPlaybook 是 Pencil.dev 搭配 Claude Code 的 UI 技能與品味技能——一套設計戰術手冊,為 Claude 注入真實的感知心理學與資深設計師的護欄,使其不再產出平庸的 AI 介面。

pencilplaybook 是什麼?

PencilPlaybook 是一個專為 Pencil.dev 與 Claude Code 設計的 UI 設計技能,它將資深設計師的感知心理學原則與嚴格護欄直接整合到 AI 的設計工作流程中。此技能透過一套可重複使用的「鷹架腳本」(Scaffold Scripts) 涵蓋九種常見佈局原型(儀表板、列表、行銷頁面、行動畫面等),確保 Claude 能夠快速產出具有品牌一致性的高品質 UI,而非平庸的 AI 生成設計。它要求每個工作階段都需進行品牌 Token 設定並載入設計指南,並定義了「畫布考古學」(Canvas Archaeology) 等核心工作流程,用於審查與重構現有設計,確保其符合感知心理學原則。此技能主要支援 Pencil.dev 與 Claude Code,透過嚴格的解析度管理與邊界案例處理,讓開發者與設計師能夠專注於創新,而不是校正 AI 的品味。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add stevembarclay/pencilplaybook

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 字樣層級

層級標籤尺寸粗細使用案例
1h132–48pxBold頁面標題、英雄文字
2h224–36pxBold區塊標題、模態視窗標題
3h320–28pxSemiBold卡片標題、區段標題
4h418–24pxSemiBold子區段、清單群組標題
5h516–20pxMedium重點項目、功能層級標題
6h614–18pxMedium小型標題、次要重點
7body-large16–18pxRegular內文、描述、長篇閱讀
8body14–16pxRegular標準內文、表格資料
9body-small12–14pxRegular輔助文字、提示、標籤
10caption11–12pxRegular圖說、時間戳、尺寸
11label12–14pxMedium表單標籤、清單項目標題
12button14–16pxMedium/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 作為文字區塊插入)。

相關技能