# 全站现代化重构（shadcn/radix 设计系统 + 公共表面）设计 / Modern site-wide redesign (shadcn/radix) design — phase 1

日期 2026-09-08。分支 `feat/ui-redesign`。状态:已获用户批准（五节设计逐节确认）。

## 目标 / Goal

以 shadcn/radix 体系从零重做全部产品表面的布局与交互（不沿袭现有布局/交互，仅阅读器的翻页/翻章语义保留），
建立 light/dark 双主题设计系统；功能面与现状等价；移动端达到真正可用。
本期（phase 1）= 设计底座 + 登录/应用壳/书架/admin 两页；阅读器 chrome 迁移为 phase 2（另立 spec）。

## 决策记录 / Decisions

- 用户选定:方案 C（shadcn/radix），视觉基调=极简书架风（Notion/Linear/豆瓣读书），主题=双主题开关（默认 system）。
- 功能等价重做;不做功能增减。明确否决/推迟:视图密度开关（=新功能，不做）、阅读器本期不动（phase 2）、
  命令面板/键盘优先导航（不适合媒体浏览）。
- 否决方案:仅换皮保结构（四项痛点都不回答）、手写 token 层不引框架（交互原语 a11y 自理成本高）。
- `components/icons.tsx`（自研 SVG）删除，由 `lucide-react` 取代。
- `components/ui.ts` 不整体删（phase-1 的 `/book/:id` 各表面仍引用）:**收缩为 `btn`/`btnGhost`/`formatBadge`
  三个 deprecated 导出**供阅读器侧继续使用，phase 2 随阅读器迁移一并删除;其余导出（`input`/`card`/`pill`/
  `pillActive`/`btnPrimary`）随公共表面重做删除;`formatSize` 属数据格式化，迁 `lib/format.ts`。
- `/book/:id`（`pages/Reader.tsx` + 四 reader 组件 + `Bookmarks` 面板）本期整体不重构、不套壳，维持现状。
  例外边界:`Cover`/`Toaster` 是跨期共享组件，phase 1 改写时**保持 props 兼容**（EpubReader/App 等旧调用零改动），
  仅视觉入新 token。
- 原生 `confirm()`（Shelf 删书、Users 删用户）→ radix AlertDialog。
- API/路由/数据流零改动;后端不在本期范围。

## 技术底座 / Foundation

- React 19.2 + Tailwind v4.3（`@tailwindcss/vite` 已在）+ react-router 7。新依赖（容器内安装，提交 lockfile）:
  `radix-ui`（统一新包，按需 import 子模块）、`class-variance-authority`、`clsx`、`tailwind-merge`、
  `lucide-react`、`tw-animate-css`。
- `components.json` 放 `frontend/`，alias: `@/* → src/*`（与 tsconfig paths 同步）。
- 工具:`src/lib/utils.ts` 提供 `cn = twMerge(clsx(...))`。
- Token:shadcn 标准语义变量（`--background --foreground --card --card-foreground --popover --primary
  --secondary --muted --accent --destructive --border --input --ring --chart-*` + `--radius`），
  `@theme inline` 映射进 Tailwind;`:root` = light（纸白中性灰，`--primary` 暖墨黑，唯一彩色点缀朱橙），
  `.dark` = 对应暗色套。全站禁止裸 `stone-*`/`amber-*` 直用（阅读器现有类在 phase 2 清理）。
- 主题:`src/components/theme.tsx` ThemeProvider — `"system" | "light" | "dark"` 持久化于
  `localStorage("ui.theme")`（默认 system）;`index.html` 内联脚本按同 key 预算 class 防 FOUC;
  入口=应用壳内 DropdownMenu（lucide Sun/Moon/Monitor，当前值打勾）。

## 应用壳 / AppShell

- 新 `src/components/app-shell.tsx` 包裹 `/` 与 `/admin/*`（登录页不套壳，居中 Card 独立布局）。
- 断点约定（Tailwind 默认值）:
  - `lg(≥1024)`:固定 `w-60` 左侧栏——品牌字标、导航（书架;admin 另加 库管理/用户管理）、
    库筛选列表（全部+各库，来自 `GET /libraries`）、底部 主题切换 + 用户/退出。
  - `sm–lg`:图标窄栏（`w-14`，Tooltip 标注）。
  - `<sm`:顶部 Header（品牌+搜索入口）+ 底部 Tab 栏（书架 / 管理(admin 可见) / 账户）;
    账户页=弹出 DropdownMenu（主题、库管理入口、退出）。
- 现 `TopBar.tsx` 删除，职责并入壳。

## 书架页 / Shelf

- 粘性工具条（主列顶部）:搜索 Input（沿用 300ms 防抖与 `q` 参数）、排序 DropdownMenu
  （新加时间/标题/阅读进度，前端排序，默认新加时间）、分组 SegmentedControl（平铺|按目录，默认平铺）。
- 「继续阅读」:等价保留（progress 前 12 条），桌面横滑大卡轨，移动端降级为单行紧凑卡横滑。
- 网格:`grid-cols-[repeat(auto-fill,minmax(...))]`，卡=封面 3:4 + 标题 + 格式徽章 + 进度细线;
  整卡链接进阅读器;操作 DropdownMenu（打开;admin 追加 删除）叠于封面右上，hover/focus 出现。
- 删除确认 = AlertDialog，文案语义与现状一致（提示磁盘文件连带删除、进度保留）。
- 空态/错误重试/骨架屏按新语言重绘;损坏书红徽章保留。
- 数据源不变:`useQuery(["books", lib, q])` + `["progress"]` + 全量 books 缓存复用。

## admin 页 / Admin

- 库管理:库=Card 列表（名称、`#id`、root 路径、扫描按钮、上传 input）;上传入口升级=dropzone
  （Label+Input 包装，拖拽与点击同效，仍串行 `uploadBook`，toast 用快照计数——保留 2721df8 修复语义）。
- 用户管理:Table（用户名/角色/创建时间/操作）+ 顶部新建行（Input+Select 角色+提交）;删除=AlertDialog。
- 权限与错误处理逻辑不变（非 admin 由 AuthContext 路由守卫拦截）。

## 错误处理 / Errors

- 网络错误路径不变（`apiFetch` 抛错→toast）；radix 组件不新增失败面。
- `localStorage` 不可用（隐私模式）:主题回落 system、渲染不崩（读写包 try/catch）。

## 测试与验收 / Verification

- `npm run -s check`（tsc+vitest+build）绿;既有 33 用例保持绿。
- 纯逻辑新增件（排序比较器、分组视图函数迁自 `lib/group.ts`）补 vitest。
- playwright 走查并截图:375/768/1280 三宽 × light/dark ×（登录→书架→筛选/搜索/排序→
  删除确认→admin 两页），核对布局无溢出、焦点环可见、AlertDialog 焦点收拢。
- a11y 基线:导航 landmark、图标按钮 aria-label、`aria-current`、主题切换 `aria-pressed`。

## 文档 / Docs

- `docs/CHANGELOG_web.md` 新增 Changed 条目（英中相邻行）:全站 UI 重构为 shadcn/radix 设计系统 +
  双主题 + 新应用壳;阅读器注明「交互不变，样式后续」。

## Phase 2（另立 spec 的边界）

- 四阅读器 chrome（工具条/目录/书签面板/主题卡）迁入同一 token + radix 原语（Sheet/Popover）;
  翻页、翻屏、CBZ 章锁/连读/预读、书签 seek、进度上报逻辑与 localStorage 键原样保留;
  「纸/米/夜」重映射为语义变量并与全局主题定联动规则;清理 `rd-*`/裸色类。

## 不做 / Non-goals

- 视图密度开关、虚拟化长列表（当前量级不需要）、i18n、SSR、后端 API 改动、收藏/标签等新功能。