agentcss 0.0.0-stage → 0.11.2

package/01-tokens/typography.css

@@ -0,0 +1,156 @@
+/* ============================================================================
+   frontend-lib / 01-tokens / typography.css
+   排版辅助类（跨组件共享）
+
+   依赖：无（只用 tokens.css 里的变量）
+   版本：A ✅ / B ✅ / C ✅
+
+   🔴 建立。此前 8 个 demo 各自在内联 <style> 里**重复定义**
+      .small / .note / .lead 等，全库没有一个共同出处 ——
+      改一处就要改八处，漏一处就样式不一致（这次就被 refs.py 当场抓到）。
+   ========================================================================= */
+
+/* ============================================================================
+   页面级默认值
+   ============================================================================
+   🔴 补（暗色模式首次生效后暴露的真问题）：
+      此前 tokens.css 与 typography.css 都**没有给 body 设 color / background**
+      ⇒ 暗色下所有页面继承**浏览器默认黑**（rgb(0,0,0)）
+      ⇒ 实测 19 个 demo 页面的 h1 是「黑字 on #14171A」，对比度 1.17:1（几乎看不见）
+   ⇒ 页面底色与文字色的默认值属于**排版层**职责，故放在 typography.css。
+   ⚠️ 加在文件**头部**：此前我加在末尾，结果末尾的说明注释没闭合，
+      规则被当成注释吞掉（CSSOM 里查不到）—— 又一次同类问题。
+   ============================================================================ */
+body {
+  color: var(--text-primary);
+  background: var(--paper);
+}
+
+/* 辅助文字：说明、注释、元信息 */
+.small {
+  font-size: var(--fs-xs);
+  color: var(--text-secondary);
+  line-height: 1.7;
+}
+
+/* 更弱一档：几乎不抢眼，用在页脚、版权行 */
+.small--faint { color: var(--text-tertiary); }
+
+/* 导语：紧跟标题的一段话，比正文略大、略淡 */
+.lead {
+  font-size: var(--fs-md);
+  color: var(--text-secondary);
+  line-height: 1.6;
+}
+
+/* 说明块：补充/解释，不是警告，更不是错误。要"注意"用 .note--warn。
+   🔴 0.4.2 底色 --warning-bg → --surface-sunken：实测 21 页用 .note，
+     20 页当灰底说明块手写同一个值，只有 1 页用 warning ⇒ 取众数。 */
+.note {
+  /* 🔴 去掉 `border-left: 3px solid`。
+     评审意见"很蠢的左边侧边阴影" —— 说得对：
+       ① 它是**纯装饰**，不传达信息（颜色已经表达了）
+       ② 3px 竖条在浅底上形成一条硬边，视觉噪声比信息量大
+       ③ 满库 13 处同款，一眼就能看出"模板感" —— 这正是 AI 味的来源。
+     真实产品（GitHub callout / Vercel / Stripe）都是**纯底色 + 圆角**，没有竖条。 */
+  background: var(--surface-sunken);
+  color: var(--text-secondary);
+  padding: var(--sp-3) var(--sp-4);
+  border-radius: var(--r-sm);
+  font-size: var(--fs-sm);
+  line-height: 1.6;
+  /* 众数写法是 `margin: 0 0 var(--sp-4)`（9 页）。
+     上下都要留出呼吸，但它是**紧跟上下文的补充**，不是独立章节，
+     所以下边距给 --sp-4、上边距为 0（由上一个块的 margin 负责）。 */
+  margin: 0 0 var(--sp-4);
+}
+
+/* 注意块：同样一块，但要"提醒"而不是"补充" —— 唯一差别是底色。 */
+.note--warn {
+  background: var(--warning-bg);
+}
+
+/* 分隔线：比 border 轻，用于段落之间 */
+.rule {
+  border: 0;
+  border-top: 1px solid var(--border-decor);
+  margin: var(--sp-6) 0;
+}
+
+/* 代码片段（行内）—— 与 content.css 的 .prose > code 呼应 */
+code {
+  font-family: var(--mono);
+}
+
+/* ============================================================================
+   反模式
+   =========================================================================
+   1. 在每个 demo 的内联 <style> 里重复定义 .small / .note
+      八处重复，改一处漏一处。不如引这一个文件。
+   2. 用 .note 装错误消息
+      它是"注意"不是"错误"，颜色与语义都不对。错误用 .field__error。
+   3. 在这里加组件专有样式
+      这是 tokens 层，只放跨组件通用的东西。
+   ========================================================================= */
+
+/* ============================================================================
+   数字排印：`.num`
+   ============================================================================
+   🔴 建立。之前的情况是「每个组件自己写一遍」：
+   `list.css` 有 `tabular-nums`、longform 用自造的 `.num`、
+   而 states 的数据行（26,831 条记录）根本没处理。
+   ⇒ 同一个库里三套做法，且**只有一处**是真规则。
+
+   为什么必须等宽（实测）：
+   Windows 的 Segoe UI 里 `1` `8` `0` 本来就等宽（都 10.33px @14px），
+   **但逗号只有 4.25px** ⇒ `12,345,678` 仍然会歪。
+   也就是说：**不能依赖系统字体的默认**，
+   不同系统（macOS SF / Linux DejaVu）连数字本身都不一定等宽。
+   必须显式声明。
+
+   为什么不做成全局 `* { font-variant-numeric: tabular-nums }`：
+   比例数字在正文里更好看（"第 3 步"不该被拉宽）。
+   ⇒ **只在"需要成列比较"的地方用**，这是排版判断，不是全局开关。
+
+   用法：
+       <td class="num">26,831</td>        表格、金额、指标
+       <span class="num">+2.41%</span>    涨跌幅
+   ------------------------------------------------------------------------ */
+.num {
+  font-variant-numeric: tabular-nums;
+  /* 🔴 负数与小数点也要等宽，否则 "-1.2%" 和 "12.3%" 仍然对不齐 */
+  font-feature-settings: "tnum" 1;
+}
+
+/* 指标块的数字：更大的、更"技术"的一档。
+   金融看板的标志性元素 —— 数字本身成为视觉主体，而不是正文的一部分。 */
+.num-lg {
+  font-variant-numeric: tabular-nums;
+  font-feature-settings: "tnum" 1;
+  font-weight: 500;
+  letter-spacing: -0.01em;   /* 大字号收紧一点，数字块更整齐 */
+}
+
+/* ==========================================================================
+   🔴 补：`.lede`（导语/引言段）
+
+   ⭐ 为什么补它（refs 门禁抓到）：
+     全库有 **6 个 demo** 都在用 `class="lede"`（导语段），
+     但**从来没有定义过** ⇒ 属于「静默失效」——
+     浏览器不报错、页面照常显示，只是这一段**根本没生效**。
+     这类问题只能靠门禁抓，肉眼完全看不出来。
+
+   用途：标题下面那段摘要性文字。要比正文大一号、行距更松，
+        但**不能大到抢标题的视觉重量**（标题才是层级入口）。
+
+   ⚠️ 全部走令牌，不写死值 —— 换主题/换字号版本时自动跟随。
+   ========================================================================== */
+.lede {
+  /* 🔴 0.4.2：--fs-lg → --fs-md。前者与 h2 同档，导语抢了小节标题的层级。 */
+  font-size: var(--fs-md);
+  line-height: 1.65;
+  color: var(--text-secondary);
+  /* 众数是 --sp-6（6 页）；--measure-lede 取代各页手写的 60ch / 62ch。 */
+  margin: 0 0 var(--sp-6);
+  max-width: var(--measure-lede);
+}

package/02-primitives/badge/README.md

@@ -0,0 +1,71 @@
+# badge · 状态标记
+
+承载**一个短状态词**（"已披露""已停牌""审计中"）。
+
+## 类
+
+| 类 | 作用 |
+|---|---|
+| `.badge` | 基础（不带变体时是中性色）|
+| `.badge--neutral` | 中性：草稿 / 归档 / 草稿态 |
+| `.badge--success` | 成功 / 已披露 |
+| `.badge--warning` | 警告 / 审计中 |
+| `.badge--danger` | 危险 / 已停牌 |
+| `.badge--info` | 信息 / 待复核 |
+| `.badge--lg` | 较大一档（13px）|
+| `.badge--clickable` | 可点 —— **必须配合 `<button>` 或 `<a>`** |
+
+## 用法
+
+```html
+<!-- 不可点（默认） -->
+<span class="badge badge--success">已披露</span>
+
+<!-- 可点：语义由元素承担，样式照抄 .badge -->
+<button class="badge badge--info badge--clickable">待复核</button>
+```
+
+## 三条硬规矩
+
+**1. 不可点就别用 button。** 要能点必须用 `<button>` 或 `<a>` ——
+`div + onclick` 对读屏是「没有角色的按钮」：读不出能点，键盘也 Tab 不到。
+
+**2. 一定要有文字。** WCAG 1.4.1 要求不能只靠颜色区分。
+本组件的颜色是**冗余线索**，不是唯一编码 —— 去掉颜色也必须能读懂。
+
+**3. 不要数字角标。** badge 是"状态词"，不是"数字气泡"。
+
+## 为什么是「淡底 + 深字」
+
+小字号（11–12px）在饱和底上白字对比度普遍不够。本库五组实测：
+
+| 变体 | 浅色 | 暗色 |
+|---|---|---|
+| `--neutral` | 6.76 | 10.59 |
+| `--success` | 5.58 | 5.92 |
+| `--danger` | 4.82 | 5.37 |
+| `--warning` | 5.29 | 6.05 |
+| `--info` | 6.01 | 5.25 |
+
+**全部 ≥ 4.5** ⇒ 不需要为 badge 单独调一套色（省一次决策，也少一套漂移风险）。
+
+**反例的真实数字**：暗色下白字在 `--success` 上只有 **2.72:1**（浅色是 6.39 达标）——
+**看浅色时完全发现不了这个失效**。这就是为什么每组都要两套都算。
+
+## 两档尺寸
+
+出现第三档说明信息密度没规划好 —— 与 `card` 的判断标准一致。
+
+## 强制高对比模式
+
+`@media (forced-colors: active)` 下边框改用 `currentColor` ——
+**靠边框保住边界，不靠底色**。这一段本机无法验证（需系统级开关）。
+
+## 尺寸
+
+高度 24px（默认）· 字号 12px —— 达 WCAG 2.2 的 24×24 最小目标。
+
+## 验证
+
+- `component-contrast.py`：5 组字/底组合两套配色全过
+- `a11y-scan`：本 demo axe 0 违规 / 16 条通过

package/02-primitives/badge/badge.css

@@ -0,0 +1,141 @@
+/* ============================================================================
+   Badge — 状态标记
+   ============================================================================
+   为什么用「淡底 + 深字」而不是「饱和底 + 白字」
+   ----------------------------------------------------
+   饱和底（如 --success #2f6b3a）+ 白字在**小字号**下对比度普遍不够 ——
+   本库正文门槛是 4.5:1，而 badge 只有 11–12px，更严格才对。
+
+   实测（本库令牌，两套配色）：
+     success  浅 5.58 · 暗 5.92
+     danger   浅 4.82 · 暗 5.37
+     warning  浅 5.29 · 暗 6.05
+     info     浅 6.01 · 暗 5.25
+     neutral  浅 6.76 · 暗 10.59
+   ⇒ 全部 ≥ 4.5，不需要为 badge 单独调色。
+
+   为什么可以只用颜色
+   ----------------
+   🔴 **不行。** WCAG 1.4.1（不能只靠颜色）要求形状或文字参与区分。
+   本组件的做法：**badge 一律带文字**（"已停牌"/"审计中"），
+   颜色只是**冗余线索**，不是唯一线索。
+   ⇒ 这是"可选的辅助"，不是"唯一的编码"。
+
+   不用它承载什么信息
+   ------------------
+   ❌ 不用 badge 装数字角标（那是另一类设计，且数字变化读屏未必会念）
+   ❌ 不用 badge 装可点击的东西（那是 button，见下）
+   ========================================================================= */
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--sp-1);
+  padding: 2px var(--sp-2);
+  border: 1px solid transparent;
+  border-radius: var(--r-sm);
+  font-size: var(--fs-xs);
+  line-height: 1.5;              /* 不用行高单位：11px 字号下 1.5em 会虚 */
+  white-space: nowrap;
+  vertical-align: baseline;
+  align-self: flex-start;        /* flex 容器里不被 stretch 拉满（实测 54→355px） */
+  /* 🔴 不可点 ⇒ cursor 默认、不要 transition 假装能点 */
+}
+
+/* 中性（默认）—— 数量最多的一档，别让它显得像"缺省" */
+.badge--neutral {
+  background: var(--surface-sunken);
+  border-color: var(--border-decor);
+  color: var(--text-secondary);
+}
+
+.badge--success {
+  background: var(--success-bg);
+  border-color: var(--success-bg);       /* 同色底 ⇒ 边框不产生额外对比 */
+  color: var(--success);
+}
+
+.badge--danger {
+  background: var(--danger-bg);
+  border-color: var(--danger-bg);
+  color: var(--danger);
+}
+
+.badge--warning {
+  background: var(--warning-bg);
+  border-color: var(--warning-bg);
+  color: var(--warning);
+}
+
+.badge--info {
+  background: var(--info-bg);
+  border-color: var(--info-bg);
+  color: var(--info);
+}
+
+/* ---------------------------------------------------------------- 可点版
+   🔴 当 badge **需要可点**时（比如点标签跳到筛选结果），
+   语义必须是 button/a —— div + onClick 对读屏是"没有角色的按钮"。
+
+   给 .badge--clickable 时**必须**同时在 HTML 上写正确的元素与键盘支持。
+   本类只负责**看起来可点**（hover/focus 反馈），
+   焦点环用 :focus-visible（键盘才出现，鼠标点击不出现 —— 与本库 button 一致）。
+   ---------------------------------------------------------------- */
+
+.badge--clickable {
+  cursor: pointer;
+  transition: background var(--dur-fast) var(--ease-out);
+}
+
+/* 🔴 两处修正：
+   ① 加 @media (hover) 门控 —— 触屏上"点一下"会先点亮 hover 再 click，
+      于是保持"被悬停"的颜色不褪（hover-gate 抓到的）。
+   ② **不用 `filter: brightness(0.97)`** —— states 门禁把它列为反模式，
+      理由成立：brightness 是**整体乘亮**，换主题时效果完全不同
+      （浅色下几乎看不出，暗色下明显压暗）⇒ 颜色跟着主题漂。
+      ⇒ 改成显式换边框色，行为可预测。 */
+@media (hover: hover) and (pointer: fine) {
+  .badge--neutral.badge--clickable:hover { border-color: var(--text-tertiary); }
+  .badge--success.badge--clickable:hover  { border-color: var(--success); }
+  .badge--warning.badge--clickable:hover  { border-color: var(--warning); }
+  .badge--danger.badge--clickable:hover   { border-color: var(--danger); }
+  .badge--info.badge--clickable:hover     { border-color: var(--info); }
+}
+
+/* 强制高对比模式（Windows）—— 淡底会被系统强制色覆盖，
+   这时靠边框保住边界，而不是靠底色。 */
+@media (forced-colors: active) {
+  .badge {
+    border-color: currentColor;         /* 强制色下边框取文字色 */
+  }
+}
+
+/* ---------------------------------------------------------------- 尺寸
+   两档够了。badge 出现三档说明信息密度没规划好
+   （与 card 的判断标准一致）。 */
+.badge--lg {
+  font-size: var(--fs-sm);
+  padding: var(--sp-1) var(--sp-3);
+}
+
+/* ============================================================================
+   实心态变体
+   ============================================================================
+   🔴 新增（暗色门禁抓出来的）：
+      demo 原来用**行内 style** 写 `background: var(--success); color: #fff`
+      ⇒ 暗色下 --success 变浅（#6FAA7A），白字压上去只有 2.72:1
+      ⇒ 行内 style 还会**绕过 tokens 门禁**（门禁只扫 CSS 文件）
+
+   ⇒ 正确做法：把"实心底 + 白字"做成**变体类**，让暗色令牌能接管。
+      白字写在 `--text-on-*` 上（暗色下会变深色），而不是写死 #fff。
+   ============================================================================ */
+.badge--solid-success { background: var(--success); color: var(--text-on-solid); }
+.badge--solid-danger  { background: var(--danger);  color: var(--text-on-solid); }
+.badge--solid-warning { background: var(--warning); color: var(--text-on-solid); }
+
+/* 🔴 暗色下：--success / --danger 都**变浅**了（为的是在深底上更醒目）
+   ⇒ 白字压上去只有 2.72:1 ⇒ 实心态在暗色下必须换成**深字**。
+   ⚠️ 这不是"暗色就该反色"，而是 WCAG 的硬要求：
+      浅底必须配深字，否则对比度不够。 */
+/* 原有 `@media (prefers-color-scheme: dark)` 块已删：它的内容与上面三行
+   逐字相同（`--text-on-solid` 令牌化后暗色自己会变深），是死代码。 */

package/02-primitives/badge/demo.html

@@ -0,0 +1,101 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="data:,">
+<title>badge · 状态标记</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="../../02-primitives/button/button.css">
+<link rel="stylesheet" href="../../02-primitives/badge/badge.css">
+<style>
+.row { display: flex; gap: var(--sp-2); flex-wrap: wrap; align-items: center;
+         padding: var(--sp-4) 0; }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+  <h1>badge · 状态标记</h1>
+  <p class="lede">
+    badge 承载<strong>一个短状态词</strong>（"已停牌""审计中"）。
+    它<strong>不可点</strong> —— 要能点请用 <code>&lt;button class="badge badge--clickable"&gt;</code>
+    或 <code>&lt;a&gt;</code>，语义由元素本身承担。
+  </p>
+
+  <h2 class="rule-top">五个变体</h2>
+  <div class="row">
+    <span class="badge badge--neutral">草稿</span>
+    <span class="badge badge--success">已披露</span>
+    <span class="badge badge--warning">审计中</span>
+    <span class="badge badge--danger">已停牌</span>
+    <span class="badge badge--info">待复核</span>
+  </div>
+  <p class="small">
+    为什么是「淡底 + 深字」而不是「饱和底 + 白字」？因为 badge 只有 11–12px，
+    小字号在饱和底上对比度普遍不够。本库五组实测 4.82–6.76（浅色）· 5.25–10.59（暗色），
+    全部 ≥ 4.5，<strong>不需要为 badge 单独调一套色</strong>。
+  </p>
+
+  <h2 class="rule-top">用在真实语境里</h2>
+  <div class="row">
+    <span class="small">600519</span>
+    <span class="badge badge--success">已披露</span>
+    <span class="small">000001</span>
+    <span class="badge badge--danger">已停牌</span>
+    <span class="small">688981</span>
+    <span class="badge badge--warning">审计中</span>
+  </div>
+  <p class="small">
+    每一枚都<strong>自带文字</strong>（WCAG 1.4.1：不能只靠颜色区分）——
+    去掉颜色也能读懂，颜色只是冗余线索。
+  </p>
+
+  <h2 class="rule-top">两档尺寸</h2>
+  <div class="row">
+    <span class="badge badge--neutral">默认 11px</span>
+    <span class="badge badge--neutral badge--lg">较大 13px</span>
+  </div>
+  <p class="small">
+    只有两档。出现第三档说明信息密度没规划好
+    （与 <code>card</code> 的判断标准一致）。
+  </p>
+
+  <h2 class="rule-top">反例</h2>
+  <div class="box bad">
+    <h3>反例：饱和底 + 白字</h3>
+    <div class="row">
+      <span class="badge badge--solid-success">已披露</span>
+      <span class="badge badge--solid-danger">已停牌</span>
+      <span class="badge badge--solid-warning">>审计中</span>
+    </div>
+    <p class="small">
+      看起来"更醒目"，但白字在小字号饱和底上<strong>对比度普遍不足</strong>。
+      实测（<code>contrast.py</code>）：暗色下白字在 <code>--success</code> 上只有
+      <strong>2.72:1</strong>，远低于 4.5；浅色下是 6.39 达标 ——
+      也就是说<strong>这套写法在暗色下会直接失效</strong>，而看浅色时完全发现不了。
+      并且全页面只有这三个色块时，视觉噪声远大于信息量。
+    </p>
+  </div>
+
+  <div class="box bad">
+    <h3>反例：用 badge 装可点的东西</h3>
+    <p class="small">
+      <code>&lt;div class="badge badge--info" onclick="..."&gt;待复核&lt;/div&gt;</code>
+      —— div 加 onclick 对读屏是<strong>「没有角色的按钮」</strong>：
+      读不出来它是能点的，键盘也 Tab 不到。
+      要能点就用 <code>&lt;button&gt;</code> 或 <code>&lt;a&gt;</code>，样式照抄 <code>.badge</code>。
+    </p>
+  </div>
+
+  <h2 class="rule-top">强制高对比模式</h2>
+  <p class="small">
+    Windows 的高对比模式会覆盖底色。本组件在
+    <code>@media (forced-colors: active)</code> 下把边框换成
+    <code>currentColor</code> —— <strong>靠边框保住边界，不靠底色</strong>。
+    这一段无法在本机验证（需要系统级开关）。
+  </p>
+</main>
+</body>
+</html>

package/02-primitives/button/README.md

@@ -0,0 +1,99 @@
+# button
+
+| 字段 | 内容 |
+|---|---|
+| **来源** | 原创（依据 WCAG 2.1 + 实测诊断） |
+| **实测** | 对比度见下，全部由 `05-audit/contrast.py` 得出；44px 依据 WCAG 2.5.5 |
+| **适用** | 精简档 / B / C，纯 CSS，可整段复制 |
+| **依赖** | `01-tokens/tokens.css`  + `01-tokens/typography.css`（`.note` 提示框） + `01-tokens/page.css`（页面骨架：`.wrap` / `.lede` / `.note`） |
+
+---
+
+## 七态清单（按钮取的是这七个，不是九个）
+
+| # | 状态 | 实现 | 不做会怎样 |
+|---|---|---|---|
+| 1 | default | `.btn--primary` | — |
+| 2 | hover | `:hover` + `--accent-hover` | 用户不知道能点 |
+| 3 | active | `:active` 下沉 1px | 点了没反馈 |
+| 4 | **focus-visible** | `:focus-visible` 2px outline | **键盘用户彻底迷失** |
+| 5 | **disabled** | `:disabled` 明确色值（不用 opacity） | **点了没反应，以为坏了** |
+| 6 | **loading** | `[aria-busy]` + `pointer-events:none` | **重复提交** |
+| 7 | success | `data-state="success"`（约 1.2s） | 不知道成没成 |
+
+🔴 实测动机：某项目 的按钮**只有 default + hover 两态**，`:disabled` 0 处。
+用户不会抱怨"你缺 disabled 态"，只会觉得"这个按钮点了没反应，是不是坏了"。
+
+---
+
+## 用法
+
+```html
+<button class="btn btn--md btn--primary">提交</button>
+
+<!-- loading：宽度不变，防重复点击 -->
+<button class="btn btn--md btn--primary" aria-busy="true">
+  <span class="btn__label">提交</span>
+  <span class="btn__spinner"></span>
+</button>
+
+<!-- 图标按钮必须带 aria-label -->
+<button class="btn btn--icon btn--ghost" aria-label="关闭">
+  <svg ...></svg>
+</button>
+```
+
+变体：`primary` / `secondary` / `ghost` / `danger`
+尺寸：`sm`(32) / `md`(44) / `lg`(52)
+
+---
+
+## 🔴 最关键的一个判断：`disabled` 还是 `aria-disabled`
+
+这两个不是同义词，选错会直接伤到键盘用户。
+
+| | `disabled` 属性 | `aria-disabled="true"` |
+|---|---|---|
+| Tab 能聚焦 | ❌ 不能，从 tab 顺序移除 | ✅ 能 |
+| 屏幕阅读器 | 直接跳过，用户不知道有这个按钮 | 读到"不可用" |
+| 适用 | **永久**不可用（权限不足、功能下线） | **暂时**不可用（表单没填完） |
+
+**表单提交按钮应该用 `aria-disabled`**。理由：用户 Tab 到它，才知道"哦，还差点什么"；
+用 `disabled` 的话他永远找不到这个按钮，也不知道为什么提交不了。
+
+两个都不要的情况：**别用视觉上的"灰掉"来假装禁用**。灰了但还能点，是欺骗。
+
+---
+
+## 反例 —— 什么时候不该用
+
+- ❌ **一个视图里出现两个 `primary`** —— 有两个就等于没有重点。其余全降为 secondary/ghost。
+- ❌ **`danger` 做成和 `primary` 一样大** —— 破坏性动作不该被引导去点。
+- ❌ **普通操作加 `success` 态** —— 只有不可逆动作（提交、支付）需要确认反馈，其余是噪音。
+- ❌ **桌面端用 `btn--block`** —— 全宽按钮把视觉动线压成一条竖线。它是移动端方案。
+- ❌ **`ghost` 用在主路径上** —— ghost 的语义是"我不建议你点这个"，不是"这个比较淡"。
+
+---
+
+## 两个容易被跳过的细节
+
+**1. loading 时宽度不能变**
+
+常见做法是把文字换成 spinner，结果按钮缩窄 → 整行布局跳动。
+解法：文字 `visibility: hidden` 保留占位，spinner 绝对定位居中。
+
+**2. spinner 要豁免 `prefers-reduced-motion`**
+
+全局兜底会把动画压到 0.01ms，spinner 就停了 —— 用户会以为页面卡死。
+WCAG 的 reduced-motion 针对**大幅位移**（前庭功能障碍），
+小幅度原地旋转不属于此类。**放慢但保留，不要停。**
+
+这是"照抄规范"和"理解规范"的区别。
+
+---
+
+## 已记录的废弃写法
+
+详见 `button.css` 末尾。要点：
+`filter: brightness()` 当 hover / `transition: all` / `opacity` 当 disabled /
+loading 换文字 / hover 用 `scale()`。