agentcss 0.0.0-stage → 0.11.3

package/02-primitives/button/button.css

@@ -0,0 +1,353 @@
+/* ============================================================================
+   frontend-lib / 02-primitives / button / button.css
+   按钮 · 状态矩阵完整实现
+
+   依赖：01-tokens/tokens.css（必须先加载）
+   版本：A ✅ / B ✅ / C ✅  —— 纯 CSS，无 JS 依赖，可整段复制
+
+   🔴 关于"九态"的正确理解：不是每个组件都要九个态。
+      按钮取前六态 + success；容器/列表取后四态。混着套会做出多余的东西。
+
+      ┌ 交互元素（按钮、链接、开关）
+      │   default → hover → active → focus-visible → disabled → loading → success
+      └ 容器（列表、卡片区、表单体）
+          content → empty → loading → error → success
+
+      按钮没有 empty / error 态 —— "按钮是空的"没有意义。
+      容器没有 hover / active 态 —— 容器不响应按压。
+   ========================================================================= */
+
+/* ---------------------------------------------------------------- 基础
+   🔴 改用 **grid 叠放**（原 inline-flex + absolute 定位）：
+
+   实测反馈"按着不动，加载内容就叠上来了"。根因是：
+   inline-flex 容器里，文字**没有溢出保护**，
+   而 spinner 是 position:absolute 居中 —— 文字一长就溢出按钮边界，
+   与 spinner **物理重叠**，两个词叠在一起。
+
+   改法：把 label 与 spinner 放进**同一个 grid 单元**（grid-area: stack）。
+   这样：
+     · 物理上不可能重叠（同一格）
+     · 容器宽度 = max(两者) ⇒ 切换时宽度**自动不变**，不需要手算
+     · 不再依赖 absolute 定位 ⇒ 不会和 :active 的 transform 打架
+*/
+.btn {
+  /* 全部使用 token。出现任何硬编码的 px 色值都是分层崩了。 */
+  display: inline-grid;
+  grid-template-areas: "stack";
+  place-items: center;
+
+  font-family: inherit;
+  font-size: var(--fs-sm);
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+
+  /* 🔴 补回：改 grid 那一版把 height / padding 弄丢了，
+     而 .btn--sm/md/lg 才有它们 —— 于是「不写 size 类」的地方（弹窗按钮、
+     JS 生成的按钮）就只剩内容高度 + 零 padding，**文字直接顶着边框**。
+     实测反馈"框又小、文字顶着方框"，根因就在这里。
+
+     默认尺寸必须是**可用的**（44px 触摸目标），不该要求每个调用方都记得加 size 类。 */
+  min-height: 44px;
+  padding: 0 var(--sp-5);
+
+  border: 1px solid transparent;
+  border-radius: var(--r-sm);
+  cursor: pointer;
+  user-select: none;
+  text-decoration: none;
+
+  /* 🔴 兜底：即使内容异常长也不许溢出边界 */
+  overflow: hidden;
+  max-width: 100%;
+
+  /* 动效只用 token 里的那一组 —— 一源原则 */
+  transition: background-color var(--dur-fast) var(--ease-out),
+              border-color     var(--dur-fast) var(--ease-out),
+              color            var(--dur-fast) var(--ease-out),
+              transform        var(--dur-fast) var(--ease-out);
+}
+
+/* ---------------------------------------------------------------- 尺寸
+   三档。md 是 44px —— 不是随便定的：
+   WCAG 2.5.5 增强级要求触摸目标 >= 44x44，这是手指的物理尺寸，不是审美。
+   sm 只用在表格行内等密集处（那里用户用鼠标，不是手指）。
+   ---------------------------------------------------------------- */
+/* 🔴 每个变体都要同时写 min-height，且选择器用 **.btn.btn--xx 双类**
+     （特异度 0,2,0 > .btn 的 0,1,0 ⇒ 不依赖源码顺序，改文件也不会失效）
+     —— 原来的 .btn 上的 min-height:44px
+   在层叠里永远赢过 height，只写 height 的变体会被压回 44px，"小按钮"就没了。 */
+/* ============================================================================
+   🔴 **修正变体高度被压平**（clicktest 门禁实测：sm/md/lg 全是 44px）
+
+   真因（做了 5 组浏览器实验才定位，不是猜的）：
+     `.btn` 基类是 `display: inline-grid` + `grid-template-areas: "stack"`
+     ⇒ 网格行是 **auto**（由内容撑开）
+     ⇒ 变体里同时写 `min-height: 32px` **和** `height: 32px` 时，
+        **`height` 反而成了下限**，把 32px 顶不上去；
+     ⇒ 实测：单独把 `min-height` 压到 32px ⇒ 高度**立刻变成 32px** ✅
+        （加 `grid-template-rows: 32px` 也是 32，效果相同）
+
+   ⚠️ 教训（grid 容器特有）：
+      **grid/flex 容器上不要同时写 `height` 与 `min-height`** ——
+      `height` 会变成硬下限，变体就再也压不下去。
+      只写 `min-height`（下限可被内容顶大）才是变体该用的。
+
+   ⇒ 修法：变体**只保留 `min-height`**，删掉 `height`。
+   ============================================================================ */
+.btn.btn--sm {
+  /* 🔴 修正（button 契约抓到：命中区 60×32，违反 WCAG 2.5.5 AAA）
+
+     ⚠️ 上一轮我写的注释是**错的**：「命中区由基类的 min-height 44px 兜底」
+     —— 事实是 `.btn.btn--sm` 的**特异性 (0,2,0) 高于**基类 `.btn` (0,1,0)，
+     所以 `min-height: 32px` **把基类的 44px 盖掉了** ⇒ 命中区真的只有 32px。
+
+     ⭐ 正确做法（业界标准）：**视觉 32px，命中区 44px**，两者分开。
+       用 `::after` 伪元素在垂直方向各扩 6px（不占布局、不影响相邻元素）：
+
+           视觉高度 = min-height 32px   （看起来就是个小按钮）
+           命中区域 = 32 + 6 + 6 = 44px  （手指落点够大）
+
+       ⚠️ 为什么不用 `padding` 撑：会让按钮**真的变高**，
+          视觉上就不是"小按钮"了，与设计意图相反。
+       ⚠️ 为什么 `position: relative` 是必需的：
+          伪元素要相对按钮定位，按钮本身必须是定位上下文。 */
+  position: relative;
+  min-height: var(--sz-touch-sm, 32px);
+  padding: 0 var(--sp-3);
+  font-size: var(--fs-xs);
+}
+
+/* sm 变体的命中区扩展：垂直方向补足到 44px（WCAG 2.5.5 Level AAA） */
+.btn.btn--sm::after {
+  content: "";
+  position: absolute;
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+  top: 50%;
+  height: var(--sz-touch, 44px);
+  transform: translateY(-50%);
+  /* 伪元素不接收事件之外的任何样式；这里只是扩大命中区域 */
+}
+.btn.btn--md { min-height: 44px; padding: 0 var(--sp-5); }
+.btn.btn--lg { min-height: 52px; padding: 0 var(--sp-6); font-size: var(--fs-base); }
+
+/* ---------------------------------------------------------------- 变体 */
+
+/* primary：一个视图里只能有一个。有两个就等于没有重点。 */
+.btn--primary {
+  background: var(--accent);
+  color: var(--text-on-accent);   /* 白字压 accent = 5.87 AA（已实测） */
+}
+@media (hover: hover) and (pointer: fine) {
+.btn--primary:hover {
+  background: var(--accent-hover);   /* 白字压 hover = 7.73 AAA */
+}
+}
+/* secondary：次要动作。用边框区分，不是靠"更浅的底"。 */
+.btn--secondary {
+  background: var(--surface);
+  color: var(--text-primary);
+  border-color: var(--border-control);   /* 3.56 达标（UI 边界需 >= 3.0） */
+}
+@media (hover: hover) and (pointer: fine) {
+.btn--secondary:hover {
+  background: var(--surface-sunken);
+  border-color: var(--text-tertiary);
+}
+}
+/* ghost：最低优先级。没有边框也没有底 —— 靠文字色和间距存在。
+   用在"取消""暂不"这类用户不该被引导去点的动作。 */
+.btn--ghost {
+  background: transparent;
+  color: var(--text-secondary);
+}
+@media (hover: hover) and (pointer: fine) {
+.btn--ghost:hover {
+  background: var(--surface-sunken);
+  color: var(--text-primary);
+}
+}
+/* danger：破坏性动作。红底，且**永远不要**做成 primary 的大小。 */
+.btn--danger {
+  background: var(--danger);
+  /* 🔴 写死白字。暗色下 --danger 变亮（#e07a6e），
+     白字压在上面会看不清。改用 --text-on-accent（暗色下是深字）。 */
+  color: var(--text-on-accent);
+}
+@media (hover: hover) and (pointer: fine) {
+.btn--danger:hover {
+  /* 加深而不是变亮 —— 危险动作 hover 变亮会显得"更安全"，是反的。
+     🔴 深色模式下方向相反 —— 深底上"加深"等于消失，
+     所以暗色必须**变亮**（下方 @media dark 里覆盖）。 */
+  background: var(--danger-hover);
+}
+}
+/* ---------------------------------------------------------------- 状态 2：active（按下）
+   下沉 1px。幅度必须是 --lift-sm（1px），
+   用 4px、6px 会显得像在玩玩具 —— 这种"果冻感"是廉价感的主要来源。
+   ---------------------------------------------------------------- */
+.btn:active {
+  transform: translateY(var(--lift-sm));
+}
+
+/* ---------------------------------------------------------------- 状态 4：focus-visible
+   🔴 用 :focus-visible 而不是 :focus。
+   :focus 会让鼠标点击也冒出框，难看；:focus-visible 只在键盘导航时出现。
+
+   tokens.css 里已给全局兜底，这里显式写一遍是因为按钮是最该被看见焦点的元素。
+   ---------------------------------------------------------------- */
+.btn:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+/* ---------------------------------------------------------------- 状态 5：disabled
+   🔴 不要用 opacity。
+   opacity: 0.5 会让对比度变成不可控的随机数（取决于底下是什么）。
+   正确做法是明确指定一组"不可点"的色值。
+
+   对比度说明：WCAG 1.4.3 对 inactive 组件是豁免的，
+   所以这里的低对比度合规 —— 但文字仍要能读，因为用户需要知道"这里写的是什么"。
+   ---------------------------------------------------------------- */
+.btn:disabled,
+.btn[aria-disabled="true"] {
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);        /* 5.16 AA，仍可读 */
+  border-color: var(--border-decor);
+  cursor: not-allowed;
+}
+@media (hover: hover) and (pointer: fine) {
+.btn:disabled:hover,
+.btn[aria-disabled="true"]:hover {
+  background: var(--surface-sunken);   /* 关键：hover 不能有变化，否则看着像能点 */
+  transform: none;
+}
+}
+.btn:disabled:active,
+.btn[aria-disabled="true"]:active {
+  transform: none;                     /* 按下去也不许动 */
+}
+
+/* ---------------------------------------------------------------- 状态 6：loading
+   🔴 核心品味点：loading 时按钮宽度**不能变**。
+   常见做法是替换文字为 spinner，结果按钮缩窄 → 整行布局跳动 → 很难看。
+
+   解法：**label 与 spinner 放在同一个 grid 单元**（grid-area: stack）。
+   容器宽度 = max(两者) ⇒ 切换时宽度自动不变，且物理上不可能重叠。
+
+   ⚠️ 早期版本用的是「文字 visibility:hidden + spinner 绝对定位居中」，
+   **错在**：文字没有溢出保护，文案一长就溢出按钮边界，与 spinner 物理重叠
+   （实测反馈"按着不动，加载内容就叠上来了"）。absolute 还会和 :active
+   的 transform 打架。已改为 grid 叠放，见文件头。
+   ---------------------------------------------------------------- */
+.btn[aria-busy="true"] {
+  cursor: progress;
+  pointer-events: none;   /* 防重复提交 —— 这是 loading 态存在的真正理由 */
+}
+
+/* 🔴 label 与 spinner 都在 grid-area: stack ⇒ 同一格，物理上不可能重叠。
+
+   ⚠️ 这里**不能**写 `max-width: 100%`：
+   容器是 inline-grid（宽度由内容决定），label 又是 grid 单元
+   （宽度由容器决定）—— `max-width:100%` 构成**循环依赖**，
+   浏览器会把它解析成一个很小的值，于是**文字被压扁、按钮变窄**
+   （实测反馈"弹窗里按钮文字太大框太小"，就是它造成的）。
+
+   `min-width: 0` 才是 grid/flex item 该用的：允许收缩，但不给错误的约束。 */
+.btn__label {
+  grid-area: stack;
+  min-width: 0;
+}
+
+/* loading 时用 opacity 而不是 visibility：
+   opacity 可过渡（能做出淡入淡出），visibility 瞬间切换会显得"跳"。 */
+.btn[aria-busy="true"] .btn__label { opacity: 0; }
+
+.btn__spinner {
+  grid-area: stack;
+  opacity: 0;
+  width: 16px;
+  height: 16px;
+  border: 2px solid currentColor;
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: btn-spin 700ms linear infinite;
+}
+
+.btn[aria-busy="true"] .btn__spinner { opacity: 1; }
+
+@keyframes btn-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* 🔴 spinner 必须豁免 prefers-reduced-motion
+   tokens.css 的全局兜底会把动画压到 0.01ms —— 对位移类动效是对的，
+   但 spinner 停掉会让用户以为页面卡死。
+
+   WCAG 的立场：reduced-motion 针对的是**大幅位移**（前庭功能障碍），
+   spinner 是小幅原地旋转，不属于此类，应当保留。
+   这是"照抄规范"和"理解规范"的区别。 */
+@media (prefers-reduced-motion: reduce) {
+  .btn__spinner {
+    animation-duration: 1.2s !important;   /* 放慢但保留，不停 */
+  }
+}
+
+/* ---------------------------------------------------------------- 状态 7：success
+   短暂反馈（约 1.2s），需要 JS 加类再移除。
+   只在"动作不可逆且需要确认"时用（提交、支付）。
+   普通操作加 success 是噪音。
+   ---------------------------------------------------------------- */
+
+/* 🔴 与 combobox 同一处半自动改写事故，已修。
+     经过见 `docs/INVARIANT.md` I-8，不在这里重复第二份。 */
+.btn[data-state="success"] {
+  background: var(--success);
+  /* 🔴 暗色下底色变亮，写死的白字会看不清。 */
+  color: var(--text-on-accent);
+}
+.btn[data-state="success"] .btn__label { opacity: 1; }
+.btn[data-state="success"] .btn__spinner { opacity: 0; }
+
+/* ---------------------------------------------------------------- 图标按钮
+   正方形。必须带 aria-label，因为里面没有文字。
+   ---------------------------------------------------------------- */
+.btn--icon {
+  width: 44px;
+  padding: 0;
+}
+.btn--icon.btn--sm { width: 32px; }
+.btn--icon.btn--lg { width: 52px; }
+
+/* ---------------------------------------------------------------- 块级
+   移动端常用。注意：block 按钮在桌面端慎用 ——
+   全宽按钮会让页面的视觉动线变成一条竖线。
+   ---------------------------------------------------------------- */
+.btn--block {
+  display: flex;
+  width: 100%;
+}
+
+/* ============================================================================
+   废弃 / 反模式 —— 这些写法在本库内一律退回
+   =========================================================================
+   1. filter: brightness(1.08) 当 hover
+      实测来源：某项目 的 .send-btn 就是这么写的。
+      问题：hover 色变成不可控的计算结果，无法验证对比度，
+      且在不同底色上表现不一致。改用明确的 --accent-hover。
+
+   2. transition: all
+      会把 box-shadow、width 等一起动画化，性能和观感都失控。
+      逐个属性写，像上面基础段那样。
+
+   3. :disabled 用 opacity
+      对比度变成随机数。见上。
+
+   4. loading 时替换文字导致宽度变化
+      布局跳动。见上。
+
+   5. hover 用 transform: scale(1.05)
+      按钮"长大"是廉价感来源之一。要反馈就用 active 的下沉 1px。
+   ========================================================================= */

package/02-primitives/button/demo.html

@@ -0,0 +1,200 @@
+<!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>button · 七态矩阵</title>
+<!-- 直接引库内文件，不复制副本 —— token 一改这里同步生效。
+     要单文件部署到 某项目 时，把这两个 CSS 的内容粘进 <style>
+即可。 --><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="button.css"><style>body { margin: 0; padding: var(--sp-7) var(--sp-5); background: var(--paper);
+         color: var(--text-primary); font: var(--fs-base)/var(--lh-base) system-ui, sans-serif; }
+.grid { display: grid; gap: var(--sp-3); grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+.cell { background: var(--surface); border: 1px solid var(--border-decor);
+          border-radius: var(--r-md); padding: var(--sp-5); }
+.cell h3 { margin: 0 0 var(--sp-1); font-size: var(--fs-sm); font-weight: 500; }
+.cell p { margin: 0 0 var(--sp-4); font-size: var(--fs-xs);
+             color: var(--text-tertiary); line-height: 1.55; }
+.row { display: flex; gap: var(--sp-3); flex-wrap: wrap; align-items: center; }
+.cmp { display: grid; gap: var(--sp-4); grid-template-columns: 1.55fr 1fr; }
+@media (max-width: 640px) {.cmp { grid-template-columns: 1fr; }
+
+ }
+.cmp>div { padding: var(--sp-4); border-radius: var(--r-md); border: 1px solid var(--border-decor); }
+.bad { background: var(--surface-sunken); }
+.good { background: var(--surface-sunken); }
+.cmp h3 { margin: 0 0 var(--sp-3); font-size: var(--fs-sm); font-weight: 500; }
+.bad h3 { color: var(--danger); }
+.good h3 { color: var(--success); }
+/* 反例演示用 */
+.btn--naive { height: 44px; padding: 0 var(--sp-5); border: none; border-radius: var(--r-sm);
+                background: var(--accent); color: #fff; cursor: pointer; font-size: var(--fs-sm);
+                transition: all 200ms; }
+.btn--naive:hover { filter: brightness(1.08); transform: scale(1.05); }
+.btn--naive:disabled { opacity: 0.5; }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+
+  <h1>button · 七态矩阵</h1>
+  <p class="lede">
+    按钮取七态，不是九态。另外两态（empty / error）属于容器，按钮没有"空"的概念。
+  </p>
+
+  <div class="note">
+    实测动机：某项目 的按钮只有 default + hover 两态，<code>:disabled</code> 0 处。
+    用户不会抱怨"你缺 disabled 态"，只会觉得"这个按钮点了没反应，是不是坏了"。
+  </div>
+
+  <h2 class="rule-bottom">七态</h2>
+  <div class="grid">
+
+    <div class="cell">
+      <h3>1. default</h3>
+      <p>静止。accent 底 + 白字，实测 5.87 AA。</p>
+      <button class="btn btn--md btn--primary">提交</button>
+    </div>
+
+    <div class="cell">
+      <h3>2. hover</h3>
+      <p>明确的 <code>--accent-hover</code> 色值（白字 7.73 AAA），不是 brightness 计算。</p>
+      <button class="btn btn--md btn--primary">鼠标移上来</button>
+    </div>
+
+    <div class="cell">
+      <h3>3. active</h3>
+      <p>下沉 1px。<strong>只用 1px</strong>——用 4px/6px 会有果冻感，那是廉价感的主要来源。</p>
+      <button class="btn btn--md btn--primary">按住不放</button>
+    </div>
+
+    <div class="cell">
+      <h3>4. focus-visible</h3>
+      <p>键盘 Tab 到这里才出现。<code>:focus</code> 会让鼠标点击也冒框，所以用 <code>-visible</code>。</p>
+      <button class="btn btn--md btn--primary">Tab 键切过来</button>
+    </div>
+
+    <div class="cell">
+      <h3>5. disabled</h3>
+      <p>明确色值，<strong>不用 opacity</strong>——opacity 让对比度变成不可控的随机数。hover 无任何变化。</p>
+      <button class="btn btn--md btn--primary" disabled>已禁用</button>
+    </div>
+
+    <div class="cell">
+      <h3>6. loading</h3>
+      <p>宽度不变（label 与 spinner 同一 grid 单元，容器宽 = max(两者)）。<code>pointer-events:none</code> 防重复提交。</p>
+      <button class="btn btn--md btn--primary" aria-busy="true">
+        <span class="btn__label">提交</span><span class="btn__spinner"></span>
+      </button>
+    </div>
+
+    <div class="cell">
+      <h3>7. success</h3>
+      <p>仅用于不可逆动作（提交、支付）。普通操作加这个是噪音。</p>
+      <button class="btn btn--md btn--primary" data-state="success">
+        <span class="btn__label">已提交</span><span class="btn__spinner"></span>
+      </button>
+    </div>
+
+    <div class="cell">
+      <h3>交互演示</h3>
+      <p>点一下：default → loading（1.4s）→ success（1.2s）→ 复位。注意宽度全程不变。</p>
+      <button class="btn btn--md btn--primary" id="demo">
+        <span class="btn__label">点我走一遍</span><span class="btn__spinner"></span>
+      </button>
+    </div>
+
+  </div>
+
+  <h2 class="rule-bottom">变体</h2>
+  <div class="row">
+    <button class="btn btn--md btn--primary">primary</button>
+    <button class="btn btn--md btn--secondary">secondary</button>
+    <button class="btn btn--md btn--ghost">ghost</button>
+    <button class="btn btn--md btn--danger">danger</button>
+  </div>
+  <p style="font-size:var(--fs-xs); color:var(--text-tertiary); margin-top:var(--sp-3)">
+    一个视图里只能有一个 primary。danger 不应该做得和 primary 一样显眼。
+  </p>
+
+  <h2 class="rule-bottom">尺寸</h2>
+  <div class="row">
+    <button class="btn btn--sm btn--primary">sm 32</button>
+    <button class="btn btn--md btn--primary">md 44</button>
+    <button class="btn btn--lg btn--primary">lg 52</button>
+  </div>
+  <p style="font-size:var(--fs-xs); color:var(--text-tertiary); margin-top:var(--sp-3)">
+    md = 44px 是 WCAG 2.5.5 增强级的触摸目标尺寸，来自手指物理尺寸，不是审美。
+    sm 只在表格行内等鼠标场景用。
+  </p>
+
+  <h2 class="rule-bottom">对比：常见的错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="box bad">
+      <h3>常见写法（某项目 现状）</h3>
+      <div class="row">
+        <button class="btn--naive">hover 看我</button>
+        <button class="btn--naive" disabled>disabled 看我</button>
+      </div>
+      <p style="font-size:var(--fs-xs); margin:var(--sp-3) 0 0; color:var(--text-secondary)">
+        <code>filter: brightness(1.08)</code> —— hover 色是算出来的，无法验证对比度，不同底色表现不一致。<br>
+        <code>transform: scale(1.05)</code> —— 按钮"长大"，廉价感。<br>
+        <code>opacity: 0.5</code> —— 对比度变成随机数。<br>
+        <code>transition: all</code> —— 所有属性一起动画，性能和观感失控。
+      </p>
+    </div>
+    <div class="good">
+      <h3>本库写法</h3>
+      <div class="row">
+        <button class="btn btn--md btn--primary">hover 看我</button>
+        <button class="btn btn--md btn--primary" disabled>disabled 看我</button>
+      </div>
+      <p style="font-size:var(--fs-xs); margin:var(--sp-3) 0 0; color:var(--text-secondary)">
+        明确的 <code>--accent-hover</code> 色值，实测 7.73 AAA。<br>
+        active 只下沉 1px。<br>
+        disabled 用明确的低对比色组，仍可读。<br>
+        逐属性写 transition，只动颜色和 transform。
+      </p>
+    </div>
+  </div>
+
+  <h2 class="rule-bottom">一个容易被跳过的判断：disabled 还是 aria-disabled</h2>
+  <div class="grid">
+    <div class="cell">
+      <h3>disabled 属性</h3>
+      <p>从 Tab 顺序移除，键盘用户永远找不到它。适合<strong>永久</strong>不可用（权限不足）。</p>
+      <button class="btn btn--md btn--secondary" disabled>功能未开放</button>
+    </div>
+    <div class="cell">
+      <h3>aria-disabled="true"</h3>
+      <p>保留可聚焦，屏幕阅读器读"不可用"。表单提交按钮<strong>应该用这个</strong>——用户 Tab 到它才知道"还差点什么"。</p>
+      <button class="btn btn--md btn--secondary" aria-disabled="true">请先填写金额</button>
+    </div>
+  </div>
+
+  <h2 class="rule-bottom">spinner 与 prefers-reduced-motion</h2>
+  <div class="note">
+    系统开启"减少动效"后，全局兜底会把动画压到 0.01ms——spinner 就停了，用户会以为页面卡死。<br><br>
+    WCAG 的 reduced-motion 针对的是<strong>大幅位移</strong>（前庭功能障碍），
+    小幅原地旋转不属于此类。本库的做法是<strong>放慢到 1.2s 但保留，不停</strong>。<br><br>
+    这是"照抄规范"和"理解规范"的区别。
+  </div>
+
+<script>
+  var b = document.getElementById('demo');
+  b.addEventListener('click', function () {
+    if (b.getAttribute('aria-busy') === 'true') return;
+    b.setAttribute('aria-busy', 'true');
+    setTimeout(function () {
+      b.removeAttribute('aria-busy');
+      b.setAttribute('data-state', 'success');
+      b.querySelector('.btn__label').textContent = '已提交';
+      setTimeout(function () {
+        b.removeAttribute('data-state');
+        b.querySelector('.btn__label').textContent = '点我走一遍';
+      }, 1200);
+    }, 1400);
+  });
+</script></main>
+</body>
+</html>