第 32 期 · 前端重构开工:设计系统的地基
1.0 的前端功能齐全,但看起来像拼起来的:组件库只有 5 个组件,14 个地方弹浏览器自带的确认框,中文用的是各平台的系统字体,手机上顶栏会溢出。这期开始重做前端,先打地基:
- 一套设计规则(
web/design.md)和一份重构方案(设计文档 07),配了 Pencil 画的高保真原型; - 新的配色与字体,换进两个内置主题;
- TanStack Query、菜单图标表和一个拦住"写死颜色"的检查。
页面本身这期还没动,下一期是组件库。
先定方向,再画原型
方向一句话:界面安静克制,颜色和细节留给皮肤。皮肤站最好看的东西是皮肤本身,按钮、导航、表格都应该退到后面。
- 颜色只有五种:中性灰、靛蓝(主色,取自蓝染布,呼应"云织")、金线(积分、签到、警告)、成功绿、危险红。
- 标志性的细节是像素格:皮肤预览一律放在淡淡的棋盘格上,像图像编辑器显示透明区域,皮肤的镂空和第二层一眼就能看出来。
- 列表里的皮肤用双面视图(正面和背面并排,就是后端
/preview现在画的样子),首页展示区和详情页用单面视图(skinview3d 的 3D 角色)。
原型画了首页(桌面和手机)、用户中心、后台概览,评审时改了三处:列表改用双面视图;手机首页的展示区压矮;首页展示区改成"当前皮肤在走路、前后两个半透明陪衬、每 6 秒轮播"。动画规则写在原型旁边的说明板和 design.md §9.5 里。
配色是算出来的
每个颜色都用 OKLCH 写,再换算成 sRGB 算对比度。新加的测试会读两个内置主题的 plugin.json,逐对检查文字与底色(正文 7:1,其余 4.5:1)。
测试第一次跑就抓到了我自己的错:设计稿里成功绿配纯白字是 4.56:1,但实际用的"白字"是带一点蓝的 primary-foreground,只有 4.37:1。把绿色压暗一点(亮度 0.55 → 0.52)才过。
另一个测试检查 globals.css 里的兜底值和默认主题完全一致,两边以后不会各改各的。
字体:可商用、能随开源包分发
| 用途 | 字体 |
|---|---|
| 英文与数字 | Inter |
| 中文 | 思源黑体(Noto Sans SC) |
| 哈希、UUID、令牌 | JetBrains Mono |
三种都是 SIL OFL,从 npm 装、随前端构建,由站点自己提供,国内访问不依赖 Google Fonts。MiSans、HarmonyOS Sans 的协议限制单独再分发或修改(网页切片就算修改),没有选。
中文字体按 unicode-range 切了一百多片,页面用到哪些字只下载哪几片。实测首页第一次打开下载 842 KB 字体(思源黑体 13 片),之后浏览器缓存。比预想的多,记在了风险里,收尾阶段再评估要不要换静态字重或常用字子集。
其它几件小事
- token 搬进
@skinloom/ui:插件以后用 Tailwind 时引入同一份@skinloom/ui/globals.css,跟着主题变色。兜底值放进@layer base,主题的 CSS 不在任何 layer 里,所以总能盖过站点自己的样式,主题作者不用写!important。 - TanStack Query:orval 在原来的 fetch 函数之外,再生成一份 Query 钩子(
@skinloom/api-client/query),走同一个apiFetch。服务端组件仍用 fetch 函数,因为 TanStack Query 在服务端组件里加载不了。通知铃铛先换成了钩子,每分钟数一次未读。 - 菜单图标表:后端下发的菜单图标是 lucide 的名字,前端只映射一张允许的表,不会把整个图标库打进首屏。测试会读
site.go,确认后端用到的名字都在表里。这次还发现 lucide 1.70 把circle-alert改名成了circle-exclamation-point,旧名字留作别名。 - 样式检查:
bun run test会拒绝text-white、bg-slate-900、bg-[#fff]这类绕过 token 的写法,现有的 9 处已经改掉。
下一期
P1 组件库:用 shadcn CLI 把基础组件装进 packages/ui,再做皮肤站自己的组件(双面预览、展示区轮播、确认对话框……),以及一个后台里的组件总览页,给主题作者核对用。