agentcss 0.0.0-stage → 0.11.2

package/02-primitives/select/select.js

@@ -0,0 +1,549 @@
+/**
+ * select.js — 自建下拉选择（E1 /
+ *
+ * 依据：APG Select-Only Combobox 模式
+ * ============================================================================
+ * ⭐ 四条最容易漏的键盘契约（逐条实现并在注释里标出）：
+ *
+ * ① **打开后焦点落在"选中项"**（不是第一项，也不是按钮）
+ *    ⇒ 用户按 Alt+↓ 打开后，直接 Enter 就能确认当前值。
+ *    ⇒ 若落在第一项，一开就选错了 —— 这是自建 select 最常见的错。
+ *
+ * ② **↑↓ 循环 · Home/End 首末 · Enter/Space 选中并关闭**
+ *
+ * ③ **Esc 关闭并把焦点还给按钮**（不是"选中项"）
+ *
+ * ④ **类型搜索**：连续打字跳到匹配项（原生 select 有，必须做）
+ *    ⇒ 缓冲 500ms，超时清空（否则 "abc" 永远搜不到）。
+ *
+ * 无依赖 · ES5
+ */
+(function (global) {
+  'use strict';
+
+  /* ==== BEHAVIOR INJECT BEGIN: dismissable ==== */
+  var flDismissable = function (opts) {
+    var opt = opts || {};
+    var escOn = opt.escOn || [];
+    var inside = opt.inside || [];
+    var when = opt.when || function () { return true; };
+    var onDismiss = opt.onDismiss || function () {};
+
+    var shared = window.__flDismiss || (window.__flDismiss = { stack: [], bound: false });
+
+    function isInside(node) {
+      if (!node) return false;
+      for (var i = 0; i < inside.length; i++) {
+        var el = inside[i];
+        if (!el || !el.contains) continue;
+        if (el === node || el.contains(node)) return true;
+      }
+      return false;
+    }
+
+    function onKey(e) {
+      if (!when()) return;
+      var k = e.key;
+      if (k !== 'Escape' && k !== 'Esc' && e.keyCode !== 27) return;
+      /* 🔴 为什么 onDismiss 在前、preventDefault/stopPropagation 在后
+         （0.8.8 改）：**分级 Esc** 需要核让组件有机会说"这次我没关"。
+         combobox 的 Esc 是三级的：
+           ① 列表开着 → 关列表
+           ② 列表关了、输入有字 → 清空输入
+           ③ 都没了 → 什么都不做（此时**不该**阻止默认行为，
+              让 Esc 能继续传给外层浮层）
+         而原实现是「无条件 preventDefault + stopPropagation，再调 onDismiss」
+         ⇒ 组件根本无法表达"这次我没关"。
+         ⇒ 改成：先问onDismiss，它返回 false 就**不干预**默认行为。
+         ⚠️ 顺序安全性：stopPropagation 只需在**本次监听器执行期间**被调用即可
+            阻止冒泡到外层，放在 onDismiss 之后仍然有效。
+      */
+      var closed = onDismiss(e, 'esc');
+      if (closed === false) return;
+      if (e.preventDefault) e.preventDefault();
+      if (e.stopPropagation) e.stopPropagation();
+    }
+
+    function onDocClick(e) {
+      var top = null;
+      for (var i = shared.stack.length - 1; i >= 0; i--) {
+        if (shared.stack[i].when()) { top = shared.stack[i]; break; }
+      }
+      if (!top || top.isInside(e.target)) return;
+      top.onDismiss(e, 'outside');
+    }
+
+    var rec = { when: when, isInside: isInside, onDismiss: onDismiss };
+
+    for (var j = 0; j < escOn.length; j++) {
+      if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
+    }
+    shared.stack.push(rec);
+    if (!shared.bound) {
+      shared.bound = true;
+      document.addEventListener('click', onDocClick, true);
+    }
+
+    return {
+      destroy: function () {
+        for (var j = 0; j < escOn.length; j++) {
+          if (escOn[j]) escOn[j].removeEventListener('keydown', onKey);
+        }
+        var k = shared.stack.indexOf(rec);
+        if (k >= 0) shared.stack.splice(k, 1);
+      },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: dismissable ==== */
+  /* ==== BEHAVIOR INJECT BEGIN: focus-return ==== */
+  var flFocusReturn = function (opts) {
+    var opt = opts || {};
+    var saved = null;
+
+    return {
+      save: function () {
+        var a = document.activeElement;
+        saved = (a && a !== document.body && a.focus) ? a : null;
+        return saved;
+      },
+
+      restore: function () {
+        var target = saved;
+        /* ⚠️ 见文档 ②：不判 contains 的话，元素被移除后 focus() 不报错
+           但焦点不动 ⇒ 用户以为还回去了，其实掉在 body 上。 */
+        if (!target || !document.contains(target)) target = opt.fallback || null;
+        if (!target) { saved = null; return false; }
+        try {
+          target.focus();
+        } catch (e) {
+          saved = null;
+          return false;
+        }
+        var ok = document.activeElement === target;
+        saved = null;   /* 见文档 ③ */
+        return ok;
+      },
+
+      target: function () { return saved; },
+      clear: function () { saved = null; },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: focus-return ==== */
+  /* ==== BEHAVIOR INJECT 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 INJECT END: typeahead ==== */
+  /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
+  var flEmit = function (el, name, detail) {
+    if (!el || !el.dispatchEvent) return null;
+    var type = name.indexOf('fl-') === 0 ? name : 'fl-' + name;
+    var ev = null;
+    /* 老 WebView 没有 CustomEvent 构造函数 ⇒ 兜底走 createEvent（理由见文件头）*/
+    if (typeof window.CustomEvent === 'function') {
+      try {
+        ev = new window.CustomEvent(type, {
+          detail: detail || null, bubbles: true, cancelable: false
+        });
+      } catch (e) { ev = null; }
+    }
+    if (!ev) {
+      try {
+        ev = document.createEvent('CustomEvent');
+        ev.initCustomEvent(type, true, false, detail || null);
+      } catch (e2) { return null; }
+    }
+    el.dispatchEvent(ev);
+    return ev;
+  };
+  /* ==== BEHAVIOR INJECT END: emit ==== */
+  /* ---- 旧环境兼容：Element.closest 在老 WebView 上不存在 ----
+     直接调用会在真机上抛 `is not a function`（本地完全正常，
+     只在老环境炸 —— 属静默失效）。这里做模块内兜底，
+     不污染全局，也不需要使用者额外引入 polyfill。 */
+  function closest(el, sel) {
+    if (!el) return null;
+    if (el.closest) return el.closest(sel);
+    while (el && el.nodeType === 1) {
+      if (elMatches(el, sel)) return el;
+      el = el.parentElement;
+    }
+    return null;
+  }
+  function elMatches(el, sel) {
+    var m = sel.match(/^([a-zA-Z][\w-]*)/);
+    if (m && el.tagName.toLowerCase() !== m[1].toLowerCase()) return false;
+    var cls = sel.match(/\.([\w-]+)/g);
+    if (cls) {
+      for (var i = 0; i < cls.length; i++) {
+        var c = cls[i].slice(1);
+        if ((' ' + (el.className || '') + ' ').indexOf(' ' + c + ' ') < 0) return false;
+      }
+    }
+    var id = sel.match(/#([\w-]+)/);
+    if (id && el.id !== id[1]) return false;
+    var at = sel.match(/\[([\w-]+)(?:=["']?([^\]"']*)["']?)?\]/);
+    if (at) {
+      var v = el.getAttribute(at[1]);
+      if (v === null) return false;
+      if (at[2] !== undefined && v !== at[2]) return false;
+    }
+    return true;
+  }
+
+  var uid = 0;
+
+  function create(root, opt) {
+    opt = opt || {};
+    var btn = root.querySelector('[data-select-btn]');
+    var list = root.querySelector('[data-select-list]');
+    if (!btn || !list) throw new Error('Select: 缺少 [data-select-btn] 或 [data-select-list]');
+
+    /* 焦点归位核：open() 时save() 记住焦点、close() 时按参数 restore()。
+       原先是 close() 里直接 btn.focus() —— 那是**无条件**归位，
+       而 close(false) 的调用场景（选完就走的场景）本意就是不夺焦点。
+       核的语义是「记了才还」，正好把「打开时记、关闭时还」讲清楚。 */
+    var fr = flFocusReturn({ fallback: btn });
+
+    /* 「关得掉」核：Esc + 点外部。收编解决两个实际问题：
+       ① 原来的 document click 是**冒泡阶段**判定 ⇒ 点在按钮上但事件仍会
+          继续冒泡，容易出现「刚打开就被自己那一下点关掉」；
+       ② Esc 的 stopPropagation（只关本层、不带崩外层）由核统一承担，
+          组件里不再各写一份。
+       ⚠️ close(false) 的场景（Tab 走开）**不夺焦点**，
+          所以 onDismiss 用 close(false)、Esc 那条单独 close(true)。 */
+    var dismiss = flDismissable({
+      escOn: [btn],
+      inside: [root],
+      when: function () { return !list.hidden; },
+      onDismiss: function (ev, reason) {
+        close(reason === 'esc');
+      }
+    });
+    if (!list.id) list.id = 'select-list-' + (++uid);
+
+    var options = [].slice.call(list.querySelectorAll('[role="option"]'));
+    var isMulti = !!opt.multiple;
+    var selected = opt.value != null ? String(opt.value) : null;
+    var activeIdx = -1;
+
+    list.setAttribute('role', 'listbox');
+    if (isMulti) list.setAttribute('aria-multiselectable', 'true');
+    list.setAttribute('aria-label', opt.label || '选项');
+    btn.setAttribute('aria-haspopup', 'listbox');
+    btn.setAttribute('aria-expanded', 'false');
+    btn.setAttribute('aria-controls', list.id);
+
+    /* 保证每个 option 都有 id（aria-activedescendant 需要） */
+    options.forEach(function (o, i) {
+      o.setAttribute('role', 'option');
+      if (!o.id) o.id = list.id + '-o' + i;
+      o.setAttribute('aria-selected', 'false');
+      if (o.hasAttribute('disabled') || o.getAttribute('aria-disabled') === 'true') {
+        o.setAttribute('aria-disabled', 'true');
+      }
+      o.setAttribute('tabindex', '-1');   /* 焦点在按钮上，选项不占 Tab */
+      if (o.className.indexOf('select__opt') < 0) {
+        o.className = (o.className ? o.className + ' ' : '') + 'select__opt';
+      }
+    });
+
+    function enabled() {
+      return options.filter(function (o) { return o.getAttribute('aria-disabled') !== 'true'; });
+    }
+    /* 类型搜索（连续打字定位）走 typeahead 核（01-tokens/behavior/typeahead.js）。
+       ⭐ 之前这里只实现了"累积前缀"，**没有连打同一字符时循环** ⇒
+         连按两次同一个字母，游标不动（用户以为卡了）。
+       ⭐ 而 tree 里那一份只实现了循环、没有累积 —— 两份各缺一半。
+       ⇒ 核一次把两半都补齐（APG 的 typeahead 约定），两处共用一份规则。 */
+    var typeahead = flTypeahead({
+      items: function () { return options; },
+      textOf: optText,
+      usable: function (o) { return o.getAttribute('aria-disabled') !== 'true'; },
+      onHit: function (i) { setActive(i, 1); },
+    });
+
+    function selectedIdx() {
+      for (var i = 0; i < options.length; i++) {
+        if (options[i].getAttribute('data-value') === selected) return i;
+      }
+      return -1;
+    }
+    function valueText() {
+      var i = selectedIdx();
+      return i < 0 ? (opt.placeholder || '请选择') : optText(options[i]);
+    }
+    function optText(o) {
+      var t = o.querySelector('.select__opt-text');
+      return ((t || o).textContent || '').replace(/[✓\s]/g, '').trim();
+    }
+
+    function paint() {
+      var v = valueText();
+      var vEl = btn.querySelector('.select__value');
+      if (vEl) {
+        vEl.textContent = v;
+        vEl.classList.toggle('select__value--placeholder', selectedIdx() < 0);
+      }
+      options.forEach(function (o) {
+        var on = o.getAttribute('data-value') === selected;
+        o.setAttribute('aria-selected', on ? 'true' : 'false');
+        var ck = o.querySelector('.select__check');
+        if (ck) ck.textContent = on ? '✓' : '';
+      });
+      /* hidden input 承接表单值（自建组件最容易漏的）*/
+      var hidden = root.querySelector('input[type="hidden"]');
+      if (hidden) hidden.value = selected == null ? '' : selected;
+      flEmit(root, 'fl-change',
+             { value: selected, text: optText(options[selectedIdx()] || options[0]) });
+      if (opt.onChange) opt.onChange(selected, optText(options[selectedIdx()] || options[0]));
+    }
+
+    /**
+     * 🔴 修一个**索引错位导致 ↑↓ 卡死**的 bug。
+     *
+     * 原来：`setActive(i)` 里的 i 被调用方按 **enabled() 过滤后数组**的索引传，
+     *      而函数内部又当成 **options 原数组**的索引用
+     *      ⇒ 两者含义不同；末项之后算出越界，被 Math.min 夹回末项
+     *      ⇒ **连按 ↓ 永远停在最后一项**。
+     * ⚠️ 症状极具欺骗性：前几项能正常走，最后一项之后就"卡住"了。
+     *
+     * ⭐ 正解：**对外统一用 options 的索引**，
+     *      跳过 disabled 的逻辑放在函数内部做（步进 + 环绕）。
+     *
+     * @param {number} i  options 数组里的索引（可越界，会自动环绕）
+     * @param {number} [dir=1] 步进方向（-1 用于 ↑）
+     */
+    function setActive(i, dir) {
+      if (!options.length) return;
+      dir = dir || 1;
+      /* 从 i 开始按 dir 找第一个未禁用的（最多转一圈）*/
+      var n = options.length;
+      var idx = ((i % n) + n) % n;
+      for (var k = 0; k < n; k++) {
+        if (options[idx].getAttribute('aria-disabled') !== 'true') break;
+        idx = ((idx + dir) % n + n) % n;
+      }
+      activeIdx = idx;
+      options.forEach(function (o) { o.removeAttribute('data-state'); });
+      options[idx].setAttribute('data-state', 'active');
+      /* ⭐ aria-activedescendant：焦点始终在按钮上，靠它告诉读屏"当前在第几项" */
+      btn.setAttribute('aria-activedescendant', options[idx].id);
+      if (options[idx].scrollIntoView) {
+        options[idx].scrollIntoView({ block: 'nearest' });
+      }
+    }
+
+    /** 当前游标所在项在 options 里的索引（没打开时用选中项）*/
+    function activeIndex() {
+      if (activeIdx >= 0) return activeIdx;
+      var i = selectedIdx();
+      if (i >= 0) return i;
+      var e2 = enabled();
+      return e2.length ? options.indexOf(e2[0]) : 0;
+    }
+
+    function open() {
+      /* 打开这一刻先记焦点，close() 才能还回去（要在改焦点之前做）。 */
+      fr.save();
+      list.hidden = false;
+      btn.setAttribute('aria-expanded', 'true');
+      /* 🔴 修：必须**先把焦点放到按钮上**。
+         本组件用 aria-activedescendant 模式（焦点常驻按钮，靠它告知读屏
+         "当前在第几项"）⇒ 焦点必须始终在按钮，事件也必须由按钮处理。
+         原来只设了 aria-activedescendant 就 open()
+         ⇒ 用鼠标点开时焦点可能停在 body
+         ⇒ 挂在 list 上的 keydown（Esc / 类型搜索）**收不到事件**。
+         ⚠️ 症状：鼠标能选、↑↓ 能走、Esc 与字母键完全无效。 */
+      btn.focus();
+      /* ① 焦点落在**选中项**（没有选中则落在第一个未禁用的项）*/
+      setActive(activeIndex());
+      flEmit(root, 'fl-open', null);
+      if (opt.onOpen) opt.onOpen();
+    }
+    function close(restoreFocus) {
+      list.hidden = true;
+      btn.setAttribute('aria-expanded', 'false');
+      btn.removeAttribute('aria-activedescendant');
+      options.forEach(function (o) { o.removeAttribute('data-state'); });
+      activeIdx = -1;
+      typeahead.clear();   /* 关闭即清空缓冲：下次打开不该接着上次的半个词 */
+      /* ③ Esc 关闭时焦点**还给按钮**（不是选中项）*/
+      if (restoreFocus !== false) fr.restore();
+      flEmit(root, 'fl-close', null);
+      if (opt.onClose) opt.onClose();
+    }
+    function commit(i) {
+      var o = options[i];
+      if (!o || o.getAttribute('aria-disabled') === 'true') return;
+      if (isMulti) {
+        /* 多选：再点一次取消 */
+        selected = o.getAttribute('data-value') === selected ? null : o.getAttribute('data-value');
+      } else {
+        selected = o.getAttribute('data-value');
+        close(true);                              /* 选中并关闭 + 归位 */
+      }
+      paint();
+    }
+
+    /* ---------- 键盘（APG Select）---------- */
+    btn.addEventListener('keydown', function (e) {
+      var k = e.key;
+      if (k === 'ArrowDown' || k === 'ArrowUp' || k === 'Enter' || k === ' ' ||
+          k === 'Spacebar' || (k === 'Alt' && false)) {
+        if (k === 'ArrowDown' || k === 'ArrowUp') {
+          e.preventDefault();
+          if (list.hidden) { open(); return; }
+          var dir = k === 'ArrowDown' ? 1 : -1;
+          setActive(activeIndex() + dir, dir);
+          return;
+        }
+        e.preventDefault();
+        if (list.hidden) open();
+        else if (activeIdx >= 0) commit(activeIdx);
+        return;
+      }
+      /* Alt+↓ 直接打开（不改值）*/
+      if (k === 'ArrowDown' && e.altKey) { e.preventDefault(); open(); return; }
+      /* Home/End */
+      if (list.hidden && (k === 'Home' || k === 'End')) {
+        e.preventDefault(); open();
+        if (k === 'Home') setActive(0);
+        else setActive(options.length - 1);
+        return;
+      }
+    });
+
+    /* 🔴 焦点常驻按钮 ⇒ 键盘事件主要落在 btn 上。
+       这里把 btn 的 handler 也挂一份完整逻辑（Esc/类型搜索/Home/End），
+       否则它们永远收不到事件。 */
+    function onListKey(e) {
+      var k = e.key;
+      if (k === 'ArrowDown') { e.preventDefault(); setActive(activeIndex() + 1, 1); return; }
+      if (k === 'ArrowUp')   { e.preventDefault(); setActive(activeIndex() - 1, -1); return; }
+      if (k === 'Home')      { e.preventDefault(); setActive(0, 1); return; }
+      if (k === 'End')       { e.preventDefault(); setActive(options.length - 1, -1); return; }
+      /* ③ Esc 关闭 + 焦点还按钮
+         🔴 加 stopPropagation（**组合契约**抓到的真问题）：
+         本组件常被放进 drawer / dialog 里。
+         原来只 preventDefault ⇒ 事件**继续冒泡**到外层弹层
+         ⇒ **按一次 Esc 把内外两层一起关掉**。
+         ⚠️ 单组件契约**测不到这个**（它没有外层）——
+            所以必须有"组合契约"这种真嵌套的测试。
+         ⇒ 正解：内层弹层"吃掉"这个键时必须 stopPropagation。
+         层级弹层的 Esc 语义本来就是"只关最上面那层"。 */
+      /* Esc 已由 dismissable 核接管（见上面的 flDismissable）：
+         核把它挂在 btn 上冒泡、并 stopPropagation ⇒ 只关最内层，
+         组件里不再各写一份（原先手写 10 处、分布 7 个文件）。 */
+      if (k === 'Tab') { close(false); return; }
+      if (k === 'Enter' || k === ' ' || k === 'Spacebar') {
+        e.preventDefault();
+        if (activeIdx >= 0) commit(activeIdx);
+        return;
+      }
+      /* ④ 类型搜索 —— 已移到 typeahead 核（见上面的 flTypeahead）。
+         ⚠️ 核不监听键盘：Enter / Space / Tab 在本组件各有语义，
+            只有"单个可打印字符"才算打字。 */
+      if (k.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        typeahead.type(k);
+      }
+    }
+    /* 挂在按钮上（焦点常驻处）*/
+    btn.addEventListener('keydown', function (e) {
+      /* 列表没开时，btn 自己的 handler 已经处理了开合；开了之后交给 onListKey */
+      if (list.hidden) return;
+      var k = e.key;
+      /* 这些键在"已打开"状态下由 onListKey 统一处理 */
+      if (k === 'Escape' || k === 'Esc' || k === 'ArrowDown' || k === 'ArrowUp' ||
+          k === 'Home' || k === 'End' || k === 'Enter' || k === ' ' ||
+          k === 'Spacebar' || k === 'Tab') {
+        /* Enter/Space 在关闭态要"打开"，交给 btn 原 handler */
+        if (list.hidden) return;
+        onListKey(e);
+        return;
+      }
+      if (k.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) onListKey(e);
+    });
+
+    /* ---------- 点击 ---------- */
+    btn.addEventListener('click', function () {
+      if (list.hidden) open(); else close();
+    });
+    list.addEventListener('click', function (e) {
+      var o = e.target.closest ? closest(e.target, '[role="option"]') : null;
+      if (!o) return;
+      commit(options.indexOf(o));
+    });
+    /* 点外部关闭已由 dismissable 核接管（document 捕获阶段判定）。 */
+
+    paint();
+    return {
+      open: open, close: close,
+      get value() { return selected; },
+      set value(v) { selected = v == null ? null : String(v); paint(); },
+    };
+  }
+
+  global.Select = { create: create };
+})(window);

package/02-primitives/separator/README.md

@@ -0,0 +1,63 @@
+# separator · 分隔线
+
+## 两种，必须分清
+
+| | 类 | 用途 | 读屏 |
+|---|---|---|---|
+| **装饰性** | `.separator` | 只把内容分成块 | **不播报** |
+| **语义性** | `.separator--label` | 分开**不同的东西** | **播报"分隔符"** |
+
+**为什么必须分**：两者视觉上都是一条线，但**对辅助技术的意义相反** ——
+装饰性的播报是噪音，语义性的不播报则丢信息。
+
+## 类
+
+| 类 | 作用 |
+|---|---|
+| `.separator` | 装饰性（`<hr>`）|
+| `.separator--tight` | 间距更小（同组内部）|
+| `.separator--label` | 语义性，文字**前**画线 |
+| `.separator--both` | 两侧都画线 |
+
+## 用法
+
+```html
+<!-- 装饰性 -->
+<hr class="separator">
+
+<!-- 语义性：必须有名字 -->
+<hr class="separator separator--label" role="separator" aria-label="高级设置">
+```
+
+## 为什么用两档颜色（实测，不是拍脑袋）
+
+本库实测（vs `--surface`，WCAG 1.4.11 非文字对比要 ≥ 3:1）：
+
+| 令牌 | 浅色 | 暗色 | 判定 |
+|---|---|---|---|
+| `--border-decor` | 1.26 | 1.23 | < 3 |
+| `--border-decor-str` | 1.60 | 1.61 | < 3 |
+| `--border-control` | **3.42** | **4.34** | ✅ ≥ 3 |
+
+**差 2.7 倍。** 所以：
+
+- **装饰性**用 `--border-decor` —— 1.4.11 **不适用于它**（不承担语义）
+- **语义性**用 `--border-control` —— 它是读屏用户**唯一能看到的线索**，
+  视觉上必须够明显
+
+**这就是"不要一档打天下"的实测依据。**
+
+## 两个反例
+
+**① 语义分隔用装饰色** —— 分隔"基本信息"与"高级设置"是两类不同的东西，
+但 1.26:1 的线在低视力与暗色下几乎看不见，而读屏只念"分隔符"、
+不解释两边是什么 ⇒ 该线是唯一线索时必须用达标的档。
+
+**② 用 div + border-bottom 代替 hr** —— `<div class="line">` 对读屏
+**什么都没有**。语义分隔必须用 `<hr>` 或 `role="separator"`，
+装饰性的才可以用纯 div。
+
+## 细节
+
+用 `border` 而不是 `box-shadow` 画线 —— 1px 的线用 box-shadow
+在某些浏览器上会渲染成 2px（亚像素取整）。