---
name: ui-aesthetic-design
description: 用于进行高质量 UI 美学设计、界面精致化、组件视觉评审与前端 demo 设计的通用设计规范。当任务涉及现代系统界面、侧边栏、资源面板、消息流、代码展示、按钮、hover/active 状态、二级菜单、展示项/可选项区分、内容对齐、图标视觉体积对齐、浅色/深色主题等 UI 美学问题时使用。
---

# UI Aesthetic Design

当设计、评审或实现 UI 改动时使用此 skill。目标不是做通用 SaaS 模板，而是形成克制、现代、精致、像成熟 AI 系统产品的界面。

## 核心审美方向

整体风格参考 ChatGPT / Claude / Linear 一类现代 AI 系统的克制感：

- 使用干净的浅色/深色表面、细边框、轻量阴影和安静的 hover 状态。
- 避免过度发光、重阴影、毛玻璃、强模糊、圆角矩形套圆角矩形、霓虹渐变和无意义装饰。
- 优先使用细线图标、浅灰 hover 底色、短而稳定的动效。
- 布局要紧凑但不拥挤，信息密度可以高，但不能乱。
- 精致感来自准确的间距、对齐、命中区域、状态反馈和微交互，而不是视觉噪音。

## 颜色与字体层级

使用少量语义化颜色：

- 背景/表面：浅色模式使用白色或近白；深色模式使用近黑或炭黑。
- 主文字：高对比，用于主要内容。
- 次文字：浅灰，用于路径、状态、元信息、辅助说明。
- 边框：中性 1px 细边框。
- Hover：低透明度灰色填充。
- Active/当前项：略强的低透明度灰色，或明确但克制的选择标记。
- Danger：只用于删除等破坏性操作。

字体层级：

- 主内容文字应更深、更大或更有字重。
- 次内容文字应更浅、更小。
- 不要为了“丰富界面”凭空添加解释性次级文本；只有真实数据结构里存在时才显示。
- 紧凑面板里的行默认单行显示，长文本截断；不要因为某条内容更长就撑高行高，除非产品信息结构明确需要多行。

## 对齐原则

追求**内容对齐**，不是容器对齐，也不是机械文字左对齐。

- 对齐有意义的视觉内容，而不是外层矩形框。
- 如果某一行由 SVG + 文字组成，标题或相关内容应根据 SVG 的视觉位置做对齐，而不是盲目对齐文字边缘。
- 如果下方具体内容本身没有图标，不要为了凑齐文字起点而乱加假图标。
- 按实际视觉体积对齐：不同 SVG 的 viewBox 和形状不同，真实尺寸可以不同，只要视觉大小一致。
- 不要强行把所有 SVG 设成同样宽高。
- 可以统一按钮命中区域，但图标本身大小要按视觉体积校准。

## 组件状态原则

状态设计必须反映真实语义：

- Hover：只用于可交互项。
- Active/当前：只用于当前选择、当前模式或当前项。
- Disabled：降低对比度，并移除点击暗示。
- 展示内容：不要看起来像按钮；避免 hover 底色、阴影、指针光标。
- 可点击内容：可以使用轻量 hover 底色、指针光标和当前项标记。

不要把“有没有阴影”当成唯一状态区别。状态语义应该通过结构、标记、间距和交互暗示共同表达。

## 可选项 vs 展示项

设计前必须先判断内容类型。

### 可选项

用于用户从多个选项中选择一个，例如环境切换、资源位置切换、账号/空间切换、筛选条件切换。

- 必须有明确的“可选择”视觉语义，例如 radio 圆点、check 标记或清晰的选中行。
- 当前项必须一眼能看出来。
- 可以有浅灰 hover 底色。
- 行本身可以是可点击的。
- `默认`、`当前` 这类 badge 只是元信息，不能单独承担“这是可选项”的职责。

### 展示项

用于展示状态或列表数据，例如任务条目、命令摘要、进程摘要、通知摘要，除非真实组件会打开详情。

- 保持安静，不要做成按钮或卡片。
- 不要乱加假图标。
- 不要加卡片阴影或嵌套圆角容器。
- 如果真实产品里不是可点击项，就不要加 hover 效果。
- 紧凑面板中使用统一行高和单行截断。
- 只显示真实数据模型里存在的字段。

## 二级菜单与更多操作

二级菜单要一致、克制、可读：

- 使用紧凑浮层，带轻量边框、适中圆角和轻阴影。
- 菜单选项无论文字长短，hover 背景宽度必须一样长。
- 菜单宽度由最长内容决定，所有选项填满同一宽度。
- 不要让每个选项的阴影/hover 背景长度随文字变短变长。
- 文案要短。
- 删除等破坏性项只用 danger 色区分，不要用更大尺寸或更重阴影。
- 列表行右侧 `...` 使用简单圆点视觉；hover 可以只变色，不一定加背景。

## 侧边栏展开原则

消息类/导航类侧边栏可使用“遮罩露出”模型，而不是新建一个展开浮层：

- 把侧边栏理解为一张完整面板，被一个移动边界遮住。
- 收起态只露出固定图标列。
- 展开时右侧竖线向右移动，内容被裁切后逐渐露出。
- 每个动作从始至终只有一个图标，不要展开后再出现第二个图标。
- 图标右侧文字和新出现的列表内容同时执行两种效果：淡入 + 随移动边界逐渐露出。
- 展开时不应挤压主内容布局；如设计目标是覆盖/露出，就保持主布局稳定。
- 收起态 hover 只作用在图标的圆角正方形上，不要露出被裁切的大圆角整行背景。
- 展开态 hover 才可以作用于整行。

## 资源面板原则

资源面板、管理面板、辅助面板应避免旧式“圆角矩形套圆角矩形套圆角矩形”的低级感。

- 优先做窄而扁平的面板；如果它位于主导航旁边，可以让展开后的侧边栏完整覆盖它。
- 顶部标题显示当前内容类型，例如资源、环境、任务、命令、通知、日志等。不要把所有模式标题硬塞到同一种视觉层级里。
- 标题下方可放一个“模式切换按钮”，点击展开二级菜单；旁边按需放紧凑管理图标按钮。
- 不要把浅色小号“管理”文字按钮放在大标题同一行，容易层级违和；优先使用图标按钮。
- 不要无意义增加搜索框；只有真实工作流需要搜索或过滤时才加。
- 层级资源树可以使用文件/文件夹/类别图标，因为这类图标本身承载结构语义。
- 环境/空间/资源位置切换属于可选项 UI，不是普通展示文本。
- 任务、命令、进程、通知等区域按真实数据字段显示：
  - 任务/进程：标识、摘要、状态、可选当前步骤。
  - 命令/作业：命令或作业预览、状态、返回码/结果码。
  - 清单/待办：序号、标题、状态；如果存在总说明，可单独显示。
- 内容行默认统一高度，除非真实信息结构明确需要展开。

## 代码展示原则

代码块、日志块或等宽文本展示精致化时：

- 做成现代 artifact/card 感：1px 细边框、较大圆角、清晰 header/body 分区。
- 避免粗边框和重嵌套面板。
- 复制/运行按钮要遵循同一套按钮系统。
- Header 里的语言名称是次级信息；代码内容才是主内容。
- padding、等宽字体、行高要统一；流式输出时避免视觉抖动。

## 实现前检查清单

修改 UI 前必须：

1. 先读取真实组件、状态或数据结构，不准凭印象设计假数据。
2. 判断每个内容是可选项、可点击动作，还是展示内容。
3. 按视觉内容对齐，而不是按容器边缘或文字边缘机械对齐。
4. 复用产品已有图标资源或统一图标库，不要自己编造 SVG。
5. 统一图标命中区域，但按视觉体积调整真实图标大小。
6. 避免嵌套卡片、大阴影和假的 hover 暗示。
7. 同时检查浅色和深色模式。
8. 写 demo 时也要贴近真实产品结构和真实字段；如必须使用示例数据，要保持字段语义真实，不要写臆想说明。
