ui-design-system

设计系统

此技能提供一套完整的设计系统：理念（如何思考设计）和文档（持续更新的风格指南模板）。每个界面都应呈现出由一支对 1 像素的差异精益求精的团队设计的质感。

工作流

1. 从设计方向开始 — 阅读第 1 部分，并在编写代码前确定设计方向
2. 应用工艺原则 — 构建时遵循第 2 部分的核心规则
3. 记录到风格指南中 — 将每个组件添加到风格指南中（第 3 部分）

---

第 1 部分：设计方向

编写任何代码之前，先确定设计方向。 不要默认采用某种风格。思考这款特定产品需要给人怎样的感觉。

考虑背景

• 这款产品的用途是什么？ 金融工具需要与创意工具不同的氛围。
• 谁会使用它？ 高级用户需要信息密集。偶尔使用的用户需要引导。
• 它要满足什么情感需求？ 信任？效率？愉悦？专注？
• 怎样才能让它令人印象深刻？ 每款产品都有机会展现独特个性。

选择个性

企业级 / SaaS UI 的风格范围比你想象的更广。不妨考虑以下方向：

精准与密集 — 紧凑间距、单色调、信息优先。适合长期使用该工具的高级用户。可以参考 Linear、Raycast 和终端美学。

温暖与亲和 — 宽松间距、柔和阴影、友好色彩。适合希望展现人情味的产品。可以参考 Notion、Coda 和协作工具。

精致与可信 — 冷色调、层叠质感、金融领域的沉稳气度。适合处理资金或敏感数据的产品。可以参考 Stripe、Mercury 和企业级 B2B 产品。

大胆与清晰 — 高对比度、大胆的留白、自信的字体。适合希望呈现现代、果断风格的产品。可以参考 Vercel 和极简仪表板。

实用与功能 — 柔和的配色、功能优先的信息密度、清晰的层级。适合工作本身比界面装饰更重要的产品。可以参考 GitHub 和开发者工具。

数据与分析 — 针对图表优化，兼具技术感与易用性，将数字视为核心内容。适用于分析、指标和商业智能产品。

选择一种，或融合两种。但要确定符合产品需求的方向。

选择色彩基础

不要默认使用暖色中性色。 请结合产品特点考虑：

• 暖色基础（奶油色、暖灰色）——亲和、舒适、有人情味
• 冷色基础（板岩色、蓝灰色）——专业、可信、严肃
• 纯中性色（纯灰色、黑白）——极简、大胆、技术感
• 带色调的基础色（略带色彩倾向）——独特、令人印象深刻、具有品牌感

浅色还是深色？ 深色模式并非简单地将浅色模式反转。深色给人技术感、专注感和高级感。浅色则显得开放、亲和、清爽。根据背景选择。

强调色 — 选择一种有意义的颜色。蓝色代表信任，绿色代表成长，橙色代表活力，紫色代表创造力。不要每次都选同一种强调色。

选择布局方式

应由内容决定布局：

• 密集网格，适用于信息量大、需要用户浏览和比较的界面
• 宽松间距，适用于需要用户专注的任务
• 侧边栏导航，适用于包含多个版块和许多目标位置的应用
• 顶部导航，适用于版块较少的简单工具
• 分栏面板，适用于需要保留上下文的列表—详情模式

选择字体

字体决定整体基调。不要总是默认采用同一种风格：

• 系统字体 — 快速、原生、不显眼（适合注重实用性的产品）
• 几何无衬线字体（Geist、Inter）— 现代、简洁、技术感
• 人文主义无衬线字体（SF Pro、Satoshi）— 更温暖、更亲和
• 融入等宽字体风格 — 技术感强、面向开发者、适合数据密集型场景

---

第 2 部分：工艺原则

无论设计方向如何，这些原则都适用。这是质量底线。

4px 网格

所有间距都使用 4px 基准网格：

• 4px - 微间距（图标间隙）
• 8px - 紧凑间距（组件内部）
• 12px - 标准间距（相关元素之间）
• 16px - 舒适间距（区块内边距）
• 24px - 宽裕间距（区块之间）
• 32px - 主要分隔

对称内边距

TLBR 必须一致。 如果顶部内边距为 16px，那么左侧、底部和右侧也必须是 16px。例外：当内容自然形成视觉平衡时。

/* Good */
padding: 16px;
padding: 12px 16px; /* Only when horizontal needs more room */

/* Bad */
padding: 24px 16px 12px 16px;

边框圆角一致性

遵循 4px 网格。更锐利的边角显得专业，更圆润的边角则显得亲切。选择一套规范并坚持使用：

• 锐利：4px、6px、8px
• 柔和：8px、12px
• 极简：2px、4px、6px

不要混用不同规范。一致性带来协调感。

层次与海拔策略

让层次处理方式与设计方向相匹配。 层次是一种工具，而非必需品：

仅使用边框（扁平） — 简洁、专业、密集。适用于注重实用性的工具，这类工具更看重信息密度，而非视觉上的悬浮感。Linear、Raycast 和许多开发者工具几乎不使用阴影，只用细微边框划分区域。

细微的单层阴影 — 轻柔的悬浮感，不显复杂。简单的 0 1px 3px rgba(0,0,0,0.08) 就足够。

多层阴影 — 丰富、高级、有立体感。多个阴影层可营造逼真的层次。Stripe 和 Mercury 采用这种方式。

表面颜色变化 — 无需任何阴影，背景色调变化就能建立层级。#f8fafc 背景上的 #fff 卡片看起来已经有悬浮感。

选择一种方式并坚持使用。

/* Borders-only approach */
--border: rgba(0, 0, 0, 0.08);
border: 0.5px solid var(--border);

/* Single shadow approach */
--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

/* Layered shadow approach */
--shadow-layered:
  0 0 0 0.5px rgba(0, 0, 0, 0.05),
  0 1px 2px rgba(0, 0, 0, 0.04),
  0 2px 4px rgba(0, 0, 0, 0.03),
  0 4px 8px rgba(0, 0, 0, 0.02);

卡片布局

单调的卡片布局是敷衍的设计。应根据每张卡片的具体内容设计其内部结构，但保持表面样式一致：相同的边框粗细、阴影深度、圆角、内边距比例和字体排版。

独立控件

UI 控件值得拥有容器样式。日期选择器、筛选器和下拉菜单都应该像精心设计的对象。

不要使用原生表单元素来实现样式化 UI。 应改用自定义组件：

• 自定义选择器：触发按钮 + 定位下拉菜单
• 自定义日期选择器：输入框 + 日历弹出层
• 自定义复选框／单选框：带状态管理的样式化 div

字体层级

• 标题：字重 600，字距较紧（-0.02em）
• 正文：字重 400-500，标准字距
• 标签：字重 500，大写文字使用略微为正的字距
• 字号：11px、12px、13px、14px（基准）、16px、18px、24px、32px

数据使用等宽字体

数字、ID、代码和时间戳应使用等宽字体。使用 tabular-nums 实现列对齐。

图标

使用 Phosphor Icons (@phosphor-icons/react) 或 Lucide (lucide-react)。图标用于阐明含义，而非装饰——如果移除图标不会损失任何含义，就移除它。

动画

• 微交互使用 150ms，较大的过渡使用 200-250ms
• 缓动：cubic-bezier(0.25, 1, 0.5, 1)
• 企业级 UI 中不要使用弹簧／弹跳效果

对比度层级

建立四级系统：前景（主要）→ 次要 → 柔和 → 微弱。始终一致地使用全部四级。

颜色只用于传达含义

灰色用于构建结构。颜色只在传达状态、操作、错误或成功时出现。装饰性颜色只会造成干扰。

导航上下文

屏幕需要明确所处位置：

• 导航 — 侧边栏或顶部导航，显示当前位置
• 位置指示 — 面包屑、页面标题或当前导航状态
• 用户上下文 — 谁已登录，当前工作区／组织是什么

深色模式注意事项

优先使用边框而非阴影 — 阴影在深色背景上不明显，应更多依靠边框。

调整语义颜色 — 状态颜色在深色背景上通常需要略微降低饱和度。

---

第 3 部分：反模式

绝不要这样做

• 使用夸张的投影（box-shadow: 0 25px 50px...）
• 在小元素上使用较大的圆角（16px 及以上）
• 没有明确理由却采用不对称内边距
• 在彩色背景上使用纯白卡片
• 使用粗边框（2px 及以上）作装饰
• 间距过大（各区块之间的边距超过 48px）
• 使用弹簧式或弹跳动画
• 使用渐变作装饰
• 在一个界面中使用多种强调色

始终反思

• “我是否考虑了这个产品的实际需求，还是默认采用了某种做法？”
• “这个方向是否适合当前的场景和用户？”
• “这个元素是否经过精心设计？”
• “我的层次策略是否一致且经过深思熟虑？”
• “所有元素是否都对齐网格？”

---

第 4 部分：风格指南模板

风格指南是设计系统的动态文档。 你构建的每个组件都应在此记录。

模板会创建什么

一个 /style-guide 页面，包含：

• 左侧导航 — 带层级区块导航的粘性侧边栏
• 颜色 — 品牌调色板、类别颜色、系统颜色
• 排版 — 字体系列、字号、字重
• 按钮 — 所有变体、尺寸和状态
• 输入框 — 默认、聚焦、错误、禁用状态
• 卡片 — 布局变体
• 头像 — 尺寸和后备状态
• 对话框 — 模态模式
• 加载/思考 — 加载旋转图标、指示器、动画状态
• 设计令牌 — 间距比例、圆角、阴影

使用模板

1. 复制到你的项目中

cp templates/style-guide-page.tsx your-app/app/style-guide/page.tsx

2. 自定义

1. 更新标题 — 将“STYLE GUIDE”替换为你的项目名称
2. 添加品牌颜色 — 使用你的调色板更新“Colors”区块
3. 添加字体 — 更新“Typography”区块
4. 导入组件 — 用实际组件替换占位导入
5. 添加项目专属区块 — 为自定义组件添加区块

3. 维护

风格指南是所有 UI 组件的权威来源。

构建或修改组件时：

1. 先查看风格指南 — 创建组件前先确认是否已有该组件
2. 添加新组件 — 每个可复用组件都应有一个区块
3. 展示所有状态 — 正常、悬停、聚焦、禁用、错误、加载
4. 变更时更新 — 修改组件后，更新其风格指南条目

模板结构

导航项定义侧边栏结构：

const NAV_ITEMS = [
  { id: 'colors', label: 'Colors', icon: Palette, children: [
    { id: 'brand', label: 'Brand' },
    { id: 'system', label: 'System' },
  ]},
  { id: 'typography', label: 'Typography', icon: Type },
  { id: 'buttons', label: 'Buttons', icon: MousePointer },
  // ... more sections
]

每个区块遵循以下模式：

<section id="buttons">
  <SectionHeader title="Buttons" />
  <div>
    <h4 className="text-xs font-medium text-muted-foreground mb-3 uppercase tracking-wide">
      Variants
    </h4>
    <div className="flex flex-wrap gap-3">
      <Button variant="default">Default</Button>
      <Button variant="secondary">Secondary</Button>
    </div>
  </div>
</section>

添加自定义区块

1. 添加到 NAV_ITEMS：

{ id: 'my-component', label: 'My Component', icon: Box },

2. 添加区块：

<section id="my-component">
  <SectionHeader title="My Component" />
  {/* Component variations */}
</section>

维护清单

每次 UI 变更时：

• 将组件添加到风格指南（如果是新组件）
• 展示所有状态（正常、悬停、禁用、加载、错误）
• 使用设计令牌（主题中的颜色、间距、圆角）
• 从组件索引正确导出

最佳实践

1. 保持更新 — 过时的风格指南比没有更糟
2. 展示真实数据 — 使用逼真的模拟数据，而不是“Lorem ipsum”
3. 测试交互 — 对话框应能打开，按钮应能点击
4. 记录边界情况 — 长文本、空状态、加载状态
5. 考虑移动端 — 如适用，展示响应式变体

---

标准

每个界面都应看起来像是由一支会仔细打磨 1 像素差异的团队设计的。不是一味删减，而是精心打造，并针对具体场景进行设计。

目标：兼具精致细节与简约风格，并展现恰当的个性。品质标准一致，执行方式由场景决定。