modelgo-design-tokens 0.8.1 → 0.10.0
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 +331 -0
- package/README.md +11 -4
- package/TOKEN-GOVERNANCE.md +84 -0
- package/USAGE.md +75 -1
- package/package.json +12 -2
- package/scripts/check-token-contract.mjs +64 -0
- package/scripts/check-token-usage.mjs +87 -0
- package/token-contract.json +18 -0
- package/tokens.css +569 -120
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **对比度门禁(关卡 4)**:`scripts/check-token-contrast.mjs` + `contrast-contract.json`(语义配对表)
|
|
8
|
+
+ `contrast-baseline.json`(存量快照)。解析 `tokens.css` 的 `var()` 链与 `color-mix()`,
|
|
9
|
+
在 `market × theme` 全矩阵下算 WCAG 2.1 对比度。接在三处:`pre-commit-all.sh`、
|
|
10
|
+
`release.mjs` 预检、`preview.mjs` 的 `/api/save`(保存那一刻就拦,`blocked:'contrast'`)。
|
|
11
|
+
新增 `pnpm check:contrast`(`--all` 看全量,`--update-baseline` 刷新快照)。
|
|
12
|
+
- 补的是现有三关的空白:自闭合 / 契约 / 改值数量查的都是引用完整性与改动规模,
|
|
13
|
+
没有一关问「改出来的颜色还能不能读」。预览站能让设计同学不碰代码写回真源,
|
|
14
|
+
同样也能一路顺畅地把正文色拖到 3.9:1,四端一起降标且全程零提示。
|
|
15
|
+
- **只拦「新增」与「恶化」**,存量原样不达标不阻断(沿用本仓「机器能判死的才阻断」)。
|
|
16
|
+
首次接入记录 25 项存量,见 `contrast-baseline.json`。
|
|
17
|
+
- 半透明色(`color-mix(..., transparent)`)按 alpha 合成到页面根底色计算,是个**假设**——
|
|
18
|
+
真实叠在卡片/弹窗上会不同,精确值仍靠消费方浏览器态验证(axe / Lighthouse)。
|
|
19
|
+
- 交叉验证:本脚本独立算出「浅色 10 项 Badge 全 AAA、深色四个语义 `-text` 与 audio 达 AA 未达 AAA」,
|
|
20
|
+
与 qa#614 人工逐项实测的结论一致(绝对值差 ~0.7,因该单在真实渲染环境量、含玻璃层叠加)。
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
|
|
24
|
+
- **对比度门禁在含空格路径下静默空转**。`isMain` 用 `new URL(import.meta.url).pathname` 判定,
|
|
25
|
+
而 `pathname` 不做百分号解码:仓库路径含空格或非 ASCII 时得到 `.../model%20go/...`,
|
|
26
|
+
与 `process.argv[1]` 的解码形式永不相等 → `isMain` 恒为 false → **主流程从不执行,
|
|
27
|
+
以退出码 0 冒充「通过」**。该关已接在 pre-commit、`release.mjs` 预检、预览站 `/api/save`
|
|
28
|
+
三处,等于三道口子一起放空。改用 `fileURLToPath`(本仓其余脚本用的就是这个写法)。
|
|
29
|
+
修后首次真跑:96 组合 · 达标 74 · 不达标 22。
|
|
30
|
+
|
|
31
|
+
### 存量已清零(原 25 项)
|
|
32
|
+
|
|
33
|
+
首次接入记录的 25 项存量(去重后 22 项组合)**已在本轮全部改到达标**,
|
|
34
|
+
`contrast-baseline.json` 已用 `--update-baseline` 收口为空。
|
|
35
|
+
当前 **96 组合 · 达标 96 · 不达标 0**。逐项处理见 0.10.0 的 Changed:
|
|
36
|
+
主按钮白字、浅色文字梯、深色 `--mg-text-3`、深色四个语义 `-text` 与 `audio`。
|
|
37
|
+
|
|
38
|
+
`--mg-text-3` 的阈值已定为 **3**(原 `todo` 已结):定位是极弱标注、不承载必读信息。
|
|
39
|
+
按 4.5 判会把它压到与 `--mg-text-2` 只差 1.44 倍、两级分不出,且 `t3→t4` 落差反而
|
|
40
|
+
变成全梯最大,节奏是坏的。判定依据与附带约束(不得用 `text-3` 承载必读信息)
|
|
41
|
+
写在 `contrast-contract.json` 该条的 `note`。
|
|
42
|
+
|
|
43
|
+
### 配对表选 token 的一个坑(已记入豁免依据)
|
|
44
|
+
|
|
45
|
+
首版配对表把 `--mg-success / -warning / -error / -info` 当状态文字色判,产出 4 项假阳性——
|
|
46
|
+
它们是**填充级**语义色(进度条/图标/描边),当文字用的是 `-text` 变体,而后者已由 qa#614 修到 AAA。
|
|
47
|
+
配对表现按「`-text` on `-bg` 成套」配,填充色进 `exempt` 并写明这段依据。
|
|
48
|
+
|
|
49
|
+
## 0.10.0
|
|
50
|
+
|
|
51
|
+
设计依据:[qa#611](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/611)(四项定案,UI 侧 2026-08-17 / 08-18 逐项拍板)
|
|
52
|
+
与 [qa#613](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/613)(浅色阴影并入 sm/md/lg 体系,2026-08-18 定案)。
|
|
53
|
+
本轮只落值与规格,不改任何消费方代码。
|
|
54
|
+
|
|
55
|
+
### ⚠ BREAKING CHANGES
|
|
56
|
+
|
|
57
|
+
- **移除 `[data-theme='dark-showcase']`**(3 个独有块,以及共享选择器上的 `dark-showcase` 分支)。
|
|
58
|
+
它从未在真实产品里生效过——控制台的 `applyTheme` 只设 `data-theme="dark"`,所以库的这套深色档等于死代码。
|
|
59
|
+
仍挂 `dark-showcase` 的页面会**掉回浅色**(该值现在不匹配任何规则),必须改用 `data-theme="dark"`。
|
|
60
|
+
- **移除 `--mg-control-px-md`**。它只是 `--mg-control-pad-x-md` 的历史短名别名;
|
|
61
|
+
留着会让「md 档到底是 16 还是 20」这个分叉多一个入口。
|
|
62
|
+
其余短名 `--mg-control-px-{xs,sm,lg,xl}` 保留为迁移别名,不受影响。
|
|
63
|
+
|
|
64
|
+
### Removed
|
|
65
|
+
|
|
66
|
+
- **移除 Tailwind v4 适配层**:删掉 `tailwind.css`(`@theme inline` 入口)与 `token-contract.json`
|
|
67
|
+
的 `tailwind.requiredMappings` 契约,`check:contract` 不再校验框架映射。
|
|
68
|
+
**不是破坏性变更** —— 该文件是本轮新加的、从未发布,也没有任何消费方 import 过。
|
|
69
|
+
移除理由:框架适配层反向约束了设计真源。qa#613 里出现过
|
|
70
|
+
「`--mg-shadow-card` 因为是 Tailwind 必需映射所以只能改值不能删」——
|
|
71
|
+
一个框架映射决定了一个设计 token 的生死,方向反了。本包回到只出 CSS 自定义属性、
|
|
72
|
+
完全框架无关;用 Tailwind v4 的端在自己仓里写约 20 行 `@theme inline` 映射,
|
|
73
|
+
映射哪些、叫什么由该端自己定。
|
|
74
|
+
(另:5 个消费方里只有 2 个能用 v4 语法,controller-web 仍在 v3,global-web / doc-web 不用 Tailwind。)
|
|
75
|
+
|
|
76
|
+
### Added
|
|
77
|
+
|
|
78
|
+
- `--mg-shadow-sm` / `--mg-shadow-md`:补齐分层阴影的低两档。
|
|
79
|
+
浅色采纳控制台现行 `--shadow-sm/md` 的值为库的设计值;深色指向库内已有的同值 token
|
|
80
|
+
(`--mg-shadow-card` / `--mg-shadow-card-hover`),不重复造值。
|
|
81
|
+
至此 `--mg-shadow-*` 与控制台 `--shadow-*` 不再是「两套值打架」,而是同一套体系。
|
|
82
|
+
- `[data-theme='dark']` 补齐 4 个分类色前景,取控制台线上已验证的深色档:
|
|
83
|
+
|
|
84
|
+
```css
|
|
85
|
+
--mg-modality-image-fg: #c4b5fd;
|
|
86
|
+
--mg-modality-video-fg: #fed7aa;
|
|
87
|
+
--mg-modality-embedding-fg: #fde68a;
|
|
88
|
+
--mg-modality-reranker-fg: var(--mg-text-2);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
这 4 个此前只在 `dark-showcase` 块里有深色档,深色态实际回落 `:root` 的浅色值。
|
|
92
|
+
控制台因为本地 `src/styles/tokens.css` 有一份兜底才没暴露;没有本地兜底的官网会直接拿到浅色。
|
|
93
|
+
- `TOKEN-GOVERNANCE.md`:token 工程契约的文字真源——正式深色只认 `data-theme="dark"`、
|
|
94
|
+
命名唯一性、派生 token 的指向方向、层级与透明度、以及「已下沉未接入」token 的定位。
|
|
95
|
+
- `token-contract.json` + `scripts/check-token-contract.mjs`:把上述契约变成可执行校验,
|
|
96
|
+
已纳入 pre-commit 门禁与发布预检。
|
|
97
|
+
- 文档补齐:`USAGE.md` 新增「阴影」章节(档位真源 `sm/md/lg` 与四个语义别名的指向关系、
|
|
98
|
+
深浅两套的差异),并补 `--mg-select-*`、`--mg-header-bg` 条目;`README.md` 的「Token 分类」
|
|
99
|
+
表格补「阴影」一组。此前 `--mg-shadow-sm/md/lg` 在全部文档里零提及。
|
|
100
|
+
- 门禁增强:`npm run check:closure` 增加**环引用检测**与**级联顺序检测**(按主题 × 市场
|
|
101
|
+
四个上下文分别建图,避免把不同上下文的反向指针误判成环)。两类故障此前三道门禁全放行,
|
|
102
|
+
但都会静默失效——环让属性变初始值(`box-shadow` 直接消失),条件覆盖写在 `:root` 之前
|
|
103
|
+
则永不生效。同时接进 pre-commit 与预览站写回路径(设计同学改值时就拦,HTTP 422)。
|
|
104
|
+
- `TOKEN-GOVERNANCE.md` 新增第 5 节「阴影等派生 token 的指向方向(硬规则)」:
|
|
105
|
+
档位 token 持字面值、语义别名单向指过去;条件覆盖必须写在对应 `:root` 声明之后。
|
|
106
|
+
- `--mg-select-bg-from` / `--mg-select-bg-to` / `--mg-select-bg` / `--mg-select-border`:
|
|
107
|
+
单选卡片选中态的渐变底与描边。深色档把品牌色占比提到 26%(浅色 12%)。
|
|
108
|
+
- 浅色 `--mg-header-bg`(`var(--mg-surface-3)`):此前只有深色档有值,浅色顶栏没有规范底色可用。
|
|
109
|
+
|
|
110
|
+
### Changed
|
|
111
|
+
|
|
112
|
+
- `--mg-control-pad-x-md`:`--mg-space-5`(20px) → `--mg-space-4`(16px)(qa#611 ② 定案 16px)。
|
|
113
|
+
分叉点在规范名上而不在别名,所以改的是 `-md` 的值;`--mg-control-pad-x` 改为
|
|
114
|
+
`var(--mg-control-pad-x-md)`,与 `--mg-control-height` 同一套写法,值只在 `-md` 上维护一处。
|
|
115
|
+
- `--mg-dialog-max-height`:`min(720px, 100dvh - 128px)` → `90dvh`。
|
|
116
|
+
定案不切规范值,保持 qa#458 已验收的「封顶到视口内并内部滚动」行为。
|
|
117
|
+
- `--mg-brand-glow` / `--mg-brand-subtle`:不迁 showcase 的 28% / 10%,回落 `:root` 的 14% / 6%。
|
|
118
|
+
它们本身是 `color-mix(... var(--mg-brand-base) N%)`,跟着品牌色走;
|
|
119
|
+
迁 showcase 的值会改深色观感,与「废弃旧稿、深色不改版」的定案冲突。
|
|
120
|
+
- 深色填色规律写入治理文档:**语义色去饱和,品牌色与分类色提亮保饱和**。
|
|
121
|
+
现行 `dark` 不是一刀切莫兰迪——按莫兰迪规律反算品牌色会得到 `#4f649c` 的灰蓝,等于把品牌洗成灰。
|
|
122
|
+
- 深色 `--mg-header-bg`:`rgba(24, 24, 28, 0.85)` → `#18181c`(实色)。
|
|
123
|
+
统一顶栏在四个模式下都不透明,避免半透明底叠出深浅不一。
|
|
124
|
+
- `[data-market='global']` 浅色 `--mg-glass-canvas`:`#b7e0cd → #e7fbf2` 改为 `#f5fbf6 → #fafdfb`。
|
|
125
|
+
按 OKLab 把国内 `#edf5ff → #f4faff` 的明度与彩度平移到品牌绿色相——原值明度低 9.5 个点、
|
|
126
|
+
彩度高 3.2 倍,导致海外站整页压内容。**只影响海外站,控制台不涉及。**
|
|
127
|
+
- `--mg-control-h-sm` 改为引用 `var(--mg-control-height-sm)`(原字面量 `2rem`)。
|
|
128
|
+
纯写法收口,**生效值仍是 32px,无视觉变化**。
|
|
129
|
+
- 浅色 `--mg-shadow-card`、`--mg-shadow-elevated` 并入 `sm/md/lg` 体系
|
|
130
|
+
([qa#613](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/613) 定案):
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
--mg-shadow-card: 0 1px 3px rgba(0,0,0,.06) → var(--mg-shadow-sm)
|
|
134
|
+
--mg-shadow-elevated: 0 4px 16px rgba(0,0,0,.08) → var(--mg-shadow-md)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
原为单层纯黑旧基线,与 `sm/md/lg` 的多层蓝调 `rgba(16,24,40,*)` 不是一路。
|
|
138
|
+
`--mg-tile-shadow` 引用 `card`,跟着一起进入新体系。
|
|
139
|
+
- `--mg-dialog-shadow` 由 `--mg-shadow-elevated` 改指 `--mg-shadow-lg`。
|
|
140
|
+
弹窗是最高层浮层,不该与代码块、下拉面板共用同一档。
|
|
141
|
+
- 浅色 `--mg-card-border`:`rgba(16, 24, 40, 0.05)` → `rgba(16, 24, 40, 0.13)`。
|
|
142
|
+
|
|
143
|
+
浅色卡片在玻璃画布上糊边的原因不是阴影太弱,是**描边太弱**:卡面(白色 70% 覆膜)叠在
|
|
144
|
+
近白画布(`#edf5ff → #f4faff`)上对比度只有 **1.036**,白上加白靠面分不开,只能靠描边;
|
|
145
|
+
而原描边只有 **1.11**,不到治理文档第 5 节的 hairline ≥ 1.3。
|
|
146
|
+
**只提 alpha、不换色相**:alpha 型描边的对比度几乎不随卡面变(实色面与玻璃面都是 **1.312**),
|
|
147
|
+
而固定 hex 会漂移——中途曾试过 `--mg-glass-line`,它在玻璃卡面上有 1.31、
|
|
148
|
+
在实色 `--mg-surface-solid` 上只剩 1.19,会静默不达标。
|
|
149
|
+
同时保住控制台 2026-07-23 定的「淡边框、近乎 hairline、不要硬线框」的中性观感。
|
|
150
|
+
**深色不受影响**(`[data-theme='dark']` 的 `--mg-card-border` 仍是 `rgba(255,255,255,.08)`)。
|
|
151
|
+
- 理顺深浅两套的指针方向:`sm/md/lg` 在两个主题里都持字面值,`card`/`elevated` 单向指过去。
|
|
152
|
+
此前浅色 `card→sm`、深色 `sm→card` 方向相反,深色 `card` 一旦也改成指 `sm` 就会成循环引用。
|
|
153
|
+
- **行为变化**:深色 `--mg-shadow-elevated` 由 lg 级降为 md 级(与浅色同档)。
|
|
154
|
+
库内已无消费点(`--mg-dialog-shadow` 已改指 `lg`,而深色 `lg` 恰好等于原深色 `elevated`,
|
|
155
|
+
所以弹窗投影不变);三个官网锁 `^0.6.x` 不会自动获取。
|
|
156
|
+
- **浅色标签文字色达 WCAG AAA**([qa#614](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/614) 定口径 7:1)。
|
|
157
|
+
标签字号 `--mg-text-xs` 12px 属 WCAG 小字,改前 10 项**无一达 AA(4.5)**,最差 1.77:
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
--mg-success-text var(--mg-success) 2.08 → #065641 7.12
|
|
161
|
+
--mg-warning-text var(--mg-warning) 1.77 → #78350f 7.50
|
|
162
|
+
--mg-error-text var(--mg-error) 3.01 → #8f1e1d 7.08
|
|
163
|
+
--mg-info-text var(--mg-info) 2.99 → #1e40af 7.09 blue-800
|
|
164
|
+
--mg-modality-image-fg #7c3aed 4.51 → #5b21b6 7.10 violet-800
|
|
165
|
+
--mg-modality-video-fg #ea580c 2.89 → #7c2d12 7.61
|
|
166
|
+
--mg-modality-embedding-fg #a16207 4.10 → #713f12 7.22
|
|
167
|
+
--mg-modality-reranker-fg var(--mg-text-2) 4.01 → var(--mg-text-1) 13.57
|
|
168
|
+
--mg-modality-text-fg 国内 #223de5 5.80 → #3730a3 7.87 indigo-800
|
|
169
|
+
--mg-modality-text-fg 海外 #0F9F59 2.81 → #065641 7.14
|
|
170
|
+
--mg-modality-audio-fg 跟 --mg-success-text 走,未单独改 2.08 → 7.12
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
根因是「`-text` 变体直接别名填充级语义色」:`--mg-success-text` 原为 `var(--mg-success)`,
|
|
174
|
+
填充色当文字色在浅底上读不出来,warning / error / info 全是同一写法。修上游即连带修掉
|
|
175
|
+
`audio`(它就是 `var(--mg-success-text)`),不新造 token 名。
|
|
176
|
+
**取值规则是「各色相取刚过 7 的最浅值」,不是「统一某个调色板档号」**——
|
|
177
|
+
同档号在不同色相上对比度差很远(violet-800 是 7.10,amber-800 只有 5.86),
|
|
178
|
+
该统一的是目标对比度而非档号。能落在调色板整档的就用整档(info→blue-800、
|
|
179
|
+
image→violet-800、text→indigo-800),其余取刚过 7 的最浅值,尽量少改观感。
|
|
180
|
+
- 深色 `--mg-modality-text-fg` 补为 `var(--mg-brand-light)`。
|
|
181
|
+
原先无深色覆盖、兜底到 `var(--mg-brand-base)`,实测国内 4.37 / 海外 4.19,**连 AA 都不到**
|
|
182
|
+
——既有缺口,非本轮引入。改后国内 9.23 / 海外 11.4 双 AAA,仍是品牌派生、自动跟市场切色相。
|
|
183
|
+
- **深色四个语义 `-text` 提到 AAA,保莫兰迪、只提亮**:
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
--mg-success-text #8fae9b 5.42 → #b0c6b8 莫兰迪混白 30% 7.24
|
|
187
|
+
--mg-warning-text #cda971 5.74 → #dcc39c 莫兰迪混白 30% 7.45
|
|
188
|
+
--mg-error-text #c98b85 4.90 → #e0b9b4 莫兰迪混白 40% 7.67
|
|
189
|
+
--mg-info-text #8aa0c4 5.16 → #acbcd6 莫兰迪混白 30% 7.12
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
它们原是 `var(--mg-success)` 这类填充色本体,即莫兰迪降饱和值,达 AA 不达 AAA。
|
|
193
|
+
中途曾试过换 Tailwind 300 档,能达标但那是饱和鲜艳色,直接违背 qa#611 定的
|
|
194
|
+
「语义色去饱和,状态提示不该抢眼」——**达标不以推翻设计语言为代价**,故改为把各自的
|
|
195
|
+
莫兰迪色混白到刚过 7。填充色与描边仍是原莫兰迪值,未动。
|
|
196
|
+
`--mg-modality-audio-fg` 跟 `--mg-success-text` 走,连带达标。
|
|
197
|
+
该块与海外 `--mg-modality-text-fg` 的 `[data-market='global']` 块都写在对应 `:root` **之后**
|
|
198
|
+
(TOKEN-GOVERNANCE 第 4 节硬规则)。
|
|
199
|
+
- **浅色文字梯微调**(不是跳档):
|
|
200
|
+
|
|
201
|
+
```
|
|
202
|
+
--mg-text-2 gray-500 #64748b 4.26 → #5f6e84 4.64
|
|
203
|
+
--mg-text-3 gray-400 #94a3b8 2.30 → #7c8ba0 3.10
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
判定用最苛刻的面 `--mg-surface-solid`。t2 原本只差 0.24,若跳到 gray-600(6.79)
|
|
207
|
+
会把 t2/t3 的浓度差从 1.85 倍挤到 1.44 倍、两级几乎分不出,且 t3→t4 落差反而变成
|
|
208
|
+
全梯最大,节奏是坏的。故各取「四个面都能过阈值的最浅值」,改后节奏
|
|
209
|
+
3.11 / 1.50 / 2.33,接近原本的 3.38 / 1.85 / 1.73。
|
|
210
|
+
`--mg-text-3` 的阈值按「极弱标注、不承载必读信息」定为 **3**(见 `contrast-contract.json`
|
|
211
|
+
该条 note)。**约束:不得用 `--mg-text-3` 承载必读信息,需要必读就用 `--mg-text-2`。**
|
|
212
|
+
`--mg-text-4` 是禁用/极弱档,同样不判对比度,未动。
|
|
213
|
+
- 深色 `--mg-text-3`:`#a1a1aa` → `#b4b4bd`(在 `--mg-surface-3` 上由 4.32 提到 5.38)。
|
|
214
|
+
- **主按钮白字达 4.5**。实测四个上下文只有浅色国内达标:
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
浅色·国内 #223de5 7.32 ✓ 未改
|
|
218
|
+
浅色·海外 #0F9F59 3.43 → 5.27
|
|
219
|
+
深色·国内 #5b8def 3.23 → 4.99
|
|
220
|
+
深色·海外 #0F9F59 3.43 → 5.27
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
加深的是**按钮填充**而非 `--mg-brand-base`:品牌色是识别符号,且深色提亮(qa#611 定案)
|
|
224
|
+
与海外绿 `#0F9F59`(`bca4027` 设计确认)都是已定的值,不因按钮可读性反过来改品牌。
|
|
225
|
+
故在 `[data-market='global']` 与 `[data-theme='dark']` 各加一块,同公式
|
|
226
|
+
`color-mix(in oklab, <brand> 78%, #000)`。hover/active 一并加深——深色海外档
|
|
227
|
+
`--mg-brand-deep` 是 `#34a52a`,比 base 更浅,原样白字只有 3.20,比默认态还差。
|
|
228
|
+
`--mg-btn-primary-text` 改为引用 `--mg-on-primary`(两者原本同为 `#ffffff`,生效值不变)。
|
|
229
|
+
- `--mg-warning`:`#f59e0b` → `#FFA000`。原注释是「待设计确认(基线未定义)」,
|
|
230
|
+
即库自己标的占位值;`#FFA000` 是控制台线上实际在跑的值,采纳它等于**零视觉变化**,
|
|
231
|
+
反过来选 `#f59e0b` 才会改动线上警告色。两个值都不影响 `--mg-warning-text` 达 AAA
|
|
232
|
+
(7.50 / 7.56)。下游 `-bg` / `-bg-hover` / `-border` / `progress-warning-*` 均为派生,自动跟随。
|
|
233
|
+
|
|
234
|
+
### Migration Notes
|
|
235
|
+
|
|
236
|
+
> ⚠️ **升级依赖本身不会让本轮定案生效。** 消费方若在自己的 CSS 里重复声明了同名 `--mg-*`
|
|
237
|
+
> 且后加载,本地值会盖住库的值。以 modelgo-console-web 为例:它的
|
|
238
|
+
> `src/index.css` 先 import 库、再 import 本地 `src/styles/tokens.css`,
|
|
239
|
+
> 本地重复声明了库中 **383 个** `--mg-*`——其中 `--mg-control-px-md: var(--mg-space-5)`(20px)
|
|
240
|
+
> 会让本轮 ② 定的 16px 完全不生效。要让定案落地,消费方必须**删掉对应的本地声明**,
|
|
241
|
+
> 而不只是把依赖升到 `^0.10.0`。
|
|
242
|
+
|
|
243
|
+
- 挂 `data-theme="dark-showcase"` 的地方改成 `data-theme="dark"`,否则整页掉回浅色。
|
|
244
|
+
- 用 `--mg-control-px-md` 的地方改 `--mg-control-pad-x-md`(或短名 `--mg-control-pad-x`)。
|
|
245
|
+
注意这不只是改名:**md 档的生效值同时从 20px 变成 16px**。
|
|
246
|
+
- 接 Dialog 宽度时去掉 `w-full`。宽度不配固定档位,由内容在
|
|
247
|
+
`--mg-dialog-min-width`(360px) 与 `--mg-dialog-max-width`(720px) 之间自适应——
|
|
248
|
+
`w-full` 才是「所有弹窗一律撑到 max-width」的根因。
|
|
249
|
+
- 升级依赖声明时注意:**`^0.9.0` 不会自动升到 0.10.0**(caret 对 `0.x` 不跨 minor),
|
|
250
|
+
需要显式改成 `^0.10.0`。
|
|
251
|
+
- 升到 0.10.0 之后,消费方需撤掉本地重复声明。以 console-web 为例,
|
|
252
|
+
与本轮改动相关的共 **57 处 / 43 个 token**,分四类:
|
|
253
|
+
- **值不同(15 处)**:`success/warning/error/info-text`、`modality-*-fg`、`btn-primary-text` 等,
|
|
254
|
+
不删则本轮改动全部无效。
|
|
255
|
+
- **值相同但仍须删(26 处)**:如 `--mg-btn-primary-bg: var(--mg-brand-base)` 与库一字不差,
|
|
256
|
+
但它在本地 `:root`、后加载,会**压掉库里 `[data-theme]` / `[data-market]` 的条件覆盖**
|
|
257
|
+
(两者特异性同为 `(0,1,0)`)。判据:只要本地重复声明了某 token,库对它的所有条件覆盖即失效。
|
|
258
|
+
- **必须成对删(20 处)**⚠️:console-web 的 `--mg-control-h-*` / `--mg-control-height-*` 与
|
|
259
|
+
`--mg-control-px-*` / `--mg-control-pad-x-*` **指向方向与库相反**(本地是规范名→旧名,
|
|
260
|
+
库是旧名→规范名)。只删一半会让两者互相引用**成环**,CSS 判 cyclic var 为
|
|
261
|
+
invalid at computed-value time,控件高度/内边距**静默消失**。必须整段一起删。
|
|
262
|
+
注意 `check:closure` 的环检测只扫本仓、不扫消费方,抓不到这个。
|
|
263
|
+
- **顺序**:库先发版、消费方再撤,中间不会出现两边都没值的窗口。
|
|
264
|
+
|
|
265
|
+
### 已知遗留
|
|
266
|
+
|
|
267
|
+
- ~~浅色 `--mg-shadow-card` / `--mg-shadow-elevated` 仍是旧基线单层值~~ ——
|
|
268
|
+
已由 [qa#613](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/613) 定案,
|
|
269
|
+
在本版一并解决(见上方 Changed)。`--mg-shadow-card` 保留(作为既有语义位的别名)。
|
|
270
|
+
- `--mg-shadow-hover-sm/md/lg` 三档已核对与控制台无分叉(深色同名同值、浅色仅库内有),
|
|
271
|
+
本轮未动。
|
|
272
|
+
- ~~**深色标签文字色达 AA 未达 AAA**~~ —— UI 侧 2026-08-18 追加要求「都改到符合标准」后,
|
|
273
|
+
已在本版一并提到 AAA(保莫兰迪、只提亮,见上方 Changed)。
|
|
274
|
+
- **深色海外档 `--mg-brand-deep`(`#34a52a`)比 `--mg-brand-base`(`#0F9F59`)更浅**,
|
|
275
|
+
「deep 比 base 浅」是值倒挂。因此主按钮 hover 在该上下文比默认态更浅,
|
|
276
|
+
与其余三个上下文方向相反(对比度仍达标 4.95,纯观感问题)。本轮未动,建议另开单。
|
|
277
|
+
|
|
278
|
+
## 0.9.0
|
|
279
|
+
|
|
280
|
+
> 本节原标题为 `Unreleased`;其内容(205 个语义 token 的合流)已随 **0.9.0** 发布,故正名。
|
|
281
|
+
|
|
282
|
+
> **合流状态(2026-08-17 更新)**:本节源自 `preview-token-demo-20260813` 分支,
|
|
283
|
+
> 已与 main 上 0.7.0–0.8.1 的语义 token 下沉合流完成,**205 个新变量已并入**。
|
|
284
|
+
>
|
|
285
|
+
> 合流时对既有 token 的处理原则是「只增不改」,已用 `scripts/diff-token-values.mjs`
|
|
286
|
+
> 逐项验证:相对合流前**生效值改变 0 项、删除 0 项**,即下游渲染结果不受影响。
|
|
287
|
+
>
|
|
288
|
+
> 以下条目**刻意未采纳**,与本节描述不符时以此处为准:
|
|
289
|
+
> - `--mg-radius-legacy-6/-16`、无前缀 `--chart-cat-*`:都是消费方迁移期的兼容别名,
|
|
290
|
+
> SSOT 只出 `--mg-` 前缀,别名由消费方自己维护(console-web 已有)。
|
|
291
|
+
> - `--mg-radius-popover/-dialog`:只是 `--mg-radius-md/-lg` 的同义别名,
|
|
292
|
+
> `--mg-dialog-radius` 已直接引用原语,不再套一层。
|
|
293
|
+
> - z-index 层级值的重排:分支把 dropdown/tooltip/overlay/sheet/modal 重排为
|
|
294
|
+
> 1300/1350/1400/1450/1500,但控制台现行是 dropdown/popover 1450、tooltip 1470,
|
|
295
|
+
> 改值会动到控制台层叠。main 保留现行值,只把「BASE 与 CONSOLE 各一套、
|
|
296
|
+
> `--mg-z-dropdown` 被重复声明」的结构问题合并为唯一一套(生效值不变)。
|
|
297
|
+
> - `--mg-avatar-size-md` 改 32px:控制台现行就是 `2.5rem`,分支单方面改值无记录依据。
|
|
298
|
+
> md 与 lg 同值确实是个阶梯问题,但属设计决策,未擅自改。
|
|
299
|
+
|
|
300
|
+
### Added
|
|
301
|
+
|
|
302
|
+
- Added semantic z-index layers from `--mg-z-base` to `--mg-z-devtool`, plus `.mg-layer-*` utility classes.
|
|
303
|
+
- Added radius ownership for legacy `6px` and `16px` values through `--mg-radius-xs`, `--mg-radius-legacy-6`, and `--mg-radius-legacy-16`.
|
|
304
|
+
- Added spacing primitives `--mg-space-5`, `--mg-space-9`, and `--mg-space-10`, plus layout rhythm tokens for page padding, section gaps, panel gaps, toolbar gaps, and card internal spacing.
|
|
305
|
+
- Added prose tokens for Markdown paragraphs, lists, inline code, code blocks, links, blockquotes, and headings.
|
|
306
|
+
- Added form, popover, tooltip, dialog, empty-state, skeleton, motion, and interaction-state tokens.
|
|
307
|
+
- Added semantic status tone tokens (`--mg-success-bg/-border/-text`, warning, error, info, and danger aliases).
|
|
308
|
+
- Added full button state tokens for primary, neutral, outline, secondary, ghost, link, and destructive variants. Destructive buttons use `--mg-btn-danger-bg: #d9534f` with derived hover/active/shadow values.
|
|
309
|
+
- Added toast, segmented control, and model-experience chat workspace tokens for component-level spacing and states.
|
|
310
|
+
- Added model modality tokens for text/image/audio/video/embedding/reranker badges, plus featured-card badge/chip variants.
|
|
311
|
+
- Added progress bar tokens for track, bar, glow, label, and badge variants.
|
|
312
|
+
- Added favorite, accent-purple, online-status, and success-avatar tokens used by model cards and account UI.
|
|
313
|
+
- Added `npm run check:usage` to catch common consumer-side hardcoded state colors, destructive colors, overlays, and global z-index values before release.
|
|
314
|
+
- Added chart category tokens (`--mg-chart-cat-1..6`) with legacy `--chart-cat-*` aliases.
|
|
315
|
+
- Added component-fit tokens for control typography/icons/gaps, card internal typography, table density, avatar sizing, toast timing/stacking, hover shadows, and motion enter/exit behavior.
|
|
316
|
+
|
|
317
|
+
### Changed
|
|
318
|
+
|
|
319
|
+
- Reordered z-index semantics so dropdowns, tooltips, overlays, sheets, modals, blocking layers, toasts, and developer tools have a single ascending layer contract.
|
|
320
|
+
- Moved modal/sheet overlay color and blur behind `--mg-overlay-bg` and `--mg-overlay-blur`.
|
|
321
|
+
|
|
322
|
+
### Migration Notes
|
|
323
|
+
|
|
324
|
+
- Replace hardcoded `z-40`, `z-50`, `z-[2000]`, `9999`, and `10000` with `var(--mg-z-*)` or `.mg-layer-*`.
|
|
325
|
+
- Replace bare `6px` radius with `--mg-radius-xs`; keep `16px` for code/media only via `--mg-radius-code`.
|
|
326
|
+
- Replace page-level spacing combinations such as `p-6 md:p-9` with `--mg-layout-page-pad-*`.
|
|
327
|
+
- Replace component-local `bg-red-* / text-red-* / bg-black/40 / dark:bg-black/60` patterns with semantic state tokens and overlay tokens.
|
|
328
|
+
- Replace model badge color classes such as `violet-* / orange-* / yellow-* / emerald-*` with `--mg-modality-*`.
|
|
329
|
+
- Replace progress bar hardcoded gradients/glows with `--mg-progress-*`.
|
|
330
|
+
- Replace local chart palettes with `--mg-chart-cat-*` and table/avatar/toast/layout one-offs with `--mg-table-*`, `--mg-avatar-*`, and `--mg-toast-*`.
|
|
331
|
+
- Run `npm run check:usage` from this package before publishing token updates.
|
package/README.md
CHANGED
|
@@ -39,15 +39,21 @@ pnpm add modelgo-design-tokens
|
|
|
39
39
|
h1 { font-size: var(--mg-text-h1); line-height: var(--mg-text-h1-line); }
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
Tailwind v4
|
|
42
|
+
用 Tailwind v4 的站点在**自己仓里**写 `@theme inline` 映射(本包不提供框架适配层,保持框架无关):
|
|
43
43
|
|
|
44
44
|
```css
|
|
45
|
-
@
|
|
46
|
-
|
|
47
|
-
|
|
45
|
+
@import 'tailwindcss';
|
|
46
|
+
@import 'modelgo-design-tokens/tokens.css';
|
|
47
|
+
|
|
48
|
+
@theme inline {
|
|
49
|
+
--color-brand-base: var(--mg-brand-base);
|
|
50
|
+
--radius-md: var(--mg-radius-md);
|
|
51
|
+
/* 映射哪些、叫什么,由该端自己定 */
|
|
48
52
|
}
|
|
49
53
|
```
|
|
50
54
|
|
|
55
|
+
共享映射、新增应用专有映射以及主题/别名的迁移规则见 [TOKEN-GOVERNANCE.md](./TOKEN-GOVERNANCE.md)。
|
|
56
|
+
|
|
51
57
|
## 双市场 / 双主题
|
|
52
58
|
|
|
53
59
|
- **市场**:根元素 `data-market="global"` → 品牌色切 emerald;缺省 = 国内 indigo。
|
|
@@ -119,6 +125,7 @@ pnpm preview:deploy # → Cloudflare Pages 项目 modelgo-design-tokens
|
|
|
119
125
|
| 按钮 | `--mg-btn-{height,height-sm,pad-x,radius,text,weight}` | |
|
|
120
126
|
| 产品市场 UX | `--mg-text-market-title`、`--mg-tile-*`、`--mg-control-*`、`--mg-media-*` | 官网内容卡与高密度市场页的共同契约 |
|
|
121
127
|
| 语义色 | `--mg-bg`, `--mg-bg-alt`, `--mg-text-{0,1,2}`, `--mg-border` | 按主题切 |
|
|
128
|
+
| 阴影 | `--mg-shadow-{sm,md,lg}` + `--mg-shadow-hover-{sm,md,lg}` | 档位真源,按主题切;`--mg-shadow-card/-elevated`、`--mg-dialog-shadow`、`--mg-tile-shadow` 均为指向档位的语义别名 |
|
|
122
129
|
|
|
123
130
|
## 落地节奏(建议)
|
|
124
131
|
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Token 工程契约
|
|
2
|
+
|
|
3
|
+
`tokens.css` 是四端的值真源;本文件约束命名、主题选择器、派生指向与层级透明度,防止真源本身再次分叉。
|
|
4
|
+
本包**框架无关**:只出 CSS 自定义属性,不提供任何框架适配层(Tailwind `@theme` 入口已于 0.10.0 移除,理由见 CHANGELOG)。
|
|
5
|
+
|
|
6
|
+
## 1. 命名与兼容
|
|
7
|
+
|
|
8
|
+
- 一个概念只允许一个**规范名**。新增 token 必须先归入已有的语义家族,不能为同一个含义再造缩写或近义前缀。
|
|
9
|
+
- Control 尺寸的规范名是 `--mg-control-height-{size}`,横向内边距的规范名是 `--mg-control-pad-x-{size}`。
|
|
10
|
+
- `--mg-control-h-{size}` 与 `--mg-control-px-{size}` 仅用于下游迁移兼容:它们必须直接引用对应规范名,禁止再作为值的定义点或在新代码中使用。
|
|
11
|
+
- 未带 size 的 `--mg-control-pad-x` 是 `-md` 档的短名,两者同值 16px([qa#611](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/611) ② 定案)。写法与 `--mg-control-height` 一致:短名 `var()` 指向 `-md`,值只在 `-md` 上维护一处。仍然禁止新建未带 size 的 control 内边距 token。
|
|
12
|
+
|
|
13
|
+
## 2. 深色主题真源
|
|
14
|
+
|
|
15
|
+
- `data-theme="dark"` 是唯一正式深色主题,用于控制台、文档站、应用和官网。
|
|
16
|
+
- `data-theme="dark-showcase"` 已由 qa#611 定案废弃,0.10.0 从发版产物移除。新增深色档一律写进 `[data-theme='dark']`,不得再引入第二套深色选择器。
|
|
17
|
+
- 深色填色不是一刀切降饱和:语义色去饱和,品牌色与分类色提亮保饱和。新增深色值按这条分类,别把品牌色按莫兰迪规律算。
|
|
18
|
+
- 不得用消费方现有样式反推或覆盖本仓的设计值。改值必须附设计依据;消费方只向本仓同步。
|
|
19
|
+
|
|
20
|
+
## 3. 下沉但未消费的 token
|
|
21
|
+
|
|
22
|
+
- 库里存在大量**已下沉、消费方尚未接入**的 token(`--mg-chat-*` / `--mg-prose-*` / `--mg-logo-*` 等)。定位是「先下沉占位、页面按自己节奏接」,**不要求消费方立即改用**([qa#611](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/611) ④ 定案)。
|
|
23
|
+
- 因此「某个 token 零引用」本身不是删除理由,也不构成消费方的迁移工期承诺。要求某端限期接入,需另开单并写明设计依据。
|
|
24
|
+
- 反过来也成立:零引用不等于可以随手改值。改值仍走第 2 节的设计依据要求。
|
|
25
|
+
|
|
26
|
+
## 4. 阴影等派生 token 的指向方向(硬规则)
|
|
27
|
+
|
|
28
|
+
- **档位 token 持字面值,语义别名单向指向档位,不得反向。** 具体到阴影:
|
|
29
|
+
`--mg-shadow-{sm,md,lg}` 在每个主题里都写字面值;`--mg-shadow-card` / `-elevated` /
|
|
30
|
+
`-card-hover` / `--mg-dialog-shadow` / `--mg-tile-shadow` 单向指过去。
|
|
31
|
+
- 为什么是硬规则:两个 token 互相引用会成环,CSS 判 cyclic var 为
|
|
32
|
+
*invalid at computed-value time*,用到它的属性静默变成初始值(`box-shadow` 直接没了),
|
|
33
|
+
**不报错、不崩溃**。与 2026-08-14 悬空引用事故同一类故障。
|
|
34
|
+
- **条件覆盖必须写在对应 `:root` 声明之后。** `:root` 与 `[data-theme]` / `[data-market]`
|
|
35
|
+
特异性相同(0,1,0),同分时后出现的胜 —— 条件块写在前面等于永不生效。
|
|
36
|
+
2026-08-18 的 `--mg-select-bg-to` 就是这样:深色 26% 写在文件前部的 dark 块里,
|
|
37
|
+
被后面 `:root` 的 12% 压死,深色档从未生效。
|
|
38
|
+
- 上述两条已由 `npm run check:closure` 自动阻断(环检测 + 级联顺序检测,按
|
|
39
|
+
主题 × 市场四个上下文分别建图),也接进了 pre-commit 与预览站的写回路径。
|
|
40
|
+
|
|
41
|
+
## 5. 层级与透明度(半透明值必须知道自己垫在哪一层)
|
|
42
|
+
|
|
43
|
+
本仓 774 条声明里有 **116 条(14%)是半透明的**(`rgba(…, .0x)` 或 `color-mix(…, transparent)`),
|
|
44
|
+
分布最密的是 `modality`(20) / `btn`(14) / `shadow`(13) / `chart`(12) / `glass`(11)。
|
|
45
|
+
**半透明值的最终观感由它下面那几层决定,不由它自己决定。**
|
|
46
|
+
|
|
47
|
+
浅色档的层级栈(自下而上):
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
--mg-glass-canvas 渐变画布(页面底)
|
|
51
|
+
--mg-bg #ffffff 页面
|
|
52
|
+
--mg-surface ← 卡面本身就是半透明:color-mix(--mg-glass-veil 70%, transparent)
|
|
53
|
+
--mg-surface-solid #f2f2f6 实色卡面
|
|
54
|
+
--mg-surface-2 #f8fafc 抬升面 / Dropdown
|
|
55
|
+
--mg-surface-3 #ffffff 顶层面板 Modal / Tooltip
|
|
56
|
+
--mg-overlay rgba(15,23,42,.5) 遮罩
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
所以「半透明标签 → 半透明卡面 → 渐变画布」是**三层叠加**。定值时只看自己那一层的十六进制数,
|
|
60
|
+
必然估错 —— 必须渲染出来看合成后的实际像素。
|
|
61
|
+
|
|
62
|
+
**硬规则:**
|
|
63
|
+
|
|
64
|
+
- **新增或修改半透明值,必须写明它设计时垫的是哪一层**(写在紧邻的注释里)。
|
|
65
|
+
例:`--mg-featured-chip-*` 那组在 `tokens.css` 里就注明了「深色媒体卡上的类型 badge」——
|
|
66
|
+
没有这句,任何人(包括自动检查)都会拿错底色去判断它对不对。
|
|
67
|
+
- **`-fg` 与 `-bg` 必须成对定义、成对验证**,且要在**浅/深 × 国内/海外四个上下文**下都验。
|
|
68
|
+
只在一个上下文里看着没问题不算通过:`--mg-modality-text-fg` 取 `var(--mg-brand-base)`,
|
|
69
|
+
国内蓝色达标,海外品牌绿在浅色下只有 2.57 —— 换市场就掉链子。
|
|
70
|
+
- **同一组标签的文字色必须对齐色阶。** 反例:`--mg-modality-audio-fg` 用了
|
|
71
|
+
`#10b981`(emerald-**500**,填充色级别),而同组 `embedding` 用 amber-**700**、
|
|
72
|
+
`video` 用 orange-**600**、`image` 用 violet-**600**。500 那档当文字色,浅色下对比度只有 1.82。
|
|
73
|
+
- **对比度门槛**:正文与小字 ≥ 4.5:1,大字与图标 ≥ 3:1,非文本分界线(hairline)本仓实践 ≥ 1.3
|
|
74
|
+
(见 `--mg-card-border` 由 1.105 提到 1.307 的那次修复)。
|
|
75
|
+
|
|
76
|
+
## 6. 变更门禁
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pnpm check:closure # var() 引用自闭合
|
|
80
|
+
pnpm check:contract # 主题与兼容别名契约
|
|
81
|
+
pnpm check:usage # 下游常见硬编码回归
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
提交和 release 都会运行与其相关的工程门禁。设计值的取舍仍需设计依据与人工审阅,不能被脚本替代。
|
package/USAGE.md
CHANGED
|
@@ -6,6 +6,12 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
6
6
|
|
|
7
7
|
- **只用 token,不写硬编码。** 任何颜色/字号/圆角/间距/阴影都走 `var(--mg-*)`;禁止裸 hex / 裸 px(语义状态色 green/red/yellow 例外,但也应走 `--mg-success/-warning/-error`)。
|
|
8
8
|
- **优先语义,其次原子。** UI 用语义 token(`--mg-text-1`、`--mg-bg`、`--mg-border`…);只有做品牌强调时才用 `--mg-brand-*`。别直接拿灰阶原子 `--mg-gray-500` 当正文色——用 `--mg-text-2`,这样深色主题自动翻转。
|
|
9
|
+
- **SSOT 只出 `--mg-` 前缀。** 各端历史遗留的无前缀别名(如控制台的 `--chart-cat-*`)由消费方自己维护,不下沉到本包,别在新端引用。
|
|
10
|
+
- 发布前跑 `npm run check:usage`,会检查控制台里常见的散写状态色、危险色、遮罩和全局层级。
|
|
11
|
+
- 发布前还要跑 `npm run check:closure`(已接进 `release.mjs` 预检,不过也可手动跑):确保包内每个 `var(--x)` 都有声明。悬空引用会让**整条 CSS 声明静默失效**——不报错、不崩溃,样式就是悄悄没了。2026-08-14 的 0.7.0/0.8.0 正是这样带病发出去的。
|
|
12
|
+
- 发布前跑 `npm run check:contract`:校验正式主题与兼容别名没有分叉。完整的工程边界见 [TOKEN-GOVERNANCE.md](./TOKEN-GOVERNANCE.md)。
|
|
13
|
+
- **本包框架无关**:只出 CSS 自定义属性,不提供 Tailwind / UnoCSS 等框架适配层。用 Tailwind v4 的端在自己仓里写 `@theme inline` 映射(约 20 行),映射哪些、叫什么由该端自己定。
|
|
14
|
+
- 改动 token 值后跑 `npm run check:diff -- <基准文件> tokens.css` 拿变更清单:它把 `var()` 递归展开到底再比对,能看出「值被悄悄改掉」这类 diff 里看不出来的问题。
|
|
9
15
|
|
|
10
16
|
## 颜色
|
|
11
17
|
|
|
@@ -16,6 +22,32 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
16
22
|
| 边框/分隔 | `--mg-border / --mg-divider` | 裸 rgba |
|
|
17
23
|
| 品牌强调(链接/选中/主按钮) | `--mg-brand-base` 等 | 写死 `#6366f1` |
|
|
18
24
|
| 状态 | `--mg-success / -warning / -error / -info` | 临时绿/红 |
|
|
25
|
+
| 状态提示块 / Badge | `--mg-success-bg / -border / -text` 等成套 token | `bg-red-50 text-red-600` 这类散写 |
|
|
26
|
+
| 模型能力类型 / 分类 Badge | `--mg-modality-*`、`--mg-accent-purple-*` | `violet / orange / yellow / emerald` 散写类 |
|
|
27
|
+
| 收藏 / 喜欢 | `--mg-favorite / --mg-favorite-bg-hover` | 写死玫红 |
|
|
28
|
+
| 图表多序列分类 | `--mg-chart-cat-1..6`(含 `-bg` / `-border` 衍生档) | 组件里临时挑 6 个颜色 |
|
|
29
|
+
|
|
30
|
+
### 对比度(改色前必读)
|
|
31
|
+
|
|
32
|
+
改任何色值前先知道这条**硬约束**:颜色不是自由变量,它得让人读得到。判据是 WCAG 2.1 AA 对比度:
|
|
33
|
+
|
|
34
|
+
| 用途 | 最低对比度 |
|
|
35
|
+
|---|---|
|
|
36
|
+
| 正文文字 | **4.5:1**(AA) |
|
|
37
|
+
| 标签 / Badge(`-text` on `-bg` 成套) | **7:1**(AAA,qa#614 定案;字号 12px 属小字) |
|
|
38
|
+
| 大字号(≥24px,或 ≥18.7px 加粗) | **3:1** |
|
|
39
|
+
| 理解 UI 所必需的图形与边界(如校验态描边) | **3:1** |
|
|
40
|
+
| 禁用态、纯装饰分隔线 | 豁免(WCAG §1.4.3 / §1.4.11) |
|
|
41
|
+
|
|
42
|
+
**别把填充色当文字色**:`--mg-success / -warning / -error / -info` 是填充级(进度条/图标/描边),
|
|
43
|
+
文字要用 `-text` 变体。两者阈值和取值完全不同 —— 填充色在浅底上当文字用普遍读不出来。
|
|
44
|
+
|
|
45
|
+
- 想保住色相又达标:**只调亮度** —— 浅底压暗、深底提亮。调饱和度几乎无效,对比度只看亮度。
|
|
46
|
+
- 门禁会自动算:`pnpm check:contrast`(全量 `--all`)。它在**提交期**、**发版预检**、**预览站保存那一刻**三处都跑。
|
|
47
|
+
- 判据不是写死在脚本里的,而是 `contrast-contract.json`(哪个前景配哪个背景、按什么标准判、豁免依据)。
|
|
48
|
+
觉得某项判得不对,改那张表并写清依据,**不要绕过数字**。
|
|
49
|
+
- 存量不达标项记在 `contrast-baseline.json`,只拦「新增」和「变得更差」。修好一项后跑
|
|
50
|
+
`pnpm check:contrast --update-baseline` 收口,防止它被再改坏。
|
|
19
51
|
|
|
20
52
|
## 双品牌色 / 市场
|
|
21
53
|
|
|
@@ -26,8 +58,10 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
26
58
|
## 主题(深浅)
|
|
27
59
|
|
|
28
60
|
- 语义 token 随 `data-theme="dark"` 自动翻转——**写组件时不要为深色单独硬编码颜色**,用语义 token 就对了。
|
|
61
|
+
- `data-theme="dark"` 是唯一的深色主题。曾经存在的 `data-theme="dark-showcase"` 已由 qa#611 定案废弃并于 0.10.0 移除,不要再挂这个值——它现在不匹配任何规则,会整页掉回浅色。
|
|
29
62
|
- 国内官网是纯浅色站,不挂 `data-theme`;深色组主要供控制台/app。
|
|
30
63
|
- 浅色素材(图片/插画)别直接铺到深色面上——深色用深色专用素材或压暗,详见控制台广场卡片的处理。
|
|
64
|
+
- 顶栏底色用 `--mg-header-bg`,**四个模式(浅/深 × 国内/海外)下都是实色不透明**。0.10.0 起深色档由 `rgba(24,24,28,.85)` 改为 `#18181c`,浅色档新增。不要自己给顶栏叠半透明底——半透明会随滚动内容叠出深浅不一。
|
|
31
65
|
|
|
32
66
|
## 字体 / 字阶
|
|
33
67
|
|
|
@@ -50,8 +84,43 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
50
84
|
## 圆角 / 间距 / 按钮
|
|
51
85
|
|
|
52
86
|
- 圆角:卡片 `--mg-radius-card`、代码块 `--mg-radius-code`、标签 `--mg-radius-tag`、按钮/胶囊 `--mg-radius-pill`。
|
|
87
|
+
- 遗留圆角归属:`6px` 只归 `--mg-radius-xs`(密集标签/小型菜单项),`16px` 只归 `--mg-radius-code` 或业务明确的媒体/代码容器;不要再裸写 `6px / 16px`。
|
|
53
88
|
- 间距走 4px 节奏(`--mg-space-*`);区块/区段用 `--mg-space-block / -section` 保持纵向韵律一致。
|
|
89
|
+
- 页面布局不要裸写 `p-6 md:p-9` 这类组合;控制台页面外留白优先用 `--mg-layout-console-page-pad-*`,内容卡片内距用 `--mg-layout-content-pad*`,区块间距用 `--mg-layout-section-gap / --mg-layout-panel-gap / --mg-layout-workbench-gap`。当前桌面控制台页面外留白:左右 40px、顶部 32px、底部 48px。
|
|
54
90
|
- 按钮统一 `--mg-btn-*`(高 36 / 字 13 / 胶囊);主按钮 `--mg-btn-gradient` + `--mg-btn-shadow`。
|
|
91
|
+
- 危险按钮统一 `--mg-btn-danger-*`:默认底色 `#D9534F`,hover / active 不另选红色,按同色相加深生成。
|
|
92
|
+
- 普通按钮同样走成套 token:`--mg-btn-primary-* / --mg-btn-neutral-* / --mg-btn-outline-* / --mg-btn-secondary-* / --mg-btn-ghost-* / --mg-btn-link-*`。hover 位移用 `--mg-btn-hover-y`,pressed 缩放用 `--mg-btn-press-scale`。
|
|
93
|
+
|
|
94
|
+
## 阴影
|
|
95
|
+
|
|
96
|
+
- **档位真源是 `--mg-shadow-{sm,md,lg}`**,浅色与深色各自持字面值。语义别名单向指向档位,不要反向:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
--mg-shadow-card → --mg-shadow-sm
|
|
100
|
+
--mg-shadow-elevated → --mg-shadow-md
|
|
101
|
+
--mg-dialog-shadow → --mg-shadow-lg
|
|
102
|
+
--mg-tile-shadow → --mg-shadow-card(即 sm)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- 新写组件直接用档位名 `--mg-shadow-sm/md/lg`。`card` / `elevated` 是留给既有语义位的别名(官网内容卡等既有语义位),**不是另一套值**——0.10.0 起它们就是档位本身,别再当成"旧基线"绕开。
|
|
106
|
+
- hover 态用 `--mg-shadow-hover-{sm,md,lg}` 配 `--mg-hover-y-*`,不要把静态档位拿去当 hover 值。
|
|
107
|
+
- **深色不是浅色的加深**:浅色是多层蓝调 `rgba(16, 24, 40, *)`;深色是纯黑高不透明度,其中 `md` / `lg` 另加 `0 0 0 1px rgba(255,255,255,.04)` 勾边(`sm` 不带)。所以别自己算深色阴影,用同名 token 让主题自动翻转。
|
|
108
|
+
|
|
109
|
+
## 长文 / 表单 / 浮层 / 空态
|
|
110
|
+
|
|
111
|
+
- Markdown / 说明文档用 `--mg-prose-*`:段距、列表缩进、代码圆角和链接下划线偏移都从这里取。
|
|
112
|
+
- 表单用 `--mg-form-*`:字段、标签、帮助文案和错误提示的间距不要各页面自定。
|
|
113
|
+
- 控件配套用 `--mg-control-text-* / --mg-control-line-* / --mg-control-icon-* / --mg-control-gap`,按钮、输入、下拉、筛选项不要各自定义字号、图标和图文间距。
|
|
114
|
+
- Dropdown / Popover / Tooltip / Dialog / Sheet 用 `--mg-popover-* / --mg-tooltip-* / --mg-dialog-* / --mg-sheet-*`,保持浮层内距、圆角、遮罩、尺寸和触发距离一致。
|
|
115
|
+
- 表格 / 数据列表用 `--mg-table-*`:表头高度、行高密度、单元格内距、hover / selected 底色从这里取。
|
|
116
|
+
- 空态和加载态用 `--mg-empty-* / --mg-skeleton-*`,避免插图、骨架条高度在不同页面各写一套。
|
|
117
|
+
- toast / 通知用 `--mg-toast-*`:宽度、内距、圆角、阴影、标题/描述文字、四种图标色、位置 offset、最大可见数和时长都从 token 取。
|
|
118
|
+
- 分段控件 / pills tabs 用 `--mg-segmented-*`:外壳、item 高度、选中底色、文字和阴影统一,不要在不同页面各自做一套胶囊。
|
|
119
|
+
- 单选卡片选中态用 `--mg-select-*`:底色是 `--mg-select-bg`(由 `--mg-select-bg-from` → `--mg-select-bg-to` 合成的渐变),描边用 `--mg-select-border`。深色档把品牌色占比由 12% 提到 26%,不要自己叠半透明品牌色。
|
|
120
|
+
- 模型体验聊天区用 `--mg-chat-*`:空态球尺寸、球与标题距离、消息间距、输入框高度、输入框外距和示例卡间距都在这里调。
|
|
121
|
+
- 进度条 / 用量拆分用 `--mg-progress-*`:track、bar、glow、badge 背景和边框都走 variant token,不在组件里写渐变。
|
|
122
|
+
- 在线状态点 / 成功类头像用 `--mg-status-* / --mg-avatar-success-bg`,不要在页面里写 emerald 色。
|
|
123
|
+
- 头像用 `--mg-avatar-size-* / --mg-avatar-text-* / --mg-avatar-radius`,状态点用 `--mg-avatar-status-offset` 与 `--mg-status-dot-size-*`。
|
|
55
124
|
|
|
56
125
|
## 产品市场页
|
|
57
126
|
|
|
@@ -59,10 +128,12 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
59
128
|
|
|
60
129
|
- **官网内容卡**:`--mg-radius-card`、`--mg-space-card-pad`、`--mg-shadow-card`,用于专题、能力介绍和落地页内容。
|
|
61
130
|
- **高密度 tile**:`--mg-tile-*`,用于模型卡、筛选栏、目录列表等可扫描、可点击的信息块;hover 只使用 `--mg-tile-border-hover` 与 `--mg-tile-shadow-hover`。
|
|
131
|
+
- **卡片内部版式**:标题、摘要、meta、kicker 和行间距用 `--mg-card-title-* / --mg-card-subtitle-* / --mg-card-meta-* / --mg-card-row-gap`,不要在每张业务卡里重新选字号。
|
|
62
132
|
- **工具栏**:输入、搜索和排序使用 `--mg-control-*`;默认高 `--mg-control-height`,需要承担搜索主入口时才用 `--mg-control-height-lg`。聚焦态统一 `box-shadow: var(--mg-focus-ring)`。
|
|
63
133
|
- **市场页标题**:`--mg-text-market-title` 只用于模型目录等市场型产品页;官网营销页继续使用 `--mg-text-h1` / `--mg-text-hero`,控制台普通页面继续使用其页面标题档。
|
|
64
134
|
- **图片 Banner**:业务侧必须提供真实图片,图片铺满容器;文字可读性只叠加 `--mg-media-panel-overlay`。无图片时不伪造渐变 Banner,应隐藏该推荐位或由产品提供兜底素材。
|
|
65
135
|
- **图片上的操作**:文字使用 `--mg-media-text` / `--mg-media-text-muted`,主操作使用 `--mg-media-action-*`。不要在图片上继续使用普通品牌实底按钮,避免与背景竞争。
|
|
136
|
+
- **媒体/精选卡片上的标签**:普通模型类型标签用 `--mg-modality-*`;深色图片上的类型标签和指标 chip 用 `--mg-modality-*-featured-* / --mg-featured-chip-*`,不要直接写白色透明度。
|
|
66
137
|
|
|
67
138
|
## 图标
|
|
68
139
|
|
|
@@ -74,9 +145,12 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
74
145
|
|
|
75
146
|
## 层级 / 焦点 / 动效
|
|
76
147
|
|
|
77
|
-
- 浮层只用 `--mg-z-*`(
|
|
148
|
+
- 浮层只用 `--mg-z-*`(base→devtool 单调递增),别手写魔数 z-index;组件可直接用 `.mg-layer-*` 工具类。
|
|
78
149
|
- 可聚焦元素 `:focus-visible` 用 `box-shadow: var(--mg-focus-ring)`。
|
|
79
150
|
- 过渡时长用 `--mg-duration-*` + 缓动 `--mg-ease-*`;避免弹跳/橡皮筋等花哨曲线。
|
|
151
|
+
- 进场 / 出场距离和缩放用 `--mg-motion-enter-* / --mg-motion-exit-*`;骨架屏、注意力提示和错峰进场用 `--mg-motion-skeleton-duration / --mg-motion-attention-duration / --mg-motion-stagger-gap`。
|
|
152
|
+
- 交互四态用 `--mg-state-*`:hover、pressed、disabled、selected 必须从 token 取状态底色/边框/缩放/透明度。
|
|
153
|
+
- hover 阴影和位移用 `--mg-shadow-hover-* / --mg-hover-y-*`,避免同一类卡片 hover 高度不一致。
|
|
80
154
|
|
|
81
155
|
## Do / Don't 速查
|
|
82
156
|
|
package/package.json
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "modelgo-design-tokens",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "ModelGo 四端统一设计 token(CSS 变量,框架无关):品牌色阶 / 字体 / 字阶 / 圆角 / 间距 / 按钮。",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"scripts": {
|
|
8
|
+
"check:closure": "node scripts/check-token-closure.mjs",
|
|
9
|
+
"check:contract": "node scripts/check-token-contract.mjs",
|
|
10
|
+
"check:contrast": "node scripts/check-token-contrast.mjs",
|
|
11
|
+
"check:diff": "node scripts/diff-token-values.mjs",
|
|
12
|
+
"check:usage": "node scripts/check-token-usage.mjs",
|
|
8
13
|
"preview": "node scripts/preview.mjs",
|
|
9
14
|
"preview:deploy": "node scripts/preview-deploy.mjs",
|
|
10
15
|
"release": "node scripts/release.mjs",
|
|
@@ -19,7 +24,12 @@
|
|
|
19
24
|
},
|
|
20
25
|
"files": [
|
|
21
26
|
"tokens.css",
|
|
22
|
-
"USAGE.md"
|
|
27
|
+
"USAGE.md",
|
|
28
|
+
"TOKEN-GOVERNANCE.md",
|
|
29
|
+
"token-contract.json",
|
|
30
|
+
"CHANGELOG.md",
|
|
31
|
+
"scripts/check-token-usage.mjs",
|
|
32
|
+
"scripts/check-token-contract.mjs"
|
|
23
33
|
],
|
|
24
34
|
"keywords": [
|
|
25
35
|
"modelgo",
|