elegant-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Designing Elegant Interfaces

设计优雅界面

Philosophy

设计理念

World-class design is intentional, accessible, and delightful. Every element serves a purpose, every interaction feels natural, and the experience adapts gracefully across contexts.

Core Principles:

Clarity over cleverness - Users should never wonder what to do next
Consistency over novelty - Patterns should repeat predictably
Performance over features - Fast, smooth interactions trump visual complexity
Accessibility always - Design for all users from the start
Progressive disclosure - Reveal complexity only when needed
Intentional friction - Make destructive actions harder, constructive actions effortless

世界级的设计是有目的性、可访问且令人愉悦的。每个元素都有其存在的意义，每个交互都感觉自然，体验能在不同场景下优雅适配。

核心原则：

清晰优先于花哨——用户永远不必疑惑下一步该做什么
一致性优先于新颖性——设计模式应具备可预测的重复性
性能优先于功能——流畅快速的交互比视觉复杂度更重要
始终兼顾无障碍——从设计之初就为所有用户考虑
渐进式披露——仅在必要时展示复杂内容
合理设置操作门槛——让破坏性操作更难执行，建设性操作更轻松

When to Use This Skill

适用场景

Use this skill when:

Building web applications with React/Next.js/similar frameworks
Creating developer tools or technical interfaces
Designing interfaces with chat, terminals, or code display
Implementing real-time or streaming features
Ensuring accessibility and responsive design
Working with shadcn/ui, daisyUI, or HeroUI design systems

在以下场景可使用本技能：

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

Design Process Workflow

设计流程

Follow this workflow for optimal results:

遵循以下工作流以获得最佳效果：

1. Discovery & Planning (15-30 min)

1. 需求探索与规划（15-30分钟）

Map User Experience:

bash

undefined

梳理用户体验流程：

bash

undefined

Create flow diagrams with Graphviz

使用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 Loop Mapping:**
For each major user goal, optimize the cycle:
1. **Observe** - What information does the user need?
2. **Orient** - How do they make sense of it?
3. **Decide** - What choices are available?
4. **Act** - How do they execute?

**Document States:**
- Entry points (how users arrive)
- Core loops (repeated actions)
- Success states (goals achieved)
- Failure states (errors, recovery paths)
- Edge cases (empty, loading, error, extreme data)

**List Affordances:**
Identify every UI element needed:
- Navigation (movement between sections)
- Actions (buttons, links, controls)
- Inputs (forms, editors, pickers)
- Feedback (success, error, loading)
- Content (text, images, data)
- Wayfinding (breadcrumbs, progress)

**Before Building Custom Components:**
1. Search shadcn/ui first (https://ui.shadcn.com)
2. Check daisyUI (https://daisyui.com)
3. Explore HeroUI (https://heroui.com)
4. Build custom only when necessary

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. Design Foundation (20-40 min)

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

Establish Visual System:

Read the detailed foundation guides:

```
foundation/typography.md
```
- Font selection (Geist, JetBrains Mono), scales, loading
```
foundation/colors-and-spacing.md
```
- Color palettes, spacing systems, dark mode
```
foundation/layout-patterns.md
```
- Grids, containers, white space, responsive breakpoints

Quick Reference:

Typography: Geist for UI, JetBrains Mono for code (14px minimum)
Spacing: 8px base system (0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem, 6rem, 8rem)
Colors: Semantic tokens (--color-background, --color-primary, --color-error, etc.)
Layout: Mobile-first, 12-column grid, generous white space

建立视觉系统：

阅读详细的基础指南：

```
foundation/typography.md
```
——字体选择（Geist、JetBrains Mono）、字号层级、加载状态
```
foundation/colors-and-spacing.md
```
——调色板、间距系统、深色模式
```
foundation/layout-patterns.md
```
——网格、容器、留白、响应式断点

快速参考：

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

3. Interactive Elements (30-60 min)

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

For sophisticated interactive features, reference the specialized guides:

Chat & Messaging:

Read
```
interactive/chat-and-messaging.md
```
when building conversational interfaces
Covers message states, streaming, auto-scrolling, markdown rendering

Terminals & Code Display:

Read
```
interactive/terminals-and-code.md
```
for terminal emulators, syntax highlighting, semantic highlighting
Covers ANSI colors, Shiki integration, copy buttons, line highlighting

Streaming & Loading:

Read
```
interactive/streaming-and-loading.md
```
for progressive loading, streaming text, optimistic updates
Covers skeleton screens, progress indicators, loading hierarchies

Diffs & Logs:

Read
```
interactive/diffs-and-logs.md
```
for version control UIs, log viewers
Covers split/unified diffs, character-level changes, virtual scrolling

对于复杂交互功能，请参考专门的指南：

聊天与消息：

构建对话界面时阅读
```
interactive/chat-and-messaging.md
```
涵盖消息状态、流内容、自动滚动、Markdown渲染

终端与代码展示：

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

流内容与加载状态：

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

差异对比与日志：

构建版本控制UI、日志查看器时阅读
```
interactive/diffs-and-logs.md
```
涵盖拆分/统一对比、字符级变更、虚拟滚动

4. Implementation (1-3 hours)

4. 开发实现（1-3小时）

Build Components:

Read
```
implementation/components-and-accessibility.md
```
for component architecture and WCAG compliance
Use atomic design: atoms → molecules → organisms → templates → pages
Ensure keyboard navigation and screen reader support

Optimize Performance:

Read
```
implementation/performance.md
```
for Core Web Vitals optimization
Lazy load, code split, optimize images, measure with Lighthouse

Test & Refine:

Read
```
implementation/testing-and-qa.md
```
for comprehensive testing approach
Test on multiple devices, screen sizes, and with accessibility tools

组件开发：

阅读

implementation/components-and-accessibility.md

了解组件架构及WCAG合规要求

使用原子设计：原子→分子→有机体→模板→页面
确保键盘导航和屏幕阅读器支持

性能优化：

阅读
```
implementation/performance.md
```
优化核心Web指标
懒加载、代码分割、图片优化、使用Lighthouse测量

测试与优化：

阅读
```
implementation/testing-and-qa.md
```
了解全面测试方法
在多设备、多屏幕尺寸及无障碍工具上测试

5. Validation & Refinement

5. 验证与优化

Quick Decision Tree

快速决策树

Need to understand the basics? → Read

foundation/

files first

Building chat or messaging? → Read

interactive/chat-and-messaging.md

Building terminal or code editor? → Read

interactive/terminals-and-code.md

Need streaming or loading states? → Read

interactive/streaming-and-loading.md

Building diffs or log viewers? → Read

interactive/diffs-and-logs.md

Ready to implement? → Read

implementation/

files

Need tools or want to avoid mistakes? → Read

reference/

files

需要了解基础内容？ → 先阅读

foundation/

目录下的文件

构建聊天或消息界面？ → 阅读

interactive/chat-and-messaging.md

构建终端或代码编辑器？ → 阅读

interactive/terminals-and-code.md

需要处理流内容或加载状态？ → 阅读

interactive/streaming-and-loading.md

构建差异对比或日志查看器？ → 阅读

interactive/diffs-and-logs.md

准备开发实现？ → 阅读

implementation/

目录下的文件

需要工具或想要避免错误？ → 阅读

reference/

目录下的文件

Design Systems Priority

设计系统优先级

shadcn/ui (https://ui.shadcn.com) - PRIMARY CHOICE
- Excellent accessibility defaults
- Radix UI primitives
- Tailwind-based, customizable
- Copy-paste into project
daisyUI (https://daisyui.com)
- Semantic component names
- Tailwind plugin
- Rapid prototyping
HeroUI (https://heroui.com)
- Modern, polished
- Strong design language
- Product interfaces

See

reference/design-systems.md

for detailed comparison and usage patterns.

shadcn/ui（https://ui.shadcn.com）——首选
- 优秀的无障碍默认配置
- 基于Radix UI原语
- 基于Tailwind，可自定义
- 可直接复制粘贴到项目中
daisyUI（https://daisyui.com）
- 语义化组件名称
- Tailwind插件
- 快速原型开发
HeroUI（https://heroui.com）
- 现代、精致
- 清晰的设计语言
- 适用于产品界面

查看

reference/design-systems.md

了解详细对比及使用模式。

Typography Standards

排版标准

Use these fonts exclusively:

Geist (https://vercel.com/font) - For ALL interface text
- UI labels, body text, headings
- 95% of your typography
JetBrains Mono (https://jetbrains.com/mono) - For ALL code/technical content
- Code blocks, terminals, logs, diffs
- 14px minimum size
- Enable ligatures

Never mix multiple sans-serif or multiple monospace fonts.

See

foundation/typography.md

for complete guidance.

仅使用以下字体：

Geist（https://vercel.com/font）——所有界面文本
- UI标签、正文、标题
- 95%的排版场景
JetBrains Mono（https://jetbrains.com/mono）——所有代码/技术内容
- 代码块、终端、日志、差异对比
- 最小14px字号
- 启用连字

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

查看

foundation/typography.md

获取完整指南。

Inspiration Sites

灵感参考网站

Study these for design patterns:

Vercel (https://vercel.com) - Generous white space, clear typography
Hex (https://hex.tech) - Data-dense but organized
Baseten (https://docs.baseten.co) - Clear documentation structure
Weather Underground (https://wunderground.com) - Complex data, clean presentation
Ghostty (https://ghostty.org) - Modern terminal, elegant design

学习以下网站的设计模式：

Vercel（https://vercel.com）——充足留白、清晰排版
Hex（https://hex.tech）——数据密集但结构清晰
Baseten（https://docs.baseten.co）——清晰的文档结构
Weather Underground（https://wunderground.com）——复杂数据、简洁展示
Ghostty（https://ghostty.org）——现代终端、优雅设计

Common Anti-Patterns

常见反模式

Avoid these mistakes:

❌ Building custom components when design system has them
❌ Using absolute positioning for layout
❌ Animating expensive properties (width, height)
❌ Skipping mobile testing
❌ Ignoring accessibility
❌ Using
```
<div>
```
for everything
❌ Mixing multiple monospace fonts
❌ Auto-scrolling when user is reading
❌ Showing raw ANSI codes in terminals
❌ Forgetting empty/loading/error states

See

reference/anti-patterns.md

for complete list with explanations.

避免以下错误：

❌ 设计系统已有组件时仍自定义开发
❌ 使用绝对定位进行布局
❌ 对高开销属性（宽度、高度）做动画
❌ 跳过移动端测试
❌ 忽略无障碍设计
❌ 所有元素都用
```
<div>
```
实现
❌ 混合使用多种等宽字体
❌ 用户阅读时自动滚动
❌ 在终端中显示原始ANSI代码
❌ 忽略空/加载/错误状态

查看

reference/anti-patterns.md

获取完整列表及解释。

Iterative Development

迭代开发

For simple interfaces (single page, few components):

Start with foundation (read foundation files)
Use design system components
Test and refine

For complex interfaces (multiple features, interactive elements):

Map flows and create diagrams
Establish foundation (read foundation files)
Build one feature at a time (read relevant interactive files)
Test each feature before moving to next
Optimize and polish (read implementation files)

For developer tools or technical interfaces:

Map OODA loops carefully
Read ALL interactive files (chat, terminals, code, streaming, diffs, logs)
Focus on keyboard navigation and performance
Test with actual technical content

针对简单界面（单页、少量组件）：

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

针对复杂界面（多功能、交互元素多）：

梳理流程并绘制图表
搭建基础（阅读基础文件）
逐个功能开发（阅读对应交互文件）
每个功能测试通过后再进行下一个
优化打磨（阅读实现文件）

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

仔细梳理OODA循环
阅读所有交互文件（聊天、终端、代码、流内容、差异对比、日志）
重点关注键盘导航和性能
使用真实技术内容测试

Getting Help

获取帮助

If unsure where to start:

Read the philosophy section above
Follow the Design Process Workflow
Reference specific guides as needed

If design feels off:

Check against principles (clarity, consistency, performance)
Review anti-patterns list
Study inspiration sites
Test with real users

If implementation is slow:

Use design system components first
Don't build what exists
Focus on one feature at a time
Test early and often

不确定从何开始？

先阅读上方的设计理念部分
遵循设计流程工作流
按需参考特定指南

设计感觉有问题？

对照核心原则检查（清晰、一致、性能）
查看反模式列表
研究灵感参考网站
真实用户测试

开发进度缓慢？

优先使用设计系统组件
不重复开发已有功能
逐个功能聚焦开发
尽早并频繁测试

File Organization

文件结构

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)

elegant-design/
├── SKILL.md (当前文件)
├── foundation/
│   ├── typography.md (字体、字号层级、加载状态)
│   ├── colors-and-spacing.md (调色板、间距系统、深色模式)
│   └── layout-patterns.md (网格、容器、响应式)
├── interactive/
│   ├── chat-and-messaging.md (聊天UI、消息流)
│   ├── terminals-and-code.md (终端、语法高亮)
│   ├── streaming-and-loading.md (渐进式加载、骨架屏)
│   └── diffs-and-logs.md (版本控制UI、日志查看器)
├── implementation/
│   ├── components-and-accessibility.md (组件架构、WCAG合规)
│   ├── performance.md (核心Web指标、优化)
│   └── testing-and-qa.md (测试清单、工具)
└── reference/
    ├── design-systems.md (shadcn、daisyUI、HeroUI详情)
    ├── tools-and-libraries.md (完整工具列表)
    └── anti-patterns.md (错误示例及解释)

Remember

谨记

World-class design is invisible. Users shouldn't notice your clever solutions - they should simply accomplish their goals effortlessly and maybe smile along the way.

Start simple, iterate based on real use. Don't build everything at once. Build what's needed, test it, refine it, then move to the next feature.

Accessibility is not optional. Design for keyboard navigation, screen readers, and sufficient contrast from the start. Retrofitting is much harder.

Performance matters. A beautiful interface that's slow is a bad interface. Measure performance early and often.

世界级的设计是无形的。 用户不应注意到你的巧妙设计方案——他们只需轻松完成目标，甚至可能在此过程中感到愉悦。

从简单开始，基于真实使用迭代。 不要一次性构建所有功能。先开发所需功能，测试，优化，再进行下一个功能。

无障碍不是可选项。 从设计之初就考虑键盘导航、屏幕阅读器和足够的对比度。后期再改造会困难得多。

性能至关重要。 美观但缓慢的界面是糟糕的界面。尽早并频繁测量性能。