modelgo-design-tokens 0.9.0 → 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 CHANGED
@@ -2,6 +2,283 @@
2
2
 
3
3
  ## Unreleased
4
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
+
5
282
  > **合流状态(2026-08-17 更新)**:本节源自 `preview-token-demo-20260813` 分支,
6
283
  > 已与 main 上 0.7.0–0.8.1 的语义 token 下沉合流完成,**205 个新变量已并入**。
7
284
  >
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 的站点(国内官网)在 `@theme` 里映射即可:
42
+ 用 Tailwind v4 的站点在**自己仓里**写 `@theme inline` 映射(本包不提供框架适配层,保持框架无关):
43
43
 
44
44
  ```css
45
- @theme {
46
- --color-brand: var(--mg-brand-base);
47
- --font-size-h1: var(--mg-text-h1);
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
@@ -9,6 +9,8 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
9
9
  - **SSOT 只出 `--mg-` 前缀。** 各端历史遗留的无前缀别名(如控制台的 `--chart-cat-*`)由消费方自己维护,不下沉到本包,别在新端引用。
10
10
  - 发布前跑 `npm run check:usage`,会检查控制台里常见的散写状态色、危险色、遮罩和全局层级。
11
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 行),映射哪些、叫什么由该端自己定。
12
14
  - 改动 token 值后跑 `npm run check:diff -- <基准文件> tokens.css` 拿变更清单:它把 `var()` 递归展开到底再比对,能看出「值被悄悄改掉」这类 diff 里看不出来的问题。
13
15
 
14
16
  ## 颜色
@@ -25,6 +27,28 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
25
27
  | 收藏 / 喜欢 | `--mg-favorite / --mg-favorite-bg-hover` | 写死玫红 |
26
28
  | 图表多序列分类 | `--mg-chart-cat-1..6`(含 `-bg` / `-border` 衍生档) | 组件里临时挑 6 个颜色 |
27
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` 收口,防止它被再改坏。
51
+
28
52
  ## 双品牌色 / 市场
29
53
 
30
54
  - 默认 = 国内 indigo;根元素加 `data-market="global"` → 全站品牌色切 emerald。
@@ -34,8 +58,10 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
34
58
  ## 主题(深浅)
35
59
 
36
60
  - 语义 token 随 `data-theme="dark"` 自动翻转——**写组件时不要为深色单独硬编码颜色**,用语义 token 就对了。
61
+ - `data-theme="dark"` 是唯一的深色主题。曾经存在的 `data-theme="dark-showcase"` 已由 qa#611 定案废弃并于 0.10.0 移除,不要再挂这个值——它现在不匹配任何规则,会整页掉回浅色。
37
62
  - 国内官网是纯浅色站,不挂 `data-theme`;深色组主要供控制台/app。
38
63
  - 浅色素材(图片/插画)别直接铺到深色面上——深色用深色专用素材或压暗,详见控制台广场卡片的处理。
64
+ - 顶栏底色用 `--mg-header-bg`,**四个模式(浅/深 × 国内/海外)下都是实色不透明**。0.10.0 起深色档由 `rgba(24,24,28,.85)` 改为 `#18181c`,浅色档新增。不要自己给顶栏叠半透明底——半透明会随滚动内容叠出深浅不一。
39
65
 
40
66
  ## 字体 / 字阶
41
67
 
@@ -65,6 +91,21 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
65
91
  - 危险按钮统一 `--mg-btn-danger-*`:默认底色 `#D9534F`,hover / active 不另选红色,按同色相加深生成。
66
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`。
67
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
+
68
109
  ## 长文 / 表单 / 浮层 / 空态
69
110
 
70
111
  - Markdown / 说明文档用 `--mg-prose-*`:段距、列表缩进、代码圆角和链接下划线偏移都从这里取。
@@ -75,6 +116,7 @@ token 解决"值统一",这页解决"用法统一"——四端照同一套规则
75
116
  - 空态和加载态用 `--mg-empty-* / --mg-skeleton-*`,避免插图、骨架条高度在不同页面各写一套。
76
117
  - toast / 通知用 `--mg-toast-*`:宽度、内距、圆角、阴影、标题/描述文字、四种图标色、位置 offset、最大可见数和时长都从 token 取。
77
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%,不要自己叠半透明品牌色。
78
120
  - 模型体验聊天区用 `--mg-chat-*`:空态球尺寸、球与标题距离、消息间距、输入框高度、输入框外距和示例卡间距都在这里调。
79
121
  - 进度条 / 用量拆分用 `--mg-progress-*`:track、bar、glow、badge 背景和边框都走 variant token,不在组件里写渐变。
80
122
  - 在线状态点 / 成功类头像用 `--mg-status-* / --mg-avatar-success-bg`,不要在页面里写 emerald 色。
package/package.json CHANGED
@@ -1,11 +1,13 @@
1
1
  {
2
2
  "name": "modelgo-design-tokens",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "ModelGo 四端统一设计 token(CSS 变量,框架无关):品牌色阶 / 字体 / 字阶 / 圆角 / 间距 / 按钮。",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "scripts": {
8
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",
9
11
  "check:diff": "node scripts/diff-token-values.mjs",
10
12
  "check:usage": "node scripts/check-token-usage.mjs",
11
13
  "preview": "node scripts/preview.mjs",
@@ -23,8 +25,11 @@
23
25
  "files": [
24
26
  "tokens.css",
25
27
  "USAGE.md",
28
+ "TOKEN-GOVERNANCE.md",
29
+ "token-contract.json",
26
30
  "CHANGELOG.md",
27
- "scripts/check-token-usage.mjs"
31
+ "scripts/check-token-usage.mjs",
32
+ "scripts/check-token-contract.mjs"
28
33
  ],
29
34
  "keywords": [
30
35
  "modelgo",
@@ -0,0 +1,64 @@
1
+ #!/usr/bin/env node
2
+ // Token 工程契约检查:防止主题选择器与兼容别名再次分叉。
3
+ // 注:Tailwind 注册契约已于 0.10.0 移除——框架适配不应反向约束设计真源的生死
4
+ // (qa#613 里 --mg-shadow-card「因为是 Tailwind 必需映射所以只能改值不能删」就是这个反向约束的后果)。
5
+ import fs from 'node:fs'
6
+ import path from 'node:path'
7
+
8
+ const rootFlag = process.argv.indexOf('--root')
9
+ const ROOT = rootFlag === -1 ? process.cwd() : path.resolve(process.argv[rootFlag + 1] || '')
10
+ const CSS_PATH = path.join(ROOT, 'tokens.css')
11
+ const CONTRACT_PATH = path.join(ROOT, 'token-contract.json')
12
+
13
+ const read = (file) => fs.readFileSync(file, 'utf8')
14
+
15
+ function declarations(css) {
16
+ const values = new Map()
17
+ for (const match of css.matchAll(/^\s*(--[\w-]+)\s*:\s*([^;]+);/gm)) {
18
+ values.set(match[1], match[2].trim())
19
+ }
20
+ return values
21
+ }
22
+
23
+ function themeValues(css) {
24
+ return new Set([...css.matchAll(/data-theme\s*=\s*['"]([^'"]+)['"]/g)].map((match) => match[1]))
25
+ }
26
+
27
+ function checkThemes(css, contract) {
28
+ const actual = themeValues(css)
29
+ const known = new Set(Object.keys(contract.themeModes))
30
+ return [...actual].filter((theme) => !known.has(theme)).map((theme) => `未登记的 data-theme: ${theme}`)
31
+ }
32
+
33
+ function checkAliases(values, contract) {
34
+ const errors = []
35
+ for (const { legacyPrefix, canonicalPrefix } of contract.deprecatedAliases) {
36
+ for (const [name, value] of values) {
37
+ if (!name.startsWith(legacyPrefix)) continue
38
+ const canonical = `${canonicalPrefix}${name.slice(legacyPrefix.length)}`
39
+ if (!values.has(canonical)) {
40
+ errors.push(`${name} 缺少规范名 ${canonical}`)
41
+ } else if (value !== `var(${canonical})`) {
42
+ errors.push(`${name} 必须直接引用 ${canonical},当前为 ${value}`)
43
+ }
44
+ }
45
+ }
46
+ return errors
47
+ }
48
+
49
+
50
+ const css = read(CSS_PATH)
51
+ const contract = JSON.parse(read(CONTRACT_PATH))
52
+ const values = declarations(css)
53
+ const errors = [
54
+ ...checkThemes(css, contract),
55
+ ...checkAliases(values, contract),
56
+ ]
57
+
58
+ if (errors.length) {
59
+ console.error(`Token contract check failed with ${errors.length} error(s):`)
60
+ for (const error of errors) console.error(`- ${error}`)
61
+ process.exit(1)
62
+ }
63
+
64
+ console.log(`Token contract check passed: ${Object.keys(contract.themeModes).length} theme modes, ${contract.deprecatedAliases.length} compatibility families.`)
@@ -0,0 +1,18 @@
1
+ {
2
+ "themeModes": {
3
+ "dark": {
4
+ "status": "production",
5
+ "purpose": "控制台、文档站、应用和官网的唯一正式深色主题"
6
+ }
7
+ },
8
+ "deprecatedAliases": [
9
+ {
10
+ "legacyPrefix": "--mg-control-h-",
11
+ "canonicalPrefix": "--mg-control-height-"
12
+ },
13
+ {
14
+ "legacyPrefix": "--mg-control-px-",
15
+ "canonicalPrefix": "--mg-control-pad-x-"
16
+ }
17
+ ]
18
+ }
package/tokens.css CHANGED
@@ -72,7 +72,8 @@
72
72
 
73
73
  /* ── 状态色 ── */
74
74
  --mg-success: #10b981; /* 基线 */
75
- --mg-warning: #f59e0b; /* 待设计确认(基线未定义) */
75
+ --mg-warning: #FFA000; /* 设计确认 2026-08-18:采纳控制台线上实际在跑的值,
76
+ 结掉「待设计确认」。--mg-warning-text 仍达 AAA(7.56)。 */
76
77
  --mg-error: #ef4444; /* 待设计确认 */
77
78
  --mg-info: #3b82f6; /* 待设计确认 */
78
79
 
@@ -258,7 +259,8 @@
258
259
  /* 紧凑档:侧栏筛选行 / 密集列表行内控件(设计 2026-08-10 拍板控件档收敛为 32/40/48 三档,
259
260
  消费方现存 28/30/34/44 等杂档一律就近归档) */
260
261
  --mg-control-height-sm: 32px;
261
- --mg-control-pad-x: var(--mg-space-4);
262
+ /* 短名指向 md 档,与 --mg-control-height 同一套写法,避免同概念两处独立赋值 */
263
+ --mg-control-pad-x: var(--mg-control-pad-x-md);
262
264
  --mg-control-pad-x-sm: var(--mg-space-3);
263
265
  --mg-control-radius: var(--mg-radius-md);
264
266
  --mg-control-bg: var(--mg-glass-surface);
@@ -306,9 +308,15 @@
306
308
 
307
309
  /* ═══════════════════════ 2) SEMANTIC 语义(引用原子,浅色默认) ═══════════════════════ */
308
310
  :root {
309
- --mg-text-1: var(--mg-gray-900); /* 主文字(基线墨色) */
310
- --mg-text-2: var(--mg-gray-500); /* 次级 */
311
- --mg-text-3: var(--mg-gray-400); /* 辅助 */
311
+ --mg-text-1: var(--mg-gray-900); /* 主文字(基线墨色)· 最苛刻面 14.42 */
312
+ /* 次级与辅助各微调到刚好达标,不跳整档 —— 跳档会压掉梯子的节奏:
313
+ t2 原 gray-500 只差 0.24(4.26 vs 4.5),换 gray-600 会直接到 6.79,
314
+ 连带把 t2/t3 的浓度差从 1.85 倍挤到 1.44 倍,两级几乎分不出。
315
+ 故各取「四个面都能过阈值的最浅值」:t2 → 4.64,t3 → 3.10。
316
+ t3 阈值按「极弱标注、不承载必读信息」定为 3(见 contrast-contract.json)。
317
+ t4 是禁用/极弱档,同样不承载必读信息,不判对比度。(qa#614 衍生) */
318
+ --mg-text-2: #5f6e84; /* 次级 · 最苛刻面 4.64(原 #64748b 为 4.26) */
319
+ --mg-text-3: #7c8ba0; /* 辅助 · 最苛刻面 3.10(原 #94a3b8 为 2.30) */
312
320
  --mg-text-4: var(--mg-gray-300); /* 禁用/极弱 */
313
321
 
314
322
  --mg-bg: #ffffff; /* 页面 纯白(国内官网现行 breeze 风:白页面 + 灰卡片) */
@@ -351,22 +359,25 @@
351
359
  值取控制台现行(console-web/src/styles/tokens.css:40-60),本段为下沉而非改设计。
352
360
  注:--mg-success-bg(10%) 与上面的 --mg-success-subtle(12%) 是两个用途,
353
361
  数字本就不同,不要图省事合并。 */
354
- --mg-success-text: var(--mg-success);
362
+ /* -text 必须比 -bg/-border 深一大截:填充级色当文字色在浅底上读不出来。
363
+ 浅色统一取各色相 900 档,12px 小字达 WCAG AAA(qa#614)。深色在后面的
364
+ [data-theme='dark'] 块里还原为各语义色本体,深色观感不变。 */
365
+ --mg-success-text: #065641; /* 刚过 7 的最浅值 · 7.12(900 档 #064e3b 为 7.96,深过头了) */
355
366
  --mg-success-bg: color-mix(in oklab, var(--mg-success) 10%, transparent);
356
367
  --mg-success-bg-hover: color-mix(in oklab, var(--mg-success) 16%, transparent);
357
368
  --mg-success-border: color-mix(in oklab, var(--mg-success) 28%, transparent);
358
369
 
359
- --mg-warning-text: var(--mg-warning);
370
+ --mg-warning-text: #78350f; /* amber-900 · 7.50 AAA(原 #f59e0b 仅 1.77,全场最差) */
360
371
  --mg-warning-bg: color-mix(in oklab, var(--mg-warning) 11%, transparent);
361
372
  --mg-warning-bg-hover: color-mix(in oklab, var(--mg-warning) 17%, transparent);
362
373
  --mg-warning-border: var(--mg-warning);
363
374
 
364
- --mg-error-text: var(--mg-error);
375
+ --mg-error-text: #8f1e1d; /* 刚过 7 的最浅值 · 7.08(900 档 #7f1d1d 为 8.01) */
365
376
  --mg-error-bg: color-mix(in oklab, var(--mg-error) 9%, transparent);
366
377
  --mg-error-bg-hover: color-mix(in oklab, var(--mg-error) 15%, transparent);
367
378
  --mg-error-border: color-mix(in oklab, var(--mg-error) 28%, transparent);
368
379
 
369
- --mg-info-text: var(--mg-info);
380
+ --mg-info-text: #1e40af; /* blue-800 · 7.09(900 档 8.42 深过头;800 恰好够,用调色板整档) */
370
381
  --mg-info-bg: color-mix(in oklab, var(--mg-info) 9%, transparent);
371
382
  --mg-info-bg-hover: color-mix(in oklab, var(--mg-info) 15%, transparent);
372
383
  --mg-info-border: color-mix(in oklab, var(--mg-info) 26%, transparent);
@@ -434,6 +445,7 @@
434
445
  --mg-glass-surface: color-mix(in oklab, var(--mg-glass-veil) 70%, transparent);
435
446
  --mg-glass-surface-strong: color-mix(in oklab, var(--mg-glass-veil) 84%, transparent);
436
447
  --mg-glass-header: color-mix(in oklab, var(--mg-glass-veil) 30%, transparent);
448
+ --mg-header-bg: var(--mg-surface-3); /* 顶栏实色底:不透明 */
437
449
  --mg-glass-line: #dadff3;
438
450
  --mg-glass-header-edge: rgba(241, 247, 255, 0.4); /* 40%:实色 2px 太硬,压到四成只留一道亮痕 */
439
451
 
@@ -452,18 +464,28 @@
452
464
 
453
465
  --mg-overlay: rgba(15, 23, 42, 0.5);
454
466
 
455
- --mg-shadow-card: 0 1px 3px rgba(0, 0, 0, 0.06); /* 基线 */
456
- --mg-shadow-card-hover: 0 8px 24px color-mix(in oklab, var(--mg-brand-base) 12%, transparent); /* 基线 */
457
- --mg-shadow-elevated: 0 4px 16px rgba(0, 0, 0, 0.08); /* 基线 */
458
- /* 分层柔和阴影(toast/浮层用,多层叠加做出悬浮感;浅色,深色在 [data-theme=dark] 覆盖) */
467
+ /* 分层柔和阴影 sm/md/lg —— 浅色阴影的唯一值定义点(多层叠加做出悬浮感,深色在 [data-theme=dark] 覆盖)
468
+ 同一基色 rgba(16,24,40) 只变 alpha;档位靠加层不靠加深;blur≈2~2.5×y;负 spread≈-blur/3 收束。
469
+ 三层分工:接触层(y1-2/alpha.04) + 扩散层(y4-8/-2~-4 spread) + 环境层(y10-20/-8~-12 spread)。
470
+ 值来自控制台现行 --shadow-sm/md/lg,qa#611 ④ 定案提升为库的值。 */
471
+ --mg-shadow-sm: 0 1px 2px rgba(16, 24, 40, 0.04), 0 1px 3px rgba(16, 24, 40, 0.05);
472
+ --mg-shadow-md: 0 1px 2px rgba(16, 24, 40, 0.04), 0 4px 10px -2px rgba(16, 24, 40, 0.06), 0 10px 24px -8px rgba(16, 24, 40, 0.08);
459
473
  --mg-shadow-lg: 0 2px 4px rgba(16, 24, 40, 0.04), 0 8px 20px -4px rgba(16, 24, 40, 0.08), 0 20px 40px -12px rgba(16, 24, 40, 0.12);
474
+
475
+ /* 语义别名单向指向档位,浅深两套同方向、同档位(qa#613 定案):
476
+ card = 卡片静置 = sm;elevated = 贴页面的浮层(代码块/下拉面板)= md。
477
+ 弹窗不走 elevated,--mg-dialog-shadow 直接指 lg。 */
478
+ --mg-shadow-card: var(--mg-shadow-sm);
479
+ --mg-shadow-elevated: var(--mg-shadow-md);
480
+ /* hover 态是品牌染色光晕,不属 sm/md/lg 体系,保持独立 */
481
+ --mg-shadow-card-hover: 0 8px 24px color-mix(in oklab, var(--mg-brand-base) 12%, transparent);
460
482
  }
461
483
 
462
484
  /* ═══════════════════════ 3) MARKET 市场覆盖:当前市场指向 global 色阶 ═══════════════════════ */
463
485
  [data-market='global'] {
464
486
  /* 玻璃:只换画布与描边的色相(蓝→翠),veil/alpha/模糊/颗粒四档共用,
465
487
  所以海外站不需要单独维护一套玻璃逻辑,只是画布换色。 */
466
- --mg-glass-canvas: linear-gradient(180deg, #b7e0cd 0%, #e7fbf2 100%);
488
+ --mg-glass-canvas: linear-gradient(180deg, #f5fbf6 0%, #fafdfb 100%); /* 明度/彩度对齐国内 #edf5ff→#f4faff,仅平移到品牌绿色相 */
467
489
  --mg-glass-line: #cfe6db;
468
490
  --mg-glass-header-edge: rgba(238, 250, 244, 0.4);
469
491
 
@@ -486,22 +508,25 @@
486
508
  --mg-brand-gradient-to: var(--mg-brand-global-base);
487
509
  }
488
510
 
489
- /* ═══════════════════════ 深色主题 —— 两套深色系 ═══════════════════════
490
- * [data-theme='dark'] 舒适型:暖炭灰 + 莫兰迪语义,长时间看不累 —— 控制台/文档/app 默认
491
- * [data-theme='dark-showcase'] 酷炫型:近黑 + 高对比 + 凸显主题色 —— 营销官网(国外站)
492
- * 两套共用品牌原子(提亮,暗底可读);bg/文字/语义/阴影各一套。深色 ≠ 纯黑。
511
+ /* ═══════════════════════ 深色主题 —— 唯一一套 ═══════════════════════
512
+ * [data-theme='dark'] 舒适型:暖炭灰 + 莫兰迪语义,长时间看不累 —— 控制台/文档/app/官网统一用它
513
+ * 填色逻辑不是一刀切降饱和:语义色去饱和(状态提示不该抢眼),
514
+ * 品牌色与分类色提亮保饱和(品牌是识别符号,去饱和等于洗成灰)。深色 ≠ 纯黑。
515
+ * 曾有一套「酷炫型」近黑草稿主题,qa#611 定案废弃,2026-08-18 从发版产物移除。
493
516
  * ═══════════════════════════════════════════════════════════════════ */
494
517
 
495
- /* 品牌色深色变体(两套深色共用):CN 提亮靛蓝、global 与浅色同值 #0F9F59 */
496
- [data-theme='dark'],
497
- [data-theme='dark-showcase'] {
518
+ /* 品牌色深色变体:CN 提亮靛蓝、global 与浅色同值 #0F9F59 */
519
+ [data-theme='dark'] {
498
520
  --mg-brand-cn-deep: #223de5;
499
521
  --mg-brand-cn-base: #5b8def;
500
522
  --mg-brand-cn-base-rgb: 91, 141, 239;
501
523
  --mg-brand-cn-mid: #8fb2f5;
502
524
  --mg-brand-cn-light: #bcd2fb;
503
525
  --mg-brand-cn-pale: #16224d;
504
- --mg-brand-global-deep: #34a52a;
526
+ --mg-brand-global-deep: #047857; /* 与浅色档同值。原 #34a52a 亮度 0.278 > base 0.256,
527
+ deep 比 base 还亮属值倒挂,且色相偏黄绿;它当初是为了
528
+ 让 brand-deep 当文字色时能读,而那三处已在上面单独覆盖。
529
+ 改回后按钮 hover 方向与其余三个上下文一致(白字 8.99)。 */
505
530
  --mg-brand-global-base: #0F9F59;
506
531
  --mg-brand-global-base-rgb: 15, 159, 89;
507
532
  --mg-brand-global-mid: #8aec7d;
@@ -513,7 +538,7 @@
513
538
  [data-theme='dark'] {
514
539
  --mg-text-1: #f4f4f5; /* 主文字 zinc-100 */
515
540
  --mg-text-2: #d4d4d8; /* 次级 zinc-300 */
516
- --mg-text-3: #a1a1aa; /* 辅助 zinc-400(AA 5.2:1) */
541
+ --mg-text-3: #b4b4bd; /* 辅助 · 原 zinc-400 #a1a1aa 在 --mg-surface-3(#3b3b44) 上只有 4.32,提到 5.38 */
517
542
  --mg-text-4: #52525b; /* 禁用 zinc-600 */
518
543
  --mg-bg: #18181c; /* 页面 暖炭灰(不过黑不过闷) */
519
544
  --mg-bg-alt: #1f1f25;
@@ -546,13 +571,17 @@
546
571
  --mg-glass-header-edge: rgba(255, 255, 255, 0.4);
547
572
  --mg-glass-grain-opacity: 0.34;
548
573
  --mg-glass-grain-blend: soft-light;
549
- --mg-header-bg: rgba(24, 24, 28, 0.85);
574
+ --mg-header-bg: #18181c;
550
575
  --mg-overlay: rgba(0, 0, 0, 0.55);
551
- --mg-shadow-card: 0 1px 2px rgba(0, 0, 0, 0.35);
552
- --mg-shadow-card-hover: 0 8px 24px rgba(0, 0, 0, 0.35), 0 0 0 1px rgba(255, 255, 255, 0.04);
553
- --mg-shadow-elevated: 0 20px 48px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(255, 255, 255, 0.04);
554
- /* 分层柔和阴影深色档(toast/浮层):柔和烟灰投影 + 极细中性高光描边 */
576
+ /* 分层柔和阴影深色档 —— 深色阴影的唯一值定义点。暗底上投影本就看不见,
577
+ 改用纯黑投影 + 1px 中性高光描边分层(值已核对控制台深色 --shadow-sm/md/lg)。 */
578
+ --mg-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.35);
579
+ --mg-shadow-md: 0 8px 24px rgba(0, 0, 0, 0.35), 0 0 0 1px rgba(255, 255, 255, 0.04);
555
580
  --mg-shadow-lg: 0 20px 48px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(255, 255, 255, 0.04);
581
+ /* 别名方向与浅色一致:card→sm、elevated→md */
582
+ --mg-shadow-card: var(--mg-shadow-sm);
583
+ --mg-shadow-card-hover: var(--mg-shadow-md);
584
+ --mg-shadow-elevated: var(--mg-shadow-md);
556
585
  /* 悬浮阴影深色档(下沉自 console-web/src/styles/tokens.css:584-586) */
557
586
  --mg-shadow-hover-sm: 0 6px 16px rgba(0, 0, 0, 0.32), 0 0 0 1px rgba(255, 255, 255, 0.04);
558
587
  --mg-shadow-hover-md: 0 12px 30px rgba(0, 0, 0, 0.38), 0 0 0 1px rgba(255, 255, 255, 0.05);
@@ -568,59 +597,6 @@
568
597
  --mg-chart-cat-6: #e66767;
569
598
  }
570
599
 
571
- /* —— 酷炫型(营销官网):近黑底 + 高对比 + 加强品牌光晕,凸显主题色 —— */
572
- [data-theme='dark-showcase'] {
573
- --mg-text-1: #ededf0;
574
- --mg-text-2: #a0a0b0;
575
- --mg-text-3: #8a8a9a;
576
- --mg-text-4: #5a5a68;
577
- --mg-bg: #0d0d11; /* 页面 近黑 */
578
- --mg-bg-alt: #111118;
579
- --mg-surface: var(--mg-glass-surface); /* 卡片并入玻璃(酷炫档 veil 5%) */
580
- --mg-surface-solid: #0c0d10;
581
- --mg-surface-2: #141517; /* 悬浮 */
582
- --mg-surface-3: #1c1d20; /* 顶层 */
583
- --mg-border: rgba(255, 255, 255, 0.1);
584
- --mg-divider: rgba(255, 255, 255, 0.08);
585
- --mg-fill-0: rgba(255, 255, 255, 0.03);
586
- --mg-fill-1: rgba(255, 255, 255, 0.06);
587
- --mg-fill-2: rgba(255, 255, 255, 0.1);
588
- --mg-success: #10b981; /* 满血语义,近黑底上更跳 */
589
- --mg-warning: #f59e0b;
590
- --mg-error: #ef4444;
591
- --mg-info: #3b82f6;
592
- --mg-brand-glow: color-mix(in oklab, var(--mg-brand-base) 28%, transparent); /* 凸显主题色:加强光晕 */
593
- --mg-brand-subtle: color-mix(in oklab, var(--mg-brand-base) 10%, transparent);
594
- --mg-glass-tint: #000000;
595
- /* 酷炫档:近黑页底,玻璃面更暗、描边更亮一点以保住边界 */
596
- /* 玻璃(深色·酷炫):近黑底,薄膜再降一档、描边再提一点保住边界 */
597
- --mg-glass-surface: color-mix(in oklab, var(--mg-glass-veil) 5%, transparent);
598
- --mg-glass-surface-strong: color-mix(in oklab, var(--mg-glass-veil) 9%, transparent);
599
- --mg-glass-header: color-mix(in oklab, var(--mg-glass-veil) 4%, transparent);
600
- --mg-glass-canvas: linear-gradient(180deg, #0f1622 0%, #090b0f 100%);
601
- --mg-glass-line: rgba(255, 255, 255, 0.13);
602
- --mg-glass-header-edge: rgba(255, 255, 255, 0.4);
603
- --mg-glass-grain-opacity: 0.28;
604
- --mg-glass-grain-blend: soft-light;
605
- --mg-header-bg: rgba(13, 13, 17, 0.85);
606
- --mg-overlay: rgba(0, 0, 0, 0.6);
607
- --mg-shadow-card: 0 2px 8px rgba(0, 0, 0, 0.4);
608
- --mg-shadow-elevated: 0 12px 32px rgba(0, 0, 0, 0.5);
609
- /* 悬浮阴影酷炫档:比舒适型再压深一档,配合近黑底拉开层次。
610
- 无「控制台现行」可对照(控制台不用 dark-showcase),沿用分支设计值。 */
611
- --mg-shadow-hover-sm: 0 6px 18px rgba(0, 0, 0, 0.42), 0 0 0 1px rgba(255, 255, 255, 0.05);
612
- --mg-shadow-hover-md: 0 14px 36px rgba(0, 0, 0, 0.50), 0 0 0 1px rgba(255, 255, 255, 0.07);
613
- --mg-shadow-hover-lg: 0 24px 60px rgba(0, 0, 0, 0.58), 0 0 0 1px rgba(255, 255, 255, 0.08);
614
-
615
- /* 图表分类色酷炫档:与舒适型同值(两套深色的图表可读性诉求一致) */
616
- --mg-chart-cat-1: #3987e5;
617
- --mg-chart-cat-2: #199e70;
618
- --mg-chart-cat-3: #c98500;
619
- --mg-chart-cat-4: #008300;
620
- --mg-chart-cat-5: #9085e9;
621
- --mg-chart-cat-6: #e66767;
622
- }
623
-
624
600
  /* ──────────────────────────────────────────────────────────────
625
601
  * 断点(CSS 变量不能进 @media,作为契约清单 + JS/容器查询消费)
626
602
  * sm 640 · md 768 · lg 1024 · xl 1280 · 2xl 1536
@@ -642,11 +618,6 @@
642
618
  --mg-glass-canvas: linear-gradient(180deg, #16241f 0%, #111614 100%);
643
619
  --mg-glass-line: rgba(255, 255, 255, 0.10);
644
620
  }
645
- [data-theme='dark-showcase'][data-market='global'],
646
- [data-theme='dark-showcase'] [data-market='global'] {
647
- --mg-glass-canvas: linear-gradient(180deg, #0c1712 0%, #080b09 100%);
648
- --mg-glass-line: rgba(255, 255, 255, 0.13);
649
- }
650
621
 
651
622
  /* ── 通用工具类:页面挂类名即可,不再各自写玻璃 CSS ──────────────────
652
623
  .mg-glass-canvas 给页面外壳:整屏固定画布 + 磨砂颗粒(::before)
@@ -754,11 +725,16 @@
754
725
  --mg-btn-hover-y: -0.5px;
755
726
  --mg-btn-press-scale: 0.98;
756
727
 
757
- /* primary(品牌主按钮) */
728
+ /* primary(品牌主按钮)
729
+ 白字要达 4.5,底色就得够深。浅色国内档 #223de5 白字 7.32 已达标,直接用品牌色;
730
+ 另外三个上下文不够(浅色海外 3.43、深色国内 3.23、深色海外 3.43),
731
+ 在后面的 [data-market='global'] 与 [data-theme='dark'] 块里加深底色(qa#614 衍生)。
732
+ 加深的是「按钮填充」而不是 --mg-brand-base 本身:品牌色是识别符号,
733
+ 且深色提亮、海外绿 #0F9F59 都是已定案的值,不因按钮可读性反过来改品牌。 */
758
734
  --mg-btn-primary-bg: var(--mg-brand-base);
759
735
  --mg-btn-primary-bg-hover: var(--mg-brand-deep);
760
736
  --mg-btn-primary-bg-active: var(--mg-brand-deep);
761
- --mg-btn-primary-text: #ffffff;
737
+ --mg-btn-primary-text: var(--mg-on-primary);
762
738
  --mg-btn-primary-shadow: 0 1px 3px rgba(0, 0, 0, 0.12);
763
739
  --mg-btn-primary-shadow-hover: 0 4px 16px var(--mg-brand-glow), 0 2px 4px rgba(0, 0, 0, 0.1);
764
740
 
@@ -802,6 +778,22 @@
802
778
  --mg-btn-danger-shadow-hover: 0 4px 12px color-mix(in oklab, var(--mg-btn-danger-bg) 28%, transparent), 0 1px 2px rgba(0, 0, 0, 0.05);
803
779
  }
804
780
 
781
+ /* 主按钮填充加深:白字达 4.5 的最低要求。两块用同一个公式,所以
782
+ 深色 × 海外落到哪一块胜出都一致。必须写在上面 :root 之后(TOKEN-GOVERNANCE 第 4 节)。
783
+ 实测白字对比度:浅色海外 3.43 → 6.11;深色国内 3.23 → 5.80;深色海外 3.43 → 6.11。
784
+ hover/active 同步加深:深色海外档 --mg-brand-deep 是 #34a52a,比 base 更浅,
785
+ 原样白字只有 3.20(比默认态还差),这一处配对表没查到。 */
786
+ [data-market='global'] {
787
+ --mg-btn-primary-bg: color-mix(in oklab, var(--mg-brand-base) 78%, #000);
788
+ --mg-btn-primary-bg-hover: color-mix(in oklab, var(--mg-brand-deep) 78%, #000);
789
+ --mg-btn-primary-bg-active: color-mix(in oklab, var(--mg-brand-deep) 78%, #000);
790
+ }
791
+ [data-theme='dark'] {
792
+ --mg-btn-primary-bg: color-mix(in oklab, var(--mg-brand-base) 78%, #000);
793
+ --mg-btn-primary-bg-hover: color-mix(in oklab, var(--mg-brand-deep) 78%, #000);
794
+ --mg-btn-primary-bg-active: color-mix(in oklab, var(--mg-brand-deep) 78%, #000);
795
+ }
796
+
805
797
  /* 深色主题覆盖 neutral 按钮 */
806
798
  [data-theme='dark'] {
807
799
  --mg-btn-neutral-bg: rgba(255, 255, 255, 0.10);
@@ -816,34 +808,37 @@
816
808
  /* ── 控件(Control)尺寸与内边距 ── */
817
809
  :root {
818
810
  /* 高度 */
819
- --mg-control-h-xs: 1.75rem;
820
- --mg-control-h-sm: 2rem;
821
- --mg-control-h-md: 2.5rem;
822
- --mg-control-h-lg: 3rem;
823
- --mg-control-h-xl: 3.5rem;
824
- --mg-control-height-xs: var(--mg-control-h-xs);
811
+ --mg-control-height-xs: 1.75rem;
825
812
  /* --mg-control-height-sm 已在原子层定义为 32px(2026-08-10 设计收敛),此处不重复 */
826
- --mg-control-height-md: var(--mg-control-h-md);
813
+ --mg-control-height-md: 2.5rem;
827
814
  --mg-control-height: var(--mg-control-height-md);
828
- --mg-control-height-lg: var(--mg-control-h-lg);
829
- --mg-control-height-xl: var(--mg-control-h-xl);
815
+ --mg-control-height-lg: 3rem;
816
+ --mg-control-height-xl: 3.5rem;
817
+
818
+ /* 历史短名仅供下游迁移兼容;规范名是 --mg-control-height-{size}。 */
819
+ --mg-control-h-xs: var(--mg-control-height-xs);
820
+ --mg-control-h-sm: var(--mg-control-height-sm);
821
+ --mg-control-h-md: var(--mg-control-height-md);
822
+ --mg-control-h-lg: var(--mg-control-height-lg);
823
+ --mg-control-h-xl: var(--mg-control-height-xl);
830
824
 
831
825
  /* 水平内边距 */
832
- --mg-control-px-xs: var(--mg-space-2);
833
- --mg-control-px-sm: var(--mg-space-3);
834
- --mg-control-px-md: var(--mg-space-5);
835
- --mg-control-px-lg: 2rem;
836
- --mg-control-px-xl: 2.5rem;
826
+ --mg-control-pad-x-xs: var(--mg-space-2);
827
+ --mg-control-pad-x-sm: var(--mg-space-3);
828
+ /* md 档 16px(qa#611 ② 定案;原为 space-5 = 20px,与 --mg-control-pad-x 的 16px 打架) */
829
+ --mg-control-pad-x-md: var(--mg-space-4);
830
+ --mg-control-pad-x-lg: 2rem;
831
+ --mg-control-pad-x-xl: 2.5rem;
832
+
833
+ /* 历史短名仅供下游迁移兼容;规范名是 --mg-control-pad-x-{size}。 */
834
+ --mg-control-px-xs: var(--mg-control-pad-x-xs);
835
+ --mg-control-px-sm: var(--mg-control-pad-x-sm);
836
+ --mg-control-px-lg: var(--mg-control-pad-x-lg);
837
+ --mg-control-px-xl: var(--mg-control-pad-x-xl);
837
838
 
838
839
  /* 垂直内边距 */
839
840
  --mg-control-py-sm: var(--mg-space-2);
840
841
 
841
- /* 语义化内边距别名 */
842
- --mg-control-pad-x-xs: var(--mg-control-px-xs);
843
- --mg-control-pad-x-sm: var(--mg-control-px-sm);
844
- --mg-control-pad-x-md: var(--mg-control-px-md);
845
- --mg-control-pad-x-lg: var(--mg-control-px-lg);
846
- --mg-control-pad-x-xl: var(--mg-control-px-xl);
847
842
  --mg-control-pad-y-sm: var(--mg-control-py-sm);
848
843
 
849
844
  /* 控件文字 */
@@ -935,7 +930,14 @@
935
930
 
936
931
  /* ── 卡片(Card / Tile) ── */
937
932
  :root {
938
- --mg-card-border: rgba(16, 24, 40, 0.05);
933
+ /* 浅色卡片靠描边分界,不靠投影:卡面(白色覆膜)叠在近白玻璃画布上对比度只有 1.036,
934
+ 白上加白分不开,只能靠描边。原 rgba(16,24,40,.05) 只有 1.11,不到治理文档第 5 节的
935
+ hairline ≥ 1.3,卡片在画布浅端糊边。
936
+ 只提 alpha 到 .13(1.312),不换色相 —— 两个理由:
937
+ 一是保住控制台 2026-07-23 定的「淡边框、近乎 hairline、不要硬线框」的中性观感;
938
+ 二是 alpha 型描边的对比度几乎不随卡面变,而固定 hex 会:#dadff3 垫在玻璃卡面上有
939
+ 1.31,垫在实色 --mg-surface-solid 上只剩 1.19,会静默不达标。(qa#614 衍生) */
940
+ --mg-card-border: rgba(16, 24, 40, 0.13);
939
941
  --mg-card-shadow: 0 1px 2px rgba(16, 24, 40, 0.04), 0 6px 16px -6px rgba(16, 24, 40, 0.10), 0 16px 32px -14px rgba(16, 24, 40, 0.08);
940
942
  --mg-tile-radius: var(--mg-radius-md);
941
943
  }
@@ -1096,6 +1098,18 @@
1096
1098
  --mg-nav-icon-active: var(--mg-brand-base);
1097
1099
  }
1098
1100
 
1101
+ /* --mg-brand-deep 在浅色下是「比 base 更深的品牌色」,当强调文字正合适;
1102
+ 但深色下它仍是深色,叠在暗底上读不出来——实测国内深色档只有 2.42,三处全不达标
1103
+ (海外档 5.53 只是因为它的 deep 值本身偏亮,属巧合补偿,不是设计)。
1104
+ 深色下这三处改指 --mg-brand-mid(深色档的提亮级):国内 7.33、海外 10.70。
1105
+ 注意这里只改「当文字用」的三处,--mg-brand-deep 作 hover 填充的用法不变。
1106
+ 写在对应 :root 之后是硬要求(TOKEN-GOVERNANCE 第 4 节)。 */
1107
+ [data-theme='dark'] {
1108
+ --mg-nav-text-active: var(--mg-brand-mid);
1109
+ --mg-media-action-text: var(--mg-brand-mid);
1110
+ --mg-btn-link-text-hover: var(--mg-brand-mid);
1111
+ }
1112
+
1099
1113
  /* ── 浮层(Dialog / Popover / Tooltip) ── */
1100
1114
  :root {
1101
1115
  --mg-dialog-radius: var(--mg-radius-lg);
@@ -1159,13 +1173,16 @@
1159
1173
  只有 image/video/embedding 需要独立色相。 */
1160
1174
  :root {
1161
1175
  --mg-modality-text-bg: var(--mg-brand-selected-bg);
1162
- --mg-modality-text-fg: var(--mg-brand-base);
1176
+ /* 品牌色不能直接当文字色:国内 #223de5 尚可(5.80),海外品牌绿 #0F9F59 在浅底只有 2.81。
1177
+ 浅色两个市场各给 900 档字面值(海外覆盖见后面的 [data-market='global'] 块),
1178
+ 深色还原为品牌派生(见后面的 dark 块)。 */
1179
+ --mg-modality-text-fg: #3730a3; /* indigo-800 · 7.87(900 档 9.05 深过头) */
1163
1180
  --mg-modality-text-border: color-mix(in oklab, var(--mg-brand-base) 22%, transparent);
1164
1181
 
1165
1182
  --mg-modality-image: #8b5cf6;
1166
1183
  --mg-modality-image-bg: color-mix(in oklab, var(--mg-modality-image) 10%, transparent);
1167
1184
  --mg-modality-image-bg-hover: color-mix(in oklab, var(--mg-modality-image) 16%, transparent);
1168
- --mg-modality-image-fg: #7c3aed;
1185
+ --mg-modality-image-fg: #5b21b6; /* violet-800 · 7.10(900 档 8.66 深过头;800 恰好够) */
1169
1186
  --mg-modality-image-border: color-mix(in oklab, var(--mg-modality-image) 24%, transparent);
1170
1187
 
1171
1188
  --mg-modality-audio-bg: var(--mg-success-bg);
@@ -1176,18 +1193,18 @@
1176
1193
  --mg-modality-video: #f97316;
1177
1194
  --mg-modality-video-bg: color-mix(in oklab, var(--mg-modality-video) 10%, transparent);
1178
1195
  --mg-modality-video-bg-hover: color-mix(in oklab, var(--mg-modality-video) 16%, transparent);
1179
- --mg-modality-video-fg: #ea580c;
1196
+ --mg-modality-video-fg: #7c2d12; /* orange-900 · 7.61 AAA(原 600 档 2.89) */
1180
1197
  --mg-modality-video-border: color-mix(in oklab, var(--mg-modality-video) 24%, transparent);
1181
1198
 
1182
1199
  --mg-modality-embedding: #eab308;
1183
1200
  --mg-modality-embedding-bg: color-mix(in oklab, var(--mg-modality-embedding) 12%, transparent);
1184
1201
  --mg-modality-embedding-bg-hover: color-mix(in oklab, var(--mg-modality-embedding) 18%, transparent);
1185
- --mg-modality-embedding-fg: #a16207;
1202
+ --mg-modality-embedding-fg: #713f12; /* yellow-900 · 7.22 AAA(原 700 档 4.10) */
1186
1203
  --mg-modality-embedding-border: color-mix(in oklab, var(--mg-modality-embedding) 28%, transparent);
1187
1204
 
1188
1205
  --mg-modality-reranker-bg: var(--mg-fill-0);
1189
1206
  --mg-modality-reranker-bg-hover: var(--mg-fill-1);
1190
- --mg-modality-reranker-fg: var(--mg-text-2);
1207
+ --mg-modality-reranker-fg: var(--mg-text-1); /* 中性档跟文字 token 走;text-2 仅 4.01,text-1 约 12 AAA */
1191
1208
  --mg-modality-reranker-border: var(--mg-border);
1192
1209
 
1193
1210
  /* accent-purple 是 modality-image 的语义别名(账号/标签等非模态场景复用同一紫)。
@@ -1233,12 +1250,37 @@
1233
1250
  --mg-modality-reranker-featured-fg: #e4e4e7;
1234
1251
  }
1235
1252
 
1236
- /* 酷炫型深色下把模态前景提亮(近黑底需要更高对比) */
1237
- [data-theme='dark-showcase'] {
1253
+ /* 海外浅色:品牌绿 #0F9F59 当文字色只有 2.81,脱离 var(--mg-brand-base) 单独给 900 档。
1254
+ 必须写在上面 :root 之后(同特异性后出现的胜,见 TOKEN-GOVERNANCE 第 4 节)。 */
1255
+ [data-market='global'] {
1256
+ --mg-modality-text-fg: #065641; /* 与 --mg-success-text 同值,刚过 7 · 7.14 */
1257
+ }
1258
+
1259
+ /* 深色下把模态前景提亮:分类色走「提亮保饱和」,不跟语义色一起降饱和。
1260
+ 值来自控制台线上已验证的深色档(qa#611 ①,2026-08-18 提升为库的值)。 */
1261
+ [data-theme='dark'] {
1238
1262
  --mg-modality-image-fg: #c4b5fd;
1239
1263
  --mg-modality-video-fg: #fed7aa;
1240
1264
  --mg-modality-embedding-fg: #fde68a;
1241
1265
  --mg-modality-reranker-fg: var(--mg-text-2);
1266
+ /* 深色 text-fg 原先兜底到 var(--mg-brand-base),实测 cn 4.37 / 海外 4.19,连 AA 都不到
1267
+ —— 这是既有缺口,不是本轮升级带出来的。改取 brand-light:cn 9.23 / 海外 11.4 双 AAA,
1268
+ 仍是品牌派生,自动跟 [data-market] 切色相(qa#614)。 */
1269
+ --mg-modality-text-fg: var(--mg-brand-light);
1270
+ }
1271
+
1272
+ /* 语义 -text 的深色档:不能沿用浅色 900 档(深底上几乎不可见),也不能退回
1273
+ var(--mg-success) 这类填充色本体 —— 那是莫兰迪降饱和值,实测 4.90~5.74,达 AA 不达 AAA。
1274
+ 做法是**保莫兰迪、只提亮**:把各自的莫兰迪色混白到刚过 7,而不是换成 Tailwind 300 档。
1275
+ 换 300 档能达标但那是饱和鲜艳色,直接违背 qa#611 定的
1276
+ 「语义色去饱和,状态提示不该抢眼」—— 达标不能以推翻设计语言为代价。
1277
+ 填充色与描边仍是原莫兰迪值,未动;-text 是独立 token,深色下同样不该由填充色兼任。
1278
+ 写在 :root 之后是硬要求(TOKEN-GOVERNANCE 第 4 节)。 */
1279
+ [data-theme='dark'] {
1280
+ --mg-success-text: #b0c6b8; /* 莫兰迪 #8fae9b 混白 30% · 7.24 */
1281
+ --mg-warning-text: #dcc39c; /* 莫兰迪 #cda971 混白 30% · 7.45 */
1282
+ --mg-error-text: #e0b9b4; /* 莫兰迪 #c98b85 混白 40% · 7.67(30% 只有 6.88) */
1283
+ --mg-info-text: #acbcd6; /* 莫兰迪 #8aa0c4 混白 30% · 7.12 */
1242
1284
  }
1243
1285
 
1244
1286
  /* ── 对话框(Dialog)与抽屉(Sheet)──────────────────────────
@@ -1246,13 +1288,23 @@
1246
1288
  dialog 居中、受视口边距夹逼;sheet 贴边、占满高度。 */
1247
1289
  :root {
1248
1290
  --mg-dialog-pad: var(--mg-space-6);
1291
+ /* 不配固定档位:宽度由内容在 min/max 之间自适应(qa#611 ③ 定案,撤回 400/560/720 分档)。
1292
+ 消费方接的时候去掉 Dialog 的 w-full,否则所有弹窗仍会一律撑到 max-width。 */
1249
1293
  --mg-dialog-min-width: 360px;
1250
1294
  --mg-dialog-max-width: 720px;
1251
- --mg-dialog-max-height: min(720px, calc(100dvh - 128px));
1295
+ /* 90dvh:qa#611 ③ 定案不切 min(720px, 100dvh-128px),保持 qa#458 已验收的封顶行为 */
1296
+ --mg-dialog-max-height: 90dvh;
1252
1297
  --mg-dialog-viewport-margin: var(--mg-space-8);
1298
+
1299
+ /* ── 选中卡片渐变(Key 类型 / 方案卡等单选卡片)── */
1300
+ --mg-select-bg-from: var(--mg-surface-3);
1301
+ --mg-select-bg-to: color-mix(in oklab, var(--mg-brand-base) 12%, var(--mg-surface-3));
1302
+ --mg-select-bg: linear-gradient(135deg, var(--mg-select-bg-from) 0%, var(--mg-select-bg-to) 100%);
1303
+ --mg-select-border: var(--mg-brand-base);
1253
1304
  --mg-dialog-bg: var(--mg-surface-3);
1254
1305
  --mg-dialog-border: var(--mg-border);
1255
- --mg-dialog-shadow: var(--mg-shadow-elevated);
1306
+ /* 弹窗是最高层浮层,直接取 lg,不跟代码块/下拉面板共用 elevated(qa#613) */
1307
+ --mg-dialog-shadow: var(--mg-shadow-lg);
1256
1308
  --mg-dialog-header-gap: var(--mg-space-2);
1257
1309
  --mg-dialog-body-gap: var(--mg-space-3);
1258
1310
  --mg-dialog-footer-gap: var(--mg-space-3);
@@ -1284,6 +1336,14 @@
1284
1336
  --mg-popover-offset: var(--mg-space-2);
1285
1337
  }
1286
1338
 
1339
+ /* —— 选中卡片渐变 · 深色 —— */
1340
+ /* 必须放在上面 :root 声明之后::root 与 [data-theme='dark'] 特异性相同(0,1,0),
1341
+ 同分时后出现的胜。之前这条写在文件前部的 dark 块里,被后面的 :root 12% 压死,
1342
+ 深色档从未生效(qa#611 / d1f84ea 定的 26% 等于白写)。 */
1343
+ [data-theme='dark'] {
1344
+ --mg-select-bg-to: color-mix(in oklab, var(--mg-brand-base) 26%, var(--mg-surface-3));
1345
+ }
1346
+
1287
1347
  /* ── 布局节奏(页面留白)──────────────────────────────────
1288
1348
  替代组件里手写的 p-6 md:p-9 组合;-lg 档对应宽屏断点。 */
1289
1349
  :root {