visual-design-foundations

visual-design-foundations 技能總覽

visual-design-foundations 是做什麼的

visual-design-foundations 技能能幫助代理把模糊的 UI 設計目標，整理成更一致、更有系統的視覺基礎，重點落在實用面：字體比例、色彩系統、間距 token，以及 icon 使用規則。當你需要的是快速建立結構，而不只是找靈感時，它特別有用——尤其適合用在 design token 規劃、style guide 起手式、視覺層級整理，或產品介面的第一版 UI system。

最適合的使用者與專案類型

這個 visual-design-foundations skill 特別適合：

• 要定義基礎設計系統的產品設計師
• 需要在 CSS 中建立 design token 的前端工程師
• 想統一間距、字級與語意色彩的團隊
• 需要可重複規則的 AI 輔助 UI 設計流程

它的重點不是直接產出精修完成的 mockup，而是幫你的介面建立一套站得住腳、也能被一致實作的基礎。

這個技能和一般 prompt 有什麼不同

一般像「讓這個 UI 看起來更好」這類 prompt，通常還是停留在主觀評論。visual-design-foundations 比較適合需要模型從「系統」角度思考的情境，例如：

• 用 modular typography scales，而不是隨意指定字體大小
• 用 8-point spacing 邏輯，而不是零散的 padding 數值
• 用 semantic color tokens，而不是一次性的 hex 選色
• 提供可及性導向的層級建議，而不只是美感回饋

內附的參考資料也補足了不少實作細節，特別是 OKLCH 色階、semantic token 分層，以及以比例建立的 typography 系統。

使用者通常最先在意什麼

在安裝 visual-design-foundations 之前，多數人最想先確認的是：

1. 它輸出的是可重複使用的 token，還是只有原則性建議
2. 它是否有助於處理可及性與 dark mode
3. 沒有完整 design system 團隊時，它能不能協助整理 UI
4. 範例是否足夠貼近前端實作，能直接拿來落地

就這幾點來看，這個技能偏實用路線：原始內容裡有具體的 CSS token 寫法，也有幾份很值得先讀的參考檔，最好在依賴第一版輸出前先看過。

如何使用 visual-design-foundations 技能

visual-design-foundations 的安裝情境

請從 wshobson/agents repository 安裝這個技能：

npx skills add https://github.com/wshobson/agents --skill visual-design-foundations

由於上游 skill 本身沒有附 helper scripts，所以你能拿到多少價值，主要取決於你怎麼下指令，以及在要求它產出完整系統之前，有沒有先讀過參考文件。

建議先讀這些檔案

如果你想把 visual-design-foundations install 的時間花得值得，建議依序閱讀：

1. plugins/ui-design/skills/visual-design-foundations/SKILL.md
2. plugins/ui-design/skills/visual-design-foundations/references/typography-systems.md
3. plugins/ui-design/skills/visual-design-foundations/references/color-systems.md
4. plugins/ui-design/skills/visual-design-foundations/references/spacing-iconography.md

這個順序的原因是：

• SKILL.md 先交代使用範圍
• typography 與 color 的參考內容，最能看出它偏向哪些可實作的輸出
• spacing 和 iconography 則能把抽象原則進一步轉成 token 與元件間距規則

這個技能需要哪些輸入，效果才會好

visual-design-foundations usage 的品質，非常吃你提供的輸入資訊。建議至少給代理這些內容：

• 產品類型：SaaS dashboard、mobile app、marketing site、admin tool
• 平台：web、iOS、Android、cross-platform
• 品牌語氣：clinical、playful、premium、utilitarian
• 目前限制：既有品牌色、字體、component library、accessibility 目標
• 需要的交付物：token set、style guide、audit、hierarchy revision、dark mode system
• 實作格式：CSS variables、Tailwind tokens、design spec、Figma-ready naming

如果沒有這些資訊，這個技能通常就會退回比較泛泛的「好設計原則」建議。

怎麼把模糊目標轉成有效 prompt

弱的 prompt：

• “Use visual-design-foundations for my app.”

更好的 prompt：

• “Use visual-design-foundations to define a visual system for a B2B analytics dashboard. I need a typography scale, semantic color tokens, spacing tokens, and icon guidelines. Primary users are analysts working long sessions, so readability matters more than visual novelty. Keep existing brand hue near blue, support light and dark themes, and output implementation-ready CSS custom properties plus rationale.”

這個版本更好，因為它明確定義了：

• 情境
• 使用者需求
• 限制條件
• 輸出內容
• 取捨方向

分層要求輸出

一個實用的 workflow，是按照這個順序要求結果：

1. 視覺原則與限制
2. typography system
3. spacing system
4. color token system
5. iconography rules
6. 元件層級的套用範例

這個順序和技能本身的結構一致，也能降低一次要完整答案時常見的低品質輸出。

善用 references，逼出可實作的回答

這些 reference 檔其實已經透露出這個技能最擅長的範圍：

• references/typography-systems.md：modular scale ratios、line-height 邏輯、CSS custom properties
• references/color-systems.md：perceptual scales、semantic tokens、OKLCH 範例
• references/spacing-iconography.md：8-point grid、component spacing tokens、icon 尺寸一致性

如果你在 prompt 裡明確要求模型沿用這些模式，就更容易拿到可重用的 token，而不是模糊的 art direction 建議。

適用於 UI Design 的 visual-design-foundations 強力 prompt 模板

你可以用這種 prompt 結構：

• Goal
• Product context
• Visual tone
• Accessibility requirements
• Existing constraints
• Requested output format
• Examples of screens or components to prioritize

範例：

• “Apply visual-design-foundations for UI Design to a healthcare patient portal. Keep the UI calm and trustworthy, preserve our teal brand direction, meet WCAG-friendly contrast expectations, and propose a type scale, semantic colors, spacing tokens, and icon sizing rules. Then show how these choices affect form fields, tables, alerts, and navigation.”

visual-design-foundations 特別擅長的地方

實際使用上，visual-design-foundations guide 在以下情境特別有價值：

• 第一版 token system
• 用來做一致性 audit 的分析框架
• 更易於無障礙的色彩結構
• 整理高密度介面的層級關係
• dark mode 的起始規則
• 可直接實作的 CSS variables

它特別適合把「設計看起來不一致」這種模糊問題，轉成「這裡有一套可治理的系統」。

哪些地方可能會覺得不夠

這個技能不是完整的 UI kit generator。從 repo 結構來看，它不包含：

• 自動驗證工具
• 元件專用 scripts
• design file 匯出
• screenshot analysis workflow
• 深度品牌策略框架

如果你的需求是高度視覺探索、marketing art direction，或大量客製化、偏動態表現的設計，光靠這個技能可能會太偏基礎。

第一次輸出後的實務流程

跑完第一輪之後，建議這樣做：

1. 保留符合你 codebase 的 token 命名
2. 用真實的 accessibility 目標去檢查每組色彩搭配
3. 把 type scale 實際套進 table、form、card 等版面測試
4. 如果模型產出太多變體，主動刪減 token 數量
5. 用你選定的 base size、ratio、brand hue 要求它再修一版

通常從第二輪開始，visual-design-foundations usage 才會真正接近 production 可用的程度。

visual-design-foundations 技能常見問題

visual-design-foundations 適合初學者嗎？

適合，但前提是你已經懂一些基本 UI 術語。這個技能會把 typography、color、spacing 和 iconography 的結構整理出來，所以它本身就有一定的教學效果。不過初學者還是應該自己再次確認對比、尺寸與實作決策，不要整份原封不動照抄。

visual-design-foundations 會產出程式碼，還是只有原則？

兩者都能支援，但它最有力的證據還是偏向實作導向的範例，例如 CSS custom properties 和 token 結構。如果你有明確要求 CSS variables、semantic token 命名，或 design-system-ready 的輸出格式，通常結果會更好。

它真的比一般 UI design prompt 更好嗎？

通常是的，尤其當你的問題在於一致性、層級或 token 設計時。一般 prompt 也許能產出看起來不錯的建議，但當你需要的是工程端也能持續落地的可重複系統，visual-design-foundations skill 會更有用。

我可以用 visual-design-foundations 來做 audit 嗎？

可以。它很適合用來檢查既有介面的這些問題：

• 間距不一致
• 文字層級薄弱
• 色彩使用缺乏語意
• icon 尺寸逐漸失控
• 高密度版面可讀性差

如果能附上 screenshot，或至少列出目前的 token 與 components 清單，audit 的品質通常會更好。

它對 dark mode 有幫助嗎？

有，但比較偏間接幫助。color 的參考資料本身就有 semantic token 思維和結構化色階，這會讓 dark mode 比較容易推導出來。它比較擅長幫你建立可切換 theme 的系統，而不是在完全沒有上下文的情況下，直接做出精修完成的 dark mode 視覺。

什麼情況下不該用 visual-design-foundations？

如果你的主要需求是以下這些，就可以先跳過 visual-design-foundations：

• 高擬真視覺探索
• 品牌敘事與創意方向
• 進階 motion design
• illustration systems
• 沒有 design-system 目標、只想修飾單一 landing page

這些情境下，改用更偏 brand 或 art direction 的 workflow，通常會更適合。

如何提升 visual-design-foundations 技能的輸出品質

先給限制條件，再要求方案

visual-design-foundations 最明顯的品質提升，通常來自限制條件。請明確指定：

• base font size
• 如果知道的話，偏好的 type scale ratio
• brand hue 或既有 palette
• accessibility 目標
• 密度偏好：compact、balanced、spacious
• 元件優先順序

這會迫使模型做出更貼地、可解釋的取捨。

不要只要 raw values，請要求 semantic tokens

很多第一版輸出失敗，是因為最後只停在 raw hex colors 和 font sizes。建議要求：

• primitive tokens
• semantic tokens
• component usage guidance

例如：

• primitive: blue-500
• semantic: color-action-primary
• usage: button background、active nav state、focus ring

這樣會讓 visual-design-foundations guide 的輸出更容易直接採用。

避免字級比例設計過頭

很常見的失敗模式，是 type scale 單看很優雅，但放進真實產品畫面就失衡。你可以透過這些資訊改善結果：

• body text size range
• 可接受的最小文字尺寸
• 介面是否屬於高資料密度
• headings 是否應該保持克制

對 dashboard 和 form 來說，保守的 scale 往往比戲劇化的比例更實用。

讓 spacing 回到元件現實

另一個常見問題，是 token 階梯看起來很整齊，卻很難對應到真實 UI pattern。建議直接要求模型展示這些項目的 spacing 規則：

• form fields
• cards
• tables
• modals
• page sections
• button padding

這樣 8-point system 就不只是理論，而會變成你可以實測的設計決策。

讓色彩輸出更安全、也更實用

如果想提升 visual-design-foundations for UI Design 的結果，請要求代理把這些分開處理：

• brand colors
• surface colors
• text colors
• status colors
• interactive states

也請它說明哪些地方最容易有對比風險，例如帶色底面、disabled states，或很淡的邊框。這通常會比直接要求「modern colors」得到更可靠的 palette。

要求一版「更少 token」的修訂

第一版輸出常常會給太多層級或太多 semantic roles。一個很有效的第二輪 prompt 是：

• “Reduce this system to the minimum viable token set for version 1 while preserving accessibility and consistency.”

這樣通常能幫團隊更快採用這個技能的成果。

把建議對齊你的技術堆疊

如果你使用 Tailwind、CSS variables，或正式的 design token pipeline，請要求代理把輸出映射到那個結構裡。當輸出能貼合你真實的實作路徑，而不是停在抽象層次時，visual-design-foundations install 的價值會高很多。

用具體的 before-and-after 任務提升輸出品質

與其籠統地要求一套 visual system，不如直接請這個技能改善某個特定畫面：

• “Here are the current font sizes, spacing values, and colors on our settings page. Use visual-design-foundations to normalize them into a coherent system and explain what changes first.”

這會比開放式地要求系統設計，產生更尖銳、也更容易驗證的建議。

用迭代把 foundation 和 styling 分開

一個穩定的 workflow 是：

1. 第一輪：只做 foundations
2. 第二輪：映射成 tokens
3. 第三輪：套用到 components
4. 第四輪：再微調 tone 與品牌表現

這能讓 visual-design-foundations usage 聚焦在它真正擅長的地方：先把系統品質做好，再談裝飾與風格。