modelgo-design-tokens 0.10.0 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,8 +2,53 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Fixed
6
+
7
+ - **`check:usage` 修掉静默假绿,并补齐覆盖范围**(工具改动,不影响任何 token 值,
8
+ 消费方无需升级即可用)。三个叠在一起的问题:
9
+ 1. **找不到扫描目标时静默通过。** 原实现 `.filter(existsSync)` 把不存在的目标直接丢掉,
10
+ 全丢光时扫 0 个文件仍打印 `Token usage check passed.`。而 `DEFAULT_TARGETS` 是相对
11
+ `cwd` 的兄弟仓路径,**在 worktree 里跑必然全部找不到**(cwd 是
12
+ `<repo>/.claude/worktrees/<name>`)—— 也就是说在 worktree 里这道门禁长期是假绿。
13
+ 现在既感知 worktree 布局(能正确回溯到工作区根,也可用 `MODELGO_WORKSPACE` 覆盖),
14
+ 又在一个目标都找不到、或扫到 0 个文件时以**退出码 2** 明确失败。
15
+ 2. **只扫 console-web。** `DEFAULT_TARGETS` 另一项 `wt-console-glass` 早已不存在,
16
+ 于是**国内官网、海外官网、文档站从未被扫过**。现在四端全覆盖。
17
+ 3. **规则只查颜色和 z-index。** 库里 `ease` / `duration` / `radius` / `shadow` 早已成体系,
18
+ 却一条都没查。补四条规则后存量从 22 处涨到 **402 处**(console-web 187 / 国内官网 180 /
19
+ 海外官网 35 / 文档站 0),即原先只看得见 5.5%。
20
+
21
+ 配套引入 `token-usage-baseline.json`:**存量不阻断,只拦新增**(照 `check:contrast` 的口径,
22
+ 否则第一次接入就拦死所有提交,最后只会被 `--no-verify` 绕过)。key 为 `文件::规则`
23
+ 不含行号,重构挪动代码不会误判成新增。收口 `-- --update-baseline`,看清单 `-- --all`。
24
+
25
+ ⚠️ **已知缺口**:这道检查扫的是下游代码,本仓 pre-commit 只在 `tokens.css` 进暂存区时触发,
26
+ 所以**它至今没有自动触发点**。要真正拦住下游新增硬编码,得在各端自己的提交期调用它。
27
+ 详见 TOKEN-GOVERNANCE.md §6.1。
28
+
5
29
  ### Added
6
30
 
31
+ - **Token 分层产物:`base.css` / `console.css` / `website.css`**(241 / 434 / 4 个 token)。
32
+ 消费方按需只引自己那层:控制台引 `base + console`,官网引 `base + website`;继续引全量
33
+ `tokens.css` 的行为与 0.10.0 完全一致,**不是 breaking change**。
34
+ - 三份是 `tokens.css` 的**投影,不是第二真源**。改值仍然只改 `tokens.css`(走预览站),
35
+ 再 `npm run split` 重新生成。之所以不把真源拆成三份:本仓改值入口是预览站
36
+ `/api/save` 直接写回 `tokens.css`,四道门禁也全部扫它,拆真源要把这些全改一遍,
37
+ 收益却只是消费方少引几个 token —— 不值得。
38
+ - 归属按 **token 名**判定(`token-layers.json`,本关唯一人工输入),不按它在
39
+ `tokens.css` 里的物理位置:物理位置只是作者组织文件的方式,同一个
40
+ `[data-theme='dark']` 块里可能混着不同层的 token;而分层要求同一个 token 的
41
+ **所有档(`:root` / dark / market)必须落在同一层**,否则只引 base 的消费方会缺档。
42
+ - 新增两道门禁,均已接进 `release.mjs` 预检:`check:layers-sync`(产物与 `tokens.css`
43
+ 是否同步,过期直接拦住发版)、`check:layers`(无跨层重复 / 引用方向单向 / 档位完整 /
44
+ `base` 与 `base+console`、`base+website` 各自自闭合)。产物过期的故障形态是**静默的**
45
+ ——消费方拿到旧值且不报错,同悬空 var,所以必须机器拦。
46
+ - ⚠️ **不能只引 `console.css` 不引 `base.css`**:console 层大量 token 是
47
+ `var(--mg-brand-base)` 这类对 base 的引用,缺 base 即悬空 var → 整条声明静默失效。
48
+ - **解决的真问题**:消费方为拿到派生层,历史上会把库的整份 token 抄进本地做转发
49
+ (console-web 抄了 337 个),于是库改值被本地重复声明压死、每次升级都要重复一遍撤除
50
+ 动作(见下方 0.10.0 与 qa#615、qa#611 ④)。按需只引一层后,抄整份的动机就消失了。
51
+
7
52
  - **对比度门禁(关卡 4)**:`scripts/check-token-contrast.mjs` + `contrast-contract.json`(语义配对表)
8
53
  + `contrast-baseline.json`(存量快照)。解析 `tokens.css` 的 `var()` 链与 `color-mix()`,
9
54
  在 `market × theme` 全矩阵下算 WCAG 2.1 对比度。接在三处:`pre-commit-all.sh`、
@@ -76,9 +76,36 @@
76
76
  ## 6. 变更门禁
77
77
 
78
78
  ```bash
79
- pnpm check:closure # var() 引用自闭合
79
+ pnpm check:closure # var() 引用自闭合(含环 + 级联顺序)
80
80
  pnpm check:contract # 主题与兼容别名契约
81
- pnpm check:usage # 下游常见硬编码回归
81
+ pnpm check:contrast # 语义色对比度(有 baseline,只拦新增与恶化)
82
+ pnpm check:usage # 下游硬编码回归(有 baseline,只拦新增)
82
83
  ```
83
84
 
84
- 提交和 release 都会运行与其相关的工程门禁。设计值的取舍仍需设计依据与人工审阅,不能被脚本替代。
85
+ 前三道由 `scripts/pre-commit-all.sh` 在 `tokens.css` 进暂存区时自动跑,是本仓提交期门禁的
86
+ 唯一真源。设计值的取舍仍需设计依据与人工审阅,不能被脚本替代。
87
+
88
+ ### 6.1 `check:usage` 的定位与它的缺口(读完再依赖它)
89
+
90
+ 它扫的是**消费方源码**,不是本仓。所以:
91
+
92
+ - **它没有自动触发点。** 本仓 pre-commit 只在 `tokens.css` 进暂存区时触发,而本检查
93
+ 和 `tokens.css` 无关;本仓提交时跑它也没意义(本仓提交不改下游代码)。
94
+ **「库侧门禁全绿」不代表下游没有新增硬编码。** 要真拦住,得在各端自己的提交期调用它
95
+ —— 这一步**尚未做**,是已知缺口。
96
+ - **存量不阻断**:`token-usage-baseline.json` 记 `文件::规则 → 处数`,只有新组合出现、
97
+ 或已记组合处数变多才拦。key 刻意不含行号,重构挪代码不会被误判成新增。
98
+ 收口用 `pnpm check:usage -- --update-baseline`,看清单用 `-- --all`。
99
+ - **豁免三种**:文件里写 `token-check-ignore` 整 file 跳过;`--x: <字面值>` 这种
100
+ token 定义行不算违规(本地 token 层该不该收进库是另一个议题);命中文本里已含
101
+ `var()` 的不算。
102
+ - **路径靠工作区布局推断**:默认按兄弟仓找(`modelgo-console-web/src` 等)。
103
+ 在 worktree 里跑也能正确解析;布局不同用 `MODELGO_WORKSPACE=/path` 覆盖。
104
+ **找不到目标时会以退出码 2 失败,不会静默通过** —— 2026-08-24 之前它会把找不到的
105
+ 目标静默丢掉、扫 0 个文件仍打印 `passed`,在 worktree 里跑必然假绿。
106
+
107
+ > 覆盖范围的历史教训:这个脚本原先只有 4 条规则(Tailwind 语义色、两个 legacy hex、
108
+ > z-index),且 `DEFAULT_TARGETS` 只含 console-web 和一个早已不存在的目录。
109
+ > 结果是**国内官网从未被扫过**,而库里成体系的 `ease` / `duration` / `radius` / `shadow`
110
+ > 一条都没查 —— 补齐后存量从 22 处涨到 402 处,即原先只看得见 5.5%。
111
+ > 新增规则时记住:**没被规则覆盖的维度,等于默许硬编码**。
package/USAGE.md CHANGED
@@ -2,6 +2,42 @@
2
2
 
3
3
  token 解决"值统一",这页解决"用法统一"——四端照同一套规则用,才不会再飘。
4
4
 
5
+ ## 引哪一份(0.11.0 起)
6
+
7
+ 包里除全量 `tokens.css` 外,另出三份分层产物,**按你是哪一端只引自己那层**:
8
+
9
+ ```css
10
+ /* 控制台 */
11
+ @import "modelgo-design-tokens/base.css";
12
+ @import "modelgo-design-tokens/console.css";
13
+
14
+ /* 官网(domestic / global) */
15
+ @import "modelgo-design-tokens/base.css";
16
+ @import "modelgo-design-tokens/website.css";
17
+
18
+ /* 不确定 / 图省事 —— 全量,行为与 0.10.0 及以前完全一致 */
19
+ @import "modelgo-design-tokens/tokens.css";
20
+ ```
21
+
22
+ | 层 | token 数 | 内容 | 依赖 |
23
+ |---|---|---|---|
24
+ | `base` | 241 | 原子与跨端语义:品牌色阶/灰阶/字阶/间距/圆角/阴影/动效/层级/断点/面与文字/玻璃/状态语义色 | 自闭合,不依赖任何层 |
25
+ | `console` | 434 | 控制台专用组件语义 | 只依赖 `base` |
26
+ | `website` | 4 | 官网专用组件语义(官网组件层大部分仍在官网本地维护、尚未下沉) | 只依赖 `base` |
27
+
28
+ 三份是 `tokens.css` 的**投影,不是第二真源**:改值仍然只改 `tokens.css`(走预览站),
29
+ 然后 `npm run split` 重新生成。`release.mjs` 预检会跑 `check:layers-sync`,产物过期
30
+ 直接拦住发版——因为过期产物的故障形态是**静默的**(消费方拿到旧值,不报错)。
31
+
32
+ > ⚠️ **别只引 `console.css` 不引 `base.css`**。console 层里大量 token 是
33
+ > `var(--mg-brand-base)` 这类对 base 的引用,缺了 base 就是悬空 var → **整条声明
34
+ > 静默失效**。分层门禁保证的是「base 自闭合」和「base+console 自闭合」,
35
+ > 单独一个 console 不成立。
36
+
37
+ **这一层解决的真问题**:消费方为了拿到派生层,历史上会把库的整份 token 抄进本地
38
+ 转发(console-web 就抄了 337 个),于是库改值被本地重复声明压死、每次升级都要重复
39
+ 一遍撤除动作(见 CHANGELOG 0.10.0 与 qa#615)。按需只引一层之后,抄整份的动机就没了。
40
+
5
41
  ## 总则
6
42
 
7
43
  - **只用 token,不写硬编码。** 任何颜色/字号/圆角/间距/阴影都走 `var(--mg-*)`;禁止裸 hex / 裸 px(语义状态色 green/red/yellow 例外,但也应走 `--mg-success/-warning/-error`)。