设计与 UI
打造看起来有意图且高级的界面,而不是模板化的通用界面。这是应用构建器中最重要的质量杠杆。将其应用于 DOM / 覆盖层 UI — 页面、浏览器 chrome、HUD、菜单、表单。(对于 3D 游戏玩法画布,请参阅 building-games 技能;本技能管辖覆盖在其之上的 DOM UI。)
深入阅读 references/ 目录(按需加载——不要全部内联):
references/refined-ui.md— 完整的产品 chrome/覆盖层设计系统。references/typography.md— 字体尺度、搭配、节奏。references/surfaces.md— 层级、边框、阴影、分层。references/animations.md— 动效、缓动、过渡。references/performance.md— 保持 UI 流畅(60fps,无卡顿)。
1. 设计系统优先(在编写任何样式之前这样做)
先定义系统,然后从系统中组合。永远不要随意使用临时值。
- CSS 中的令牌(Tailwind v4 是 CSS 优先)。 在
src/styles.css的@theme中将调色板、圆角和字体定义为 CSS 变量;通过 Tailwind 工具类来使用它们。保持单一事实来源。@import "tailwindcss"; @theme { --color-bg: #0b0b0f; --color-surface: #16161d; --color-fg: #e7e7ea; --color-muted: #a0a0ab; --color-primary: #14b8a6; --color-border: #26262f; --radius: 0.75rem; --font-sans: "Inter", system-ui, sans-serif; } - 使用 shadcn/ui 组件(Radix 原语 +
cva变体 +tailwind-merge)来构建按钮、对话框、下拉菜单、输入框等。它们具有可访问性和一致性。将它们生成到src/components/ui中;通过令牌设置样式,不要使用内联十六进制颜色。 - Tailwind v4 基础修复——按钮需要指针光标。 v4 的 Preflight 使
<button>使用cursor: default,这感觉像是有问题的。在src/styles.css中一次性添加以下代码,以便按钮/可点击角色显示指针:@layer base { button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; } } - 禁止临时样式: JSX 中不得出现原始十六进制颜色,不得有
text-white/bg-black字面量,不得使用像p-[16px]或text-[13px]这样的任意值。如果需要某个值,它必须成为一个令牌或尺度步进。
2. 量化规则(防止“丑”的廉价规则)
- 总共 ≤ 3–5 种颜色(一个主色 + 中性色 + 最多一个强调色)。无随机额外色调。除非被要求,否则不要默认使用紫色。
- ≤ 2 种字体族(通常是一种)。可以将展示/标题字体与正文字体配对,或者只使用一种。
- 正文字体行高 1.4–1.6;大标题行高更紧凑。
- 当你覆盖背景颜色时,也要同时覆盖前景/文本颜色(对比度必须保持——同时检查亮色和暗色模式)。
- 移动优先:先设计约 390px 的布局,然后向上扩展。无水平溢出;触摸目标 ≥ 44px。
- 一致的空间尺度(基于 4/8)。慷慨的留白优于拥挤。
- 一个强调色,适度使用用于主要操作——而不是到处使用。
3. 反“AI 味”(那些让输出显得模板化的特征——避免它们)
- 无渐变色块填充,无作为内容替代的巨大 hero 渐变。
- 无表情符号作为图标——使用真正的图标集(
lucide-react)。 - 无手绘 SVG 插图/地图/图表——使用真正的库(图表用
recharts)或真正的生成图像。 - 最终产品中无占位图 / 灰色 Lorem 占位框——生成真正的图像或使用真实内容;对 canvas 图像设置
crossOrigin="anonymous"。 - 避免过度使用的字体外观(仅默认系统字体,或 Comic Sans 级别的字体选择)。
- 每个元素都要有它存在的理由。 削减装饰性噪音。建立一个系统,然后有意图地变化——而不是随机变化。
- 在编辑现有应用时,匹配已有的 UI;不要引入第二种视觉语言。
4. 布局与层级
- 清晰的视觉层级:每个视图一个主要操作;大小/粗细/颜色表达重要性。参见
references/typography.md和references/surfaces.md。 - 使用真正的布局结构(网格/弹性容器、容器最大宽度),而不是绝对定位的 hack。对齐到一致的网格。
- 空状态、加载状态和错误状态是设计的一部分——不要发布空白/卡顿的中间状态。
5. 动效(微妙、有目的)
- 短暂、缓和的过渡(150–250ms)用于悬停/按下/进入;尊重
prefers-reduced-motion。详细内容见references/animations.md。 - 永远不要以导致卡顿的方式动画化布局;优先使用 transform/opacity。
6. 游戏覆盖层(当此技能与 building-games 配合使用时)
游戏画布由 building-games 管理。本技能为 DOM 覆盖层 设置样式:开始/“点击以播放”画面、HUD、分数、菜单、暂停、移动端控件。保持覆盖层在画布上可读(背景遮罩、对比度),并使其远离指针锁定/游戏输入路径。
完成清单(在您认为 UI 完成之前)
- 在
@theme中定义了令牌;JSX 中没有临时十六进制颜色 / 任意值。 - ≤ 5 种颜色,≤ 2 种字体,一致的空间尺度。
- 对比度保持;在覆盖背景的地方同时覆盖了前景色。
- 移动端(约 390px)无溢出;触摸目标 ≥ 44px。
- 使用真正的图标/图像/图表——没有反“AI 味”的特征。
- 处理了加载/空/错误状态;动效微妙且支持减少动效模式。
- 在浏览器中渲染并肉眼检查过(参见 AGENTS.md 验证),而不仅仅是 curl 测试。