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. 动手前：先对齐现有系统（最高优先级）

先读项目现有代码，找到已有的设计系统 / 主题 / 组件，优先复用，绝不另起炉灶。
本仓库技术栈分工：
- 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——只在维护它们时才用对应框架；新建页面一律用该子项目的主方案。
一个子项目只允许一套主样式体系：不混用 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 间距、色彩克制且对比达标、字号阶梯统一、圆角 / 阴影 / 图标统一、三态齐全、响应式通过、无魔法数字、与项目现有设计系统一致。

SKILL.md 5.9 KB Permalink History Raw