跳到主要内容

第 32 期 · 前端重构开工:设计系统的地基

· 阅读需 4 分钟

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,再做皮肤站自己的组件(双面预览、展示区轮播、确认对话框……),以及一个后台里的组件总览页,给主题作者核对用。