全站现代化重构（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 改动、收藏/标签等新功能。

6.8 KiB Raw Permalink Blame History Unescape Escape