agentcss 0.25.2 → 0.25.4

package/ai/tokens.json

@@ -7,7 +7,7 @@
       "--paper": {
         "$value": "#f6f7f8",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 基底"
+        "$description": "paper = 页面底（冷灰白）。🔴 不能更浅：与 --surface 的对比度要 >= 1.06:1， 否则页面看着就是纯白，\"表面浮在底上\"的分层完全消失。 surface= 卡片/面板底，比纸底亮一档，靠明度差而非描边来分层"
       },
       "--surface": {
         "$value": "#ffffff",
@@ -20,131 +20,131 @@
       "--surface-raised": {
         "$value": "#ffffff",
         "$type": "color",
-        "$description": "🔴 浮层底（下拉/气泡/抽屉面板）。"
+        "$description": "🔴 浮层底（下拉/气泡/抽屉面板）。 这条**原本只在暗色段定义** ⇒ 浅色下 6 个组件（combobox/popover/select/ dropdown/tooltip/table）的 `background` 整条失效 ⇒ 实测**完全透明**。 浅色值 = --surface：浅色抬高靠阴影（--shadow-*），暗色才靠\"面更亮\"。"
       },
       "--scrollbar-size": {
         "$value": "10px",
         "$type": "dimension",
-        "$description": "============================================================================"
+        "$description": "桌面宽度；移动端由浏览器接管"
       },
       "--scrollbar-size-thin": {
         "$value": "6px",
         "$type": "dimension",
-        "$description": "桌面宽度；移动端由浏览器接管"
+        "$description": "代码块等次要场景"
       },
       "--scrollbar-thumb": {
         "$value": "#7A808A",
         "$type": "color",
-        "$description": "🔴 色值是**脚本反解**出来的（WCAG 1.4.11 要求 thumb 对 track ≥3:1），"
+        "$description": "🔴 色值是**脚本反解**出来的（WCAG 1.4.11 要求 thumb 对 track ≥3:1）， 不是\"看着差不多\"挑的： #7a808a 对 #ffffff 3.98:1 · 对 #f6f7f8 3.71:1 ✅ ⚠️ 第一版我随手挑的 #B4BAC4 只有 1.82:1 ⇒ 门禁直接判不合格。 中性**冷**灰（非品牌色，且保持蓝调）"
       },
       "--scrollbar-thumb-hov": {
         "$value": "#6E747E",
         "$type": "color",
-        "$description": "中性**冷**灰（非品牌色，且保持蓝调）"
+        "$description": "hover 更深一档 · 4.06:1"
       },
       "--scrollbar-radius": {
         "$value": "5px",
         "$type": "dimension",
-        "$description": "hover 更深一档 · 4.06:1"
+        "$description": "= size/2 ⇒ 胶囊形"
       },
       "--text-primary": {
         "$value": "#15181c",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 文字"
+        "$description": "16.60 纸底 / 17.81 表面 · AAA"
       },
       "--text-secondary": {
         "$value": "#4f555e",
         "$type": "color",
-        "$description": "16.60 纸底 / 17.81 表面 · AAA"
+        "$description": "7.01 AAA"
       },
       "--text-tertiary": {
         "$value": "#606770",
         "$type": "color",
-        "$description": "🔴 由 #6b7280 调深到 #606770。"
+        "$description": "🔴 由 #6b7280 调深到 #606770。 axe-core 实测发现：#6b7280 压在**语义底色**上只有 4.13:1 （4.5 是正文门槛）—— 它只在白底上勉强过线（4.83）， 一放到 --surface-sunken / --warning-bg 等底上就不达标。 调深后最低 4.89（压在最亮的 --surface 上），留了 0.39 余量。 梯度仍在：primary 17.8 / secondary 7.5 / tertiary 4.9 —— 明显分层。 5.33 纸底 / 4.89 最亮底(surface) · AA 4.51 AA"
       },
       "--text-on-accent": {
         "$value": "#ffffff",
         "$type": "color",
-        "$description": "4.51 AA"
+        "$description": "8.38 压在 accent 上（不是压纸底）· AAA"
       },
       "--text-on-solid": {
         "$value": "#ffffff",
         "$type": "color",
-        "$description": "🔴 新增（ H9 期间由暗色门禁逼出来）："
+        "$description": "🔴 新增（ H9 期间由暗色门禁逼出来）： 「实心态」组件（filled badge 等）压在**语义色实底**上的文字色。 ⚠️ 为什么不能复用 --text-on-accent： 暗色下 --success / --danger / --warning 都**变浅**了（为在深底上更醒目）， 实心态的底色也随之变浅 ⇒ 白字压上去只有 2.72:1。 ⇒ 需要一个**独立令牌**，让暗色能把它换成深字。 亮色：实底（深色语义色）⇒ 白字"
       },
       "--skeleton-bg": {
         "$value": "#e9ecef",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 骨架屏"
+        "$description": "骨架底色：比纸面略深一档"
       },
       "--skeleton-shimmer": {
         "$value": "rgba(255, 255, 255, 0.72)",
         "$type": "color",
-        "$description": "骨架底色：比纸面略深一档"
+        "$description": "微光高光"
       },
       "--skeleton-h": {
         "$value": "1em",
         "$type": "dimension",
-        "$description": "微光高光"
+        "$description": "单行默认高度"
       },
       "--skeleton-size": {
         "$value": "40px",
         "$type": "dimension",
-        "$description": "单行默认高度"
+        "$description": "circle 默认直径"
       },
       "--skeleton-duration": {
         "$value": "1.4s",
         "$type": "duration",
-        "$description": "circle 默认直径"
+        "$description": "微光扫过周期"
       },
       "--ease-out": {
         "$value": "cubic-bezier(0.23, 1, 0.32, 1)",
         "$type": "cubicBezier",
-        "$description": "---------------------------------------------------------------- 进度条"
+        "$description": "🔴 新增（ I5）。组件私有参数集中在这里定义， 而不是散在 CSS 里用 fallback —— 否则 deps 门禁会报\"未定义令牌\"。 ⭐ --ease-out 刻意独立命名：进度条要\"向前\"的 feel， 匀速（linear）反而像卡住了。"
       },
       "--progress-h": {
         "$value": "6px",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "线形默认高度"
       },
       "--progress-dur": {
         "$value": "240ms",
         "$type": "duration",
-        "$description": "线形默认高度"
+        "$description": "宽度过渡时长"
       },
       "--r-full": {
         "$value": "999px",
         "$type": "dimension",
-        "$description": "宽度过渡时长"
+        "$description": "胶囊形圆角"
       },
       "--ring-size": {
         "$value": "64px",
         "$type": "dimension",
-        "$description": "胶囊形圆角"
+        "$description": "环形默认直径"
       },
       "--ring-thickness": {
         "$value": "8px",
         "$type": "dimension",
-        "$description": "环形默认直径"
+        "$description": "环形环宽"
       },
       "--progress": {
         "$value": "0%",
         "$type": "dimension",
-        "$description": "进度条的当前值。默认 0% 是**正确默认**（不是占位）——"
+        "$description": "进度条的当前值。默认 0% 是**正确默认**（不是占位）—— 实例用 JS setProperty 覆盖它（见 progress demo）。 ⚠️ 必须有默认值，否则\"忘了设值\"会渲染成 0% 且**没人发现**。"
       },
       "--progress-num": {
         "$value": "0",
         "$type": "number",
-        "$description": "环形用**无单位**数值（conic-gradient 的角度计算不接受带 % 的长度）。"
+        "$description": "环形用**无单位**数值（conic-gradient 的角度计算不接受带 % 的长度）。 ⚠️ 这就是环形曾完全不显示的原因，别再改成 --progress。"
       },
       "--z-popover": {
         "$value": "60",
         "$type": "number",
-        "$description": "---------------------------------------------------------------- 气泡卡片"
+        "$description": "层级：高于导航，低于 dialog"
       },
       "--popover-min-w": {
         "$value": "200px",
-        "$type": "dimension",
-        "$description": "层级：高于导航，低于 dialog"
+        "$type": "dimension"
       },
       "--popover-max-w": {
         "$value": "320px",
@@ -156,56 +156,57 @@
       },
       "--popover-gap": {
         "$value": "8px",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "浮层与触发器的距离"
       },
       "--popover-dur": {
         "$value": "140ms",
-        "$type": "duration",
-        "$description": "浮层与触发器的距离"
+        "$type": "duration"
       },
       "--border-control": {
         "$value": "#868b94",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 边框"
+        "$description": "3.19 / 3.42 AA Large"
       },
       "--border-decor": {
         "$value": "#e2e5e9",
         "$type": "color",
-        "$description": "3.19 / 3.42 AA Large"
+        "$description": "1.18 纯装饰，WCAG 不强制"
       },
       "--border-decor-str": {
         "$value": "#c8cdd4",
         "$type": "color",
-        "$description": "1.18 纯装饰，WCAG 不强制"
+        "$description": "1.49 装饰，需要更强分隔时用"
       },
       "--danger": {
         "$value": "#c0392b",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 语义色"
+        "$description": "全部实测 >= 5.6 AA（vs 纸底）。可当文字用，也可当底色用。"
       },
       "--danger-hover": {
         "$value": "#8f1e17",
-        "$type": "color"
+        "$type": "color",
+        "$description": "危险按钮 hover：加深（浅色下加深才对）"
       },
       "--scrim": {
         "$value": "rgba(21, 24, 28, 0.4)",
         "$type": "color",
-        "$description": "危险按钮 hover：加深（浅色下加深才对）"
+        "$description": "抽屉/弹窗遮罩 5.07 AA"
       },
       "--success": {
         "$value": "#2f6b3a",
         "$type": "color",
-        "$description": "5.07 AA"
+        "$description": "5.96 vs 纸底 · AA"
       },
       "--warning": {
         "$value": "#8a5a00",
         "$type": "color",
-        "$description": "5.96 vs 纸底 · AA"
+        "$description": "5.53 vs 纸底 · AA"
       },
       "--info": {
         "$value": "#1d5f8a",
         "$type": "color",
-        "$description": "5.53 vs 纸底 · AA"
+        "$description": "6.41 vs 纸底 · AA"
       },
       "--danger-bg": {
         "$value": "#fdeeec",
@@ -227,32 +228,32 @@
       "--dir-up": {
         "$value": "#c0392b",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 方向色"
+        "$description": "🔴 为什么方向要独立成令牌，而不是复用 --danger / --success 这两组读起来都是\"红/绿\"，但它们是**两件事**： --danger / --success = 好恶（错误/成功）。这是**评价**。 --dir-up / --dir-down = 涨跌（方向）。这是**事实**。 把两件事共用一个名字，会在这个场景里立刻暴露： 「研发费用同比 +38%」—— 是\"涨\"，但那是**坏消息**。 用 --danger 表示它，颜色说着\"错了\"，语义说着\"涨了\"，读者收到矛盾信号。 所以方向色单独命名，取值可以与语义色相同（当前就相同）， 但**允许将来分开调**：金融终端普遍用比 --danger 更饱和的红。 🔴 口径可整体切换（不要在每个组件里判断） 默认是 A 股 / 东亚口径：**红涨绿跌**。…"
       },
       "--dir-down": {
         "$value": "#2f6b3a",
         "$type": "color",
-        "$description": "涨：默认红"
+        "$description": "跌：默认绿"
       },
       "--accent": {
         "$value": "#1b4d8f",
         "$type": "color",
-        "$description": "---------------------------------------------------------------- 强调色"
+        "$description": "🔴 一源原则：一个项目只选一个 accent，不要混用。 accent 决定\"可点击\"的语义，混用等于取消了这层语义。 三选一，把另外两个删掉，别全留着。"
       },
       "--switch-on": {
         "$value": "#1b4d8f",
         "$type": "color",
-        "$description": "开关开态轨道色（浅色版）：与品牌色一致；暗色下换降彩度值（见 dark 段）。"
+        "$description": "开关开态轨道色（浅色版）：与品牌色一致；暗色下换降彩度值（见 dark 段）。 不用 var(--accent) —— 暗色下 accent 太亮，铺满一大块会发光。 ⚠️ 这段注释原本**缺开头**，导致 --switch-on 被浏览器当成坏声明丢掉 （实测浅色下取值为空）。已由 token-parse-gate.py 兜住。 7.82 AAA"
       },
       "--accent-hover": {
         "$value": "#163a6d",
         "$type": "color",
-        "$description": "7.82 AAA"
+        "$description": "11.29 白字压上 · AAA"
       },
       "--accent-soft": {
         "$value": "#e6eef7",
         "$type": "color",
-        "$description": "11.29 白字压上 · AAA"
+        "$description": "focus ring / 浅底，不要拿它放正文"
       },
       "--tooltip-bg": {
         "$value": "#15181c",
@@ -270,7 +271,7 @@
       "--sp-1": {
         "$value": "4px",
         "$type": "dimension",
-        "$description": "================================================================ [核心]"
+        "$description": "间距：8px 网格为基准，大值流体。 想要的值不在表里 => 说明布局没规划，改设计，不要加 token。 🔴 哪些该流体：--sp-4 往上（区块间距，随屏幕变大而变大，观感自然） 哪些不该：--sp-1..3（元素内部间距，流体化会让控件尺寸忽大忽小）"
       },
       "--sp-2": {
         "$value": "8px",
@@ -282,117 +283,118 @@
       },
       "--sp-4": {
         "$value": "clamp(1rem,     0.95rem + 0.3vw,  1.25rem)",
-        "$type": "other"
+        "$type": "other",
+        "$description": "16 → 20px"
       },
       "--sp-5": {
         "$value": "clamp(1.25rem,  1.15rem + 0.7vw,  1.75rem)",
         "$type": "other",
-        "$description": "16 → 20px"
+        "$description": "20 → 28px"
       },
       "--sp-6": {
         "$value": "clamp(1.5rem,   1.3rem  + 1.2vw,  2.25rem)",
         "$type": "other",
-        "$description": "20 → 28px"
+        "$description": "24 → 36px"
       },
       "--sp-7": {
         "$value": "clamp(2rem,     1.7rem  + 1.8vw,  3.5rem)",
         "$type": "other",
-        "$description": "24 → 36px"
+        "$description": "32 → 56px"
       },
       "--sp-8": {
         "$value": "clamp(2.5rem,   2.1rem  + 2.4vw,  4.5rem)",
         "$type": "other",
-        "$description": "32 → 56px"
+        "$description": "40 → 72px"
       },
       "--bp-sm": {
         "$value": "30rem",
         "$type": "dimension",
-        "$description": "================================================================ [核心]"
+        "$description": "480px 大手机 / 小平板"
       },
       "--bp-md": {
         "$value": "48rem",
         "$type": "dimension",
-        "$description": "480px  大手机 / 小平板"
+        "$description": "768px 平板"
       },
       "--bp-lg": {
         "$value": "64rem",
         "$type": "dimension",
-        "$description": "768px  平板"
+        "$description": "1024px 小笔记本"
       },
       "--bp-xl": {
         "$value": "80rem",
         "$type": "dimension",
-        "$description": "1024px 小笔记本"
+        "$description": "1280px 桌面"
       },
       "--fs-xs": {
         "$value": "0.75rem",
         "$type": "dimension",
-        "$description": "================================================================ [核心]"
+        "$description": "字号阶梯 🔴 修正：上下限从 px 改成 rem。 px 上下限不尊重\"用户把浏览器默认字号调大\"的设置 —— 那样 clamp 的下限会锁死，用户放到 200% 也涨不上去。 rem 基准跟着用户设置走，这是无障碍底线。 🔴 哪些该流体、哪些不该（这条更容易做错）： 该流体：正文、小标题、大标题、间距 —— 它们随屏幕变大而变大，观感自然 不该流体**：UI 文本（--fs-xs / --fs-sm）、小间距（--sp-1..3） —— 它们是控件尺寸的一部分。流体会让按钮和输入框在不同屏幕下 大小不一，布局抖动。搜索到的原话： \"UI typography benefits from minimal scaling. Too much fluidity breaks layout.\" 公式：clamp(MIN-REM, REM基准 + VW系数, MAX-REM)…"
       },
       "--fs-sm": {
         "$value": "0.875rem",
         "$type": "dimension",
-        "$description": "12px 固定：辅助文字不流体"
+        "$description": "14px 固定：UI 文本不流体"
       },
       "--fs-base": {
         "$value": "clamp(1rem,       0.95rem + 0.3vw,  1.125rem)",
         "$type": "other",
-        "$description": "14px 固定：UI 文本不流体"
+        "$description": "16 → 18px"
       },
       "--fs-md": {
         "$value": "clamp(1.125rem,   1.05rem + 0.5vw,  1.3125rem)",
         "$type": "other",
-        "$description": "16 → 18px"
+        "$description": "18 → 21px"
       },
       "--fs-lg": {
         "$value": "clamp(1.3125rem,  1.2rem  + 0.7vw,  1.5rem)",
         "$type": "other",
-        "$description": "18 → 21px"
+        "$description": "21 → 24px"
       },
       "--fs-xl": {
         "$value": "clamp(1.5rem,     1.3rem  + 1.2vw,  1.875rem)",
         "$type": "other",
-        "$description": "21 → 24px"
+        "$description": "24 → 30px"
       },
       "--fs-2xl": {
         "$value": "clamp(1.75rem,    1.45rem + 1.8vw,  2.5rem)",
         "$type": "other",
-        "$description": "24 → 30px"
+        "$description": "28 → 40px"
       },
       "--lh-tight": {
         "$value": "1.25",
         "$type": "number",
-        "$description": "行高：正文 1.7 是中文长文的舒适值（西文常用 1.5，中文需要更松）"
+        "$description": "行高：正文 1.7 是中文长文的舒适值（西文常用 1.5，中文需要更松） 标题"
       },
       "--lh-base": {
         "$value": "1.7",
         "$type": "number",
-        "$description": "标题"
+        "$description": "正文"
       },
       "--lh-loose": {
         "$value": "1.85",
         "$type": "number",
-        "$description": "正文"
+        "$description": "长段落、低龄/无障碍场景"
       },
       "--measure-page": {
         "$value": "52rem",
         "$type": "dimension",
-        "$description": "----------------------------------------------------------------"
+        "$description": "此前 33 个页面各自写 `.wrap { max-width: 680px / 720 / 760 / 800 / 820 / 860 / 900 / 42rem / 44rem / 46rem / 52rem … }` —— 16 种写法。 结果就是「没有全局可改」：想改列宽要改 33 处，漏一处就不一致。 实测众数是 820px（8/33 页），取 52rem = 832px（干净的 rem 值， 且 rem 会跟随用户字号设置，px 不会）。 改这一个令牌 ⇒ 全部页面列宽一起变。"
       },
       "--tracking-title": {
         "$value": "-0.02em",
         "$type": "dimension",
-        "$description": "🔴 补：标题字距 --tracking-title（0.4.2）"
+        "$description": "🔴 补：标题字距 --tracking-title（0.4.2） 大字号要收紧字距，否则标题散。此前只有 list/nav/states 三页写了 `letter-spacing: -0.02em`（写死值），其余 33 页没有 ⇒ 标题观感不一致。"
       },
       "--r-sm": {
         "$value": "6px",
         "$type": "dimension",
-        "$description": "---------------------------------------------------------------- 圆角"
+        "$description": "一套就够。圆角混搭（卡片 20px、按钮 4px）是典型的没想清楚。"
       },
       "--r-xs": {
         "$value": "3px",
         "$type": "dimension",
-        "$description": "🔴 补：内嵌小元素用的小圆角（菜单项、标签、chip）。"
+        "$description": "🔴 补：内嵌小元素用的小圆角（菜单项、标签、chip）。 之前 dropdown.css 里凭空写了 var(--r-xs, 3px) —— 令牌不存在时 CSS 变量会**静默失效**（整条声明被丢弃），所以一直没被发现。 ⇒ 补上这个令牌（deps 门禁抓到）。"
       },
       "--r-md": {
         "$value": "10px",
@@ -409,7 +411,7 @@
       "--shadow-1": {
         "$value": "0 1px 2px rgba(31, 29, 25, 0.05), 0 1px 3px rgba(31, 29, 25, 0.06)",
         "$type": "other",
-        "$description": "---------------------------------------------------------------- 阴影"
+        "$description": "两级。第三级阴影出现的时候，通常说明层级设计出了问题。 y 轴偏移小、模糊大 —— 模拟纸面浮起，不是悬浮在太空。"
       },
       "--shadow-2": {
         "$value": "0 2px 4px rgba(31, 29, 25, 0.05), 0 6px 16px rgba(31, 29, 25, 0.08)",
@@ -418,27 +420,27 @@
       "--dur-fast": {
         "$value": "120ms",
         "$type": "duration",
-        "$description": "---------------------------------------------------------------- 动效"
+        "$description": "颜色、透明度"
       },
       "--dur-base": {
         "$value": "180ms",
         "$type": "duration",
-        "$description": "颜色、透明度"
+        "$description": "位移、展开"
       },
       "--dur-slow": {
         "$value": "280ms",
         "$type": "duration",
-        "$description": "位移、展开"
+        "$description": "大块入场、遮罩"
       },
       "--ease-in-out": {
         "$value": "cubic-bezier(0.77, 0, 0.175, 1)",
         "$type": "cubicBezier",
-        "$description": "UI 默认：入场、展开"
+        "$description": "屏上位移、折叠"
       },
       "--ease-drawer": {
         "$value": "cubic-bezier(0.32, 0.72, 0, 1)",
         "$type": "cubicBezier",
-        "$description": "屏上位移、折叠"
+        "$description": "抽屉式滑入（iOS 观感）"
       },
       "--lift-sm": {
         "$value": "1px",
@@ -456,7 +458,7 @@
       "--z-base": {
         "$value": "0",
         "$type": "number",
-        "$description": "---------------------------------------------------------------- z-index"
+        "$description": "乱写 z-index（999、9999）是前端最常见的失控点。 只用这六个值。需要更高的 => 说明层级模型有问题。"
       },
       "--z-sticky": {
         "$value": "10",
@@ -469,12 +471,11 @@
       "--z-raised": {
         "$value": "5",
         "$type": "number",
-        "$description": "🔴 补回：上一轮\"清理重复 z 令牌\"时把它误删了，"
+        "$description": "🔴 补回：上一轮\"清理重复 z 令牌\"时把它误删了， 而 card / pagination 都在用 ⇒ 它们的 z-index 声明**静默失效**。 ⚠️ CSS 变量不存在时**不报错**，声明直接被丢弃 —— 这类问题只能靠门禁抓。 浮起层（卡片悬停、下拉、内层可点元素）"
       },
       "--z-overlay": {
         "$value": "30",
-        "$type": "number",
-        "$description": "浮起层（卡片悬停、下拉、内层可点元素）"
+        "$type": "number"
       },
       "--z-modal": {
         "$value": "40",
@@ -487,12 +488,12 @@
       "--sz-touch": {
         "$value": "44px",
         "$type": "dimension",
-        "$description": "------------------------------------------------------------"
+        "$description": "最小命中区（指针）"
       },
       "--sz-touch-sm": {
         "$value": "32px",
         "$type": "dimension",
-        "$description": "最小命中区（指针）"
+        "$description": "次要场景（表格行内等密排）"
       },
       "--measure-prose": {
         "$value": "34em",
@@ -501,22 +502,23 @@
       },
       "--measure-title": {
         "$value": "20em",
-        "$type": "dimension"
+        "$type": "dimension",
+        "$description": "标题比正文窄，避免大字长时间扫视"
       },
       "--measure-lede": {
         "$value": "32em",
         "$type": "dimension",
-        "$description": "标题比正文窄，避免大字长时间扫视"
+        "$description": "导语"
       },
       "--measure-pull": {
         "$value": "30em",
         "$type": "dimension",
-        "$description": "导语"
+        "$description": "引言块"
       },
       "--measure-aside": {
         "$value": "32em",
         "$type": "dimension",
-        "$description": "引言块"
+        "$description": "边注"
       },
       "--sans": {
         "$value": "/* 拉丁 */\n    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,\n    'Helvetica Neue', Arial,\n    /* 中文 */\n    'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei',\n    'Source Han Sans SC', 'Noto Sans CJK SC',\n    /* 阿拉伯 / 希伯来 / 泰文（系统通常自带相应字体）*/\n    'Geeza Pro', 'Segoe UI Historic',\n    /* 泛型 */\n    sans-serif",
@@ -533,14 +535,13 @@
       "--tracking-normal": {
         "$value": "0",
         "$type": "number",
-        "$description": "字距：默认 0。中文与拉丁的字距需求不同，"
+        "$description": "字距：默认 0。中文与拉丁的字距需求不同， 阿拉伯/希伯来文连字后密度更高，需要更松 —— 下面按语言覆盖。"
       }
     },
     "dark": {
       "--paper": {
         "$value": "#14171A",
-        "$type": "color",
-        "$description": "⚠️ `:not([data-theme=\"light\"])` —— 让「强制亮」能压过系统暗色。"
+        "$type": "color"
       },
       "--surface": {
         "$value": "#1C2024",
@@ -558,12 +559,12 @@
       "--scrollbar-thumb": {
         "$value": "#6E747E",
         "$type": "color",
-        "$description": "🔴滚动条（暗色）"
+        "$description": "🔴滚动条（暗色） ⚠️ 暗色下 thumb 要比浅色**更亮**（#4A515C）才看得见； 用浅色那档会变成\"黑里有黑\"。 对 #14171a 3.82:1 · 对 #232830 3.15:1 ✅"
       },
       "--scrollbar-thumb-hov": {
         "$value": "#7D828A",
         "$type": "color",
-        "$description": "对 #14171a 3.82:1 · 对 #232830 3.15:1 ✅"
+        "$description": "4.24:1"
       },
       "--border-decor": {
         "$value": "#2A3038",
@@ -598,17 +599,17 @@
       },
       "--text-on-solid": {
         "$value": "#15181c",
-        "$type": "color"
+        "$type": "color",
+        "$description": "暗色：success/danger/warning 都变浅了 ⇒ 实心态换深字"
       },
       "--skeleton-bg": {
         "$value": "#2E343C",
         "$type": "color",
-        "$description": "暗色：底色比纸面**略浅**（深底上\"更亮\"才看得出是占位）"
+        "$description": "暗色：底色比纸面**略浅**（深底上\"更亮\"才看得出是占位） 亮度差 0.032（契约要求 >0.02）"
       },
       "--skeleton-shimmer": {
         "$value": "rgba(255, 255, 255, 0.06)",
-        "$type": "color",
-        "$description": "亮度差 0.032（契约要求 >0.02）"
+        "$type": "color"
       },
       "--danger": {
         "$value": "#E07A6E",
@@ -634,7 +635,7 @@
       "--dir-up": {
         "$value": "#E07A6E",
         "$type": "color",
-        "$description": "方向色（暗色）：与 success / danger 同值，理由见浅色段。"
+        "$description": "方向色（暗色）：与 success / danger 同值，理由见浅色段。 暗色下红 5.60–6.15 · 绿 6.01–6.60，四组底全部 AA。"
       },
       "--dir-down": {
         "$value": "#6FAA7A",
@@ -647,7 +648,7 @@
       "--warning-bg": {
         "$value": "#242A31",
         "$type": "color",
-        "$description": "🔴 最终定的（第二次修正）："
+        "$description": "🔴 最终定的（第二次修正）： 「本身**淡黄色的那些框**你就改成**暖灰色**， 在深色模式下的暖灰色**这个就很好啊」 浅色下 --warning-bg 是 #fbf1dd（淡黄）—— **保持不动**。 暗色下原来是 #2B2313（**深红棕**）⇒ 在冷灰背景里 像一块\"**咖啡色**\"的脏斑 ⇒ 这就是 真机实测看到的。 ⇒ 暗色下改成**暖灰**（保留一点暖调，与浅色的淡黄呼应， 但**不再偏红褐**，与整体的冷灰底融合）。 ⚠️ 只改这一个令牌，**底色/表面/文本一律不动**。"
       },
       "--info": {
         "$value": "#5B9BC4",
@@ -665,7 +666,7 @@
       "--switch-on": {
         "$value": "#3E6EA8",
         "$type": "color",
-        "$description": "🔴 开关开态的轨道色 -- 暗色版"
+        "$description": "🔴 开关开态的轨道色 -- 暗色版 🔴 **降彩度**：#7AA9DE 太亮，铺满一大块会发光。 实测：滑块是纯白 #FFF，轨道若也接近白 ⇒ 对比不足、边界糊。 ⇒ 轨道取**中深蓝**（#3E6EA8 族），与白滑块有清晰对比， 在 #1C2024 的深底上又不刺眼。"
       },
       "--accent-hover": {
         "$value": "#8FB8E6",
@@ -678,7 +679,7 @@
       "--tooltip-bg": {
         "$value": "#232830",
         "$type": "color",
-        "$description": "气泡：暗色下不再\"反色\"（反色会变成浅底深字，在暗界面里像个白块），"
+        "$description": "气泡：暗色下不再\"反色\"（反色会变成浅底深字，在暗界面里像个白块）， 改用抬高面 + 正文色 —— 但只比纸面亮一档，所以必须补一条描边。 文字/底 11.93:1（AAA），实测见 contrast.py。"
       },
       "--tooltip-fg": {
         "$value": "#E4E7EA",