agentcss 0.0.0-stage → 0.11.2

package/01-tokens/behavior/typeahead.js

@@ -0,0 +1,124 @@
+/**
+ * typeahead.js — 「首字母跳转 / 连续打字定位」微行为核
+ *
+ * ==========================================================================
+ * 🔴 为什么要抽成核（实测，不是推测）
+ * --------------------------------------------------------------------------
+ *   迁移前只有两处实现，而它们**各做了一半**：
+ *
+ *     · select：累积多字符前缀（"co" ⇒ components），但**不循环** ——
+ *       连按两次同一个字母，游标**不动**（用户以为卡了）
+ *     · tree：  单字符跳转且会往后找，但**不累积** ——
+ *       打 "co" 只会先跳到 c 项再跳到 o 项，永远到不了 "components"
+ *
+ *   ⇒ 两处都缺另一半，而且缺的**不是同一半**。
+ *     这正是"同一件事写 N 份"的典型代价：没有一处是完整的，
+ *     而"完整"这件事没有任何地方定义过。
+ *
+ * ==========================================================================
+ * 边界（照 APG 的 typeahead 约定，不是我的设计）
+ * --------------------------------------------------------------------------
+ *   ① 打一个可打印字符 ⇒ 跳到**下一个**名称以该字符开头的项（会绕回）
+ *   ② 快速连打多个字符 ⇒ 缓冲**累积**，按前缀匹配
+ *   ③ 连打**同一个**字符 ⇒ 在匹配项之间**循环**（不是停在原地）
+ *   ④ 停顿超过 `timeout`（默认 500ms）⇒ 缓冲清空，重新累积
+ *   ⑤ 禁用项不参与匹配
+ *   ⑥ 不匹配 ⇒ 不动焦点，也不报错（APG 不要求"没找到"有任何反馈）
+ *
+ * ==========================================================================
+ * 用法
+ * --------------------------------------------------------------------------
+ *   var ta = flTypeahead({
+ *     items:  function () { return options; },        // 候选集（按视觉顺序）
+ *     textOf: function (x) { return x.textContent; }, // 项 → 用于匹配的文本
+ *     usable: function (x) { return !x.disabled; },   // 可选：跳过禁用项
+ *     timeout: 500,                                   // 缓冲保留时长（ms）
+ *     onHit: function (i, item, buf) { setActive(i); }
+ *   });
+ *   ta.type(ch);        // 喂一个字符，返回命中索引（没命中 -1）
+ *   ta.clear();         // 主动清空缓冲（关闭/重开时调）
+ *   ta.destroy();       // 清掉定时器
+ *
+ * ⚠️ 核**不监听键盘**：什么时候算"打字"由组件决定
+ *    （本组件的 Enter/Space/Tab 各有语义，核不该抢）。
+ *
+ * ==========================================================================
+ * ⚠️ 注入块里的注释会**被复制进每个使用点**（gzip 也要算）
+ * --------------------------------------------------------------------------
+ *   ⇒ 长解释一律写在**本文件头**（BEGIN 标记之外），注入块内只留一行提示。
+ *
+ * ④ 为什么"连打同一个字符"要特判：不特判的话 buf 会变成 "bb"，
+ *    而没有任何项以 "bb" 开头 ⇒ 连按两次同一个字母就再也匹配不上，
+ *    用户眼里就是"按第二次没反应"。按首字符匹配 + 从当前项之后找 ⇒ 变成循环。
+ * ④b 超时清空**只清缓冲、不清 last**：清空后重新打字仍应"从当前项往后找"，
+ *    否则会突然跳回第一个匹配项（用户眼里就是"乱跳"）。
+ *
+ * ==========================================================================
+ * 约束：ES5 · 零依赖 · 可被整块注入 · 不新增任何全局
+ * ==========================================================================
+ */
+/* ==== BEHAVIOR CORE BEGIN: typeahead ==== */
+var flTypeahead = function (opts) {
+  var opt = opts || {};
+  var items = opt.items || function () { return []; };
+  var textOf = opt.textOf || function (x) { return String((x && x.textContent) || ''); };
+  var usable = opt.usable || function () { return true; };
+  var timeout = opt.timeout || 500;
+  var onHit = opt.onHit || function () {};
+  var buf = '';
+  var timer = null;
+  var last = -1;
+
+  function stop() {
+    if (timer) { clearTimeout(timer); timer = null; }
+  }
+
+  /* 连打同一字符 ⇒ 只按首字符匹配（理由见文件头 ③④）*/
+  function repeated(s) {
+    if (s.length < 2) return false;
+    for (var i = 1; i < s.length; i++) {
+      if (s.charAt(i) !== s.charAt(0)) return false;
+    }
+    return true;
+  }
+
+  function find(needle) {
+    var l = items() || [];
+    var n = l.length;
+    if (!n) return -1;
+    for (var k = 0; k < n; k++) {
+      var i = (last + 1 + k) % n;      /* ① 从当前项之后开始 ⇒ 会绕回 */
+      if (!usable(l[i])) continue;     /* ⑤ */
+      if (textOf(l[i]).toLowerCase().indexOf(needle) === 0) return i;
+    }
+    return -1;                          /* ⑥ */
+  }
+
+  function type(ch) {
+    if (!ch) return -1;
+    buf += String(ch).toLowerCase();    /* ② */
+    stop();
+    timer = setTimeout(clear, timeout); /* ④ */
+    var needle = repeated(buf) ? buf.charAt(0) : buf;   /* ③ */
+    var i = find(needle);
+    if (i >= 0) {
+      last = i;
+      onHit(i, (items() || [])[i], buf);
+    }
+    return i;
+  }
+
+  /* 只清缓冲，不清 last（理由见文件头）*/
+  function clear() {
+    buf = '';
+    stop();
+  }
+
+  return {
+    type: type,
+    clear: clear,
+    buffer: function () { return buf; },
+    destroy: function () { stop(); },
+  };
+};
+/* ==== BEHAVIOR CORE END: typeahead ==== */

package/01-tokens/focus-ring-demo.html

@@ -0,0 +1,133 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="color-scheme" content="light dark">
+<title>焦点环 ·· frontend-lib</title>
+<link rel="icon" href="data:,">
+<link rel="stylesheet" href="tokens.css">
+<link rel="stylesheet" href="typography.css">
+<link rel="stylesheet" href="focus-ring.css">
+<link rel="stylesheet" href="scrollbar.css">
+<link rel="stylesheet" href="../01-tokens/page.css">
+<style>
+table { width: 100%; border-collapse: collapse; font-size: var(--fs-sm); margin: 0 0 var(--sp-4); }
+th, td { text-align: left; padding: var(--sp-2) var(--sp-3);
+           border-bottom: 1px solid var(--border-decor); }
+th { font-size: var(--fs-xs); color: var(--text-secondary); font-weight: 500; }
+.ok { color: var(--success); }
+.no { color: var(--danger); }
+/* 🔴 读屏专用：视觉隐藏但**仍在无障碍树里** （不能用 display:none —— 那会让读屏也读不到） */
+.fr-sr {
+    position: absolute; width: 1px; height: 1px;
+    padding: 0; margin: -1px; overflow: hidden;
+    clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;
+  }
+.fr-field { position: relative; display: inline-flex; }
+.row { display: flex; gap: var(--sp-3); flex-wrap: wrap; align-items: center;
+         margin: 0 0 var(--sp-4); }
+.btn {
+    min-height: 44px; padding: var(--sp-2) var(--sp-4); font: inherit;
+    font-size: var(--fs-sm); color: var(--text-on-accent);
+    background: var(--accent); border: 0; border-radius: var(--r-sm); cursor: pointer;
+  }
+.btn--ghost { background: var(--surface); color: var(--text-primary);
+                border: 1px solid var(--border-control); }
+.btn--round { border-radius: 50%; width: 44px; padding: 0; }
+input[type="text"], input[type="email"] {
+    min-height: 44px; padding: var(--sp-2) var(--sp-3); font: inherit;
+    font-size: var(--fs-sm); color: var(--text-primary);
+    background: var(--surface); border: 1px solid var(--border-control);
+    border-radius: var(--r-sm); max-width: 260px;
+  }
+a { color: var(--accent); }
+.tip { font-size: var(--fs-xs); color: var(--text-tertiary); }
+</style>
+</head>
+<body class="page page">
+<div class="wrap">
+
+  <h1>焦点环</h1>
+  <p class="lede">
+     <code></code>。<b>按 Tab 键</b>体验，<b>点鼠标</b>不会显示。
+  </p>
+
+  <h2 class="rule-top">1 · 基本形态</h2>
+  <p class="note">
+    <code>:focus-visible</code> —— <b>只给键盘用户看</b>，鼠标点击不出现。
+    这正是它比 <code>:focus</code> 好的地方（WCAG 2.4.7 只要求"键盘操作时有可见焦点"）。
+  </p>
+  <div class="row">
+    <button class="btn" type="button">按钮</button>
+    <button class="btn btn--ghost" type="button">次要按钮</button>
+    <button class="btn btn--ghost btn--round" type="button" aria-label="圆形按钮">◎</button>
+    <!-- 🔴 a11y 门禁抓到：<input> 只有 placeholder，没有可访问名称
+         ⚠️ **placeholder 不是 label**（WCAG 3.3.2 / 4.1.2）：
+           占位符在输入后就消失了，读屏软件也未必会念它。
+         ⇒ 补一个 <label for>；视觉上用 .sr-only 隐藏（不改变布局）。 -->
+    <span class="fr-field">
+      <label class="fr-sr" for="fr-demo-input">示例输入框</label>
+      <input id="fr-demo-input" type="text" placeholder="输入框">
+    </span>
+    <a href="#">链接</a>
+  </div>
+  <p class="tip">
+    试试：先点一下页面空白处（清掉焦点），再按 <b>Tab</b>。
+  </p>
+
+  <h2 class="rule-top">2 · 为什么用 <code>outline</code> 而不是 <code>box-shadow</code></h2>
+  <table>
+    <tr><th>做法</th><th>是否占布局</th><th>跟随圆角</th><th>高对比度模式</th></tr>
+    <tr><td><code>outline</code> ✅</td>
+        <td class="ok">不占</td><td class="ok">自动跟随</td><td class="ok">浏览器自动加强</td></tr>
+    <tr><td><code>box-shadow</code></td>
+        <td class="no">占（会引起回流）</td><td class="no">要自己设</td><td class="no">不响应</td></tr>
+  </table>
+  <p class="note">
+    关键差别：<code>box-shadow</code> <b>会占布局</b> ⇒ 聚焦时元素尺寸变化 ⇒
+    周围内容<b>回流</b>。焦点环是<b>纯视觉提示</b>，不该推动任何东西。
+  </p>
+
+  <h2 class="rule-top">3 · 单一真相源</h2>
+  <p class="note">
+    全库的焦点环只认这三个令牌（<code>01-tokens/focus-ring.css</code>）：
+  </p>
+  <table>
+    <tr><th>令牌</th><th class="num">值</th><th>作用</th></tr>
+    <tr><td><code>--focus-ring-width</code></td><td class="num">2px</td><td>环的粗细</td></tr>
+    <tr><td><code>--focus-ring-offset</code></td><td class="num">2px</td><td>环离元素的距离</td></tr>
+    <tr><td><code>--focus-ring-color</code></td><td class="num">→ accent</td><td>环的颜色（跟随主题）</td></tr>
+  </table>
+  <p class="note">
+    要改焦点环的观感，<b>只改这三个令牌</b>，不要去每个组件里改。
+    <br>（实测：改造前全库有 <b>33 处</b> <code>:focus-visible</code>，
+    其中 6 处已是统一的 <code>2px solid var(--accent)</code>，
+    其余是散落的写法 ⇒ 现在统一到一处。）
+  </p>
+
+  <h2 class="rule-top">4 · 暗色下的加强</h2>
+  <p class="note">
+    暗色底上纯 outline 可能对比不足 ⇒ 加一层
+    <code>box-shadow: 0 0 0 1px rgba(255,255,255,.9)</code> 的内描边。
+    <br>⚠️ 用 box-shadow <b>而不是改 outline</b>，这样<b>仍然不占布局</b>。
+  </p>
+
+  <h2 class="rule-top">5 · 焦点不被遮住（WCAG 2.4.11）</h2>
+  <p class="note">
+    固定头 / 吸底栏可能盖住聚焦的元素 ⇒
+    给所有可聚焦元素加了 <code>scroll-margin-block</code>，
+    浏览器聚焦时会<b>自动留出空间</b>。
+  </p>
+
+  <h2 class="rule-top">6 · 禁区：不得裸写 <code>outline: none</code></h2>
+  <p class="note">
+    那会让键盘用户<b>完全看不到焦点</b>。
+    若必须去掉默认环，必须在<b>同一规则里</b>立刻给出替代样式。
+    <br><b>本库现状</b>：4 处 <code>outline:none</code>，
+    <span class="ok">全部紧跟替代样式 ✅</span>（门禁会持续盯这个）。
+  </p>
+
+</div>
+</body>
+</html>

package/01-tokens/focus-ring.css

@@ -0,0 +1,102 @@
+/* ============================================================================
+   focus-ring.css — 焦点环（全局基础设施 ·
+   ----------------------------------------------------------------------------
+   🔴 判据：WCAG 2.4.13 Focus Appearance。
+   ============================================================================
+   ⭐ 依据
+   ----------------------------------------------------------------------------
+   · **WCAG 2.4.7 Focus Visible**（A 级）—— 键盘操作必须有可见焦点
+   · **WCAG 2.4.11 Focus Not Obscured (Minimum) / 2.4.13 (Enhanced)**
+     —— 焦点元素**不能被固定元素遮住**（悬浮头/吸底栏会盖住）
+   · **WCAG 1.4.11 非文本对比** —— 焦点指示器需 ≥ 3:1
+   · **`:focus-visible` 的语义** —— **只给键盘用户看**，
+     鼠标点击不显示（这正是它比 `:focus` 好的地方）
+
+   ⚠️ 为什么用 `outline` 而不是 `box-shadow`
+   · `outline` **不占布局空间** ⇒ 聚焦时**不会引起回流**（`box-shadow` 会）
+   · `outline` 会**自动跟随元素的 `border-radius`**（现代浏览器）
+   · `outline` 是**系统级**的：高对比度模式下浏览器会自动加强它
+   ⇒ 通行做法是 `outline`，不是自绘的 box-shadow。
+
+   ⚠️ 禁区：**不得裸写 `outline: none`**
+   那会让键盘用户**完全看不到焦点**。
+   若必须去掉默认环，必须在**同一规则里**立刻给出替代样式。
+   （本文件末尾有一道门禁扫这个。）
+   ========================================================================== */
+
+:root {
+  /* 🔴 单一真相源：全库的焦点环只认这三个令牌 */
+  --focus-ring-width:   2px;
+  --focus-ring-offset:  2px;
+  --focus-ring-color:   var(--accent);
+  --focus-ring-inset:   rgba(255, 255, 255, .9);   /* 暗色下在深底上更清楚 */
+}
+
+/* ============================================================================
+   一、默认焦点环
+   ----------------------------------------------------------------------------
+   ⚠️ 用 `:focus-visible` 而不是 `:focus`：
+   键盘 Tab 才出现，鼠标点击不出现 —— 这正是 WCAG 想要的行为。
+   ========================================================================== */
+:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+  outline-offset: var(--focus-ring-offset);
+}
+
+/* ============================================================================
+   二、暗色下的加强
+   ----------------------------------------------------------------------------
+   暗色底上纯 `outline` 可能不够清楚（对比不足）⇒ 加一层内描边。
+   ⚠️ 用 `box-shadow` 而不是改 outline —— 这样**不占布局**。
+   ==========================================================================
+   🔴 暗色改为纯 CSS 表达（见 docs/BENCHMARK.md 一、二节）
+   ----------------------------------------------------------------------------
+   ⚠️ 两个选择器都要写：
+     · data-theme-current = **解析后**生效的明暗（由 JS 落，覆盖"跟随系统"）
+     · data-theme         = **使用者显式选的**（纯 CSS，不加载 JS 也成立）
+     只写前者 ⇒ 不加载 JS 时强制暗色的页面拿不到加强；只写后者 ⇒ 跟随系统
+     进入的暗色拿不到加强。两个都不能省。
+
+   🔴 `data-theme` 两项**不写 `:root` 限定**：暗色可挂在任意容器上
+     （RFC-THEME-SCOPE D1）。`data-theme-current` 仍限 `:root` —— 那是 JS 落在根上的。 */
+[data-theme="dark"] :focus-visible,
+[data-theme="dark"]:focus-visible,
+:root[data-theme-current="dark"] :focus-visible,
+:root[data-theme-current="dark"]:focus-visible {
+  outline-color: var(--accent-hover);
+  box-shadow: 0 0 0 1px var(--focus-ring-inset);
+}
+
+/* ============================================================================
+   三、焦点不被遮住（WCAG 2.4.11）
+   ----------------------------------------------------------------------------
+   固定头/吸底栏可能盖住聚焦元素。
+   ⇒ 给这些固定元素加 `scroll-margin`，聚焦时浏览器会自动留出空间。
+   ========================================================================== */
+:where(a, button, input, select, textarea, [tabindex]) {
+  scroll-margin-block: var(--focus-ring-offset) 5vh;
+}
+
+/* ============================================================================
+   四、只在键盘时"上浮"（可选的增强）
+   ----------------------------------------------------------------------------
+   聚焦时轻微提亮，帮助用户追踪焦点在长内容里的位置。
+   ⚠️ 用 `transition` 且尊重 reduced-motion（见 charter 07）。
+   ========================================================================== */
+@media (prefers-reduced-motion: no-preference) {
+  :where(a, button, [role="button"], [role="tab"]) {
+    transition: outline-offset var(--dur-fast) var(--ease-out);
+  }
+  :where(a, button, [role="button"], [role="tab"]):focus-visible {
+    outline-offset: calc(var(--focus-ring-offset) + 1px);
+  }
+}
+
+/* ============================================================================
+   五、工具类：给需要"内嵌焦点环"的场景（如已有一层边框的按钮）
+   ----------------------------------------------------------------------------
+   用 `outline-offset: -2px` 把环画在**元素内侧**，不撑大布局。
+   ========================================================================== */
+.focus-inset:focus-visible {
+  outline-offset: calc(var(--focus-ring-width) * -1);
+}

package/01-tokens/page.css

@@ -0,0 +1,244 @@
+/* ============================================================================
+   frontend-lib / 01-tokens / page.css
+   页面骨架（跨页面共享的"全局"层）
+
+   依赖：tokens.css（只用变量，不写死值）
+   版本：A ✅ / B ✅ / C ✅
+
+   🔴🔴 为什么要有这个文件（0.4.2 · 实测事故驱动）
+   ----------------------------------------------------------------------------
+   事故：用本库做十几页的成套页面，改一处"全局"的东西，整批立刻崩。
+
+   复盘结论不是"模型笨"，而是**这个库根本没有"全局"**：
+   「页面骨架」被 33 个页面**各抄了一份**在内联 <style> 里。实测（脚本量过）：
+
+     选择器      出现在   写法种数
+     h1          36 页     8
+     h2          35 页    11
+     .wrap       33 页    16   ← 列宽从 680px 到 900px 有 13 个不同数字
+     body        32 页     9
+     code        24 页     9
+     .lede       21 页     7   ← typography.css 里**已经有了**，页面还在重抄
+     .note       21 页    10   ← 同上
+     .box        13 页     2
+
+   于是"改全局"这件事在物理上不可能成立：
+   没有一处可改，只有 33 处要改 —— 漏一处就是不一致，改错一处就是崩。
+
+   本文件把上面这些收编成**一处定义**。页面不再声明它们，
+   改这里（或改对应令牌）⇒ 全部页面一起变。
+   ============================================================================
+
+   🔴 为什么全部挂在 `.page` 下面（作用域，不是偷懒）
+   ----------------------------------------------------------------------------
+   裸标签选择器（`h1 {}`）的作用域是**整个文档**。
+   本库若留下这种规则，宿主页面后面怎么改都会被它影响
+   （05-audit/bleed-gate.py 就是拦这个的，它禁止组件 CSS 里的裸标签）。
+
+   骨架也必须先遵守这条 ⇒ 全部写成 `.page h1`、`.page .wrap`。
+   用法：`<body class="page">` 才生效 —— **不引就不生效**，
+   宿主页面不会莫名其妙被改。
+
+   代价：每个页面要写一次 `class="page"`。
+   收益：库对宿主页面**零副作用**，且骨架仍然只有一处定义。
+   这两件事没有第三个选项（要么污染全局，要么显式挂载），这里选后者。
+   ============================================================================
+
+   ⚠️ 加载顺序：本文件要放在 tokens.css / typography.css **之后**、
+      组件 CSS 与页面内联 <style> **之前**。
+      这样组件若要覆盖骨架，靠"后来者同特异性胜出"就能做到，不需要 !important。
+   ========================================================================= */
+
+/* ============================================================================
+   1. 页面框（body）
+   ----------------------------------------------------------------------------
+   众数写法是 `background: var(--paper); margin: 0; padding: var(--sp-7) var(--sp-5)`
+   （10/32 页）。这里在众数基础上补两件众数里漏掉、但真机上必需的事：
+
+     ① safe-area：iOS 有刘海/底部横条的机型上，
+        不写 env() 的内容会被刘海和横条压住（实测 10-review/ios 就是这个原因）。
+        env() 在无安全区的设备上求值为 0 ⇒ 对普通机型**无副作用**。
+
+     ② 字体：众数写法**没有** font-family / font-size，
+        靠浏览器默认（Times 一类的衬线默认字体，16px）。
+        页面因此在不同系统上观感不一致 ⇒ 这里显式落到令牌上。
+   ========================================================================= */
+.page {
+  margin: 0;
+  /* 🔴 两行是有顺序的，别合并、别调换：
+     先 100vh（所有浏览器都认），再 100dvh（动态视口，新浏览器覆盖上一行）。
+     只用 100vh 时，iOS Safari 收起地址栏后 100vh 不跟着变 ⇒ 底部留白
+     （10-review/ios 就是为这个才单独写了一份 body —— 现在回到骨架里）。 */
+  min-height: 100vh;
+  min-height: 100dvh;
+  background: var(--paper);
+  color: var(--text-primary);
+  font-family: var(--sans);
+  font-size: var(--fs-base);
+  line-height: var(--lh-base);
+
+  /* iOS 横屏会自动放大字号，导致布局跟竖屏不一致 —— 关掉这个行为。 */
+  -webkit-text-size-adjust: 100%;
+
+  padding-block: calc(env(safe-area-inset-top, 0px) + var(--sp-6))
+                 calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));
+  padding-inline: max(env(safe-area-inset-right, 0px), var(--sp-4))
+                  max(env(safe-area-inset-left, 0px), var(--sp-4));
+}
+
+/* ============================================================================
+   1b. 盒模型（`border-box`）—— 只在 .page 范围内生效
+   ----------------------------------------------------------------------------
+   🔴 0.4.2 补。实测证据（02-primitives/date-range/demo.html @393px）：
+     `.drange__input { width: 100%; padding: 0 var(--sp-3); border: 1px }`
+     算出来内容是 162.08px，**实际盒宽 188px**（162 + 12×2 + 1×2）
+     ⇒ 比它的容器宽 26px ⇒ 两个日期框并排时把整页撑出横向滚动。
+
+   根因不是这一个组件写错了，而是**全库没有统一的盒模型**：
+   翻遍 01/02/03/04/09，`box-sizing` 只出现 5 次，都是某一处临时补的
+   （input.css / switch.css / dropdown.css / overlay.css / model-viewer.css）。
+   ⇒ 谁记得写谁没事，谁忘了谁静默溢出 —— 又是一次"漏一处就崩"。
+
+   ⚠️ 为什么不放在 tokens.css 写成 `* { box-sizing: border-box }`：
+      那是**全局 reset**，会改掉宿主页面自己的所有盒子。
+      组件库不该改宿主的盒模型（compare 05-audit/bleed-gate.py 的立论）。
+      ⇒ 放进骨架、挂 `.page`：**选配**。宿主不用骨架就不受影响。
+
+   为什么是 `.page *` 而不是逐个组件补：
+      逐个补 = 永远会漏下一个新组件。这一条把"新组件忘了写"变成不可能。
+   ========================================================================= */
+.page *,
+.page *::before,
+.page *::after {
+  box-sizing: border-box;
+}
+
+/* ============================================================================
+   2. 内容列 `.wrap`
+   ----------------------------------------------------------------------------
+   🔴 这是本次事故最典型的一处：33 个页面写了 16 种 `.wrap`，
+      max-width 出现过的数字有 680 / 720 / 760 / 800 / 820 / 860 / 900 px
+      和 42 / 44 / 46 / 52 rem，还有 1 页写 72ch。
+      它们之间**没有语义差别**，纯粹是每次手敲时随手写的。
+
+      现在只有一处：`min(var(--measure-page), 100%)`。
+      · --measure-page（52rem）来自实测众数 820px，见 tokens.css 里的注释
+      · min(…, 100%)：列宽永远不超过视口 ⇒ 窄屏上不会横向溢出
+   ========================================================================= */
+.page .wrap {
+  margin-inline: auto;
+  max-width: min(var(--measure-page), 100%);
+}
+
+/* 窄列：长文。68ch 是阅读上限，宽了眼睛回扫会跳行。
+   只有长文页需要，其余页面一律用上面的默认列宽。 */
+.page .wrap--prose {
+  max-width: min(var(--measure-prose), 100%);
+}
+
+/* ============================================================================
+   3. 标题阶梯
+   ----------------------------------------------------------------------------
+   h1：实测 8 种写法。这里取**最讲究的那一种**（list / nav / states 三页在用：
+       font-weight 500 + 收紧字距 + --measure-title 限宽），
+       而不是取数量最多的那一种（19 页，只有 font-size/line-height/margin）。
+       理由：19 页那种是"没写完"，不是"另一种设计" ——
+       它缺少的正是标题该有的三件事（字重、字距、限宽）。
+       收敛成"讲究版"之后，19 页的标题会变整齐，这是改进不是回归。
+
+   h2：实测 11 种写法，但它们其实是**两种东西**混在一起：
+       · 光秃秃的小节标题（16 页）
+       · 带分隔线的小节标题（13 页用上边线、6 页用下边线）
+       ⇒ 骨架只定义"光秃秃"的基础款；分隔线做成两个修饰类，
+         要线的页面加 class，不要自己再写一遍 border。
+   ========================================================================= */
+.page h1 {
+  font-family: var(--sans);
+  font-size: var(--fs-2xl);
+  font-weight: 500;
+  letter-spacing: var(--tracking-title);
+  line-height: var(--lh-tight);
+  margin: 0 0 var(--sp-3);
+  /* 标题比正文窄：大字长时间扫视会累（--measure-title 见 tokens.css） */
+  max-width: var(--measure-title);
+}
+
+.page h2 {
+  font-size: var(--fs-lg);
+  margin: var(--sp-7) 0 var(--sp-3);
+}
+
+/* 小节分隔线：加在 h2（或任何块）上。两种方向，二选一，不要同时用。 */
+.page .rule-top {
+  border-top: 1px solid var(--border-decor);
+  padding-top: var(--sp-4);
+}
+.page .rule-bottom {
+  border-bottom: 1px solid var(--border-decor);
+  padding-bottom: var(--sp-2);
+  margin-bottom: var(--sp-4);
+}
+
+/* ============================================================================
+   4. 行内代码 `code`
+   ----------------------------------------------------------------------------
+   typography.css 已经定义了 `code { font-family: var(--mono) }`。
+   这里补齐"行内代码片段"剩下的部分（底色 / 内边距 / 圆角 / 相对字号），
+   取自实测众数（badge / separator / switch / accordion / tabs / sparkline 六页）。
+
+   ⚠️ 字号用 em 不用 rem：行内代码要跟着**它所在的那段文字**缩放。
+      在 .small 里就该更小，在 h2 里就该更大。写成固定值会在小字区里显得突兀。
+   ========================================================================= */
+.page code {
+  font-family: var(--mono);
+  font-size: 0.9em;
+  background: var(--surface-sunken);
+  padding: 1px 4px;
+  border-radius: var(--r-xs);
+}
+
+/* ============================================================================
+   5. 演示块 `.box`
+   ----------------------------------------------------------------------------
+   13 页里 12 页写法完全一致（`background: var(--surface)` + 1px 边框 +
+   --r-md 圆角 + --sp-5 内边距），只有 1 页多了个 margin。
+   ⇒ 直接收编，多出来的那页用 --box--tight 之外的方式解决（它其实不需要）。
+   ========================================================================= */
+.page .box {
+  background: var(--surface);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-md);
+  padding: var(--sp-5);
+}
+
+/* 反例块：同一块，底色沉一档，用来放"错误示范" */
+.page .box.bad {
+  background: var(--surface-sunken);
+}
+
+/* ============================================================================
+   反模式（本文件自己的边界）
+   ----------------------------------------------------------------------------
+   1. 在页面内联 <style> 里再写一遍上面任何一个选择器
+      写了也不会生效吗？**会生效一部分，而且是静默的**：
+      `.page h1`（0,1,1）会盖掉页面的 `h1`（0,0,1），
+      页面那句变成死代码 —— 不报错、看不出来，只在你以为改了的时候没改。
+      ⇒ 05-audit/shell-gate.py 拦这个。
+
+   2. 在这里加组件样式
+      这是骨架层，只放"改一处必须全库跟随"的东西。
+      组件的样式属于组件自己的 CSS。
+
+   3. 为了一个页面改这里的公共值
+      一页的特殊需求请用页面自己的 class（不要挂到骨架类上），
+      或者在 tokens.css 里加令牌。**不要**为了迁就一页而把骨架改窄。
+
+   ⚠️ 有意没收编的（不是遗漏，是判断后不收）：
+      · `.row`  15 页 14 种写法 —— 它是各页的局部排布工具，不是骨架；
+                强行压成 1 种会破坏 9 个页面的实际布局。
+      · `.log`  10 页 7 种写法，且其中 2 页的 `.log` 是"一行淡字"、
+                另 8 页是"日志面板" —— 一个类名两种语义，收编前要先改名。
+      · `.pad`  6 页 4 种写法，都是各页自己的占位高度。
+      这三项的重复**不会**造成"改全局崩"（它们不是全局），
+      所以留在页面里；shell-gate 会把它们作为"已知重复"报出来，但不 fail。
+   ========================================================================= */