重构一个「看起来能跑」的演示站

1. 问题与约束

接手时项目的状态是"部分功能可用"：四个效果组件带着自己的 CSS 活着，其余全靠 Tailwind 工具类——而 Tailwind 从未安装。

约束有三条：

不能换栈：React + Vite 是既成事实，重写没有收益；
必须留住效果组件：它们是这个项目的起点，也是最贵的资产；
要有可验证的完成度：不能再用"看起来能跑"作为验收标准。

2. 关键决策

先修样式层，还是先修白屏

先修导入

两行代码，立刻能看见页面

先接 Tailwind

改动大，但决定后续所有页面的工作量

理由: 白屏消失之后页面会是裸的，看不出修好了没有。样式层先通，修导入的收益才可验证。
代价: 单次改动面更大，需要一次完整的构建验证。

那 6 个手写的 ui 组件怎么处理

手工修补

保留现有代码，逐个补状态与键盘行为

shadcn CLI 重装

直接拿到基于 Radix 的版本

理由: 项目没有 components.json，init 会覆盖我刚调好的 index.css 令牌层。保住设计系统的优先级高于省时间。
代价: Tabs 的键盘导航与焦点管理要自己实现，代码量约三倍。

Dock 要不要做全站导航

保留 Dock

视觉效果强，是这个项目最出彩的组件

换成顶部栏

阅读站的标准形态，但少一个亮点

理由: Dock 的隐喻是「应用切换」，而这个站的核心行为是阅读与检索。底部浮层在长文里会一直干扰。能为了体验砍掉自己喜欢的效果，本身就是一次产品判断。
代价: 首屏少了一个强视觉锤，需要别的方式建立第一印象。

3. 结果

指标	前	后
类型错误	13	0
App.tsx	407 行	30 行
构建 CSS	11 KB（三行死指令）	49 KB（真实工具类）
ESLint 警告	5	0

结构上，App.tsx 从"什么都干"变成纯编排，内容层从硬编码变成 MDX：

src/
├─ App.tsx           # 路由表
├─ layout/           # 导航、页脚、命令面板
├─ pages/            # 7 个路由
├─ components/       # effects / mdx / notes / common / ui
└─ lib/content.ts    # 构建期索引
content/
├─ notes/*.mdx       # 6 篇
└─ retro/*.mdx       # 2 篇

4. 如果重来

只改一件事：第一版就装 Tailwind。

那 91 处工具类从第一天起就是死代码，而它们看起来完全正常。如果构建立刻失败，后面两周的所有工作都会建立在一个真的能用的样式层上，不会出现"这个是靠组件自带 CSS 撑起来的，那个是巧合"这种判断不清的状态。