这是什么：Claude Code 对话「项目 UI 组件库」的完整复盘。这次重构从「项目有没有用组件库」这个问题开始，最后建成一套设计系统，迁移了全站页面，并合并部署上线。
时间：2026-09-23 15:15 至 09-24 11:17（北京时间）。
规模：用户提示词 25 条，对话消息约 1000 条，工具调用约 1,360 次（Bash 864 次、读文件或截图 220 次、浏览器操作约 200 次），中途压缩上下文 2 次。
产出：分支 mie/design-tokens 上 18 个提交，经 PR #6 (external link to github.com) 合并，线上版本 0b5eba3f。对比页先后发布 14 版，公开版在 opustest.mie.md (external link to opustest.mie.md)。
一、成果一览
前后对比图共 9 张，从对比页截图中挑出，原图 4K。并排或上下排列的图，左边或上边是旧版，右边或下边是新版。
二、工作流
1. 总体路线
整个过程分四个阶段：先诊断，再定令牌，然后做组件库，最后逐页迁移。每个阶段结束都有一个用户审核点。
Mermaid
2. 每一轮的循环
这个循环一共跑了 20 多轮。用户只负责两件事：看截图，圈出问题。其余步骤都由 Claude 完成，最后交回一版可审核的对比页。
Mermaid
3. 关键做法
- 先令牌，后组件库：不直接套 shadcn 或 Tailwind。先把 129 种颜色收敛成 43 个语义令牌，字号收成 7 档，圆角 6 档，间距 12 档。换库之前，样式值必须先统一。
- 组件库配开发专用展示页：/design-system/ 只在开发模式下生效，生产构建里没有这个路由。新做的组件（如底部面板、选择按钮）先加进组件库，页面再引用。
- 对比页是审核的主要载体：用一个 claude.ai (external link to claude.ai) 页面展示改版前后，支持滑块或并排对比，覆盖三种宽度，每个状态附改动说明。后期改成三层目录（端 → 页面 → 状态），共 36 种状态。
- 隔离环境：隔离数据库、独立端口、合成账号。AI 文本用标明「测试桩」的固定内容，保证前后两次截图一致，不当作真实教学数据。
- 用脚本把同类问题找全：
- leakscan：临时移除旧样式层，对比每个元素的样式变化，找出旧 CSS 残留。第一次扫出约 290 组。
- clipscan：找被外层容器裁掉的阴影和描边，覆盖 21 个场景。
- pixdiff：学生工作区 33 张截图逐像素比对，证明改教师端时没动到工作区。
- 如实汇报：每轮都写明哪些没跑、哪些没打开看过。例如双语测试需要单独的数据库；某个教师页面只跑了测试，没看过界面。
4. 各阶段概览
三、提示词与修改过程
下面按时间顺序列出每一轮：引用块是用户原话，图片是用户随提示词附的截图，列表是 Claude 做了什么。
阶段 1：诊断与设计令牌
第 1 轮 · 盘点现状
现在这个项目有用什么UI的组件库吗？
- 没有成套的组件库，也没有 Tailwind。只用了几个单一用途的库：Radix Dialog、react-resizable-panels、CodeMirror 6、lucide-react、pdfjs。
- 全部样式都在一个约 1900 行的 globals.css 里。
第 2 轮 · 找不统一的根源
现在UI风格非常不统一，你觉得有什么解决的方案和好的组件库推荐吗
- 诊断：:root 只定义了 9 个颜色变量，全文件却写死了 141 种十六进制色值。圆角 5–10px 都有，字号 11–19px 几乎每个整数都用过。
- 结论：先统一设计令牌，再谈组件库。推荐 shadcn/ui + Tailwind v4，备选 Radix Themes 或 Mantine，不推荐 Ant Design 和 MUI。
- 给出三步落地路线：定令牌 → 搭基础组件 → 逐页迁移。
第 3 轮 · 定下视觉方向
好，先做第一步整理令牌，我想要一套带有圆角，丝滑动画的组件，主要有黑白灰（强对比）和天蓝色强调色构成的设计系统，带有一定的拟态效果（例如高光，点按反馈）
- 新建 tokens.css、docs/design-tokens.md 和审计脚本 design-tokens-audit.mjs，把每个旧值对应到新令牌。
- 视觉方向：
- 纯灰阶，正文对比度 18:1。
- 天蓝只用于「当前、选中、可操作、焦点」。
- 圆角三级：控件 10px、卡片 14px、弹窗 20px。
- 轻拟态：顶部 1px 高光；按下时高光消失，出现内阴影，按钮略缩小、下沉，松开时回弹。
- 动效 4 档时长、4 条缓动曲线；系统开启「减少动态效果」时自动关闭。
- 收敛结果：颜色 129 种 → 43 个，字号 19 种 → 7 档，圆角 10 种 → 6 档，间距 38 种 → 12 档。
- 向用户确认了三件事：天蓝的深浅、主按钮用黑色还是天蓝、最小字号。
第 4 轮 · 否掉侧边细线，确认参数
高亮不允许做成这样，左侧的这个雷霆细线太奇怪了，代码块样式可以再优化一下
天蓝可以，主按钮用黑色，最小字号没问题，你修改后可以做基础组件了
- 选中态：去掉左侧细线。列表底部微凹，选中项像按键一样白色浮起。这条后来写成了设计原则：不使用侧边色条。
- 代码差异：不加边线。用极淡的底色，配合行号颜色和 +／− 符号区分；行内改动用圆角标记圈出。
- 基础组件：Button、Field、Segmented、Badge、Card、List、Skeleton、CodeBlock、CodeDiffBlock，以及 StatusView 六种状态（加载、空数据、无权限、失败、旧版本、下架）。CodeMirror 主题和代码块共用一套高亮规则。
- 提交 a0f36a4。
第 5 轮 · 对齐问题
这些还没对齐
- 编辑器折叠箭头偏低：原因是字符 ⌄ 在字体里本身偏下，外加旧的全局规则覆盖了编辑器字体。箭头改用 SVG，旧规则限定作用范围。
- 快捷键 ⌘↵ 偏低：改成用无衬线字体居中的小键帽。
- 复选框被旧的 input 样式撑成 26×22：在组件里重置后是 18×18 正方形，和文字的中心差 0.2px。
- 每一项都在浏览器里实际测量过中心点。
阶段 2：学生工作区打磨
第 6 轮 · 开始迁移，要求出对比图
确认没问题，你继续吧。完成之后给我提供前后对比图让我审核参考。
- 学生工作区换上新令牌：三栏改成三张浮起的卡片，右侧标签页改成分段控件，弹窗加了过渡动画。
- 第一版对比页上线：7 种状态 × 3 种宽度，支持滑块或并排对比。
- 顺带修了一个原有 bug：恢复历史代码后 0.65 秒内点撤销，保存状态会卡在「正在保存…」。新加的弹窗动画改变了点击时机，端到端测试因此每次都能复现它。提交 5f0ca59、536cb00。
第 7 轮 · 圆角、顶部栏、实体按钮
中间块没有圆角，顶部栏可以整体重新整理一下（不用遵循原先的结构），所有的文本按钮尽量都改为实体的
- 圆角被盖住：粘性操作栏和编辑器会被浏览器单独分层绘制，「超出隐藏 + 圆角」裁不住它们。改在卡片内层用 clip-path 裁切，阴影留在外层。
- 顶部栏重做：左边是品牌、「‹ 练习列表」、竖线分隔、题名；右边是记录按钮（带数量）、语言、头像和退出。
- 文字按钮都改成带高光的实体小按钮，按下时下沉。行内的课件引用保留为链接。提交 fd83f6d。
第 8 轮 · 省纵向空间，运行反馈改成可拖动面板
试运行和示例1放在同一行右侧，省下一些纵向空间。图片这个放在自动换行左侧。运行反馈整个模块（也换成圆角）作为可上下滑动来控制展示不同颗粒度的，这样可以流出更多空间来写代码（也可以重新排版一下）。"简体中文"按钮换成"语言"
- 运行反馈改成三档底部面板：摘要、用例、详情。拖动把手后吸附到最近一档，也可以点击或用方向键切换。档位记在本机；有新结果时自动展开到「详情」。
- 「填入试运行」挪到示例标题同一行，编辑器提示挪到「自动换行」左侧，按钮改名为「提交并测试」。提交 a565456。
第 9 轮 · 两行合一
这两行合成一行，用下面那行的那个高度，C代码编辑器那个删了改成尚未编辑，提交并测试放在最右侧
- 编辑器状态栏和工具栏合成一行，左边是保存状态，右边依次是格式化、自动换行、提交并测试。提交 447b214。
第 10–11 轮 · 阴影与按钮高度
这个外面一圈阴影和圆角有点奇怪，你在检查一下
这两个按钮应该是一样高的，下方向上的阴影应该是圆角的，现在是直角，看起来很奇怪，提交并测试可以用组件库的这个效果和颜色。把这次新增的组件加入组件库中。
- 底部面板改成和卡片两侧、底部齐平，只保留顶部圆角。
- 阴影原来横跨整张卡片，到两侧被直直切断，所以是方角。改成面板上方一道椭圆渐变阴影，两端自然收成圆弧。
- 小号按钮统一为 32px 高；「提交并测试」改用天蓝色的「运行」按钮样式。
- 把新组件加入组件库：Sheet（底部面板）、Disclosure（折叠卡片）、SelectButton（选择按钮）、按钮数字角标。提交 a281cec、3e750d6。
第 12 轮 · 六处细节（第一次压缩上下文后）
p1似乎没对齐 p2加icon和颜色，p3的运行反馈后面的v1删了，重新对齐一下和右边的按钮，然后加大一点字体，把下方的分割线删了，p4改成复跑当前用例,p5输入和输出的框长度和字符长度保持一致，这里需要再仔细打磨一下。p6这里也可以再打磨一下。
- 判定标签带图标和颜色：通过绿勾、未通过红叉、超时时钟、异常感叹号。
- 运行反馈标题栏：删掉「· v1」，字号 13 → 16px，删掉下方分割线。
- 示例的输入／输出框宽度跟着内容走，短内容只是一个小框。
- AI 输入框合成一个整体圆角框，去掉拖拽角，发送按钮用黑色主按钮。提交 3fa9632。
第 13 轮 · Markdown 与记录弹窗
所有的AI对话/解析需要做markdown解析。提交与帮助记录你根据我之前跟你提的这些设计的原则重构。
- 所有 AI 回答改用 Markdown 显示，C 代码块和编辑器同一套高亮。回答里夹带的网页代码和图片直接丢弃。只在文本变化时重新解析，只有需要的页面才加载解析器。
- 「提交与帮助记录」改成两栏各自滚动。帮助记录改成时间线，AI 问答在原位展开。提交 92b33e1。
第 14–15 轮 · AI 助手与课件引用
把AI助手和引用课件有关的UI也全部重新设计一轮
把时间，版本等信息全部加在运行反馈的最下方，上面的删除掉
- 课件引用改成编号小圆标加底部课件卡片，所有 AI 回答统一使用。
- AI 助手的空状态、等待中、请求失败、重新发送分别有独立设计。
- 课件阅读器的工具栏合成一行，重点高亮从黄色改成天蓝色。
- 运行反馈头部只留结论，时间、版本、判题环境移到最下方。
- 下拉框改用组件库自己的列表（基于 Radix Select），不再弹出系统选择器。提交 eea4002、4586b1a、559cd52。
阶段 3：全站迁移
第 16–17 轮 · 推送，然后把全站迁到新设计
先把当前进度commit并push一下
根据我的审美要求/倾向和design system，完成所有页面向新的设计的迁移，并更新改版对比（可以分层级展示以方便我查阅）
- 迁移范围：登录、404、练习列表、班级看板、学生记录、题目管理、手动编辑、课程资料。
- 旧样式整体降到最低优先级，按钮、表单、弹窗等通用样式全站共用。
- 对比页改成三层目录（端 → 页面 → 状态）：36 种状态 × 3 种宽度。提交 d2b8e6b。
阶段 4：按典型错误全站排查
这个阶段的提示词最值得复用：用户不再逐处指点，而是给出一类错误，让 Claude 自己把全站同类问题找全。
第 18 轮 · 五类典型错误（第二次压缩上下文后）
典型错误1:无意义的压缩页面组件的宽度，导致内容局促，没有需要分割的东西不要加无意义的矩形
典型错误2: 分割线穿过元素，元素之间的间距时大时小
典型错误3: 非常小的文本返回，这个在刚刚的练习工作区里已经有很好的案例了，重新做
典型错误4: 混乱的层级关系和按钮，没有经过细致的整理
典型错误5: 无意义的浪费宝贵的纵向空间，组件没有经过细致的打磨
修复以上这些错误，并查找所有类似的案例并完成修复，代码编辑器可以启用默认启用新的配色主题
- 宽度被无意义压缩、多余的框：登录卡片固定 460px 宽；题目详情内容宽 960 → 1120px；删掉发布检查的绿框和各处卡片套卡片。
- 分割线穿过元素：分段标签被旧样式的 top: -16px 上移，压在了线上；间距统一为 12 或 20px，输入框和按钮统一 36px 高。
- 返回按钮太小：新增 PageHeader 组件，统一成工作区那种小按钮加竖线分隔的写法。
- 层级混乱：每页只保留一个黑色主按钮；筛选压成一行；「下架」放最右并用红字。
- 浪费纵向空间：看板页头压成一行，题库每项三行变两行，代码快照去掉内层框。
- 用 leakscan 在 19 个页面场景里扫描旧样式残留，约 290 组逐项处理。代码编辑器默认启用新配色。提交 ccf8664、d069ebe。
第 19 轮 · 重做记录弹窗，清理口号式文案
学生提交记录弹窗这整个面板我觉得还是应该完全重新设计一次
另外还有一个典型错误，输入框和标题下方很多这种喊口号的文案全部清理掉，重要信息标注的更清楚，无效信息直接删除
- 弹窗重做：
- 左栏每条提交只占两行，筛选收进按钮，点开才展开。
- 右栏先给结论，证据用标签切换：判题与代码、帮助记录、题目、课件。
- 点「定位第 N 行」会在代码里高亮该行。
- 文案：删掉登录页、看板、题库等处标题下的口号句。真正要紧的约束压成琥珀色警示或徽标，例如「预期输出需按题意独立核对」「不计入成绩与学习记录」。提交 34df41f。
第 20 轮 · 无意义图标与被裁切的描边
典型错误：无意义的icon
被裁切的蓝色高光 / 被裁切的图标边框，这也是个典型错误
- 判断标准：只重复旁边文字或纯装饰的图标删掉，表达状态或类型的保留。删掉的包括姓名首字头像、统计卡图标、每个课件前一模一样的文件图标、AI 回答头像。
- 裁切的根源：列表项用了 content-visibility: auto，它会把超出边界的阴影和描边一起裁掉。另外，分栏组件内联写死了 overflow: hidden。
- 写了 clipscan 在 21 个场景里查全，修复后只剩一处，是面板贴底的设计本意。提交 2faa5df。
阶段 5：上线与分享
第 21 轮 · 推送、合并、部署
帮我给这个对比画板中的图片内容部署一个网页到 opustest.mie.md (external link to opustest.mie.md)就保留我截图的这部分就行，其他的不需要放进去。然后帮我给新的版本push，开pr，合并然后部署到cf。
- 开 PR #6，按仓库惯例用合并提交合入 main（64907b1）。部署到 Cloudflare，线上版本 0b5eba3f。
- 本地构建判题镜像时访问 Debian 源超时。改用离线构建，先逐个比对判题源码与仓库一致，Cloudflare 也识别出镜像没变。
- 对比页的精简版部署成独立的静态 Worker，绑定 opustest.mie.md (external link to opustest.mie.md)。第一次上线中文乱码，补上 UTF-8 声明后正常。
第 22 轮 · 挑图分享
帮我挑出9张最有代表性的对比图片，可以采用各种呈现方式，让我来和其他人分享这次UI重构案例。（图片铺满全屏，不需要加文字和标记说明），打一个压缩包发给我
- 从对比页截图中挑出 9 组，用了对角线切分、并排、上下、叠放、居中竖切等不同呈现方式，输出 3840×2160。也就是本文第一部分的那 9 张图。
四、沉淀下来的设计规则
视觉：黑白灰强对比，天蓝只用于当前、选中、可操作、焦点。主操作用黑色按钮，天蓝实心按钮只留给「运行」「提交并测试」这类即时反馈操作。
选中态：底部微凹、选中项白色浮起，不使用侧边色条。
按钮：文字按钮一律改为实体小按钮；同一行的控件等高（小号 32px，表单 36px）。每个区域只有一个主按钮。
空间：宽度要够用，不要把内容挤在一起；没有需要分隔的内容就不加框；能合成一行的就合成一行；元数据放到末尾。
文案与图标：不写口号；约束性信息压成短句加警示色；只重复文字的图标一律删除。
细节：阴影和描边不能被裁切；分割线不能穿过元素；间距用固定的几档。
五、验证与收尾
- 测试：端到端 21 项（包括 2 项调用真实 AI 的测试）、双语 9 项、单元 73 项，类型检查和生产构建都通过。
- 视觉：每轮在 1024、1440、1920 三种宽度下截图，逐张打开看过；学生工作区 33 张截图逐像素比对，确认没有回归。
- 没做或需要注意的：
- 旧样式文件里已经用不到的规则还没全部删除。
- 部署后没有按上次的格式在 docs/verification.md 补部署记录。
- 登录后的页面没有在线上逐一打开检查，验证用的是本地隔离环境里的同一份代码。
- 相关链接：PR #6 (external link to github.com) · 对比页（claude.ai，仅本人可见） (external link to claude.ai) · 公开对比页 (external link to opustest.mie.md) · 仓库文档 docs/design-tokens.md