ui-visual-composition

UI 视觉构成

目的

帮助 AI Agent 通过层级、间距、排版、色彩、纵深、图像和细节润色，创建并评估精致的视觉 UI。将视觉设计视为一种功能性沟通：界面应帮助用户理解哪些内容最重要、哪些内容彼此相关、哪些内容可以操作，以及发生了哪些变化。

此技能涵盖视觉设计质量、布局构成、排版、色彩系统、纵深、图像、润色、无障碍设计，以及会影响视觉质量的前端实现选择。除非相关问题会决定视觉构成，否则不涵盖深入的 UX 研究、信息架构策略或前端架构。

何时使用此技能

当用户要求评估 UI、重新设计、改进产品页面、实现前端视觉效果、提供设计系统指导、润色样式、优化布局、调整排版或配色、改进空状态／错误状态／加载状态，或对生成的 UI 进行视觉 QA 时，使用此技能。

生成视觉界面的前端代码时也应使用此技能，因为组件结构、语义化标记、设计令牌、状态样式、响应式行为和无障碍细节，都会决定视觉建议能否在实现后保留下来。

何时不使用此技能

当用户主要要求用户研究规划、产品策略、市场定位、分析埋点、后端／前端架构、性能工程、不涉及视觉呈现的文案撰写，或详细的交互流程设计时，不要将此技能作为主要框架。仅将其用于这些任务中的视觉设计部分。

不要用此技能为随意装饰寻找理由。如果视觉建议无法改善层级、理解度、感知质量、无障碍性或与产品情境的契合度，就应移除。

核心原则

1. 从功能入手，而不是从外壳入手。 在设计导航框架、页面布局或装饰效果之前，先明确具体的用户任务和内容。
2. 层级是基础。 让最重要的内容和操作最容易被注意到。优先使用尺寸、字重、对比度、间距、位置和顺序，而不是依赖颜色或装饰。
3. 除非创新有明确目的，否则使用熟悉的模式。 用户会带着从其他产品中形成的心理模型。对于常见控件、导航、表单和反馈，应沿用惯例；除非用户的品牌或产品目标足以证明有意打破惯例是合理的。
4. 按含义分组。 邻近关系、共同区域、对齐方式和连接关系应符合概念上的关联。间距含糊会造成含义含糊。
5. 用系统约束选择。 使用字体、间距、颜色、圆角、边框和层级令牌，而不是临时采用零散的单次取值。
6. 排版是界面结构的一部分。 选择适合内容和语境的字体，并设置易读的行长、行高、对齐方式、强调效果和层级。
7. 颜色必须安全地传达含义。 用颜色强化层级、状态和品牌，但绝不能将其作为唯一信号。保持对比度，并针对色觉和低视力需求进行测试。
8. 层次应能解释空间关系。 阴影、重叠、边框和背景变化应阐明层级、分组、焦点或交互，而不是制造视觉噪音。
9. 美观能提升认可度，但不能弥补可用性缺陷。 精致的设计能让用户更宽容、更有信心，但也可能掩盖问题。在赞赏美观之前，应先验证清晰度、无障碍性和任务适配度。
10. 在简化的同时，不要隐藏必要的复杂性。 减少可见选项，并拆分复杂任务，但不要抽象掉用户决策或恢复操作所需的信息。
11. 为真实内容的韧性而设计。 用户上传的图片、较长的标签、空数据、错误、加载状态、禁用状态和本地化都不应破坏布局。
12. 以用户为中心说明权衡。 建议应围绕用户目标、理解程度、无障碍性、系统一致性和实施可行性展开。

请参阅 references/principle-cards.md，了解每项原则对应的可复用卡片。

默认建议

除非用户提供的背景信息表明其他选择更合适，否则请采用以下默认建议。

领域	默认做法	通常最合适的原因	何时覆盖默认做法	覆盖前询问
产品/任务重点	从一个核心功能或屏幕目标入手	避免在明确内容和操作之前就设计应用外壳	用户明确要求全局导航、设计系统外壳或信息架构	询问主要任务和屏幕的成功标准
视觉方向	专业、温暖、克制，以内容为先	适用于大多数效率、SaaS、仪表板、管理和电商界面	品牌风格活泼、奢华、编辑感强、面向年轻群体、高度技术化或具有活动宣传风格	询问品牌个性和示例
信息密度	首先采用舒适的间距；仅在有意为之时才缩小间距	宽敞的布局通常更清爽、更清晰	仪表板、专业工具、交易、运营或数据监控场景需要高密度	询问对信息密度和扫描速度的需求
布局策略	使用内容宽度容器和清晰分组；默认避免填满整个屏幕	减少大屏幕上的行宽过长和视觉偏移	沉浸式画布、地图、媒体、电子表格、时间线或数据网格需要全宽布局	询问哪些内容需要同时保持可见
网格	使用简单灵活的网格和令牌化间距，不要为了网格而采用僵化布局	有助于对齐，同时避免内容被塞进任意列中	编辑、营销或数据密集型布局需要更严格的网格逻辑	询问内容类型和响应式断点
排版	界面使用系统 UI 或高品质中性无衬线字体；仅在品牌需要时搭配一种富有表现力的展示字体	降低加载风险并提高易读性	编辑/品牌项目需要独特的字体风格	询问品牌调性和字体限制
字号层级	为正文、辅助文本、标签、标题和展示文本设置少量可复用的字号级别	减少层级不一致的情况	现有设计系统已定义字号级别	询问设计系统令牌的来源
行长	正文和长篇文本应保持易读的行宽；避免文字从一侧铺满到另一侧	提高浏览效率和阅读舒适度	数据表格、代码或短卡片需要不同的行宽	仅在内容类型特殊时询问
颜色	从有限调色板中建立语义角色，包括中性色阶、强调色阶、成功/警告/错误/信息色以及焦点状态	有助于保持一致性和可访问性	品牌调色板固定，或合规/监管状态有规定	询问品牌调色板和可访问性目标
对比度	将对比度视为功能要求；检查文本、图标、控件和状态	避免界面难以访问或显得不够可靠	大型装饰性文字或非必要插图可不受此限制	询问产品是否要求符合特定的可访问性标准
层次	使用少量层级，并保持光照模型一致	创建层次，避免视觉混乱	品牌有意采用扁平/粗野主义或拟物风格	仅在层次方向属于品牌选择时询问
图像	使用高品质且适合用途的图像；通过遮罩、渐变或容器保护图像上的文字	图像差异很大，可能破坏可读性	用户提供固定摄影素材或 UGC	询问图像来源及其变化情况
边框	优先使用间距、背景、阴影或细微分隔线，避免添加过多边框	边框很快就会增加视觉噪音	数据表格、法律表单或密集的设置屏幕需要明确分隔	询问是否需要考虑信息密度或表格精度
空状态	添加有帮助的空状态，并提供下一步操作	空状态是体验的一部分，不是空白的失败页面	不可能出现空状态，或有意隐藏空状态	无需询问；默认实现
动效	使用细微且有明确目的的动效来提供反馈、保持连贯性和显示加载状态；尊重减少动态效果偏好	在避免分散注意力的同时提升清晰度	产品以娱乐为主，或品牌动效是关键差异化特征	询问对动效的偏好和可访问性限制
前端实现	使用语义化 HTML、设计令牌、响应式 CSS、可见的焦点状态、键盘访问和状态变体	在真实界面中保持视觉质量和可访问性	原型是静态且一次性的	询问是否存在生产环境限制或框架/设计系统规则

必要的用户问题

不要要求用户确认易读文本、足够的对比度或清晰的层级等常规最佳实践。这些应默认落实。

只有当答案会实质性改变视觉方案时，才提出有针对性的问题。条件允许时，使用 question 工具或同等工具。适合提问的情况包括：

• 产品目标、主要任务、受众或平台未知，且无法推断。
• 品牌个性或视觉基调可能会影响字体、颜色、信息密度、图像或装饰。
• 用户要求重新设计，但未提供当前 UI、截图、代码、设计系统限制或成功标准。
• 无障碍目标、合规要求或受众需求比通常的包容性默认标准更严格。
• UI 将处理易变内容，例如用户上传的图像、本地化、超长名称、未知的数据密度或生成内容。
• 用户要求新颖设计，但这可能与熟悉的心智模型或平台惯例冲突。
• 用户要求实现前端，且目标框架、设计系统或 CSS 限制会影响方案。

提问时，请给出推荐的默认选项和其他选项。每次只问一个问题，除非用户明确要求进行全面的需求调研。完整的决策问题集请参阅 references/decision-prompts.md 中可直接用于 question 工具的提示词。

工作流：评审现有 UI

评审现有 UI 时，请按以下顺序检查：

1. 任务与情境契合度。 明确主要用户目标、受众、平台和成功标准。如果缺少相关信息，请谨慎推断并说明假设。
2. 心智模型与惯例契合度。 检查常见控件、导航、搜索、表单和反馈是否符合用户预期。
3. 信息层级。 明确预期的主要内容或操作。确认视觉层级体现的是重要性，而不仅仅是文档顺序或语义严重程度。
4. 分组与布局。 检查邻近关系、对齐、区域划分、屏幕宽度、响应式表现和含义不明确的间距。
5. 排版。 检查字体选择、字号比例、行长、行高、强调方式、标签样式、对齐方式和长内容的呈现。
6. 颜色与对比度。 检查配色方案的作用、对比度、语义状态、仅依靠颜色传递的含义、色相与饱和度的平衡，以及深色／浅色模式的影响。
7. 层次与图层逻辑。 检查阴影、边框、重叠、表面颜色、模态框、弹出层、卡片和焦点层级。
8. 图像与媒体。 检查图像质量、裁剪、预期尺寸、叠加文字的对比度、加载失败情况、UGC 和替代文本需求。
9. 状态与稳健性。 检查空状态、加载、错误、禁用、焦点、悬停、选中、验证、破坏性操作和成功状态。
10. 无障碍与包容性。 检查可感知性、可操作性、简洁性、容错性、键盘操作流程、焦点、触控目标的舒适度、对动作敏感用户的适配，以及屏幕阅读器语义。
11. 前端可行性。 检查视觉建议是否能通过设计令牌、语义化组件、响应式 CSS 和易维护的变体实现。
12. 修复事项的优先级。 将发现的问题分为高影响修复、润色改进和视情境而定的权衡。建议只做最少量的改动，以获得最大的提升。

工作流：创建或改进 UI

生成新设计或提出建议时，请按以下顺序进行：

1. 明确核心功能。 定义具体的屏幕、任务、受众和完成目标。从内容和功能入手，而不是导航装饰。
2. 列出必需元素。 确定主要内容、主要操作、辅助操作、限制条件和状态。
3. 选择最简单且实用的结构。 以低保真方式绘制或描述布局。在结构有效之前，避免使用颜色、阴影、图标和精细排版。
4. 以灰度建立层次。 先运用顺序、分组、尺寸、字重、间距和对比度。只有在不依靠颜色也能清晰呈现层次之后，再添加颜色。
5. 建立设计系统。 选择字号层级、间距层级、网格／容器规则、颜色角色、圆角、边框和高度令牌。
6. 编排布局。 将相关元素放在彼此附近，并清晰区分无关元素。避免使用含糊的间距。
7. 应用排版。 设置易读的正文、醒目的标题、克制的标签、恰当的行高、一致的强调方式，以及基线／边缘对齐。
8. 应用颜色和状态。 使用颜色来体现品牌、可操作性、状态和焦点。检查对比度，并添加非颜色线索。
9. 添加层次感和图像。 仅在阴影、重叠、背景变化和图像有助于明确表面、层次或品牌时使用它们。
10. 设计边缘状态。 纳入空状态、加载、错误、禁用、选中、焦点、悬停、长内容和窄屏幕行为。
11. 检查无障碍性和前端实现。 确保语义结构、键盘操作流程、焦点可见性、响应式行为、令牌化和减少动态效果支持。
12. 解释设计决策。 将建议表述为对用户目标和系统质量的改进，而不是个人喜好。

决策框架

当视觉决策存在歧义时，请使用以下框架：

1. 这个决策会影响任务完成吗？ 相较于新颖性，优先考虑清晰度、熟悉度、无障碍性和出错后的恢复能力。
2. 它能体现产品个性吗？ 如果能，但缺少品牌背景，请先询问。如果不能，则采用克制的默认方案。
3. 它会减少还是增加认知负担？ 对内容进行分组、渐进式披露，并突出推荐路径，同时不隐藏必要的复杂性。
4. 它会强化还是混淆层次？ 每个视觉线索都应支持某种优先级或关系。
5. 它适用于真实内容吗？ 测试长标签、空数据、密集数据、UGC、本地化、深色模式和响应式尺寸。
6. 它能否一致地实现？ 相较于一次性定制方案，优先选择基于令牌且可复用的模式。
7. 它无需特殊解释也能满足无障碍性吗？ 如果它依赖单一颜色、过小的操作目标、隐藏焦点、动态效果、脆弱的对比度或含糊的标签，请修改。

实用规则

层次

• 在设计样式之前，先为元素排序。确定哪些是主要、次要、三级和背景元素。
• 不要把所有重要内容都做得大、粗、彩色并加框。突出主要内容，并弱化其余内容。
• 谨慎运用多种视觉手段：尺寸、字重、对比度、间距、位置、颜色和层次感。通常一两个醒目的线索就足够了。
• 破坏性操作不一定是主要操作。应根据它在当前任务中的作用来设计样式；只有在确认步骤中确实需要做出破坏性决定时，才将其突出显示。
• 对于一目了然的结构化数据，标签应是最后手段。如果值本身已能表达含义，就弱化或移除标签。

布局与间距

• 先留出充足的空白，再逐步减少，直到布局适合任务。不要一开始就挤得很满，再一点点添加小边距，直到它勉强看起来不那么糟。
• 使用有明确含义、步长有显著差异的间距刻度。避免使用彼此只差几个像素的任意数值。
• 避免间距含糊不清。相关项目之间的距离应小于它们与其他分组之间的距离。
• 默认不要铺满整个屏幕。如果全宽会影响阅读或分组，就限制文本和内容的宽度。
• 将网格用作灵活的结构，而不是装饰。让内容和关系决定网格。
• 对于面向专家、监控、表格或高频操作的任务，应有意识地采用密集布局。

排版

• 根据内容、受众、平台和品牌选择字体，而不是仅仅因为某种字体看起来时髦。
• 使用较小的字号刻度。避免看起来像是无意造成的微小差异。
• 保持正文易读。段落和卡片使用较短的行长，小号文字使用较大的行高，大号标题则使用较紧的行高。
• 以易读为目标对齐文本。大多数拉丁字母正文优先左对齐。仅对简短、信息密度低的内容少量使用居中对齐。
• 当排版是主要视觉元素时，按基线对齐文本和控件。
• 在可用时使用真正的斜体、小型大写字母、数字字形和字重。避免伪造倾斜、水平拉伸和过度字距。
• 每个层级最多使用少数几种一致的视觉提示。避免同时叠加粗体、斜体、下划线、全大写、颜色和字号变化。

颜色

• 广泛应用颜色之前，先定义中性色、品牌／强调色、语义色、焦点色和表面色的用途。
• 调整色相、饱和度和亮度时，优先采用类似 HSL/OKLCH 的思路；不要一次只挑选一个孤立的十六进制值。
• 预先准备比最终 UI 看起来所需更多的色阶，以便悬停、激活、边框、背景和文本状态保持一致。
• 如果饱和色背景上的灰色文本会降低感知对比度，就不要使用。应选择与背景协调的颜色。
• 浅色中也要保留饱和度；避免使用会丧失个性和状态区分度的褪色调色板。
• 对错误、成功、警告、选中状态、链接和必填字段，使用非颜色提示。

深度、表面与边框

• 使用一致的光照模型。凸起的表面需要彼此协调的高光和阴影。
• 使用小范围的高度刻度。控件／卡片使用低高度，弹出层／下拉菜单使用中等高度，模态框和阻挡性表面使用较高高度。
• 在为所有地方添加粗重边框之前，优先考虑细微的背景变化、间距、阴影或强调色边缘。
• 仅当重叠能明确层级、形成有目的的视觉焦点或营造可控的动感时，才让元素重叠。不要以降低重要文本或控件清晰度的方式让它们重叠。
• 扁平化设计仍需要深度提示：层级、分组、对比度和表面变化。

图像与媒体

• 使用分辨率足够、裁切得当、风格一致且用途明确的图像。
• 如果没有对比度保护策略（叠加层、渐变、纯色面板、模糊或受控裁切），切勿直接将文本放在不可预测的图像上。
• 遵循图像的预期尺寸。不要将小型素材放大到超过其画质允许的范围，也不要把细节丰富的图像缩小到内容难以辨认。
• 将用户上传的图像视为会破坏布局和对比度的风险因素。提供裁切、备用表面、安全的文本放置方式，以及审核／占位符状态。

收尾细节

• 有意识地优化默认组件：关注焦点环、空状态、悬停／激活／禁用状态、选中状态、验证、加载骨架屏和微文案。
• 在解决层级和无障碍问题后，使用强调色边框、柔和背景和小型装饰元素来提升精致感。
• 空状态应说明缺少什么、为何重要，以及接下来该采取什么操作。
• 寻找投入小、收益高的细节优化：收紧标题行高、改善图标对齐、明确选中状态、统一圆角、提升表面间的对比度，并减少多余边框。

无障碍与包容性要求

将无障碍视为视觉构图的核心要求，而不是最后才进行的合规检查。

• 确保可感知性：文本、图标、控件和状态必须通过对比度、尺寸、标签、替代文本及冗余提示来确保可感知。
• 确保可操作性：控件应有舒适的目标区域、支持键盘操作、焦点顺序合理，并显示清晰的焦点状态。
• 确保简洁性：减少不必要的复杂性，使用清晰的标签，尽可能只呈现相关信息，并让模式清晰可见。
• 确保容错性：尽可能预防错误，在相关字段附近解释错误，保留用户输入，在可行时支持撤销／恢复，并让破坏性操作需要明确确认。
• 不要仅依赖颜色。应搭配文本、图标、形状、位置或图案。
• 尊重减少动态效果的偏好。除非提供非动态替代方式，否则避免用吸引注意的动态效果传达关键信息。
• 使用符合平台规范的最小触控目标尺寸；当操作精度很重要，或使用环境涉及移动设备、手部抖动或时间紧迫时，应增大目标尺寸或间距。
• 使用包容性图像。除非产品情境要求特定表现，否则避免让视觉选择暗示只有一种体型、能力、文化、设备或环境。
• 生产环境 UI 默认采用相当于 WCAG AA 的对比度和焦点可见性标准。只有当用户的产品要求更严格或不同的标准时才询问。

前端实现指南

当输出包含前端代码或实现建议时，应确保视觉设计切实可实现：

• 保留语义结构。视觉层级可以不同于文档层级，但标题、地标、列表、表格、按钮、链接和表单控件必须保持正确的语义。
• 使用设计令牌管理间距、字号、行高、颜色、圆角、阴影／层级、z-index 和动态效果时长／缓动。
• 使用响应式布局原语：在适当情况下使用网格／弹性布局、容器查询或断点、可读文本的最大宽度，以及流式媒体。
• 为主要／次要／三级／破坏性操作、选中、悬停、激活、禁用、焦点、加载、错误和成功状态提供组件变体。
• 操作使用真正的按钮，导航使用真正的链接。没有语义和键盘行为时，不要把非交互元素设计成控件。
• 保持焦点状态清晰可见，并与色彩系统一致。除非替换为同样醒目的焦点指示器，否则不要移除轮廓。
• 表格数据使用语义表格。不要用表格排版。对于数据密集型表格，应优先考虑对齐、易浏览性、固定上下文、截断规则和响应式溢出行为。
• 使用 CSS 变量或主题令牌支持浅色／深色模式。不要机械地反转颜色；应针对每种模式调整表面、边框、阴影和语义颜色。
• 优化图像，设置明确尺寸、响应式来源、替代文本，并在适当情况下延迟加载；为媒体损坏或缺失提供回退方案。
• 使用减少动态效果的媒体查询，避免让用户反馈被漫长动画阻塞。
• 优先采用易维护、稍欠新奇的方案，而不是需要脆弱 CSS 或一次性状态逻辑的自定义视觉处理。

质量检查清单

定稿批评、建议或 UI 实现前，请确认：

• 主要用户任务和主要操作一目了然。
• 添加颜色之前，界面在灰度模式下也能正常使用。
• 相关元素通过邻近、对齐和共同区域进行分组。
• 间距、字体、颜色、圆角和层级效果使用一套精简的规范。
• 文本易读，行长适中，层级提示保持一致。
• 颜色对比度足够，且颜色不是传达含义的唯一方式。
• 阴影、表面和边框能体现真实的分组或层级。
• 图片不会影响文本对比度、布局或含义。
• 已考虑空状态、加载状态、错误状态、焦点状态、禁用状态、选中状态和悬停状态。
• 已考虑触控目标、键盘操作流程、焦点可见性和屏幕阅读器语义。
• 设计能够适应长内容、密集数据、用户生成内容、本地化和窄屏。
• 建议按优先级排序，并说明其对用户的价值。

请使用 references/checklists.md 中的完整检查清单。

应避免的常见错误

• 先设计导航框架，再设计功能。
• 在层级关系明确之前就添加颜色、阴影、渐变和图标。
• 随意使用像素值，而不是采用一套间距、字体和颜色规范。
• 让每个重要元素都格外醒目。
• 仅用颜色区分链接、错误、状态或选中项。
• 过度使用边框，而不采用间距、分组或背景对比。
• 认为好看的 UI 就一定易用。
• 过度简化，导致用户无法看到决策所需的信息。
• 无充分的用户或品牌理由，却违背熟悉的心智模型。
• 因静态的理想流程看起来很完善，就忽略边缘状态。
• 生成外观正确却无法访问或语义错误的前端代码。

完整的反模式列表见 references/anti-patterns.md。

如何向用户解释建议

将视觉建议解释为功能上的权衡，而非个人喜好。

采用以下模式：

1. 观察： 描述当前设计的表现。
2. 影响： 说明可能对用户造成的影响。
3. 建议： 指出具体的修改。
4. 理由： 关联层级、分组、可读性、无障碍、惯例或实现方式。
5. 权衡： 说明何时其他方案会更合适。

示例风格：

主要操作与筛选标签视觉权重相同，因此彼此争抢注意力。将主要操作设为唯一的实心按钮，把筛选项弱化为次级标签，并加大工具栏与内容之间的间距。这样既能保持易浏览性，也能让筛选项易于发现。