modelgo-design-tokens 0.9.0 → 0.11.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 +298 -0
- package/README.md +11 -4
- package/TOKEN-GOVERNANCE.md +84 -0
- package/USAGE.md +78 -0
- package/base.css +597 -0
- package/console.css +829 -0
- package/package.json +16 -2
- package/scripts/check-token-contract.mjs +64 -0
- package/token-contract.json +18 -0
- package/tokens.css +178 -118
- package/website.css +46 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,304 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **Token 分层产物:`base.css` / `console.css` / `website.css`**(241 / 434 / 4 个 token)。
|
|
8
|
+
消费方按需只引自己那层:控制台引 `base + console`,官网引 `base + website`;继续引全量
|
|
9
|
+
`tokens.css` 的行为与 0.10.0 完全一致,**不是 breaking change**。
|
|
10
|
+
- 三份是 `tokens.css` 的**投影,不是第二真源**。改值仍然只改 `tokens.css`(走预览站),
|
|
11
|
+
再 `npm run split` 重新生成。之所以不把真源拆成三份:本仓改值入口是预览站
|
|
12
|
+
`/api/save` 直接写回 `tokens.css`,四道门禁也全部扫它,拆真源要把这些全改一遍,
|
|
13
|
+
收益却只是消费方少引几个 token —— 不值得。
|
|
14
|
+
- 归属按 **token 名**判定(`token-layers.json`,本关唯一人工输入),不按它在
|
|
15
|
+
`tokens.css` 里的物理位置:物理位置只是作者组织文件的方式,同一个
|
|
16
|
+
`[data-theme='dark']` 块里可能混着不同层的 token;而分层要求同一个 token 的
|
|
17
|
+
**所有档(`:root` / dark / market)必须落在同一层**,否则只引 base 的消费方会缺档。
|
|
18
|
+
- 新增两道门禁,均已接进 `release.mjs` 预检:`check:layers-sync`(产物与 `tokens.css`
|
|
19
|
+
是否同步,过期直接拦住发版)、`check:layers`(无跨层重复 / 引用方向单向 / 档位完整 /
|
|
20
|
+
`base` 与 `base+console`、`base+website` 各自自闭合)。产物过期的故障形态是**静默的**
|
|
21
|
+
——消费方拿到旧值且不报错,同悬空 var,所以必须机器拦。
|
|
22
|
+
- ⚠️ **不能只引 `console.css` 不引 `base.css`**:console 层大量 token 是
|
|
23
|
+
`var(--mg-brand-base)` 这类对 base 的引用,缺 base 即悬空 var → 整条声明静默失效。
|
|
24
|
+
- **解决的真问题**:消费方为拿到派生层,历史上会把库的整份 token 抄进本地做转发
|
|
25
|
+
(console-web 抄了 337 个),于是库改值被本地重复声明压死、每次升级都要重复一遍撤除
|
|
26
|
+
动作(见下方 0.10.0 与 qa#615、qa#611 ④)。按需只引一层后,抄整份的动机就消失了。
|
|
27
|
+
|
|
28
|
+
- **对比度门禁(关卡 4)**:`scripts/check-token-contrast.mjs` + `contrast-contract.json`(语义配对表)
|
|
29
|
+
+ `contrast-baseline.json`(存量快照)。解析 `tokens.css` 的 `var()` 链与 `color-mix()`,
|
|
30
|
+
在 `market × theme` 全矩阵下算 WCAG 2.1 对比度。接在三处:`pre-commit-all.sh`、
|
|
31
|
+
`release.mjs` 预检、`preview.mjs` 的 `/api/save`(保存那一刻就拦,`blocked:'contrast'`)。
|
|
32
|
+
新增 `pnpm check:contrast`(`--all` 看全量,`--update-baseline` 刷新快照)。
|
|
33
|
+
- 补的是现有三关的空白:自闭合 / 契约 / 改值数量查的都是引用完整性与改动规模,
|
|
34
|
+
没有一关问「改出来的颜色还能不能读」。预览站能让设计同学不碰代码写回真源,
|
|
35
|
+
同样也能一路顺畅地把正文色拖到 3.9:1,四端一起降标且全程零提示。
|
|
36
|
+
- **只拦「新增」与「恶化」**,存量原样不达标不阻断(沿用本仓「机器能判死的才阻断」)。
|
|
37
|
+
首次接入记录 25 项存量,见 `contrast-baseline.json`。
|
|
38
|
+
- 半透明色(`color-mix(..., transparent)`)按 alpha 合成到页面根底色计算,是个**假设**——
|
|
39
|
+
真实叠在卡片/弹窗上会不同,精确值仍靠消费方浏览器态验证(axe / Lighthouse)。
|
|
40
|
+
- 交叉验证:本脚本独立算出「浅色 10 项 Badge 全 AAA、深色四个语义 `-text` 与 audio 达 AA 未达 AAA」,
|
|
41
|
+
与 qa#614 人工逐项实测的结论一致(绝对值差 ~0.7,因该单在真实渲染环境量、含玻璃层叠加)。
|
|
42
|
+
|
|
43
|
+
### Fixed
|
|
44
|
+
|
|
45
|
+
- **对比度门禁在含空格路径下静默空转**。`isMain` 用 `new URL(import.meta.url).pathname` 判定,
|
|
46
|
+
而 `pathname` 不做百分号解码:仓库路径含空格或非 ASCII 时得到 `.../model%20go/...`,
|
|
47
|
+
与 `process.argv[1]` 的解码形式永不相等 → `isMain` 恒为 false → **主流程从不执行,
|
|
48
|
+
以退出码 0 冒充「通过」**。该关已接在 pre-commit、`release.mjs` 预检、预览站 `/api/save`
|
|
49
|
+
三处,等于三道口子一起放空。改用 `fileURLToPath`(本仓其余脚本用的就是这个写法)。
|
|
50
|
+
修后首次真跑:96 组合 · 达标 74 · 不达标 22。
|
|
51
|
+
|
|
52
|
+
### 存量已清零(原 25 项)
|
|
53
|
+
|
|
54
|
+
首次接入记录的 25 项存量(去重后 22 项组合)**已在本轮全部改到达标**,
|
|
55
|
+
`contrast-baseline.json` 已用 `--update-baseline` 收口为空。
|
|
56
|
+
当前 **96 组合 · 达标 96 · 不达标 0**。逐项处理见 0.10.0 的 Changed:
|
|
57
|
+
主按钮白字、浅色文字梯、深色 `--mg-text-3`、深色四个语义 `-text` 与 `audio`。
|
|
58
|
+
|
|
59
|
+
`--mg-text-3` 的阈值已定为 **3**(原 `todo` 已结):定位是极弱标注、不承载必读信息。
|
|
60
|
+
按 4.5 判会把它压到与 `--mg-text-2` 只差 1.44 倍、两级分不出,且 `t3→t4` 落差反而
|
|
61
|
+
变成全梯最大,节奏是坏的。判定依据与附带约束(不得用 `text-3` 承载必读信息)
|
|
62
|
+
写在 `contrast-contract.json` 该条的 `note`。
|
|
63
|
+
|
|
64
|
+
### 配对表选 token 的一个坑(已记入豁免依据)
|
|
65
|
+
|
|
66
|
+
首版配对表把 `--mg-success / -warning / -error / -info` 当状态文字色判,产出 4 项假阳性——
|
|
67
|
+
它们是**填充级**语义色(进度条/图标/描边),当文字用的是 `-text` 变体,而后者已由 qa#614 修到 AAA。
|
|
68
|
+
配对表现按「`-text` on `-bg` 成套」配,填充色进 `exempt` 并写明这段依据。
|
|
69
|
+
|
|
70
|
+
## 0.10.0
|
|
71
|
+
|
|
72
|
+
设计依据:[qa#611](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/611)(四项定案,UI 侧 2026-08-17 / 08-18 逐项拍板)
|
|
73
|
+
与 [qa#613](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/613)(浅色阴影并入 sm/md/lg 体系,2026-08-18 定案)。
|
|
74
|
+
本轮只落值与规格,不改任何消费方代码。
|
|
75
|
+
|
|
76
|
+
### ⚠ BREAKING CHANGES
|
|
77
|
+
|
|
78
|
+
- **移除 `[data-theme='dark-showcase']`**(3 个独有块,以及共享选择器上的 `dark-showcase` 分支)。
|
|
79
|
+
它从未在真实产品里生效过——控制台的 `applyTheme` 只设 `data-theme="dark"`,所以库的这套深色档等于死代码。
|
|
80
|
+
仍挂 `dark-showcase` 的页面会**掉回浅色**(该值现在不匹配任何规则),必须改用 `data-theme="dark"`。
|
|
81
|
+
- **移除 `--mg-control-px-md`**。它只是 `--mg-control-pad-x-md` 的历史短名别名;
|
|
82
|
+
留着会让「md 档到底是 16 还是 20」这个分叉多一个入口。
|
|
83
|
+
其余短名 `--mg-control-px-{xs,sm,lg,xl}` 保留为迁移别名,不受影响。
|
|
84
|
+
|
|
85
|
+
### Removed
|
|
86
|
+
|
|
87
|
+
- **移除 Tailwind v4 适配层**:删掉 `tailwind.css`(`@theme inline` 入口)与 `token-contract.json`
|
|
88
|
+
的 `tailwind.requiredMappings` 契约,`check:contract` 不再校验框架映射。
|
|
89
|
+
**不是破坏性变更** —— 该文件是本轮新加的、从未发布,也没有任何消费方 import 过。
|
|
90
|
+
移除理由:框架适配层反向约束了设计真源。qa#613 里出现过
|
|
91
|
+
「`--mg-shadow-card` 因为是 Tailwind 必需映射所以只能改值不能删」——
|
|
92
|
+
一个框架映射决定了一个设计 token 的生死,方向反了。本包回到只出 CSS 自定义属性、
|
|
93
|
+
完全框架无关;用 Tailwind v4 的端在自己仓里写约 20 行 `@theme inline` 映射,
|
|
94
|
+
映射哪些、叫什么由该端自己定。
|
|
95
|
+
(另:5 个消费方里只有 2 个能用 v4 语法,controller-web 仍在 v3,global-web / doc-web 不用 Tailwind。)
|
|
96
|
+
|
|
97
|
+
### Added
|
|
98
|
+
|
|
99
|
+
- `--mg-shadow-sm` / `--mg-shadow-md`:补齐分层阴影的低两档。
|
|
100
|
+
浅色采纳控制台现行 `--shadow-sm/md` 的值为库的设计值;深色指向库内已有的同值 token
|
|
101
|
+
(`--mg-shadow-card` / `--mg-shadow-card-hover`),不重复造值。
|
|
102
|
+
至此 `--mg-shadow-*` 与控制台 `--shadow-*` 不再是「两套值打架」,而是同一套体系。
|
|
103
|
+
- `[data-theme='dark']` 补齐 4 个分类色前景,取控制台线上已验证的深色档:
|
|
104
|
+
|
|
105
|
+
```css
|
|
106
|
+
--mg-modality-image-fg: #c4b5fd;
|
|
107
|
+
--mg-modality-video-fg: #fed7aa;
|
|
108
|
+
--mg-modality-embedding-fg: #fde68a;
|
|
109
|
+
--mg-modality-reranker-fg: var(--mg-text-2);
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
这 4 个此前只在 `dark-showcase` 块里有深色档,深色态实际回落 `:root` 的浅色值。
|
|
113
|
+
控制台因为本地 `src/styles/tokens.css` 有一份兜底才没暴露;没有本地兜底的官网会直接拿到浅色。
|
|
114
|
+
- `TOKEN-GOVERNANCE.md`:token 工程契约的文字真源——正式深色只认 `data-theme="dark"`、
|
|
115
|
+
命名唯一性、派生 token 的指向方向、层级与透明度、以及「已下沉未接入」token 的定位。
|
|
116
|
+
- `token-contract.json` + `scripts/check-token-contract.mjs`:把上述契约变成可执行校验,
|
|
117
|
+
已纳入 pre-commit 门禁与发布预检。
|
|
118
|
+
- 文档补齐:`USAGE.md` 新增「阴影」章节(档位真源 `sm/md/lg` 与四个语义别名的指向关系、
|
|
119
|
+
深浅两套的差异),并补 `--mg-select-*`、`--mg-header-bg` 条目;`README.md` 的「Token 分类」
|
|
120
|
+
表格补「阴影」一组。此前 `--mg-shadow-sm/md/lg` 在全部文档里零提及。
|
|
121
|
+
- 门禁增强:`npm run check:closure` 增加**环引用检测**与**级联顺序检测**(按主题 × 市场
|
|
122
|
+
四个上下文分别建图,避免把不同上下文的反向指针误判成环)。两类故障此前三道门禁全放行,
|
|
123
|
+
但都会静默失效——环让属性变初始值(`box-shadow` 直接消失),条件覆盖写在 `:root` 之前
|
|
124
|
+
则永不生效。同时接进 pre-commit 与预览站写回路径(设计同学改值时就拦,HTTP 422)。
|
|
125
|
+
- `TOKEN-GOVERNANCE.md` 新增第 5 节「阴影等派生 token 的指向方向(硬规则)」:
|
|
126
|
+
档位 token 持字面值、语义别名单向指过去;条件覆盖必须写在对应 `:root` 声明之后。
|
|
127
|
+
- `--mg-select-bg-from` / `--mg-select-bg-to` / `--mg-select-bg` / `--mg-select-border`:
|
|
128
|
+
单选卡片选中态的渐变底与描边。深色档把品牌色占比提到 26%(浅色 12%)。
|
|
129
|
+
- 浅色 `--mg-header-bg`(`var(--mg-surface-3)`):此前只有深色档有值,浅色顶栏没有规范底色可用。
|
|
130
|
+
|
|
131
|
+
### Changed
|
|
132
|
+
|
|
133
|
+
- `--mg-control-pad-x-md`:`--mg-space-5`(20px) → `--mg-space-4`(16px)(qa#611 ② 定案 16px)。
|
|
134
|
+
分叉点在规范名上而不在别名,所以改的是 `-md` 的值;`--mg-control-pad-x` 改为
|
|
135
|
+
`var(--mg-control-pad-x-md)`,与 `--mg-control-height` 同一套写法,值只在 `-md` 上维护一处。
|
|
136
|
+
- `--mg-dialog-max-height`:`min(720px, 100dvh - 128px)` → `90dvh`。
|
|
137
|
+
定案不切规范值,保持 qa#458 已验收的「封顶到视口内并内部滚动」行为。
|
|
138
|
+
- `--mg-brand-glow` / `--mg-brand-subtle`:不迁 showcase 的 28% / 10%,回落 `:root` 的 14% / 6%。
|
|
139
|
+
它们本身是 `color-mix(... var(--mg-brand-base) N%)`,跟着品牌色走;
|
|
140
|
+
迁 showcase 的值会改深色观感,与「废弃旧稿、深色不改版」的定案冲突。
|
|
141
|
+
- 深色填色规律写入治理文档:**语义色去饱和,品牌色与分类色提亮保饱和**。
|
|
142
|
+
现行 `dark` 不是一刀切莫兰迪——按莫兰迪规律反算品牌色会得到 `#4f649c` 的灰蓝,等于把品牌洗成灰。
|
|
143
|
+
- 深色 `--mg-header-bg`:`rgba(24, 24, 28, 0.85)` → `#18181c`(实色)。
|
|
144
|
+
统一顶栏在四个模式下都不透明,避免半透明底叠出深浅不一。
|
|
145
|
+
- `[data-market='global']` 浅色 `--mg-glass-canvas`:`#b7e0cd → #e7fbf2` 改为 `#f5fbf6 → #fafdfb`。
|
|
146
|
+
按 OKLab 把国内 `#edf5ff → #f4faff` 的明度与彩度平移到品牌绿色相——原值明度低 9.5 个点、
|
|
147
|
+
彩度高 3.2 倍,导致海外站整页压内容。**只影响海外站,控制台不涉及。**
|
|
148
|
+
- `--mg-control-h-sm` 改为引用 `var(--mg-control-height-sm)`(原字面量 `2rem`)。
|
|
149
|
+
纯写法收口,**生效值仍是 32px,无视觉变化**。
|
|
150
|
+
- 浅色 `--mg-shadow-card`、`--mg-shadow-elevated` 并入 `sm/md/lg` 体系
|
|
151
|
+
([qa#613](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/613) 定案):
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
--mg-shadow-card: 0 1px 3px rgba(0,0,0,.06) → var(--mg-shadow-sm)
|
|
155
|
+
--mg-shadow-elevated: 0 4px 16px rgba(0,0,0,.08) → var(--mg-shadow-md)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
原为单层纯黑旧基线,与 `sm/md/lg` 的多层蓝调 `rgba(16,24,40,*)` 不是一路。
|
|
159
|
+
`--mg-tile-shadow` 引用 `card`,跟着一起进入新体系。
|
|
160
|
+
- `--mg-dialog-shadow` 由 `--mg-shadow-elevated` 改指 `--mg-shadow-lg`。
|
|
161
|
+
弹窗是最高层浮层,不该与代码块、下拉面板共用同一档。
|
|
162
|
+
- 浅色 `--mg-card-border`:`rgba(16, 24, 40, 0.05)` → `rgba(16, 24, 40, 0.13)`。
|
|
163
|
+
|
|
164
|
+
浅色卡片在玻璃画布上糊边的原因不是阴影太弱,是**描边太弱**:卡面(白色 70% 覆膜)叠在
|
|
165
|
+
近白画布(`#edf5ff → #f4faff`)上对比度只有 **1.036**,白上加白靠面分不开,只能靠描边;
|
|
166
|
+
而原描边只有 **1.11**,不到治理文档第 5 节的 hairline ≥ 1.3。
|
|
167
|
+
**只提 alpha、不换色相**:alpha 型描边的对比度几乎不随卡面变(实色面与玻璃面都是 **1.312**),
|
|
168
|
+
而固定 hex 会漂移——中途曾试过 `--mg-glass-line`,它在玻璃卡面上有 1.31、
|
|
169
|
+
在实色 `--mg-surface-solid` 上只剩 1.19,会静默不达标。
|
|
170
|
+
同时保住控制台 2026-07-23 定的「淡边框、近乎 hairline、不要硬线框」的中性观感。
|
|
171
|
+
**深色不受影响**(`[data-theme='dark']` 的 `--mg-card-border` 仍是 `rgba(255,255,255,.08)`)。
|
|
172
|
+
- 理顺深浅两套的指针方向:`sm/md/lg` 在两个主题里都持字面值,`card`/`elevated` 单向指过去。
|
|
173
|
+
此前浅色 `card→sm`、深色 `sm→card` 方向相反,深色 `card` 一旦也改成指 `sm` 就会成循环引用。
|
|
174
|
+
- **行为变化**:深色 `--mg-shadow-elevated` 由 lg 级降为 md 级(与浅色同档)。
|
|
175
|
+
库内已无消费点(`--mg-dialog-shadow` 已改指 `lg`,而深色 `lg` 恰好等于原深色 `elevated`,
|
|
176
|
+
所以弹窗投影不变);三个官网锁 `^0.6.x` 不会自动获取。
|
|
177
|
+
- **浅色标签文字色达 WCAG AAA**([qa#614](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/614) 定口径 7:1)。
|
|
178
|
+
标签字号 `--mg-text-xs` 12px 属 WCAG 小字,改前 10 项**无一达 AA(4.5)**,最差 1.77:
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
--mg-success-text var(--mg-success) 2.08 → #065641 7.12
|
|
182
|
+
--mg-warning-text var(--mg-warning) 1.77 → #78350f 7.50
|
|
183
|
+
--mg-error-text var(--mg-error) 3.01 → #8f1e1d 7.08
|
|
184
|
+
--mg-info-text var(--mg-info) 2.99 → #1e40af 7.09 blue-800
|
|
185
|
+
--mg-modality-image-fg #7c3aed 4.51 → #5b21b6 7.10 violet-800
|
|
186
|
+
--mg-modality-video-fg #ea580c 2.89 → #7c2d12 7.61
|
|
187
|
+
--mg-modality-embedding-fg #a16207 4.10 → #713f12 7.22
|
|
188
|
+
--mg-modality-reranker-fg var(--mg-text-2) 4.01 → var(--mg-text-1) 13.57
|
|
189
|
+
--mg-modality-text-fg 国内 #223de5 5.80 → #3730a3 7.87 indigo-800
|
|
190
|
+
--mg-modality-text-fg 海外 #0F9F59 2.81 → #065641 7.14
|
|
191
|
+
--mg-modality-audio-fg 跟 --mg-success-text 走,未单独改 2.08 → 7.12
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
根因是「`-text` 变体直接别名填充级语义色」:`--mg-success-text` 原为 `var(--mg-success)`,
|
|
195
|
+
填充色当文字色在浅底上读不出来,warning / error / info 全是同一写法。修上游即连带修掉
|
|
196
|
+
`audio`(它就是 `var(--mg-success-text)`),不新造 token 名。
|
|
197
|
+
**取值规则是「各色相取刚过 7 的最浅值」,不是「统一某个调色板档号」**——
|
|
198
|
+
同档号在不同色相上对比度差很远(violet-800 是 7.10,amber-800 只有 5.86),
|
|
199
|
+
该统一的是目标对比度而非档号。能落在调色板整档的就用整档(info→blue-800、
|
|
200
|
+
image→violet-800、text→indigo-800),其余取刚过 7 的最浅值,尽量少改观感。
|
|
201
|
+
- 深色 `--mg-modality-text-fg` 补为 `var(--mg-brand-light)`。
|
|
202
|
+
原先无深色覆盖、兜底到 `var(--mg-brand-base)`,实测国内 4.37 / 海外 4.19,**连 AA 都不到**
|
|
203
|
+
——既有缺口,非本轮引入。改后国内 9.23 / 海外 11.4 双 AAA,仍是品牌派生、自动跟市场切色相。
|
|
204
|
+
- **深色四个语义 `-text` 提到 AAA,保莫兰迪、只提亮**:
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
--mg-success-text #8fae9b 5.42 → #b0c6b8 莫兰迪混白 30% 7.24
|
|
208
|
+
--mg-warning-text #cda971 5.74 → #dcc39c 莫兰迪混白 30% 7.45
|
|
209
|
+
--mg-error-text #c98b85 4.90 → #e0b9b4 莫兰迪混白 40% 7.67
|
|
210
|
+
--mg-info-text #8aa0c4 5.16 → #acbcd6 莫兰迪混白 30% 7.12
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
它们原是 `var(--mg-success)` 这类填充色本体,即莫兰迪降饱和值,达 AA 不达 AAA。
|
|
214
|
+
中途曾试过换 Tailwind 300 档,能达标但那是饱和鲜艳色,直接违背 qa#611 定的
|
|
215
|
+
「语义色去饱和,状态提示不该抢眼」——**达标不以推翻设计语言为代价**,故改为把各自的
|
|
216
|
+
莫兰迪色混白到刚过 7。填充色与描边仍是原莫兰迪值,未动。
|
|
217
|
+
`--mg-modality-audio-fg` 跟 `--mg-success-text` 走,连带达标。
|
|
218
|
+
该块与海外 `--mg-modality-text-fg` 的 `[data-market='global']` 块都写在对应 `:root` **之后**
|
|
219
|
+
(TOKEN-GOVERNANCE 第 4 节硬规则)。
|
|
220
|
+
- **浅色文字梯微调**(不是跳档):
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
--mg-text-2 gray-500 #64748b 4.26 → #5f6e84 4.64
|
|
224
|
+
--mg-text-3 gray-400 #94a3b8 2.30 → #7c8ba0 3.10
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
判定用最苛刻的面 `--mg-surface-solid`。t2 原本只差 0.24,若跳到 gray-600(6.79)
|
|
228
|
+
会把 t2/t3 的浓度差从 1.85 倍挤到 1.44 倍、两级几乎分不出,且 t3→t4 落差反而变成
|
|
229
|
+
全梯最大,节奏是坏的。故各取「四个面都能过阈值的最浅值」,改后节奏
|
|
230
|
+
3.11 / 1.50 / 2.33,接近原本的 3.38 / 1.85 / 1.73。
|
|
231
|
+
`--mg-text-3` 的阈值按「极弱标注、不承载必读信息」定为 **3**(见 `contrast-contract.json`
|
|
232
|
+
该条 note)。**约束:不得用 `--mg-text-3` 承载必读信息,需要必读就用 `--mg-text-2`。**
|
|
233
|
+
`--mg-text-4` 是禁用/极弱档,同样不判对比度,未动。
|
|
234
|
+
- 深色 `--mg-text-3`:`#a1a1aa` → `#b4b4bd`(在 `--mg-surface-3` 上由 4.32 提到 5.38)。
|
|
235
|
+
- **主按钮白字达 4.5**。实测四个上下文只有浅色国内达标:
|
|
236
|
+
|
|
237
|
+
```
|
|
238
|
+
浅色·国内 #223de5 7.32 ✓ 未改
|
|
239
|
+
浅色·海外 #0F9F59 3.43 → 5.27
|
|
240
|
+
深色·国内 #5b8def 3.23 → 4.99
|
|
241
|
+
深色·海外 #0F9F59 3.43 → 5.27
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
加深的是**按钮填充**而非 `--mg-brand-base`:品牌色是识别符号,且深色提亮(qa#611 定案)
|
|
245
|
+
与海外绿 `#0F9F59`(`bca4027` 设计确认)都是已定的值,不因按钮可读性反过来改品牌。
|
|
246
|
+
故在 `[data-market='global']` 与 `[data-theme='dark']` 各加一块,同公式
|
|
247
|
+
`color-mix(in oklab, <brand> 78%, #000)`。hover/active 一并加深——深色海外档
|
|
248
|
+
`--mg-brand-deep` 是 `#34a52a`,比 base 更浅,原样白字只有 3.20,比默认态还差。
|
|
249
|
+
`--mg-btn-primary-text` 改为引用 `--mg-on-primary`(两者原本同为 `#ffffff`,生效值不变)。
|
|
250
|
+
- `--mg-warning`:`#f59e0b` → `#FFA000`。原注释是「待设计确认(基线未定义)」,
|
|
251
|
+
即库自己标的占位值;`#FFA000` 是控制台线上实际在跑的值,采纳它等于**零视觉变化**,
|
|
252
|
+
反过来选 `#f59e0b` 才会改动线上警告色。两个值都不影响 `--mg-warning-text` 达 AAA
|
|
253
|
+
(7.50 / 7.56)。下游 `-bg` / `-bg-hover` / `-border` / `progress-warning-*` 均为派生,自动跟随。
|
|
254
|
+
|
|
255
|
+
### Migration Notes
|
|
256
|
+
|
|
257
|
+
> ⚠️ **升级依赖本身不会让本轮定案生效。** 消费方若在自己的 CSS 里重复声明了同名 `--mg-*`
|
|
258
|
+
> 且后加载,本地值会盖住库的值。以 modelgo-console-web 为例:它的
|
|
259
|
+
> `src/index.css` 先 import 库、再 import 本地 `src/styles/tokens.css`,
|
|
260
|
+
> 本地重复声明了库中 **383 个** `--mg-*`——其中 `--mg-control-px-md: var(--mg-space-5)`(20px)
|
|
261
|
+
> 会让本轮 ② 定的 16px 完全不生效。要让定案落地,消费方必须**删掉对应的本地声明**,
|
|
262
|
+
> 而不只是把依赖升到 `^0.10.0`。
|
|
263
|
+
|
|
264
|
+
- 挂 `data-theme="dark-showcase"` 的地方改成 `data-theme="dark"`,否则整页掉回浅色。
|
|
265
|
+
- 用 `--mg-control-px-md` 的地方改 `--mg-control-pad-x-md`(或短名 `--mg-control-pad-x`)。
|
|
266
|
+
注意这不只是改名:**md 档的生效值同时从 20px 变成 16px**。
|
|
267
|
+
- 接 Dialog 宽度时去掉 `w-full`。宽度不配固定档位,由内容在
|
|
268
|
+
`--mg-dialog-min-width`(360px) 与 `--mg-dialog-max-width`(720px) 之间自适应——
|
|
269
|
+
`w-full` 才是「所有弹窗一律撑到 max-width」的根因。
|
|
270
|
+
- 升级依赖声明时注意:**`^0.9.0` 不会自动升到 0.10.0**(caret 对 `0.x` 不跨 minor),
|
|
271
|
+
需要显式改成 `^0.10.0`。
|
|
272
|
+
- 升到 0.10.0 之后,消费方需撤掉本地重复声明。以 console-web 为例,
|
|
273
|
+
与本轮改动相关的共 **57 处 / 43 个 token**,分四类:
|
|
274
|
+
- **值不同(15 处)**:`success/warning/error/info-text`、`modality-*-fg`、`btn-primary-text` 等,
|
|
275
|
+
不删则本轮改动全部无效。
|
|
276
|
+
- **值相同但仍须删(26 处)**:如 `--mg-btn-primary-bg: var(--mg-brand-base)` 与库一字不差,
|
|
277
|
+
但它在本地 `:root`、后加载,会**压掉库里 `[data-theme]` / `[data-market]` 的条件覆盖**
|
|
278
|
+
(两者特异性同为 `(0,1,0)`)。判据:只要本地重复声明了某 token,库对它的所有条件覆盖即失效。
|
|
279
|
+
- **必须成对删(20 处)**⚠️:console-web 的 `--mg-control-h-*` / `--mg-control-height-*` 与
|
|
280
|
+
`--mg-control-px-*` / `--mg-control-pad-x-*` **指向方向与库相反**(本地是规范名→旧名,
|
|
281
|
+
库是旧名→规范名)。只删一半会让两者互相引用**成环**,CSS 判 cyclic var 为
|
|
282
|
+
invalid at computed-value time,控件高度/内边距**静默消失**。必须整段一起删。
|
|
283
|
+
注意 `check:closure` 的环检测只扫本仓、不扫消费方,抓不到这个。
|
|
284
|
+
- **顺序**:库先发版、消费方再撤,中间不会出现两边都没值的窗口。
|
|
285
|
+
|
|
286
|
+
### 已知遗留
|
|
287
|
+
|
|
288
|
+
- ~~浅色 `--mg-shadow-card` / `--mg-shadow-elevated` 仍是旧基线单层值~~ ——
|
|
289
|
+
已由 [qa#613](https://gitlab.ops.modelgo.com/qa/ai-quality-platform/-/issues/613) 定案,
|
|
290
|
+
在本版一并解决(见上方 Changed)。`--mg-shadow-card` 保留(作为既有语义位的别名)。
|
|
291
|
+
- `--mg-shadow-hover-sm/md/lg` 三档已核对与控制台无分叉(深色同名同值、浅色仅库内有),
|
|
292
|
+
本轮未动。
|
|
293
|
+
- ~~**深色标签文字色达 AA 未达 AAA**~~ —— UI 侧 2026-08-18 追加要求「都改到符合标准」后,
|
|
294
|
+
已在本版一并提到 AAA(保莫兰迪、只提亮,见上方 Changed)。
|
|
295
|
+
- **深色海外档 `--mg-brand-deep`(`#34a52a`)比 `--mg-brand-base`(`#0F9F59`)更浅**,
|
|
296
|
+
「deep 比 base 浅」是值倒挂。因此主按钮 hover 在该上下文比默认态更浅,
|
|
297
|
+
与其余三个上下文方向相反(对比度仍达标 4.95,纯观感问题)。本轮未动,建议另开单。
|
|
298
|
+
|
|
299
|
+
## 0.9.0
|
|
300
|
+
|
|
301
|
+
> 本节原标题为 `Unreleased`;其内容(205 个语义 token 的合流)已随 **0.9.0** 发布,故正名。
|
|
302
|
+
|
|
5
303
|
> **合流状态(2026-08-17 更新)**:本节源自 `preview-token-demo-20260813` 分支,
|
|
6
304
|
> 已与 main 上 0.7.0–0.8.1 的语义 token 下沉合流完成,**205 个新变量已并入**。
|
|
7
305
|
>
|
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
|
@@ -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`)。
|
|
@@ -9,6 +45,8 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
9
45
|
- **SSOT 只出 `--mg-` 前缀。** 各端历史遗留的无前缀别名(如控制台的 `--chart-cat-*`)由消费方自己维护,不下沉到本包,别在新端引用。
|
|
10
46
|
- 发布前跑 `npm run check:usage`,会检查控制台里常见的散写状态色、危险色、遮罩和全局层级。
|
|
11
47
|
- 发布前还要跑 `npm run check:closure`(已接进 `release.mjs` 预检,不过也可手动跑):确保包内每个 `var(--x)` 都有声明。悬空引用会让**整条 CSS 声明静默失效**——不报错、不崩溃,样式就是悄悄没了。2026-08-14 的 0.7.0/0.8.0 正是这样带病发出去的。
|
|
48
|
+
- 发布前跑 `npm run check:contract`:校验正式主题与兼容别名没有分叉。完整的工程边界见 [TOKEN-GOVERNANCE.md](./TOKEN-GOVERNANCE.md)。
|
|
49
|
+
- **本包框架无关**:只出 CSS 自定义属性,不提供 Tailwind / UnoCSS 等框架适配层。用 Tailwind v4 的端在自己仓里写 `@theme inline` 映射(约 20 行),映射哪些、叫什么由该端自己定。
|
|
12
50
|
- 改动 token 值后跑 `npm run check:diff -- <基准文件> tokens.css` 拿变更清单:它把 `var()` 递归展开到底再比对,能看出「值被悄悄改掉」这类 diff 里看不出来的问题。
|
|
13
51
|
|
|
14
52
|
## 颜色
|
|
@@ -25,6 +63,28 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
25
63
|
| 收藏 / 喜欢 | `--mg-favorite / --mg-favorite-bg-hover` | 写死玫红 |
|
|
26
64
|
| 图表多序列分类 | `--mg-chart-cat-1..6`(含 `-bg` / `-border` 衍生档) | 组件里临时挑 6 个颜色 |
|
|
27
65
|
|
|
66
|
+
### 对比度(改色前必读)
|
|
67
|
+
|
|
68
|
+
改任何色值前先知道这条**硬约束**:颜色不是自由变量,它得让人读得到。判据是 WCAG 2.1 AA 对比度:
|
|
69
|
+
|
|
70
|
+
| 用途 | 最低对比度 |
|
|
71
|
+
|---|---|
|
|
72
|
+
| 正文文字 | **4.5:1**(AA) |
|
|
73
|
+
| 标签 / Badge(`-text` on `-bg` 成套) | **7:1**(AAA,qa#614 定案;字号 12px 属小字) |
|
|
74
|
+
| 大字号(≥24px,或 ≥18.7px 加粗) | **3:1** |
|
|
75
|
+
| 理解 UI 所必需的图形与边界(如校验态描边) | **3:1** |
|
|
76
|
+
| 禁用态、纯装饰分隔线 | 豁免(WCAG §1.4.3 / §1.4.11) |
|
|
77
|
+
|
|
78
|
+
**别把填充色当文字色**:`--mg-success / -warning / -error / -info` 是填充级(进度条/图标/描边),
|
|
79
|
+
文字要用 `-text` 变体。两者阈值和取值完全不同 —— 填充色在浅底上当文字用普遍读不出来。
|
|
80
|
+
|
|
81
|
+
- 想保住色相又达标:**只调亮度** —— 浅底压暗、深底提亮。调饱和度几乎无效,对比度只看亮度。
|
|
82
|
+
- 门禁会自动算:`pnpm check:contrast`(全量 `--all`)。它在**提交期**、**发版预检**、**预览站保存那一刻**三处都跑。
|
|
83
|
+
- 判据不是写死在脚本里的,而是 `contrast-contract.json`(哪个前景配哪个背景、按什么标准判、豁免依据)。
|
|
84
|
+
觉得某项判得不对,改那张表并写清依据,**不要绕过数字**。
|
|
85
|
+
- 存量不达标项记在 `contrast-baseline.json`,只拦「新增」和「变得更差」。修好一项后跑
|
|
86
|
+
`pnpm check:contrast --update-baseline` 收口,防止它被再改坏。
|
|
87
|
+
|
|
28
88
|
## 双品牌色 / 市场
|
|
29
89
|
|
|
30
90
|
- 默认 = 国内 indigo;根元素加 `data-market="global"` → 全站品牌色切 emerald。
|
|
@@ -34,8 +94,10 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
34
94
|
## 主题(深浅)
|
|
35
95
|
|
|
36
96
|
- 语义 token 随 `data-theme="dark"` 自动翻转——**写组件时不要为深色单独硬编码颜色**,用语义 token 就对了。
|
|
97
|
+
- `data-theme="dark"` 是唯一的深色主题。曾经存在的 `data-theme="dark-showcase"` 已由 qa#611 定案废弃并于 0.10.0 移除,不要再挂这个值——它现在不匹配任何规则,会整页掉回浅色。
|
|
37
98
|
- 国内官网是纯浅色站,不挂 `data-theme`;深色组主要供控制台/app。
|
|
38
99
|
- 浅色素材(图片/插画)别直接铺到深色面上——深色用深色专用素材或压暗,详见控制台广场卡片的处理。
|
|
100
|
+
- 顶栏底色用 `--mg-header-bg`,**四个模式(浅/深 × 国内/海外)下都是实色不透明**。0.10.0 起深色档由 `rgba(24,24,28,.85)` 改为 `#18181c`,浅色档新增。不要自己给顶栏叠半透明底——半透明会随滚动内容叠出深浅不一。
|
|
39
101
|
|
|
40
102
|
## 字体 / 字阶
|
|
41
103
|
|
|
@@ -65,6 +127,21 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
65
127
|
- 危险按钮统一 `--mg-btn-danger-*`:默认底色 `#D9534F`,hover / active 不另选红色,按同色相加深生成。
|
|
66
128
|
- 普通按钮同样走成套 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`。
|
|
67
129
|
|
|
130
|
+
## 阴影
|
|
131
|
+
|
|
132
|
+
- **档位真源是 `--mg-shadow-{sm,md,lg}`**,浅色与深色各自持字面值。语义别名单向指向档位,不要反向:
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
--mg-shadow-card → --mg-shadow-sm
|
|
136
|
+
--mg-shadow-elevated → --mg-shadow-md
|
|
137
|
+
--mg-dialog-shadow → --mg-shadow-lg
|
|
138
|
+
--mg-tile-shadow → --mg-shadow-card(即 sm)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- 新写组件直接用档位名 `--mg-shadow-sm/md/lg`。`card` / `elevated` 是留给既有语义位的别名(官网内容卡等既有语义位),**不是另一套值**——0.10.0 起它们就是档位本身,别再当成"旧基线"绕开。
|
|
142
|
+
- hover 态用 `--mg-shadow-hover-{sm,md,lg}` 配 `--mg-hover-y-*`,不要把静态档位拿去当 hover 值。
|
|
143
|
+
- **深色不是浅色的加深**:浅色是多层蓝调 `rgba(16, 24, 40, *)`;深色是纯黑高不透明度,其中 `md` / `lg` 另加 `0 0 0 1px rgba(255,255,255,.04)` 勾边(`sm` 不带)。所以别自己算深色阴影,用同名 token 让主题自动翻转。
|
|
144
|
+
|
|
68
145
|
## 长文 / 表单 / 浮层 / 空态
|
|
69
146
|
|
|
70
147
|
- Markdown / 说明文档用 `--mg-prose-*`:段距、列表缩进、代码圆角和链接下划线偏移都从这里取。
|
|
@@ -75,6 +152,7 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
|
|
|
75
152
|
- 空态和加载态用 `--mg-empty-* / --mg-skeleton-*`,避免插图、骨架条高度在不同页面各写一套。
|
|
76
153
|
- toast / 通知用 `--mg-toast-*`:宽度、内距、圆角、阴影、标题/描述文字、四种图标色、位置 offset、最大可见数和时长都从 token 取。
|
|
77
154
|
- 分段控件 / pills tabs 用 `--mg-segmented-*`:外壳、item 高度、选中底色、文字和阴影统一,不要在不同页面各自做一套胶囊。
|
|
155
|
+
- 单选卡片选中态用 `--mg-select-*`:底色是 `--mg-select-bg`(由 `--mg-select-bg-from` → `--mg-select-bg-to` 合成的渐变),描边用 `--mg-select-border`。深色档把品牌色占比由 12% 提到 26%,不要自己叠半透明品牌色。
|
|
78
156
|
- 模型体验聊天区用 `--mg-chat-*`:空态球尺寸、球与标题距离、消息间距、输入框高度、输入框外距和示例卡间距都在这里调。
|
|
79
157
|
- 进度条 / 用量拆分用 `--mg-progress-*`:track、bar、glow、badge 背景和边框都走 variant token,不在组件里写渐变。
|
|
80
158
|
- 在线状态点 / 成功类头像用 `--mg-status-* / --mg-avatar-success-bg`,不要在页面里写 emerald 色。
|