visual-design-foundations

visual-design-foundations 技能概览

visual-design-foundations 是做什么用的

visual-design-foundations skill 的核心作用，是帮助代理把模糊的 UI 设计目标整理成更成体系的视觉系统。它依赖的是一套可落地的基础方法：字体层级比例、颜色系统、间距 token，以及图标规范。它最适合那种需要快速搭起结构、而不只是找灵感的场景——尤其是在设计 tokens、搭建 style guide、梳理视觉层级，或为产品界面做第一版 UI 系统时。

哪些用户和项目最适合用

这个 visual-design-foundations skill 特别适合以下人群和项目：

• 需要先定义一套基础规范的产品设计师
• 用 CSS 创建 design tokens 的前端工程师
• 想统一间距、字体和语义色的团队
• 需要可重复规则的 AI 辅助 UI 设计流程

它的重点不在于直接产出精修版高保真 mockup，而在于先给你的界面打下一套有依据、能持续实现的视觉基础。

它和通用提示词有什么不同

普通的“让这个 UI 更好看”提示词，结果往往停留在主观审美层面。visual-design-foundations 更适合你希望模型按“系统”来推理的时候，比如：

• 用模块化字体比例，而不是随意指定字号
• 用 8-point 间距逻辑，而不是零散的 padding 数值
• 用语义化颜色 token，而不是一次性的 hex 颜色选择
• 给出可访问性导向的层级建议，而不只是审美反馈

它附带的参考资料也很有价值，特别是在 OKLCH 色阶、语义 token 分层，以及基于比例的 typography 方面，能提供更接近实现的细节。

用户在安装前通常最关心什么

在安装 visual-design-foundations 之前，大多数用户最想先确认的是：

1. 它输出的是可复用 token，还是只有原则性建议
2. 它是否兼顾 accessibility 和 dark mode
3. 没有完整 design system 团队时，它能不能指导 UI 整理与收敛
4. 示例是否足够贴近前端实现，能不能直接拿来推进工作

从这些点来看，这个技能偏实用：源码里包含了具体的 CSS token 模式，还有几份很值得在正式依赖首轮输出前先读一遍的参考文件。

如何使用 visual-design-foundations skill

visual-design-foundations 的安装方式

从 wshobson/agents 仓库安装这个 skill：

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
• 当前约束：现有品牌色、字体、组件库、accessibility 目标
• 你要的交付物：token set、style guide、audit、hierarchy revision、dark mode system
• 实现格式：CSS variables、Tailwind tokens、design spec、Figma-ready naming

如果这些前提缺失，它大概率会退回到泛泛的“好设计建议”。

把模糊目标改写成高质量提示词

弱提示词：

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

更好的提示词：

• “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.”

这个版本更好，是因为它明确了：

• 场景上下文
• 用户需求
• 约束条件
• 输出形式
• 取舍方向

按层次索要输出

比较稳妥的工作流，是按下面这个顺序请求结果：

1. 视觉原则与约束
2. typography system
3. spacing system
4. color token system
5. iconography rules
6. 组件层的应用示例

这个顺序和 skill 本身的结构一致，也能减少“一次性全出”时常见的低质量输出。

用参考文件逼近可实现的答案

这些 reference 文件其实已经透露了这个 skill 最擅长处理什么：

• references/typography-systems.md：模块化比例、line-height 逻辑、CSS custom properties
• references/color-systems.md：感知均匀色阶、语义 token、OKLCH 示例
• references/spacing-iconography.md：8-point grid、组件间距 token、图标尺寸一致性

如果你在提示里明确要求模型按这些模式来组织答案，得到可复用 token 的概率会明显高于只拿到一堆模糊的 art direction 建议。

适用于 UI Design 的 visual-design-foundations 强提示词模板

可以按下面这个结构来写提示词：

• 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.”

这个 skill 最擅长的场景

实际使用里，visual-design-foundations guide 的价值在以下场景最明显：

• 快速搭出第一版 token system
• 做一致性审查
• 构建更可访问的颜色结构
• 梳理高密度界面的层级
• 给 dark mode 建立起步规则
• 产出可落地的 CSS variables

它尤其适合把“设计看起来不一致”推进到“这里有一套可管理的系统”。

哪些地方可能会显得不够

这个 skill 不是完整的 UI kit generator。根据仓库结构来看，它并不包含：

• 自动化校验工具
• 面向具体组件的脚本
• design file 导出能力
• screenshot analysis 工作流
• 深度品牌策略框架

如果你的需求更偏视觉探索、营销导向的 art direction，或者强调 bespoke motion-heavy design，那它单独使用可能会显得过于基础。

首轮输出之后的实操工作流

第一轮结果出来后，建议这样继续：

1. 保留那些适合你现有代码库的 token 命名
2. 用真实的 accessibility 目标去重新核验颜色搭配
3. 把 type scale 放到真实的 table、form 和 card 布局里测试
4. 如果模型给的变体太多，就主动压缩 token 数量
5. 基于你最终选定的 base size、ratio 和 brand hue，再要求它出第二版

通常到了这第二轮，visual-design-foundations usage 才真正开始接近生产可用。

visual-design-foundations skill 常见问题

visual-design-foundations 适合新手吗？

适合，但前提是你至少已经理解基本的 UI 术语。这个 skill 会围绕 typography、color、spacing 和 iconography 提供结构化输出，因此本身就有一定“边做边教”的效果。不过新手仍然需要自己复核 contrast、尺寸和实现方案，别直接原样照抄。

visual-design-foundations 输出的是代码，还是只有原则？

两者都能支持，但它最有说服力的部分，还是偏实现导向的示例，比如 CSS custom properties 和 token 结构。你如果明确要求 CSS variables、语义化 token 命名，或者 design-system-ready 的输出格式，结果通常会更好。

它比普通的 UI design prompt 更好吗？

大多数情况下是的，尤其当你的问题出在一致性、层级或 token 设计时。泛用提示词也可能给出好看的建议，但当你真正需要一套工程可以接住、能反复使用的系统时，visual-design-foundations skill 明显更有用。

我可以用 visual-design-foundations 做审查吗？

可以。它很适合审查现有界面中以下问题：

• 间距不一致
• 字体层级偏弱
• 颜色没有语义化
• 图标尺寸漂移
• 高密度布局中的可读性差

如果你能提供 screenshot，或者至少列出现有 token 和组件清单，审查结果会更有针对性。

它对 dark mode 有帮助吗？

有，但更多是间接帮助。颜色参考资料里包含了语义 token 的思路和结构化色阶，这会让 dark mode 更容易推导出来。它更擅长搭建一个可切主题的系统，而不是在没有上下文的情况下直接给你产出完成度很高的 dark mode 视觉稿。

什么情况下不该用 visual-design-foundations？

如果你的主要需求是以下这些，就不建议优先用 visual-design-foundations：

• 高保真的视觉探索
• 品牌叙事和创意方向
• 高级 motion design
• illustration systems
• 不以 design system 为目标、只想打磨单个 landing page

这些场景下，更偏 brand 或 art direction 的工作流会更合适。

如何提升 visual-design-foundations skill 的效果

先给约束，再要方案

要提升 visual-design-foundations 的输出质量，最有效的办法就是先把约束说清楚。建议明确：

• base font size
• 如果已知，给出偏好的 type scale ratio
• brand hue 或现有配色
• accessibility 目标
• 密度偏好：compact、balanced、spacious
• 组件优先级

这样模型才会做出更贴地的取舍，而不是悬空发挥。

不要只要原始数值，要语义 token

很多首轮输出之所以不好用，是因为它们停留在原始 hex 色值和字号层面。更好的要求方式是直接索要：

• 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 单看很优雅，但一落到真实产品页面就失真。要改善这一点，可以明确告诉代理：

• 正文字号范围
• 可接受的最小文字尺寸
• 你的界面是否数据密集
• heading 是否需要克制

对于 dashboard 和 form 来说，保守的 scale 往往比戏剧化的层级更耐用。

让间距规则贴近组件现实

另一个常见问题，是 token 梯度看起来很整齐，但和实际 UI 模式对不上。你可以要求模型直接展示这些场景的间距规则：

• 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

同时让它说明哪些地方最容易出现 contrast 风险，比如带色背景、disabled states 或细边框。这通常会比一句“给我一套现代感颜色”产出更可靠的 palette。

主动要求一版“更少 token”的修订

第一轮结果经常会给出过多层级或过多语义角色。一个很有效的第二轮提示词是：

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

这能帮助团队更快把这个 skill 真正落地起来。

让建议对齐你的技术栈

如果你使用 Tailwind、CSS variables，或者正式的 design token pipeline，记得要求代理把输出映射到对应结构里。visual-design-foundations install 的实际价值，只有在输出能贴合你真实实现路径时才会最大，而不是停留在抽象层面。

用具体的前后对比任务提升输出质量

与其泛泛地要求它做一整套视觉系统，不如直接让这个 skill 改一个具体页面：

• “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.”

这种任务会比开放式系统设计产出更尖锐、也更容易验证。

用迭代把“基础系统”和“视觉风格”拆开

一个比较稳的工作流是：

1. 第一轮：只做 foundations
2. 第二轮：映射到 tokens
3. 第三轮：应用到 components
4. 第四轮：再细化 tone 和 brand expression

这样能让 visual-design-foundations usage 始终聚焦在它真正擅长的地方：先把系统质量做好，再谈装饰和风格。