elegant-design

设计优雅的界面

理念

世界一流的设计是经过深思熟虑、易于访问且令人愉悦的。每个元素都有其用途，每次交互都自然流畅，体验能够在不同情境下优雅适配。

核心原则：

• 清晰胜于巧妙 - 用户不应为下一步该做什么而困惑
• 一致胜于新奇 - 模式应以可预测的方式重复出现
• 性能胜于功能 - 快速、流畅的交互胜过视觉复杂性
• 始终注重无障碍性 - 从一开始就为所有用户设计
• 渐进式披露 - 仅在需要时展示复杂内容
• 有意设置阻力 - 让破坏性操作更难执行，让建设性操作轻松完成

何时使用此技能

在以下情况下使用此技能：

• 使用 React/Next.js/类似框架构建 Web 应用
• 创建开发者工具或技术界面
• 设计包含聊天、终端或代码展示的界面
• 实现实时或流式功能
• 确保无障碍性和响应式设计
• 使用 shadcn/ui、daisyUI 或 HeroUI 设计系统

设计流程

按照此流程获得最佳效果：

1. 发现与规划（15-30 分钟）

梳理用户体验：

# Create flow diagrams with Graphviz
cat > user-flow.dot << 'EOF'
digraph UserFlow {
  Start -> "Observe State"
  "Observe State" -> "Orient Understanding"
  "Orient Understanding" -> "Decide Action"
  "Decide Action" -> "Act Execute"
  "Act Execute" -> "Observe State" [label="OODA loop"]
}
EOF

dot -Tpng user-flow.dot -o user-flow.png

OODA 循环梳理： 针对每个主要用户目标，优化以下循环：

1. 观察 - 用户需要哪些信息？
2. 判断 - 用户如何理解这些信息？
3. 决策 - 用户有哪些选择？
4. 行动 - 用户如何执行？

记录各类状态：

• 入口点（用户如何进入）
• 核心循环（重复执行的操作）
• 成功状态（目标已达成）
• 失败状态（错误及恢复路径）
• 边缘情况（空、加载中、错误、极端数据）

列出交互线索： 识别所需的每个 UI 元素：

• 导航（在各个部分之间切换）
• 操作（按钮、链接、控件）
• 输入（表单、编辑器、选择器）
• 反馈（成功、错误、加载中）
• 内容（文本、图像、数据）
• 路径指引（面包屑、进度）

构建自定义组件之前：

1. 先搜索 shadcn/ui（https://ui.shadcn.com）
2. 查看 daisyUI（https://daisyui.com）
3. 探索 HeroUI（https://heroui.com）
4. 仅在必要时构建自定义组件

2. 设计基础（20-40 分钟）

建立视觉系统：

阅读详细的基础指南：

• foundation/typography.md - 字体选择（Geist、JetBrains Mono）、字号体系和加载
• foundation/colors-and-spacing.md - 配色方案、间距系统、深色模式
• foundation/layout-patterns.md - 网格、容器、留白、响应式断点

快速参考：

• 排版：界面使用 Geist，代码使用 JetBrains Mono（最小字号为 14px）
• 间距：以 8px 为基准的系统（0.5rem、1rem、1.5rem、2rem、3rem、4rem、6rem、8rem）
• 颜色：语义化令牌（--color-background、--color-primary、--color-error 等）
• 布局：移动优先、12 列网格、充足留白

3. 交互元素（30-60 分钟）

设计复杂的交互功能时，请参考专门的指南：

聊天与消息：

• 构建对话界面时，阅读 interactive/chat-and-messaging.md
• 涵盖消息状态、流式传输、自动滚动、Markdown 渲染

终端与代码展示：

• 终端模拟器、语法高亮和语义高亮请阅读 interactive/terminals-and-code.md
• 涵盖 ANSI 颜色、Shiki 集成、复制按钮、行高亮

流式传输与加载：

• 渐进式加载、流式文本和乐观更新请阅读 interactive/streaming-and-loading.md
• 涵盖骨架屏、进度指示器、加载层级

差异与日志：

• 版本控制界面和日志查看器请阅读 interactive/diffs-and-logs.md
• 涵盖分栏式/统一式差异、字符级变更、虚拟滚动

4. 实现（1-3 小时）

构建组件：

• 阅读 implementation/components-and-accessibility.md，了解组件架构和 WCAG 合规要求
• 使用原子设计：原子 → 分子 → 有机体 → 模板 → 页面
• 确保支持键盘导航和屏幕阅读器

优化性能：

• 阅读 implementation/performance.md，了解 Core Web Vitals 优化
• 延迟加载、拆分代码、优化图片，并使用 Lighthouse 进行测量

测试与完善：

• 阅读 implementation/testing-and-qa.md，了解全面的测试方法
• 使用多种设备和屏幕尺寸进行测试，并借助无障碍工具进行测试

5. 验证与完善

发布前检查清单：

• 已测试用户流程，并优化 OODA 循环
• 已处理所有状态（空、加载中、错误、成功）
• 支持移动端响应式布局（已在真实设备上测试）
• 符合无障碍要求（WCAG AA）
• 已测量性能（Lighthouse 评分 > 90）
• UI 使用 Geist，代码使用 JetBrains Mono
• 尽可能使用设计系统组件
• 间距和排版保持一致
• 浅色和深色模式均可正常使用
• 键盘导航完整
• 交互元素已完善（参见交互指南）

快速决策树

需要了解基础知识？ → 先阅读 foundation/ 文件

要构建聊天或消息功能？ → 阅读 interactive/chat-and-messaging.md

要构建终端或代码编辑器？ → 阅读 interactive/terminals-and-code.md

需要流式传输或加载状态？ → 阅读 interactive/streaming-and-loading.md

要构建差异或日志查看器？ → 阅读 interactive/diffs-and-logs.md

准备开始实现？ → 阅读 implementation/ 文件

需要工具或想避免错误？ → 阅读 reference/ 文件

设计系统优先级

1. shadcn/ui (https://ui.shadcn.com) - 首选

   • 默认无障碍支持出色
   • 基于 Radix UI 原语
   • 基于 Tailwind，支持自定义
   • 可复制粘贴到项目中

2. daisyUI (https://daisyui.com)

   • 语义化组件名称
   • Tailwind 插件
   • 快速原型开发

3. HeroUI (https://heroui.com)

   • 现代、精致
   • 设计语言鲜明
   • 适用于产品界面

详细对比和使用模式请参阅 reference/design-systems.md。

排版规范

仅使用以下字体：

• Geist (https://vercel.com/font) - 用于所有界面文本

  • UI 标签、正文、标题
  • 占排版内容的 95%

• JetBrains Mono (https://jetbrains.com/mono) - 用于所有代码和技术内容

  • 代码块、终端、日志、差异
  • 最小字号为 14px
  • 启用连字

切勿混用多种无衬线字体或多种等宽字体。

完整指南请参阅 foundation/typography.md。

灵感网站

参考以下网站的设计模式：

• Vercel (https://vercel.com) - 宽敞的留白、清晰的排版
• Hex (https://hex.tech) - 数据密集但布局有序
• Baseten (https://docs.baseten.co) - 清晰的文档结构
• Weather Underground (https://wunderground.com) - 复杂数据，简洁呈现
• Ghostty (https://ghostty.org) - 现代终端，设计优雅

常见反模式

避免以下错误：

• ❌ 设计系统已有组件时仍自行构建自定义组件
• ❌ 使用绝对定位进行布局
• ❌ 为开销较大的属性设置动画（宽度、高度）
• ❌ 跳过移动端测试
• ❌ 忽视无障碍要求
• ❌ 所有内容都使用 <div>
• ❌ 混用多种等宽字体
• ❌ 用户正在阅读时自动滚动
• ❌ 在终端中显示原始 ANSI 代码
• ❌ 忘记空、加载中和错误状态

完整列表及说明请参阅 reference/anti-patterns.md。

迭代开发

对于简单的界面（单页、组件较少）：

1. 从基础开始（阅读基础文件）
2. 使用设计系统组件
3. 测试并优化

对于复杂的界面（包含多项功能和交互元素）：

1. 梳理流程并创建图表
2. 建立基础（阅读基础文件）
3. 一次构建一项功能（阅读相关的交互文件）
4. 在继续下一项之前测试每项功能
5. 优化并完善（阅读实现文件）

对于开发者工具或技术界面：

1. 仔细梳理 OODA 循环
2. 阅读所有交互文件（聊天、终端、代码、流式传输、差异和日志）
3. 注重键盘导航和性能
4. 使用实际的技术内容进行测试

获取帮助

如果不确定从哪里开始：

1. 阅读上面的设计理念部分
2. 遵循设计流程工作流
3. 根据需要查阅具体指南

如果感觉设计不太对：

1. 对照原则检查（清晰、一致、高性能）
2. 查看反模式列表
3. 研究灵感网站
4. 使用真实用户进行测试

如果实现进展缓慢：

1. 优先使用设计系统组件
2. 不要重复构建已有的内容
3. 一次专注于一项功能
4. 尽早并经常测试

文件组织

elegant-design/
├── SKILL.md (you are here)
├── foundation/
│   ├── typography.md (fonts, scales, loading)
│   ├── colors-and-spacing.md (palettes, spacing system, dark mode)
│   └── layout-patterns.md (grids, containers, responsive)
├── interactive/
│   ├── chat-and-messaging.md (chat UIs, streaming messages)
│   ├── terminals-and-code.md (terminals, syntax highlighting)
│   ├── streaming-and-loading.md (progressive loading, skeletons)
│   └── diffs-and-logs.md (version control UI, log viewers)
├── implementation/
│   ├── components-and-accessibility.md (architecture, WCAG)
│   ├── performance.md (Core Web Vitals, optimization)
│   └── testing-and-qa.md (testing checklist, tools)
└── reference/
    ├── design-systems.md (shadcn, daisyUI, HeroUI details)
    ├── tools-and-libraries.md (complete tool list)
    └── anti-patterns.md (what not to do, with explanations)

请记住

世界级的设计是无形的。 用户不应该注意到你巧妙的解决方案——他们只需轻松实现自己的目标，或许还能会心一笑。

从简单开始，根据真实使用情况迭代。 不要一次性构建所有内容。先构建所需内容，测试并优化，然后再开始下一项功能。

无障碍访问不是可选项。 从一开始就考虑键盘导航、屏幕阅读器和足够的对比度。事后改造要困难得多。

性能至关重要。 再美观的界面，如果运行缓慢，也是糟糕的界面。尽早并经常衡量性能。