跳到主要内容

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)+ 金线强调色(新 token highlight)+ 成功绿 + 危险红,共五种;警告复用金线,信息复用靛蓝。所有文字组合对比度不低于 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 UI useRender),不用 <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(gzip 165.3 KB)增至 876.6 KB(gzip 272.2 KB,+56.7%);/skinlib 由 567.1 KB(gzip 168.3 KB)增至 888.4 KB(gzip 276.0 KB,+56.6%);/auth/login 由 568.1 KB(gzip 168.8 KB)增至 896.9 KB(gzip 279.8 KB,+57.9%)。增幅主要来自 ADR 0042 引入的 Base UI 交互原语、@tanstack/react-query 与 sonner 运行时(约 +317 KB 原始 / +107 KB gzip),未能压低至设计文档 07 §9 原定的 +20% 以内,已通过上述优化去除多余组件泄露。
    • 含 3D 场景路由:首页 / 由 565.3 KB(无 3D 展示区)增至 1594.4 KB(gzip 454.8 KB,含异步动态加载的 three + skinview3d 约 620 KB);材质详情 /skinlib/show/1 由 1083.1 KB 增至 1633.0 KB(gzip 468.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)反而会引发双倍切片下载,因此维持可变字体按需分片方案。
  • 多宽度/多主题冒烟验证:新增可复用的 web/scripts/smoke.mjs(bun run smoke),在 375 / 768 / 1280 宽度、亮/暗双模式、default / brocade 双主题下对 28 个主要公开、404 及登录后路由(共 336 个视图组合)验证无左右溢出、无控制台/页面异常、核心无障碍不变量,以及 Skip Link Tab 激活和 375px 移动端抽屉开关交互,全部通过。