Skip to content

Phase 1 实验记录 ​

A · Patina Primary ​

Playground 固定布局、Surface 与文字,仅切换 Dark primary。实验结论已确认:Macchiato 的 primary 使用 Win98 Teal #008080,前景使用白色。更亮的 #69c7bd 作为候选对照被否决,已从样式表移除,此处仅作记录。

B · Semantic Color Preview ​

采用标准 theme.colors 暴露全部语义色,并以 var(--token, static-oklch) 兼顾动态主题和静态解析。构建验证需确认 bg-primary 等 utility 生成真实 CSS;VS Code 装饰需人工复核。

C · Surface ​

两个主题均使用四层背景 tone,结合 border 与独立 shadow。Card、Popover、Dialog 可在应用示例页同时观察。

D · Typography ​

确定字体职责分工:全局默认使用操作系统默认无衬线,霞鹜文楷降级为强调与衬线排版字体,只在需要突出或需要衬线气质的位置通过 font-serif 主动调用,并放弃打包 Geist / Inter。

霞鹜文楷是楷体,整站默认使用它会显著降低正文阅读效率,也会让界面被动带上书法气质——这一点在文档站实测后确认,因此不进入 font-sans。实验曾在 data-serif 上对比霞鹜文楷与系统衬线,现已定稿为霞鹜文楷,对照开关随实验一并移除。因为字体不随包分发,基础页保留一次本机可用性提示;未安装时回退系统衬线,中文始终有系统回退。

E · Radius ​

默认基准圆角定为 8px,并按比例推导更大的容器圆角。data-radius 作为应用级能力保留(应用可自行选择 6 / 8 / 10 基准),但基准取值本身已定稿,页面不再提供切换。

F · Iconography ​

图标统一使用 Tabler(@iconify-json/tabler + presetIcons),类名形如 i-tabler-palette。普通图标直接内联颜色语义(text-primary、text-muted-foreground),尺寸由 h-* w-* 与文字基线对齐,不引入独立图标组件封装。构建验证需确认 i-tabler-* 已被编译进产物 CSS。

G · Latte muted 对比度 ​

全量配对审计发现 Latte 的 muted / muted-foreground 仅 4.06:1,低于 AA。已将 muted-foreground 由 Catppuccin subtext0 #6c6f85 调整为同族 subtext1 #5c5f77,达到 5.14:1,并新增专门断言防止回退。

H · 变量一致性审计 ​

用 UnoCSS generator 实测预设的实际产物,发现三处「配置看起来生效、其实静默失效」:

  1. theme.easing 写错了键名——Wind4 读的是 theme.ease,因此 ease-standard 从未生成任何 CSS。
  2. theme.duration 不存在——Wind4 的 duration-* 只解析裸数值,命名时长无效。
  3. theme.spacing 用静态 px 表覆盖,但 Wind4 的间距是 calc(var(--spacing) * N),覆盖不生效,只制造了「有 Token」的错觉。

结论:删除 spacing 覆盖(间距交还 Wind4 的 --spacing),改用 ease 键名接入 --pd-ease-*,并为命名 duration-* 与语义 z-* 各补一条只匹配命名档位的自定义 rule。三处均已写入单元测试,避免再次静默回退。

I · 排版角色化 ​

排版原始档位沿用 Wind4(等价 Tailwind v4)的 text-* 阶梯,不另造数值;在其上增加 display / title / heading / body / label / caption / overline 七个语义角色,全部指向 --pd-text-* 变量。字重不进入角色,只用 font-medium / semibold / bold 三档——Playground 原先散落的 52 处任意字重(font-650、font-720、font-750)与 24 处任意字号(text-[10px]、text-[11px])已全部收敛,眉标统一为 pd-overline shortcut。

J · 工具链升级 ​

依赖升级到 UnoCSS 66.11、pnpm 12.11.2、Vite 8、Vitest 5、tsup 9、Changesets 3。两处需要留意的结论:

  • TypeScript 停在 6.x:TS 7 是 Go 原生重写版,不再导出 typescript/lib/tsc,vue-tsc 3.3.13 无法工作(ERR_PACKAGE_PATH_NOT_EXPORTED)。
  • Vitest 停在 5.0.4:pnpm 12 默认启用 minimumReleaseAge(新发布包需满 24h)供应链保护,5.0.5 发布不足 24h 会被拒绝。

CI 的 pnpm 已同步为 12.11.2,并在 pnpm-workspace.yaml 中以 allowBuilds 声明 esbuild 的构建脚本许可。

K · Playground 导航 404 ​

部署后点击右上角 Playground 会 404,但原地刷新正常。原因是 VitePress 的全局点击拦截(app/router.js):只要 href 同源且被视为 HTML,就 preventDefault 改走客户端路由并 fetch 该地址。/playground/ 返回的是 Playground 的 SPA HTML,没有 VitePress 的应用结构,渲染失败即 404;刷新则直接走静态文件,因此正常。

router 在拦截前会跳过带 target 属性的链接,这是官方留出的唯一豁免开关。因此给导航项显式声明 target: '_self'(不能用 _blank,否则多开标签页)。

同时把 dev 与 build 的链接分开:dev 下 vitepress dev(5174)与 playground dev(5173)是两个服务器,指向 http://127.0.0.1:5173/;构建产物由 scripts/assemble-site.mjs 挂到 /playground/。判断依据用子命令而不是 NODE_ENV——实测 vitepress dev 下 NODE_ENV 是 undefined,只有 build 才设为 production。Playground 的 dev 脚本已固定 --port 5173 --strictPort,避免端口漂移导致链接失效。

L · Latte muted-foreground(已确认) ​

上一版 muted-foreground 使用 Catppuccin subtext0 #6c6f85。全量配对审计发现它在 muted 上只有 4.06:1,低于 AA;进一步逐表面检查后,问题比最初判断更广——7 个 Latte 表面里有 6 个不达标:

表面底色subtext0 #6c6f85subtext1 #5c5f77foreground
muted#e6e9ef4.06 ❌5.14 ✅6.57
background#eff1f54.37 ❌5.53 ✅7.06
card#ffffff4.94 ✅6.25 ✅7.99
surface-subtle#dce0e83.73 ❌4.73 ✅6.04
surface#e6e9ef4.06 ❌5.14 ✅6.57
secondary#e2e7f03.98 ❌5.04 ✅6.44
accent(hover)#c8eeea3.97 ❌5.02 ✅6.42

关键在于 text-muted-foreground 的常见落位恰好是 background(4.37)与 accent(hover 行,3.97),二者都不达标;只有直接放在白色卡片上才合规。

代价只有一项:与 foreground 的层级差从 1.62x 收紧到 1.28x(以白卡为基准)。绝对值仍然分明——foreground 7.99:1 对 muted-foreground 6.25:1。

结论:采用 subtext1 #5c5f77,全表面达 AA。 取舍经 Playground 对比实验后拍板,subtext0 对照项与 data-muted 开关已随实验一并移除,避免已定稿的值长期挂着可切换状态。

约束已固化为永久测试:断言该值在全部 7 个 Latte 表面达到 4.5:1,且与 foreground 的层级比大于 1.2x。想重新比较时按下方约定另开临时实验页。

M · Playground 的使用约定 ​

从本轮起,Playground 不再是「所有变量的控制面板」,而是分两类内容:

  • 已确认的设计事实 → 固定页面。基础、语义色板、组件、应用示例四个页面只呈现最终效果,不提供 A/B 切换。唯一保留的运行时开关是亮/暗主题,它是产品能力而非待定方案。
  • 待确认的效果 → 临时实验页。需要比较方案时新增一个临时页面,确认后把结论固化进固定页面或 Token,并删除临时页。

决策过程(选项、取舍、驳回理由)记录在本文件,不进入页面。这样页面保持干净,实验痕迹也不会长期残留在交付物里。

本轮据此清理了四处历史实验脚手架:data-primary 的 Lightened 方案、data-muted 的 subtext0 方案、data-serif 的系统衬线方案,以及 6 / 8 / 10 基准圆角的切换。其中 data-radius 作为应用级能力保留(应用可自选基准),只是基准取值已定为 8px。