agentcss 0.0.0-stage → 0.11.2

package/03-patterns/states/states.css

@@ -0,0 +1,252 @@
+/* ============================================================================
+   frontend-lib / 03-patterns / states / states.css
+   容器四态：empty / loading / error / success
+
+   依赖：01-tokens/tokens.css
+   版本：A ✅ / B ✅ / C ✅
+
+   🔴 为什么四态必须分开做：
+      加载中和"没有数据"在视觉上都是"一片空白"，但含义完全相反 ——
+      前者是"在动"，后者是"没东西"。混成一个，用户会以为系统坏了。
+      这是 demo 和线上页面最容易露怯的一处。
+
+      四态的共同要求：每一态都必须告诉用户**下一步能做什么**。
+      只描述现状不给出口，等于把用户卡死。
+   ========================================================================= */
+
+/* ---------------------------------------------------------------- 基类 */
+.state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sp-2);
+  padding: var(--sp-8) var(--sp-5);
+  text-align: center;
+  min-height: 200px;
+}
+
+.state__icon {
+  flex: none;
+  width: 48px;
+  height: 48px;
+  margin-bottom: var(--sp-2);
+  display: grid;
+  place-items: center;
+  border-radius: var(--r-pill);
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);
+}
+
+.state__title {
+  margin: 0;
+  font-size: var(--fs-md);
+  font-weight: 500;
+  line-height: var(--lh-tight);
+  color: var(--text-primary);
+}
+
+.state__desc {
+  margin: 0;
+  max-width: 42ch;          /* 说明文字要限制行长，否则在大屏上会拉成一条 */
+  font-size: var(--fs-sm);
+  color: var(--text-secondary);
+  line-height: var(--lh-base);
+}
+
+/* 🔴 动作区不是可选装饰，是四态存在的理由。
+   empty 没有动作 = 用户不知道怎么开始
+   error 没有动作 = 死路，只能刷新页面 */
+.state__action {
+  margin-top: var(--sp-3);
+  display: flex;
+  gap: var(--sp-3);
+  flex-wrap: wrap;
+  justify-content: center;
+}
+
+/* ============================================================================
+   1. empty —— 没有数据
+   =========================================================================
+   必须三件事：说明为什么是空的 / 消除用户的自责 / 给出下一步
+   ------------------------------------------------------------------------ */
+.state--empty .state__icon {
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);
+}
+
+/* empty 的说明要写"为什么空"，不是只写"没有数据"。
+   "还没有导入任何公司" 比 "暂无数据" 有用得多。 */
+
+/* ============================================================================
+   2. loading —— 加载中
+   =========================================================================
+   两种形态，按结构是否已知选：
+
+   skeleton（骨架屏）：结构已知 —— 知道会有标题+两行文字+一张图
+   spinner        ：结构未知 —— 不知道会来什么
+
+   🔴 别在结构未知时用骨架屏，那是在撒谎：画出来的结构跟实际不一致，
+      内容到位时布局会剧烈跳动。
+   ------------------------------------------------------------------------ */
+.state--loading {
+  /* 没有图标和标题的复杂布局，只放一个指示 */
+  gap: var(--sp-3);
+}
+
+/* spinner */
+.spinner {
+  width: 24px;
+  height: 24px;
+  border: 2.5px solid var(--border-control);
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  animation: spinner-rotate 700ms linear infinite;
+}
+@keyframes spinner-rotate { to { transform: rotate(360deg); } }
+
+/* ---------------------------------------------------------------- 骨架屏
+   骨架屏的价值不在"好看"，在于**内容到位时不跳动**。
+   所以骨架的形状必须尽量贴合真实内容的结构和尺寸。
+   ---------------------------------------------------------------- */
+.skeleton {
+  /* 装饰性色，不参与对比度检查（它不承载文字）。
+     🔴 改为令牌：原值 #ece8de/#f5f2ea 是**硬编码的浅米色**，
+     暗色模式下会是两块刺眼的白块 —— 与 --text-on-accent 同类问题：
+     **写死颜色 = 主题切换时必然失效。** */
+  --sk-base: var(--surface-sunken);
+  --sk-hi:   var(--border-decor);
+
+  background: var(--sk-base);
+  border-radius: var(--r-sm);
+  position: relative;
+  overflow: hidden;
+}
+.skeleton::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(90deg,
+              transparent 0%, var(--sk-hi) 50%, transparent 100%);
+  transform: translateX(-100%);
+  animation: skeleton-sweep 1.4s ease-in-out infinite;
+}
+@keyframes skeleton-sweep {
+  to { transform: translateX(100%); }
+}
+
+.skeleton--text   { height: 1em; margin-block: 0.35em; border-radius: 4px; }
+.skeleton--title  { height: 1.4em; width: 60%; }
+.skeleton--avatar { width: 40px; height: 40px; border-radius: var(--r-pill); }
+.skeleton--block  { height: 120px; }
+/* 最后一行短一点，看起来更像真实段落 */
+.skeleton--text:last-child { width: 70%; }
+
+/* 骨架屏的"闪屏"问题：请求在 300ms 内返回时，骨架屏闪一下反而更糟，
+   正确做法是延迟 300ms 再显示 loading 态。
+
+   ⚠️ 这个能力**不由本库提供**：曾经有一个 `.state--delayed` 类，
+      但它承诺的"延迟显现"全库没有任何 JS 去驱动（`data-state="shown"`
+      得使用者自己加），读起来像本库已实现 ⇒ 已在 0.8.0 移除（0.7.7 登记）。
+      现在需要就自己写两行，见 `README.md` 的「移除记录」一节。 */
+
+/* ============================================================================
+   3. error —— 出错
+   =========================================================================
+   🔴 error 态必须可恢复。只写"出错了"是死路，用户只能刷新页面，
+      而刷新往往解决不了问题（比如参数错了）。
+
+   三件事：说清出了什么事 / 说清是不是用户的错 / 给重试或返回的出口
+   ------------------------------------------------------------------------ */
+.state--error .state__icon {
+  background: var(--danger-bg);
+  color: var(--danger);   /* 6.26 AA */
+}
+.state--error .state__title { color: var(--danger); }
+
+/* 技术细节（错误码、堆栈）单独折叠，别混进主文案。
+   用户要看的是"我该怎么办"，不是"NullPointerException"。 */
+.state__detail {
+  margin-top: var(--sp-3);
+  font-family: var(--mono);   /* 原为写死的 ui-monospace，统一走令牌 */
+  font-size: var(--fs-xs);
+  color: var(--text-tertiary);
+  background: var(--surface-sunken);
+  padding: var(--sp-2) var(--sp-3);
+  border-radius: var(--r-sm);
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+/* ============================================================================
+   4. success —— 成功
+   =========================================================================
+   🔴 success 是**过渡态**，不是停留态。
+   容器级 success 只在"这一步彻底结束"时出现（提交完成、支付完成），
+   并且必须给出口：下一步去哪。
+
+   普通操作的成功反馈用 button 的 `data-state="success"`（1.2s 自动消失），
+   不要用容器级 success —— 那会把一个瞬间反馈做成一个页面。
+   ------------------------------------------------------------------------ */
+/* 🔴 删除 .state--success
+   理由：**它自己的注释就写着"不要用容器级 success"**，
+   却把样式留在文件里 —— 这是最坏的一种：
+   注释说别用，CSS 却摆在那里，读者只会看到"有这个能力"。
+   瞬时反馈用 button 的 `data-state="success"`（1.2s 自动消失）。
+   ⇒ 要"落盘即用"的成功态，就该有一个真会被用到的类，
+   而不是一个明确标注"别用"的。 */
+
+/* ============================================================================
+   无障碍
+   =========================================================================
+   1) loading 容器要标 aria-busy="true"
+   2) error / success 动态出现时用 role="alert" 或 aria-live="polite"，
+      否则屏幕阅读器用户完全不知道状态变了
+   3) 骨架屏是纯装饰，标 aria-hidden="true" —— 不然会被读成一堆无意义的色块
+   ------------------------------------------------------------------------ */
+
+/* ============================================================================
+   reduced-motion 的两种不同处理 —— 这里的区别很重要
+   =========================================================================
+   spinner : **保留但放慢**。它停了用户会以为页面卡死。
+             reduced-motion 针对的是大幅位移（前庭功能障碍），原地旋转不属于此类。
+
+   skeleton: **可以停**。静态的占位块仍然传达"这里有内容正在来"，
+             去掉扫光不损失信息，而扫光恰好是横向位移 —— 正是要减少的那类。
+
+   同样是"加载中的动画"，一个保留一个去掉，判断依据是**去掉后是否损失信息**。
+   ========================================================================= */
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation-duration: 1.2s !important;   /* 放慢，保留 */
+  }
+  .skeleton::after {
+    animation: none;                        /* 停止扫光，保留静态占位 */
+    transform: none;
+  }
+}
+
+/* ============================================================================
+   反模式
+   =========================================================================
+   1. empty 和 loading 用同一个样式
+      用户分不清是"在加载"还是"真没有"。
+
+   2. empty 态不放动作按钮
+      "暂无数据" 四个字把用户卡死在那儿。
+
+   3. error 态没有重试出口
+      只能刷新页面，而刷新常常解决不了问题。
+
+   4. 结构未知时用骨架屏
+      画出来的结构跟实际不一致，内容到位时布局剧烈跳动。
+
+   5. 请求 <300ms 也显示骨架屏
+      闪一下，比不显示更糟。要延迟显示。
+
+   6. 把普通操作的成功做成整页 success
+      成功是过渡态。用 button 的 `data-state="success"`。
+
+   7. 骨架屏不标 aria-hidden
+      屏幕阅读器会把它读成一堆无意义内容。
+   ========================================================================= */

package/03-patterns/tabs/README.md

@@ -0,0 +1,84 @@
+# tabs · 标签页
+
+同一位置切换**同层级**的几块内容。
+
+## 结构（APG 要求，不是我的设计）
+
+```html
+<div class="tabs" data-tabs>
+  <div class="tabs__list" role="tablist" aria-orientation="horizontal" aria-label="…">
+    <button class="tabs__tab" role="tab" id="t1"
+            aria-controls="p1" aria-selected="true">基本信息</button>
+    <button class="tabs__tab" role="tab" id="t2"
+            aria-controls="p2" aria-selected="false">高级设置</button>
+  </div>
+  <div class="tabs__panel" role="tabpanel" id="p1" aria-labelledby="t1">…</div>
+  <div class="tabs__panel" role="tabpanel" id="p2" aria-labelledby="t2" hidden>…</div>
+</div>
+```
+
+**tab 必须是 `<button>`** —— APG 明确要求。
+用 `<div role="tab">` 键盘上根本 Tab 不到，也不响应 Enter/Space。
+
+## 键盘契约
+
+| 键 | 行为 |
+|---|---|
+| `Tab` | 进入组时落在**当前选中**的 tab；再按 Tab 进入面板内容 |
+| `← →` | 上一个 / 下一个 tab（并激活）|
+| `Home` / `End` | 第一个 / 最后一个 tab |
+| `Enter` / `Space` | 仅**手动模式**下用于激活 |
+
+## 🔴 roving tabindex（本组件最容易写错的地方）
+
+一组 tab 里**只有一个**是 `tabindex="0"`，其余 `-1`。
+
+**为什么要这样**：否则 Tab 键会**逐个穿过所有 tab** ——
+一排 5 个 tab 要按 5 次 Tab 才能进内容区。
+
+**更关键**：那个 `"0"` **必须跟着选中项走**。
+只在初始化时设一次是最常见的 bug（用户激活第 3 个 tab 后，Tab 键还会回到第 1 个）。
+
+## 两种激活模式
+
+| 模式 | 类 | 方向键 | 何时用 |
+|---|---|---|---|
+| **自动**（默认）| — | 移动即切换 | 面板轻 |
+| **手动** | `.tabs--manual` | 只移动焦点，Enter 才切 | 面板重（避免读屏不停播报）|
+
+## 纵向
+
+`aria-orientation="vertical"` + `.tabs--vertical`。
+
+## 一个规范与现实的张力
+
+APG 要求「在 tab 上按 Tab ⇒ 焦点进入面板内容」。
+**但全是静态文字的面板没有任何可聚焦元素** ⇒ Tab 会直接跳过整个面板。
+
+实测确认（`tabs-contract.js` 里就是用这个测的）：
+demo 的面板里放了按钮，`Tab` 序列是
+`t1 → 面板内按钮 → 下一个 tab 组` —— **符合规范**。
+
+⚠️ 纯文字面板请自己加可聚焦元素（链接、按钮、或 `tabindex="-1"` 的容器）。
+
+## 语法约束
+
+`tabs.js` **刻意用 ES5**（无箭头函数 / const / let / 模板字符串）——
+精简档（某项目 上的 WebView）版本不确定。
+
+也**刻意不用 `Element.closest` / `Array.filter`**（ES5 之后才有），
+自己写了 15 行等价实现 —— 与同目录的 `list.js` / `overlay.js` 保持一致。
+**一致比方便重要。**
+
+## 验证
+
+`tabs-contract.js` **28 项全过**（用 `page.keyboard.press()` 真实按键）：
+
+- 结构：`<button>` · `role=tablist` · `aria-controls` 双向互指 · `aria-orientation`
+- roving：唯一 `0` · **跟着选中项走** · 循环后仍唯一
+- 键盘：`←→` · `Home`/`End` · **循环** · **跳过 `aria-disabled`**
+- Tab 进出：进组落在选中项 · 进面板内容 · **不逐个穿过同组**
+- 手动模式：方向键不切面板但移焦点 · Enter 才激活
+- axe 0 违规 / 30 条通过
+
+判别力验证：破坏 roving（全部设成 `0`）⇒ **5 项立即被抓**。

package/03-patterns/tabs/demo.html

@@ -0,0 +1,139 @@
+<!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>tabs · 标签页</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="../../03-patterns/tabs/tabs.css">
+<style>
+.log { font-family: var(--mono); font-size: var(--fs-xs);
+         color: var(--text-secondary); min-height: 1.5em; }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+  <h1>tabs · 标签页</h1>
+  <p class="lede">
+    标签页用于在同一位置切换<strong>同层级的几块内容</strong>。
+    键盘行为完全按 APG Tabs Pattern：方向键切换、Home/End 跳首尾。
+  </p>
+
+  <h2 class="rule-top">基本用法（自动激活）</h2>
+  <div class="tabs" data-tabs>
+    <div class="tabs__list" role="tablist" aria-orientation="horizontal" aria-label="设置分组">
+      <button class="tabs__tab" role="tab" id="t1" aria-controls="p1"
+              aria-selected="true">基本信息</button>
+      <button class="tabs__tab" role="tab" id="t2" aria-controls="p2"
+              aria-selected="false">高级设置</button>
+      <button class="tabs__tab" role="tab" id="t3" aria-controls="p3"
+              aria-selected="false">日志</button>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="p1" aria-labelledby="t1">
+      <p>公司名称、代码、行业分类。</p>
+      <!-- 🔴 面板里必须有**可聚焦元素**，否则按 Tab 会直接跳过整个面板
+           —— APG 要求「在 tab 上按 Tab ⇒ 焦点进入面板内容」。
+           全是静态文字的面板天然没有停靠点，这是规范与现实的真实张力。 -->
+      <p><button class="btn btn--md btn--secondary">面板里的按钮（可 Tab 到）</button></p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="p2" aria-labelledby="t2" hidden>
+      <p>数据源、口径、复核规则。</p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="p3" aria-labelledby="t3" hidden>
+      <p>抓取记录与错误。</p>
+    </div>
+  </div>
+  <p class="log" id="log1">切到哪个：<b id="logv1">基本信息</b></p>
+
+  <h2 class="rule-top">禁用某个 tab</h2>
+  <div class="tabs" data-tabs>
+    <div class="tabs__list" role="tablist" aria-orientation="horizontal" aria-label="带禁用">
+      <button class="tabs__tab" role="tab" id="d1" aria-controls="dp1"
+              aria-selected="true">可用</button>
+      <button class="tabs__tab" role="tab" id="d2" aria-controls="dp2"
+              aria-selected="false" aria-disabled="true">未开通</button>
+      <button class="tabs__tab" role="tab" id="d3" aria-controls="dp3"
+              aria-selected="false">可用</button>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="dp1" aria-labelledby="d1">
+      <p>方向键会<strong>跳过</strong>禁用的 tab。</p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="dp2" aria-labelledby="d2" hidden>
+      <p>你看不到这一页。</p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="dp3" aria-labelledby="d3">
+      <p>按两次 ArrowRight 能到这里（跳过了未开通）。</p>
+    </div>
+  </div>
+
+  <h2 class="rule-top">手动激活（面板内容重时用）</h2>
+  <div class="tabs tabs--manual" data-tabs>
+    <div class="tabs__list" role="tablist" aria-orientation="horizontal" aria-label="手动激活">
+      <button class="tabs__tab" role="tab" id="m1" aria-controls="mp1"
+              aria-selected="true">第一段</button>
+      <button class="tabs__tab" role="tab" id="m2" aria-controls="mp2"
+              aria-selected="false">第二段</button>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="mp1" aria-labelledby="m1">
+      <p>方向键<strong>只移动焦点</strong>，需按 Enter 才切 —— 读屏不会不停播报。</p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="mp2" aria-labelledby="m2" hidden>
+      <p>按了 Enter 才到这里。</p>
+    </div>
+  </div>
+
+  <h2 class="rule-top">键盘契约（APG / Radix）</h2>
+  <div class="box">
+    <p>
+      <strong>Tab</strong> 进入组时落在<strong>当前选中</strong>的 tab；再按 Tab 进面板<br>
+      <strong>← →</strong> 上一个 / 下一个 tab（并激活）<br>
+      <strong>Home / End</strong> 第一个 / 最后一个 tab
+    </p>
+    <p class="small">
+      <strong>roving tabindex</strong>：一组 tab 里只有一个是 <code>tabindex="0"</code>，
+      其余全是 <code>-1</code>。否则 Tab 键会<strong>逐个穿过所有 tab</strong>
+      （一排 5 个要按 5 次）。
+      更关键的是——<strong>那个 "0" 必须跟着选中项走</strong>，
+      只在初始化时设一次是最常见的 bug。
+    </p>
+  </div>
+
+  <h2 class="rule-top">反例</h2>
+  <div class="box bad">
+    <h3>反例：用 div 当 tab</h3>
+    <p class="small">
+      <code>&lt;div role="tab"&gt;</code> 键盘上根本<strong>Tab 不到</strong>
+      （除非手写 <code>tabindex</code>），也不会响应 Enter/Space。
+      APG 明确要求 tab 是 <code>&lt;button role="tab"&gt;</code> ——
+      用原生 button，键盘行为免费且必然正确。
+    </p>
+  </div>
+  <div class="box bad">
+    <h3>反例：每个 tab 都写 tabindex="0"</h3>
+    <p class="small">
+      看起来"都能 Tab 到"，但一排 5 个 tab 就要按 <strong>5 次 Tab</strong>
+      才能进内容区。Tab 键应该是<strong>进出</strong>控件的，
+      组内移动是方向键的活。
+    </p>
+  </div>
+</main>
+<script src="tabs.js"></script>
+<script>
+  // 仅为 demo：显示切换到哪个（组件本身零依赖）
+  (function () {
+    var list = document.querySelectorAll('.tabs__list');
+    if (!list.length) return;
+    var first = document.querySelector('.tabs');
+    var v = document.getElementById('logv1');
+    first.addEventListener('click', function (e) {
+      var t = e.target.closest ? e.target.closest('[role="tab"]') : null;
+      if (t && v) v.textContent = t.textContent;
+    });
+  })();
+</script>
+</body>
+</html>

package/03-patterns/tabs/tabs.css

@@ -0,0 +1,172 @@
+/* ============================================================================
+   Tabs — 标签页（APG: Tabs Pattern）
+   ============================================================================
+   🔴 键盘契约（照抄 Radix / APG，不是我的设计）
+   ------------------------------------------------
+       Tab          焦点进入 tab 组时，落在**当前选中**的 tab 上；
+                    在 tab 上再按 Tab ⇒ 走到**面板内容**
+       ArrowRight   下一个 tab（并激活）
+       ArrowLeft    上一个 tab（并激活）
+       ArrowDown    下一个 tab（纵向时）
+       ArrowUp      上一个 tab（纵向时）
+       Home         第一个 tab（并激活）
+       End          最后一个 tab（并激活）
+
+   🔴 roving tabindex：一组 tab 里**只有一个**是 `tabindex="0`，
+      其余是 `tabindex="-1"`。
+   为什么要这样：否则 Tab 键会**逐个穿过所有 tab**（一排 5 个 tab 要按 5 次 Tab）。
+   roving 让整组只占**一个 Tab 停靠点**，组内用方向键移动 ——
+   这是 APG 的要求，也是"键盘用户效率"的关键。
+
+   🔴 激活方式有两种（Radix 叫 activationMode）
+   ------------------------------------------------
+       automatic（默认）  方向键移动即切换面板
+       manual            方向键只移动焦点，需按 Enter/Space 才切
+
+   本组件**默认 automatic**（多数场景够用），
+   加 `.tabs--manual` 变成手动 —— 面板内容重时用（避免读屏不停播报）。
+   ========================================================================= */
+
+.tabs {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-4);
+}
+
+/* 手动激活模式
+   🔴 补上真实差异（不是补一条空规则凑数）。
+   `.tabs--manual` 是**行为开关**（tabs.js 读它决定方向键要不要切面板）——
+   之前它只存在于 JS 与文档里、CSS 一个字都没有 ⇒ `refs` 门禁报「class 未定义」。
+
+   为什么给它视觉差异：
+     自动模式下，方向键移动 = 面板**立刻**切换，用户需要一眼看出现在是哪个；
+     手动模式下，面板要按 Enter 才切，**选中项与"当前显示"可能不一致** ——
+     这时反而**不该**太强调，否则会误导"面板已经切了"。
+
+   ⇒ 手动模式：选中项**不加深色、不加粗**，只保留底部强调线。
+      这是诚实：还没生效的事，不该看起来已经生效。 */
+.tabs--manual .tabs__tab[aria-selected="true"] {
+  color: var(--text-secondary);
+  font-weight: 400;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .tabs--manual .tabs__tab[aria-selected="true"]:hover {
+    color: var(--text-primary);
+  }
+}
+
+/* ---- tab 组（那一排） */
+.tabs__list {
+  display: flex;
+  gap: var(--sp-1);
+  border-bottom: 1px solid var(--border-decor);
+  position: relative;
+
+  /* 🔴 窄屏横滑，不能撑破整页：320 视口 + 三个 tab ⇒ scrollWidth 320→331。
+     ⚠️ overflow-y 必须显式 hidden —— 一个轴 auto 会让另一轴也 auto 化，
+        否则选中态的 border-bottom 会被裁。 */
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: none;   /* 下面那条 border 已经暗示"这是一条栏" */
+}
+
+.tabs__list::-webkit-scrollbar { display: none; }
+
+
+/* 纵向变体 */
+.tabs--vertical {
+  flex-direction: row;
+  gap: var(--sp-4);
+}
+
+.tabs--vertical .tabs__list {
+  flex-direction: column;
+  border-bottom: 0;
+  border-inline-end: 1px solid var(--border-decor);
+}
+
+/* ---- 单个 tab */
+.tabs__tab {
+  appearance: none;
+  background: none;
+  border: 0;
+  /* 负 margin 让 tab 的下边框与 tablist 的重叠，选中时"接管"那条线 */
+  margin-bottom: -1px;
+  padding: var(--sp-3) var(--sp-4);
+  font: inherit;
+  font-size: var(--fs-base);
+  color: var(--text-secondary);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+  transition: color var(--dur-fast) var(--ease-out),
+              border-color var(--dur-fast) var(--ease-out);
+  white-space: nowrap;
+  /* 配合上面 .tabs__list 的横滑：tab 不许被压缩，
+     压窄了文字换行，比让用户滑一下更糟 */
+  flex: 0 0 auto;
+}
+
+.tabs--vertical .tabs__tab {
+  margin-bottom: 0;
+  margin-inline-end: -1px;
+  border-bottom: 0;
+  border-inline-end: 2px solid transparent;
+  text-align: start;
+}
+
+/* 选中态 */
+.tabs__tab[aria-selected="true"] {
+  color: var(--text-primary);
+  font-weight: 600;
+  border-bottom-color: var(--accent);
+}
+
+.tabs--vertical .tabs__tab[aria-selected="true"] {
+  /* 🔴 必须与上面 `.tabs--vertical .tabs__tab` 的 border-inline-end 同一侧，
+     否则 RTL 下选中线画在错误的一边（物理 border-right-* 不会跟着翻转）。 */
+  border-inline-end-color: var(--accent);
+}
+
+/* 🔴 hover 门控：触屏上"点一下"会先点亮 hover 再 click ⇒ 粘住不褪 */
+@media (hover: hover) and (pointer: fine) {
+  .tabs__tab:not([aria-disabled="true"]):hover {
+    color: var(--text-primary);
+    background: var(--surface-sunken);
+  }
+}
+
+.tabs__tab[aria-disabled="true"] {
+  color: var(--text-tertiary);
+  cursor: not-allowed;
+}
+
+/* 🔴 焦点环：tab 是 button，用 :focus-visible（鼠标点击不该出环） */
+.tabs__tab:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: -2px;      /* 往内，避免被 tablist 裁掉 */
+  border-radius: var(--r-sm) var(--r-sm) 0 0;
+}
+
+/* ---- 面板 */
+.tabs__panel {
+  padding: var(--sp-4) 0;
+}
+
+.tabs__panel[hidden] {
+  display: none;              /* 🔴 必须是 display:none
+                                  hidden 属性在某些 CSS 重置下会被覆盖 */
+}
+
+/* 动画（可选）：只做淡入，不做高度动画 ——
+   高度动画需要 JS 测量，且在 reduced-motion 下要能被关掉 */
+@media (prefers-reduced-motion: no-preference) {
+  .tabs__panel--enter {
+    animation: tabs-fade var(--dur-base) var(--ease-out);
+  }
+}
+
+@keyframes tabs-fade {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}