uiux

/uiux — 全面 UI/UX 重设计

一个系统化、递归式的重设计循环。按照优先级从高到低处理每个屏幕，并逐一迭代，直到基于实际渲染出的 UI 外观而非代码描述，达到像素级完美。

开始之前：阅读 ~/.claude/skills/ui-design-principles/SKILL.md——其中包含所有颜色、排版、间距和层级规则，这些规则会自动应用于整个流程。

如果项目根目录中存在 DESIGN-BRIEF.md：在修改任何文件之前先阅读它。它规定了视觉方向（配色、排版、组件样式、动画程度、标志性屏幕）。设计简报中的决策优先于默认规则——不要重新推导已经确定的内容。

---

阶段 0 — 环境设置

0a. 检查 / 启动开发服务器

curl -s --max-time 2 -o /dev/null -w "%{http_code}" http://localhost:3000

如果结果不是 200，找到开发命令（pnpm dev、npm run dev 等）并在后台启动。然后等待其就绪：

until curl -s --max-time 2 http://localhost:3000 > /dev/null 2>&1; do sleep 1; done
echo "Server ready"

0b. 验证 Playwright

node -e "require('@playwright/test')" 2>/dev/null && echo "ready" || echo "missing"

如果缺少：

pnpm add -D @playwright/test && npx playwright install chromium

如果无法安装，请让用户在每次修复后提供截图。没有真实视觉输入时，不要对视觉效果作出判断。

0c. 编写截图脚本

将此文件写入项目根目录（以便解析 node_modules）。整个会话期间都保留该文件，并在阶段 4 删除。

_uiux_screenshot.mjs（写入项目根目录）：

import { chromium } from '@playwright/test';

const get = (flag) => {
  const i = process.argv.indexOf(flag);
  return i !== -1 ? process.argv[i + 1] : null;
};

const url    = get('--url');
const output = get('--output');
const width  = parseInt(get('--width')  ?? '1280');
const height = parseInt(get('--height') ?? '900');
const auth   = get('--auth');

if (!url || !output) { console.error('--url and --output required'); process.exit(1); }

const browser = await chromium.launch();
const context = await browser.newContext({
  viewport: { width, height },
  ...(auth ? { storageState: auth } : {}),
});
const page = await context.newPage();
await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
await page.screenshot({ path: output, fullPage: true });
await browser.close();
console.log('saved:', output);

用法 — 桌面端：

node _uiux_screenshot.mjs --url http://localhost:3000<ROUTE> --output /tmp/uiux-<name>-desktop.png

用法 — 移动端（375px）：

node _uiux_screenshot.mjs --url http://localhost:3000<ROUTE> --output /tmp/uiux-<name>-mobile.png --width 375 --height 812

用法 — 已认证：

node _uiux_screenshot.mjs --url http://localhost:3000<ROUTE> --output /tmp/uiux-<name>-desktop.png --auth /tmp/uiux-auth-state.json

每次截图后：使用 Read 工具打开图像文件并实际查看。 图像才是判断依据，而不是代码。

0d. 处理受身份验证保护的屏幕

检查是否存在身份验证中间件或提供程序（middleware.ts、next-auth、clerk、supabase、lucia、路由守卫）。

如果存在身份验证，请将以下内容写入项目根目录，并向用户索取测试凭据（TEST_EMAIL、TEST_PASSWORD）和登录后的 URL 模式（SUCCESS_URL，例如 **/dashboard**）：

_uiux_auth.mjs（写入项目根目录）：

import { chromium } from '@playwright/test';

const { TEST_EMAIL, TEST_PASSWORD, LOGIN_URL, SUCCESS_URL } = process.env;
if (!TEST_EMAIL || !TEST_PASSWORD) {
  console.error('Set TEST_EMAIL and TEST_PASSWORD'); process.exit(1);
}

const browser = await chromium.launch();
const page    = await browser.newPage();
await page.goto(LOGIN_URL ?? 'http://localhost:3000/sign-in');
await page.fill('input[type="email"]',    TEST_EMAIL);
await page.fill('input[type="password"]', TEST_PASSWORD);
await page.click('button[type="submit"]');
await page.waitForURL(SUCCESS_URL ?? '**/dashboard**', { timeout: 15000 });
await page.context().storageState({ path: '/tmp/uiux-auth-state.json' });
await browser.close();
console.log('Auth session saved → /tmp/uiux-auth-state.json');

从项目根目录运行：

[email protected] TEST_PASSWORD=secret LOGIN_URL=http://localhost:3000/sign-in SUCCESS_URL="**/dashboard**" node _uiux_auth.mjs

如果没有可用的测试凭据：现在为公开屏幕截图，并将受保护的屏幕标记为身份验证受阻；收到凭据后再处理。

0e. 查找设计令牌

搜索令牌层（packages/tokens/、tokens.css、tailwind.config.ts、全局文件中的 CSS 自定义属性）。记录间距、颜色和字号的定义位置。适用于全局的修复应写入令牌，而不是组件。

---

阶段 1 — 屏幕审查

遍历代码库并列出每个不同的屏幕。针对每个屏幕：

• 路由路径 + 文件路径
• 一句话描述
• 是否受身份验证保护：是/否
• 截图（受保护的屏幕使用 --auth 标志），阅读图像，并评级：损坏 / 粗糙 / 尚可 / 精致

从以下位置发现屏幕：

• App Router：每个 app/**/page.tsx
• Pages Router：pages/**/*.tsx（跳过 _app、_document、api/）
• 模态框 / 抽屉组件
• 空状态、错误状态、加载状态、未找到状态
• 身份验证流程（登录、注册、忘记密码、验证邮箱）
• 引导流程、设置、个人资料、账单页面

继续之前，展示完整的编号列表及质量评级。

---

阶段 2 — 优先级排序

为每个屏幕评分：

因素	分值
入口 / 第一印象	+3
对收入或转化至关重要	+3
流量最高 / 曝光最多	+2
当前质量为损坏或粗糙	+2
身份验证受阻（暂时无法截图）	−1
仅供高级用户使用	−1

按得分排序（最高分 = 第 1 名）。说明前 5 名的排序理由。开始阶段 3 之前，请用户确认或调整排序。

---

阶段 3 — 递归式重设计循环

按排名顺序处理屏幕。每个屏幕最多迭代 3 次——如果 3 轮后仍未通过检查清单，则标记并继续处理下一个屏幕。持续跟踪共享组件的修复（3f）。

---

3a. 修改前截图

截取桌面端和移动端截图。阅读两张图像文件。 用 2–3 句话描述实际看到的内容——这就是基准。

3b. 分析

阅读页面组件、布局封装组件、子组件和 CSS/Tailwind 类，并与截图逐项对照——截图优先于代码中的假设。检查每个维度：

层级 — 每个屏幕上是否只有一个明确的 MIT？视觉焦点流动是否自然？ 颜色 — 状态是否按 S+B 规则推导？是否遵循 60-30-10？是否符合 WCAG AA？ 排版 — 字体是否不超过 2 种？标题与正文的比例是否 ≥1.75×？字重是否正确？ 间距 — 内边距节奏是否一致？留白是否加倍到舒适的程度？ 阴影与层次 — 光线是否来自天空？阴影不透明度是否与亮度相匹配？ 控件 — 是否紧邻其所影响的内容？是否存在不必要的下拉菜单？ 图片上的文字 — 是否使用了叠加层 / 模糊 / 底部渐变淡出？ 对齐 — 是否存在对齐线？图标 / 项目符号是否悬挂对齐？ 空状态 — 是否经过设计且具有引导性，而非空白？ 响应式 — 截图中的移动端 375px 布局是否完整？ 无障碍 — 点击目标是否 ≥44px？是否有 aria 标签？颜色是否不是唯一的提示方式？

3c. 问题列表

按严重程度分组编号：

• 严重 — 功能损坏、难以阅读、无障碍失败
• 主要 — 层级错误、违反颜色体系、间距不佳
• 次要 — 润色、动画、边缘情况

3d. 修复 — 先改设计令牌，再改组件

修改任何组件前，先问：这项修复是否适用于 ≥2 个屏幕？

• 是 → 编辑设计令牌 / 配置文件。不要在组件中硬编码。
• 否 → 直接编辑组件。

应用所有修复，先处理严重问题。自动应用以下规则——无需许可：

• 加深状态：提高 S + 降低 B + 将色相移向 0°/120°/240°
• 提亮状态：降低 S + 提高 B + 将色相移向 60°/180°/300°
• 中性色表面：带一丝品牌色相（~0.005 色度），绝不使用纯灰色
• 留白：持续加倍，直到感觉过多——这才是正确的
• 一个 MIT——只有页面标题采用最大幅度的向上弹出效果
• 字号：正文 ≥15px，标签 ≥12px
• 浅色背景上的阴影：不透明度 20–30%。深色背景上：不透明度 40–50%。
• 将下拉菜单（≤5 个选项）替换为分段控件、切换控件、步进器或输入联想

3e. 等待热重载，然后截图

完成编辑后，等待开发服务器重新编译：

sleep 3

然后截取桌面端和移动端的截图。**读取两张图片文件。**与 before 截图进行视觉对比。

根据图片作答（而非代码）：

1. MIT — 视线落下时，最重要的元素是否最先映入眼帘？
2. 流动 — 注意力是否按正确顺序移动？
3. 空间 — 屏幕是否通透，还是显得拥挤？
4. 一致性 — 此屏幕是否与其他屏幕属于同一款产品？

如果任何答案是否定的：返回 3b（迭代计数加 1，最多 3 次）。

3f. 共享组件跟踪

修复涉及多个屏幕共用的组件时：

SHARED FIX: <ComponentName> — affects screens: [list routes]

之后到达这些屏幕时：跳过重复修复，但要截图并确认组件在该场景中渲染正确。

3g. 像素级精确检查清单

每项都必须通过截图验证，而非查看代码：

• 从截图中一眼就能看出 MIT
• 颜色状态按 S+B 规则推导（没有直接使用不透明度的取巧做法）
• 中性色表面带有一丝品牌色相，而非纯灰色
• 正文字号 ≥15px，标签 ≥12px，标题 / 正文比例 ≥1.75×
• 留白已加倍——所有边的内边距均 ≥ 字号
• 间距节奏一致（4/8/16/24/32/48px）
• 阴影不透明度与背景亮度相匹配
• 所有控件都紧邻其影响的内容
• 点击目标 ≥44px——已在移动端截图中验证
• WCAG AA 对比度：正文 4.5:1，标题 3:1
• 空状态经过设计（不是空白）
• 没有不必要的下拉菜单
• 图标的笔画粗细和圆角半径与字体相匹配
• 图片上的文字使用叠加层 / 文本框 / 模糊 / 底部渐变淡出
• 屏幕内的对齐线保持一致
• 移动端 375px：没有溢出，布局没有损坏

任何一项未通过 → 返回 3d，迭代次数加 1。第 3 次迭代后：标记问题并继续。

---

阶段 4 — 清理与进度报告

删除项目根目录中的临时脚本：

rm -f _uiux_screenshot.mjs _uiux_auth.mjs

每完成一个屏幕后：

✓ Screen name (rank N, iteration K) — A critical + B major + C minor fixed
  Shared fixes: [list or none] | Flagged: [list or none]

完成所有屏幕后，提供完整汇总表：

排名	屏幕	路由	已修复的问题	迭代次数	状态
1	...	...	...	...	✓ 已优化 / ⚠ 需要复查 / 🔒 身份验证受阻

在底部列出所有标记和身份验证受阻的屏幕，并注明尚未解决的具体问题。

---

规则

1. 使用 Read 工具读取每张截图。 绝不能仅凭代码描述 UI。以图片为准。
2. 先处理设计令牌，再处理组件。 首先在令牌／配置层进行全局修复。
3. 共享组件只修复一次。 修复一次，记录受影响的屏幕，并在实际使用场景中验证。
4. 每个屏幕最多迭代 3 次。 标记问题并继续。不要陷入反复调整。
5. 自动应用设计规则。 调整颜色、间距或字体排版不需要授权。
6. 保留功能。 绝不更改逻辑、路由、数据获取或无障碍语义。
7. 移动端优先。 每项修复都必须先在 375px 宽度下通过验证。
8. 身份验证受阻的屏幕。 先截取当前能看到的内容，待提供凭据后再处理。
9. 一次处理一个屏幕。 完成检查清单和所有迭代后，再继续下一个屏幕。
10. 报告进度。 随时让用户知道当前正在处理哪个屏幕，以及还剩多少个。

---

支持的项目类型

Next.js（App Router 或 Pages）、React + Vite、SvelteKit、Nuxt、Astro、纯 HTML/CSS。根据发现的项目结构调整文件检索方式。

完整的设计知识库快速参考请参阅 PRINCIPLES.md。