ux-patterns

UX 模式

概述

绝不要凭猜测生成 UI。务必先查阅已记录的模式。

核心原则： 每个 UI 元素都必须能追溯到已记录的 UX 模式或设计系统组件。如果无法引用参考依据，你就是在猜测——而猜测只会产出业余水准的结果。

没有例外。没有变通办法。没有捷径。

首要指令

NO UI CODE WITHOUT A UX REFERENCE FIRST

如果你尚未确定适用的模式，就无权编写该组件。写了没有参考依据的 UI 代码？删掉它。从查找参考依据重新开始。

别找借口：

• 不要不使用设计令牌就“快速制作原型”
• 不要想着“以后再回来完善样式”
• 不要为了“先让它跑起来”而使用任意像素值
• 不要为了“简单”组件绕过入门流程
• “又快又糙”的 UI 总会被发布。它总会被发布。

适用场景

始终适用：

• Web 应用（SaaS、仪表板、管理面板）
• 落地页和营销网站
• 游戏界面（菜单、HUD、物品栏、商店）
• CLI 界面（输出格式、交互式提示）
• 移动应用
• 组件库
• 人类能感知到的任何视觉输出

包括以下情况：

• “这只是个原型”（原型会变成产品）
• “没人会看到它”（总会有人看到）
• “我以后会完善它”（你不会）

入门流程

digraph entry_protocol {
    rankdir=TB;
    start [label="Need to author UI code", shape=doublecircle];
    identify [label="IDENTIFY\nWhat UI pattern is this?", shape=diamond];
    reference [label="REFERENCE\nConsult pattern in\npattern-libraries.md", shape=box];
    tokens [label="TOKENS\nDesign tokens established?", shape=diamond];
    define_tokens [label="Establish tokens from\ndesign-tokens.md", shape=box];
    adopt [label="ADOPT\nApply reference spacing,\ntypography, layout", shape=box];
    adapt [label="ADAPT\nModify only what the\nspecific context demands", shape=box];
    write [label="Author UI code", shape=doublecircle];
    halt [label="HALT\nYou are guessing", shape=octagon, style=filled, fillcolor=red, fontcolor=white];

    start -> identify;
    identify -> reference [label="identified"];
    identify -> halt [label="unknown\npattern"];
    reference -> tokens;
    tokens -> adopt [label="yes"];
    tokens -> define_tokens [label="no"];
    define_tokens -> adopt;
    adopt -> adapt;
    adapt -> write;
    halt -> identify [label="research\nfirst"];
}

编写任何 UI 代码之前，必须完成每个阶段：

1. 确定 —— 这是哪种 UI 模式？（导航、表单、数据表格、模态框、卡片等）
2. 查阅参考 —— 在 pattern-libraries.md 中查阅该模式
3. 确认设计令牌 —— 确认此项目已建立设计令牌（参见 design-tokens.md）
4. 采用 —— 应用参考中的间距、字体排印、布局和交互模式
5. 适配 —— 只修改具体情境所需的部分
6. 编写 —— 然后才能编写 UI 代码

跳过任何阶段 = 猜测。删除并重新开始。

设计令牌要求

每个 UI 项目都必须在编写任何组件代码之前定义以下令牌：

令牌类别	定义内容	重要性
颜色	主色、辅助色、中性色阶（50-950）、语义色（错误、成功、警告、信息）	杜绝“随意选色”综合征
字体排印	字体系列（最多 2 种）、字号阶梯（xs 至 4xl）、字重阶梯（常规、中等、半粗、粗体）、行高	字体排印决定了 95% 的视觉质量
间距	基础单位（4px 或 8px）、阶梯（xs：4px 至 3xl：64px）	系统化的间距营造专业感
边框圆角	阶梯：无、sm、md、lg、full	确保组件形状一致
阴影	3-4 个层级（sm、md、lg、xl）	建立清晰的深度层次
断点	至少包括 sm（640px）、md（768px）、lg（1024px）、xl（1280px）	从一开始就实现响应式行为
Z-index	阶梯：下拉菜单（10）、粘性元素（20）、模态框（30）、弹出框（40）、Toast（50）	避免 Z-index 冲突

按项目分类提供现成的令牌模板，请查阅 design-tokens.md。

模式查找方法

digraph pattern_selection {
    rankdir=TB;
    what [label="What am I building?", shape=diamond];
    saas [label="SaaS / Dashboard /\nAdmin Panel?", shape=diamond];
    game [label="Game Interface?", shape=diamond];
    marketing [label="Landing Page /\nMarketing Site?", shape=diamond];
    devtool [label="Developer Tool /\nCLI?", shape=diamond];
    ecommerce [label="Online Store?", shape=diamond];

    use_saas [label="SaaS patterns\n(data-dense, navigation-heavy)", shape=box];
    use_game [label="Game UI patterns\n(dark theme, bold, animated)", shape=box];
    use_marketing [label="Marketing patterns\n(conversion-focused, hero sections)", shape=box];
    use_devtool [label="Dev tool patterns\n(monospace, high contrast, minimal)", shape=box];
    use_ecommerce [label="E-commerce patterns\n(product-focused, trust signals)", shape=box];
    use_general [label="General UI patterns\n(clean, accessible, standard)", shape=box];

    lookup [label="Consult specific component\nin pattern-libraries.md", shape=box];

    what -> saas;
    saas -> use_saas [label="yes"];
    saas -> game [label="no"];
    game -> use_game [label="yes"];
    game -> marketing [label="no"];
    marketing -> use_marketing [label="yes"];
    marketing -> devtool [label="no"];
    devtool -> use_devtool [label="yes"];
    devtool -> ecommerce [label="no"];
    ecommerce -> use_ecommerce [label="yes"];
    ecommerce -> use_general [label="no"];

    use_saas -> lookup;
    use_game -> lookup;
    use_marketing -> lookup;
    use_devtool -> lookup;
    use_ecommerce -> lookup;
    use_general -> lookup;
}

按项目分类和模式类别整理的完整参考，请查阅 pattern-libraries.md。

业余 UI 的标志（反模式）

这些是 AI 生成的业余 UI 一眼可辨的特征。每一种都说明没有参考现有设计。

反模式	看起来业余的原因	专业人士的做法
间距混乱	没有网格系统，间距显得随意，同级元素之间的内边距各不相同	使用间距设计令牌。每个间距值都必须对应一个令牌。
随意选色	各组件单独选色，没有统一的调色板，色相过多	先定义完整的调色板。每种颜色都必须引用一个令牌。
排版杂乱	字号不匹配、行高不一致、字重过多、层级不清晰	最多使用 2 种字体。遵循字体比例。精心设计标题层级。
视觉层级扁平	所有内容的大小和字重都相同，没有视觉焦点，难以浏览	主要操作在视觉上要突出。次要元素应弱化。通过大小、字重、颜色和对比度制造变化。
圆角不一致	尖角和圆角混用，类似元素的边框宽度各不相同	定义圆角比例。同类组件使用相同的圆角。
占位内容	“Lorem ipsum”、“User Name”、“Description here”、“Item 1”	使用能体现实际数据结构和长度的真实内容。
缺少交互状态	按钮对鼠标光标没有反馈，链接含义模糊，没有键盘焦点环	为所有可交互元素定义交互状态（悬停、聚焦、激活、禁用）。
所有内容都居中	AI 的默认行为：将所有文本、内容和区块居中	使用带有适当网格的左对齐布局。只在有意为之时才居中（主视觉标题、CTA）。
文本墙千篇一律	每段文字、标签和描述都使用相同的字号和字重	调整字重和字号。标签字号更小、颜色更浅。标题字号更大、字重更粗。描述使用弱化的颜色。
缺少非理想状态	UI 只有“已填充”状态，没有骨架屏或错误消息	设计所有状态：空、加载中（骨架屏）、错误、部分完成、成功。
组件尺寸过大	按钮太高、输入框太宽、卡片占满整个视口	使用标准尺寸。按钮高度：36-44px。输入框：36-40px。限制卡片最大宽度。
缺少留白节奏	内容挤在一起，或散落在过多空白中	各区块保持一致的垂直节奏。相关项目彼此靠近，无关项目之间则留出明显间隔。
不必要的效果	随意添加渐变、所有元素都加阴影、动画多余	效果应有明确用途。阴影用于表示层级。渐变要柔和。动画应发挥功能。
整十数值的间距	使用 10px、20px、30px，而非遵循系统	使用 4px 或 8px 基准单位。间距值：4、8、12、16、24、32、48、64。

组件验证清单

编写任何组件前，请确认以下所有项目：

• 已为此项目建立设计令牌（颜色、排版、间距、圆角、阴影）
• 已从 pattern-libraries.md 中确定设计模式
• 间距遵循令牌比例（没有任意指定的 px 值）
• 排版遵循字体比例（没有任意指定的字号）
• 颜色均来自已定义的调色板（没有十六进制字面值）
• 边框圆角遵循已定义的比例
• 已为所有可交互元素定义悬停、聚焦、激活和禁用状态
• 已至少为移动端和桌面端指定响应式行为
• 使用了真实内容（没有占位文本）
• 已验证无障碍性：对比度（正文文本为 4.5:1，大号文本为 3:1）、ARIA 标签、键盘导航
• 已设计空状态
• 已设计加载状态（优先使用骨架屏，而非加载动画）
• 已设计错误状态

无法满足所有项目？那你还没准备好编写这个组件。

认知陷阱

合理化借口	真相
“这只是一个原型”	原型会变成产品。专业的原型也会使用设计令牌。
“我稍后再调整样式”	你不会。“稍后”永远不会到来。后续的每项任务都会优先于它。
“用户没有指定设计要求”	没有要求不代表可以随意猜测。默认使用设计令牌。
“我得先让逻辑跑起来”	逻辑和呈现不是两个独立阶段。建立设计令牌只需 5 分钟。
“这个组件太简单，用不着搞那么复杂”	不一致往往从简单组件开始。一个没有使用设计令牌的按钮，会影响它出现的每个页面。
“我以后再采用设计系统”	现在不使用设计令牌，以后就得费力适配设计系统。使用设计令牌后，采用设计系统会轻而易举。
“只写一个硬编码颜色，没什么大不了”	一个会变成十个。最后你就会得到一套意外拼凑的调色板。
“AI 能让它看起来还过得去”	“还过得去”正是业余 UI 的典型特征。选择专业，还是业余。

防护规则——停止并查阅参考

如果你发现自己在做以下任何一件事：

• 写 color: #3b82f6，但它不是已定义的设计令牌值
• 使用 padding: 10px，而不是间距设计令牌
• 选择类型比例中没有的字号
• 构建组件时没有查阅 pattern-libraries.md
• 暂时搁置悬停／焦点状态
• 使用“Lorem ipsum”或“示例文本”
• 因为“看起来还行”就把所有内容都居中
• 为了“让它更醒目”而添加渐变或阴影
• 尚未建立设计令牌就编写 CSS
• 构建表单时没有查阅表单模式
• 创建仪表盘时没有查阅仪表盘模式

每一项都意味着：立即停止。移除相关内容。返回入口协议。

集成

调用方：

• godmode:intent-discovery —— 设计涉及 UI 时，调用此技能
• godmode:task-planning —— 涉及 UI 工作的计划应参考此技能
• godmode:delegated-execution —— 执行 UI 实现的子 Agent 必须使用此技能

互补技能：

• godmode:ui-engineering —— 此技能提供参考系统；该技能提供实现模式
• godmode:design-integration —— 用于采用现有设计系统

支持文件：

• pattern-libraries.md —— 按项目分类和类别整理的完整模式参考
• design-tokens.md —— 按项目分类整理的即用型设计令牌模板