design-frontend

Web UI 的视觉设计系统

用于构建一致、无障碍、响应式界面的设计系统模式。Tailwind CSS v4 通过 CSS 变量支持运行时主题设置，改变了游戏规则。核心模式包括：设计令牌（颜色、间距、排版）、响应式断点和容器查询、具备适当对比度的深色模式、组件组合，以及间距比例。

主要挑战：使用硬编码值而不是令牌（难以维护）、响应式设计缺乏移动优先思维、事后才实现深色模式（无障碍性不足）、使用容器查询实现组件级响应式设计（而不只是基于视口）。

工作流

实现视觉设计时：

1. 定义令牌 — 在 @theme 中将颜色、间距、排版和阴影设为 CSS 变量
2. 选择容器 — 将组件包裹在 @container 中，以使用容器查询
3. 移动优先构建 — 从移动端布局开始，逐步向上添加断点
4. 测试深色模式 — 使用 dark: 变体；确保对比度符合要求
5. 验证触控目标 — 交互元素的最小尺寸为 44x44px
6. 衡量性能 — CSS-in-JS 库会影响绘制时间；Tailwind 不产生运行时开销

规则

模式按关注点分类：

• 布局 — 最大宽度容器、一致的间距、视觉层次
• 响应式设计 — 移动优先方案、断点、容器查询
• 设计令牌 — 颜色比例、间距比例、字体系列
• 深色模式 — 适当的对比度、颜色配对、用于主题设置的 CSS 变量
• 组件 — 触控目标、可供性、无障碍性

请参阅 rules/，了解实现模式和示例。

示例

正向触发

用户：“为我们的组件库搭建一个支持深色模式的 Tailwind 设计令牌系统。”

预期行为：使用 design-frontend 指南，应用 CSS 变量和颜色配对的令牌模式。

非触发

用户：“编写一个用于用户身份验证的 Node.js REST API。”

预期行为：不要优先使用 design-frontend；选择更相关的技能，或不使用技能直接处理。

• 错误：在类中硬编码颜色值；更改主题需要重构

• 原因：未使用设计令牌；颜色散布在整个代码库中

• 解决方案：使用 @theme 将颜色定义为 CSS 变量；通过 var(--color-*) 引用

• 错误：深色模式显示灰蒙；深色背景上的对比度低

• 原因：颜色未成对设计；误以为反转颜色就能奏效

• 解决方案：测试深色变体；使用对比度合适的颜色比例

故障排查

• 错误：容器查询不起作用；元素未随容器尺寸变化

• 原因：父元素未标记为 @container 类

• 解决方案：为父元素添加 @container；在子元素上使用 @sm:、@md:、@lg: 变体

• 错误：深色模式样式未生效；dark: 变体被忽略

• 原因：未配置深色模式；在配置中使用 darkMode: "class" 或 "media"

• 解决方案：在 tailwind.config.js 或 CSS @custom-variant 中配置深色模式

• 错误：触控目标过小；用户难以点击按钮

• 原因：过度针对桌面端优化；假设移动端也能像鼠标一样精准操作

• 解决方案：触控目标至少使用 h-11 / w-11（44px）