0042 前端设计系统与组件库
- 状态:已接受(2026-11-09)
- 相关:设计文档 07(前端重构方案);
web/design.md(设计规则);ADR 0004(渲染策略)、0030(外观与 token);设计文档 05 §5.5(@skinloom/ui)
背景
1.0 的前端功能齐全,但界面是 shadcn 默认样式的拼装:@skinloom/ui 只有 5 个组件,14 处 window.confirm、14 处原生 <select>,同一串输入框样式在 6 个文件里各写一份;数据请求都是 useState + useEffect;中文落到各平台的系统字体;手机宽度下顶栏溢出。设计文档 05 承诺给插件的组件库大部分不存在。设计文档 07 的审查与 Pencil 高保真原型(首页、用户中心、后台概览)已评审通过。
决策
- 设计规则写在
web/design.md,是界面的唯一依据;改规则先改它。设计文档 07 记录理由与实施阶段(P0–P5)。 - 颜色:中性色阶 + 靛蓝主色(
primary)+ 金线强调色(新 tokenhighlight)+ 成功绿 + 危险红,共五种;警告复用金线,信息复用靛蓝。所有文字组合对比度不低于 4.5:1,内置主题由测试检查。accent保持 shadcn 的含义(菜单、幽灵按钮的悬停底色),品牌强调色是highlight。- 新增 token:
faint-foreground(三级文字)、highlight、success、warning、*-foreground、pixel-a/b(像素格底板)、shadow-popover、shadow-dialog、chart-1..5、sidebar-*;字体增加mono、display。 brand-gradient保留为兼容 token,默认主题不再用色相渐变。
- 字体:Inter(英文与数字)+ 思源黑体 Noto Sans SC(中文)+ JetBrains Mono(代码、哈希、UUID),全部 SIL OFL 1.1,用 Fontsource 的可变字体包从 npm 安装,随前端构建进
/_next/static/media,由网关直接提供。中文按unicode-range切片,页面用到哪些字只下载哪几片。 - 组件:基础组件全部采用 shadcn/ui,底层 Base UI(shadcn 自 2026 年 7 月的默认),风格
nova,用 shadcn 的 monorepo 方式安装到packages/ui;皮肤站自己的组件(材质卡片、双面/单面预览、展示区轮播、确认对话框等)放在packages/ui/src/components/skinloom/。两者都通过@skinloom/ui导出给插件。 - token 与基础样式移到
packages/ui/src/styles/globals.css,应用从@skinloom/ui/globals.css引入;将来插件用 Tailwind 时引入同一份定义。 - 图标:只用 lucide,线宽全站 1.75(全局 CSS),同一概念只用同一个图标(design.md §7.1)。后端与插件下发的菜单图标是 lucide 名称字符串,由
@skinloom/ui的允许列表映射成组件,不在列表里的不显示,不按名称动态导入整个图标库。后端皮肤库菜单的图标从shirt改为layout-grid(shirt是衣柜)。 - 数据层:引入 TanStack Query 5。orval 在原有的 fetch 函数之外再生成一份 Query 钩子(
src/gen/query.ts),同样走apiFetch(CSRF 头、超时、ApiError)。服务端组件继续用 fetch 函数取首屏数据,作为initialData交给客户端;收到config.changed时除了router.refresh()还使全部查询失效。 - 皮肤的两种视图:列表一律用双面视图(后端
/preview/{tid},正反面并排的 2D 图);首页展示区、材质详情、上传预览用单面视图(skinview3d 的 3D 预览)。 - 只用 token:组件代码里不用 Tailwind 调色板颜色(
slate-*、white、black等),bun run test里的样式检查拒绝这类类名。 - 不引入:motion(CSS 过渡与
tw-animate-css够用)、Storybook(改为后台内置的组件总览页)、表单库(等 2.0 设计插件 SDK 的Form时再定)。
备选方案
- shadcn 的 Radix 底层:现有代码用 Radix 的
Slot(asChild),但这些地方在页面重写时都要改;Radix 维护放缓,shadcn 已经默认 Base UI。 - React Aria(BoardUI 的底层):与 shadcn 生态脱节,组件要自己从头写样式。
- HarmonyOS Sans、MiSans:协议限制单独再分发或修改(网页切片算修改),放进 MIT 仓库与发行包有风险。站长可以在自己的主题里换用。
- 系统字体:零下载,但 Windows 上的微软雅黑与 macOS 的苹方观感差别大,界面在各平台不一致。
- 参考组件库直接复制:beUI(MIT)可以改写后使用并在 NOTICE 注明;BoardUI 免费部分是 MIT,但底层是 React Aria,只借结构;LeiBox(MIT + Commons Clause)与 bencho(付费)只借鉴想法,不复制代码。
影响
- 发行包与镜像增加 114 个字体文件、共 4.9 MB(P0 实测)。首次访问时只下载页面用到的切片:首页共 15 个文件、842 KB,其中思源黑体 13 片约 750 KB;之后由浏览器长期缓存。
NOTICE列出三种字体的协议。P5 再评估是否改用静态字重或常用字子集。 - 内置主题的 token 换成新的一套;第三方主题(目前还没有)沿用 shadcn 名称即可继续工作,
highlight等新 token 不写时取默认值。 @skinloom/ui的公开导出会在 P1 大幅增加;插件 API 在 2.0 冻结前允许调整。- 后端 bootstrap 中皮肤库菜单的
icon从shirt变为layout-grid。
实施记录(P1,2026-11-10)
- 基础组件用
shadcn add装进packages/ui/src/components/ui/,保留上游的代码风格;按design.md调整的只有尺寸、圆角、颜色、阴影和动效。CLI 把依赖装到了应用、导入写成了应用的别名,已改到packages/ui。 - shadcn 的组件依赖
shadcn/tailwind.css里的自定义变体(如data-horizontal对应 Base UI 的data-orientation)。按shadcn eject的做法把用到的部分抄进globals.css,没有把整个 shadcn CLI 加为依赖;滚动渐隐与闪光效果没有抄。漏掉它们时滑块的轨道高度为 0。 - 看起来像按钮的链接用新增的
ButtonLink(Base UIuseRender),不用<Button render={<Link />}>:后者给链接加了role="button"。 - Base UI 会渲染内联脚本,宿主用
CSPProvider把页面的 nonce 交给它;否则每个页面都有一条 CSP 拦截。 - 共享组件自己显示的文字由宿主通过
UiLabelsProvider提供(消息里的ui命名空间),插件拿到的是同一套译文。 - 新 token
overlay(遮罩),由默认与织锦主题定义。 - Recharts 不进
@skinloom/ui的总出口,用到时从@skinloom/ui/components/ui/chart引入;包标了sideEffects,未用的组件可以被摇掉。
实施记录(P5 收尾,2026-11-17)
- 包体积与 Tree-shaking 优化:将
@skinloom/ui(packages/ui/src/index.ts)从export *改为显式命名导出,并在apps/web/next.config.ts中启用experimental.optimizePackageImports: ['@skinloom/ui'],防止引用Empty/InputGroup等组件时把未使用的cmdk(Command)和Accordion等基础组件打入/skinlib等公开页面(/skinlib实测从1148.5 KB降至888.3 KB,减少260.2 KB)。 - 无障碍(A11y)审计与修复:
(site)、(app)外壳与not-found.tsx统一抽出<SkipLink />(#main,使用bg-popover/--shadow-popover与scroll-mt-14),并将<SidebarInset>与内层容器合并为单层<main id="main" tabIndex={-1}>,消除侧栏布局下嵌套<main>问题;HeaderNav、MobileMenu、AppSidebar、AppTabNav、ComponentPreview的<nav>补齐aria-label,AppSidebar补齐aria-current="page",SettingsCenter导航按钮补aria-current;UsageMeter通过useId()关联aria-labelledby并输出格式化aria-valuetext;CardTitle新增as属性并在登录、注册、找回/重设密码、邮箱验证、社交绑定、首次安装与 OAuth 授权页统一输出<h1>标题。
- 首屏 JS 与中文字体实测(Chromium 无缓存冷启动,对比 P0 前
7a7f569):- 基础共享 JS:
/about由559.4 KB(gzip165.3 KB)增至876.6 KB(gzip272.2 KB,+56.7%);/skinlib由567.1 KB(gzip168.3 KB)增至888.4 KB(gzip276.0 KB,+56.6%);/auth/login由568.1 KB(gzip168.8 KB)增至896.9 KB(gzip279.8 KB,+57.9%)。增幅主要来自 ADR 0042 引入的 Base UI 交互原语、@tanstack/react-query与sonner运行时(约+317 KB原始 /+107 KBgzip),未能压低至设计文档 07 §9 原定的+20%以内,已通过上述优化去除多余组件泄露。 - 含 3D 场景路由:首页
/由565.3 KB(无 3D 展示区)增至1594.4 KB(gzip454.8 KB,含异步动态加载的three+skinview3d约620 KB);材质详情/skinlib/show/1由1083.1 KB增至1633.0 KB(gzip468.1 KB)。 - 字体评估结果:思源黑体(
@fontsource-variable/noto-sans-sc)在各页面首屏按unicode-range实测加载10–13个切片、共565.1–743.7 KB(首页12片688.8 KB),全部字体合计612.2–830.2 KB;单份可变字体切片同时覆盖400 / 500 / 600字重,若改用双档静态字重(400 + 500)反而会引发双倍切片下载,因此维持可变字体按需分片方案。
- 基础共享 JS:
- 多宽度/多主题冒烟验证:新增可复用的
web/scripts/smoke.mjs(bun run smoke),在375 / 768 / 1280宽度、亮/暗双模式、default / brocade双主题下对 28 个主要公开、404 及登录后路由(共 336 个视图组合)验证无左右溢出、无控制台/页面异常、核心无障碍不变量,以及 Skip Link Tab 激活和375px移动端抽屉开关交互,全部通过。