---
name: frontend-design
description: 前端视觉设计与美学规范：视觉层级、8pt 间距、60-30-10 配色、字号阶梯、组件质量与响应式。覆盖 Tailwind CSS v4、Ant Design v6、React/Inertia、Laravel Blade 与原生 HTML/CSS。目标是让生成/修改的界面「美观、专业、克制」而不只是能用。
whenToUse: 生成或修改任何页面、组件、样式时；用户要求「好看 / 美观 / 美化 / 重设计 / 更现代 / 精致」时；编写 HTML、CSS、React、Blade、Tailwind、Ant Design 代码时。
---

# Frontend Design 美学与实现规范

> 目标：让界面在「能用」之上达到「美观、专业、克制」。美观不是堆特效，而是 **一致性 + 层次 + 留白 + 克制的色彩**。

## 0. 动手前：先对齐现有系统（最高优先级）

1. 先读项目现有代码，找到已有的设计系统 / 主题 / 组件，**优先复用，绝不另起炉灶**。
2. 本仓库技术栈分工：
   - `api-v13/`：Laravel + Inertia（React 19）+ **Tailwind CSS v4**（主样式方案），图标用 `@tabler/icons` + FontAwesome。
   - `dashboard-v6/`：React 19 + **Ant Design v6**（`antd` + ProComponents + `@ant-design/charts`）。
   - 存量页面可能残留 Bootstrap 5 / Bulma / 原生 CSS——只在维护它们时才用对应框架；**新建页面一律用该子项目的主方案**。
3. 一个子项目只允许一套主样式体系：不混用 Tailwind 与 Bootstrap/Bulma 于同一页面。

## 1. 核心美学原则

### 1.1 视觉层级：一屏只有一个主角
- 每个页面有且仅有一个**主焦点**（标题、关键数据或主操作）。
- 用「字号 / 字重 / 颜色 / 间距」四件套制造层级，而不是「更大 + 更亮 + 更粗」一起堆。
- 次要信息主动降噪：降低对比度、缩小字号、移到次要位置。

### 1.2 间距：8pt 网格
- 间距一律取 4 或 8 的倍数：`4 8 12 16 24 32 48 64 96`。
- 卡片内边距 `16 / 20 / 24`；卡片间距 `16 / 24`；区块间距 `32 / 48 / 64`。
- 禁止出现 `7px`、`13px`、`19px` 这类零碎值。

### 1.3 色彩：60-30-10 + 语义色 + 对比度
- 60% 中性底色（背景 / 卡片）、30% 主色（品牌 / 交互）、10% 强调色（关键状态 / CTA）。
- 主色只用于交互与强调，**不要大面积铺满**。
- 状态色语义固定：success=绿、warning=黄/橙、danger=红、info=蓝；不要用彩色随意表达「好看」。
- 文字与背景对比度满足 WCAG AA（正文 ≥ 4.5:1，大字 ≥ 3:1）。灰色文字不要浅到看不清。

### 1.4 排版
- 每个页面用**同一套字号阶梯**（见 `references/design-tokens.md`），不即兴造字号。
- 标题与正文要有明确字重 / 字号对比；正文行高 1.5–1.6，标题行高 1.2–1.3。
- 数字 / 金额 / 表格用 tabular-nums 并右对齐，便于扫描。

### 1.5 留白与密度
- 默认**宁可多留白**：拥挤是「丑」的头号来源。
- 相关元素靠得近（成组），不相关元素拉开距离（分隔）。

### 1.6 一致性（重中之重）
- 圆角、阴影、边框、图标风格、按钮尺寸在一页内**统一**。
- 圆角：小元素 `6–8px`、卡片 `10–12px`、全圆（头像 / 徽章）。同一界面最多 2 档圆角。
- 阴影只用 1–2 层、且非常克制（hover / 浮层才用），不要到处投影。

### 1.7 克制
- 动画只用于反馈（hover / 进入 / 加载），时长 150–250ms，缓动一致。
- 少用高饱和渐变、玻璃拟态、发光、大图背景；需要时只做点缀。
- 图标统一一套（`@tabler/icons` 或 antd icons），不混搭风格。

## 2. 布局模式（可直接套用）

- **卡片**：标题 + 正文 + 操作区（右下角）。用边框或浅色底代替重阴影。
- **表单**：标签在输入框上方、左对齐；必填用 `*`；错误信息贴近字段且为红色；主提交按钮位置固定。
- **表格**：表头加粗、行高 48–56px、斑马纹可选但弱；数字右对齐；操作列固定右侧。
- **导航**：当前项高亮（主色或字重），hover 有反馈；层级清晰。
- **空状态**：图标 + 一句说明 + 一个行动按钮，不要留白一片。
- **加载态**：骨架屏或 spinner + 文案；不要在空白里闪一下。
- **错误 / 异常态**：清楚说明「发生了什么 + 用户可以做什么」，不要只抛红字。

## 3. 组件质量红线（每个组件交付前自查）

- [ ] 交互元素有 hover / focus / disabled 三态。
- [ ] 键盘可达，表单 / 弹窗 / 菜单有正确的 `aria-*`。
- [ ] 长文本不截断不溢出（ellipsis 或换行策略）。
- [ ] 响应式：至少 3 档断点不塌；移动端可点区域 ≥ 44×44px。
- [ ] 间距、圆角、阴影、颜色来自 token，不写魔法数字。
- [ ] 空 / 加载 / 错误三态齐全。

## 4. 技术栈指引（按子项目阅读对应参考）

- Tailwind CSS v4（api-v13 主方案）→ 读 `references/tailwind-v4.md`
- Ant Design v6（dashboard-v6）→ 读 `references/ant-design-v6.md`
- Laravel Blade + Inertia → 读 `references/laravel-blade.md`
- 具体 token 数值 → 读 `references/design-tokens.md`

## 5. 反模式（出现即视为不合格）

- ❌ 原生浏览器默认样式直接上线（默认按钮、无样式表格、蓝色下划线链接墙）。
- ❌ 满屏高饱和色 / 彩虹配色 / 大面积纯黑纯白强对比。
- ❌ 间距凌乱（`7px / 13px`）或元素挤成一团。
- ❌ 同一页面混用多套圆角、多套阴影、多套图标风格。
- ❌ 纯功能无状态：没有空态、加载态、错误态、hover 反馈。
- ❌ 无响应式：只适配一种宽度。
- ❌ 文案未对齐、数字不对齐、按钮大小不一。

## 6. 完成标准（Definition of Done）

提交前逐条确认：层级清晰、8pt 间距、色彩克制且对比达标、字号阶梯统一、圆角 / 阴影 / 图标统一、三态齐全、响应式通过、无魔法数字、与项目现有设计系统一致。
