agentcss 0.0.0-stage → 0.11.2

package/02-primitives/input/input.css

@@ -0,0 +1,239 @@
+/* ============================================================================
+   frontend-lib / 02-primitives / input / input.css
+   输入框 · 状态矩阵 + 无障碍
+
+   依赖：01-tokens/tokens.css
+   版本：A ✅ / B ✅ / C ✅
+
+   🔴 与 button 最大的一处不同，别照抄：
+      button 用 :focus-visible  —— 鼠标点击时不该冒出难看的框
+      input  用 :focus        —— 用户必须随时知道"我现在在哪个框里"，
+                                 不管是鼠标点进去的还是 Tab 过去的。
+      这一条搞反，表单会非常难用。
+   ========================================================================= */
+
+/* ---------------------------------------------------------------- 容器 */
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-1);
+}
+
+/* ---------------------------------------------------------------- label
+   🔴 label 不是装饰。没有 label 的输入框，屏幕阅读器读出来只是一句"编辑框"。
+   三种合法写法：
+     <label for="x"> + <input id="x">           ← 推荐
+     <label>包住 input</label>                   ← 也行
+     <input aria-label="x">                      ← 仅在确实不能有可见 label 时
+   placeholder 不算 label —— 它一输入就消失，且对比度通常不达标。
+   ---------------------------------------------------------------- */
+.field__label {
+  font-size: var(--fs-sm);
+  font-weight: 500;
+  color: var(--text-primary);
+  line-height: var(--lh-tight);
+}
+
+/* 必填标记。不要只靠星号颜色 —— 带上 required 属性让机器也能读。 */
+.field__req {
+  color: var(--danger);   /* 6.26 AA */
+  margin-inline-start: 2px;
+}
+
+/* ---------------------------------------------------------------- 输入框本体 */
+.field__input {
+  width: 100%;
+  box-sizing: border-box;
+
+  height: 44px;             /* 同 button，触摸目标 */
+  padding: 0 var(--sp-3);
+
+  font-family: inherit;
+  /* 🔴 16px 是硬下限，不是审美。
+     iOS Safari 在 font-size < 16px 的输入框获得焦点时会**自动放大整个页面**，
+     用户会以为页面坏了。这是移动端最常见的表单 bug。 */
+  font-size: 16px;
+  line-height: 1.5;
+  color: var(--text-primary);
+
+  background: var(--surface);
+  border: 1px solid var(--border-control);   /* 3.56 达标（UI 边界需 >= 3.0） */
+  border-radius: var(--r-sm);
+
+  transition: border-color var(--dur-fast) var(--ease-out),
+              box-shadow   var(--dur-fast) var(--ease-out),
+              background-color var(--dur-fast) var(--ease-out);
+}
+
+.field__input::placeholder {
+  color: var(--text-tertiary);   /* 5.16 AA —— 占位符也要能读 */
+  opacity: 1;                    /* Firefox 默认给占位符加 opacity，会破坏对比度 */
+}
+
+/* 多行 */
+.field__input--textarea {
+  height: auto;
+  min-height: 88px;
+  padding: var(--sp-3);
+  resize: vertical;
+  line-height: var(--lh-base);
+}
+
+/* 紧凑（表格行内等鼠标场景）
+   ⚠️ demo 未用它，README 类名表列了它 ⇒ 是"已文档化的能力"，不是死代码。 */
+.field__input--sm { height: 36px; font-size: 16px; 
+  /* 🔴 输入框 的命中区给到 44px（WCAG 2.5.5）。
+     视觉高度不变，只是**手指落在这条带内任意位置都能命中**。 */
+  min-height: 44px;}
+
+/* ---------------------------------------------------------------- 状态：hover */
+@media (hover: hover) and (pointer: fine) {
+.field__input:hover:not(:disabled):not([readonly]) {
+  border-color: var(--text-tertiary);
+}
+}
+/* ---------------------------------------------------------------- 状态：focus
+   用 :focus 不用 :focus-visible（理由见文件头）。
+   视觉 = 边框变色 + 外圈 ring。两层是为了在深色/浅色背景下都看得清。
+   ---------------------------------------------------------------- */
+.field__input:focus {
+  outline: none;                        /* 去掉默认，用下面的自绘替代 */
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px var(--accent-soft);
+}
+
+/* ---------------------------------------------------------------- 状态：disabled
+   不可聚焦、值不提交、光标 not-allowed。
+   ---------------------------------------------------------------- */
+.field__input:disabled {
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);
+  border-color: var(--border-decor);
+  cursor: not-allowed;
+}
+
+/* ---------------------------------------------------------------- 状态：readonly
+   🔴 和 disabled 是两回事，别混用：
+     disabled : 不可聚焦、不可复制、**值不提交**
+     readonly : 可聚焦、可选中复制、**值会提交**
+   场景：展示计算结果、展示从别处带过来的值 —— 用 readonly，让用户能复制。
+   视觉上要能区分：readonly 保持可读（正常文字色），只把底色调暗一点。
+   ---------------------------------------------------------------- */
+.field__input[readonly] {
+  background: var(--surface-sunken);
+  color: var(--text-primary);   /* 保持正常对比度，用户要读它 */
+  border-color: var(--border-decor);
+  cursor: default;
+}
+.field__input[readonly]:focus {
+  border-color: var(--text-tertiary);
+  box-shadow: 0 0 0 3px var(--surface-sunken);
+}
+
+/* ---------------------------------------------------------------- 状态：error
+   🔴 WCAG 1.4.1：不能**只靠颜色**传达信息。
+   红边框 + 错误文字 + 图标，三者至少要有两个。
+   只把边框变红 = 色盲用户完全看不出哪里错了。
+   ---------------------------------------------------------------- */
+.field__input[aria-invalid="true"] {
+  border-color: var(--danger);
+}
+.field__input[aria-invalid="true"]:focus {
+  border-color: var(--danger);
+  box-shadow: 0 0 0 3px var(--danger-bg);
+}
+
+/* 错误图标：给色盲用户的第二条线索 */
+.field__input[aria-invalid="true"] {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%23b3261e' stroke-width='2.5' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='10'/%3E%3Cpath d='M12 8v5M12 16.5v.5'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right var(--sp-3) center;
+  padding-inline-end: 40px;   /* 给图标留位，否则文字会压在图标上 */
+}
+
+/* ---------------------------------------------------------------- 辅助说明
+   放在输入框下方，比 placeholder 好 —— 它不会消失。
+   用 aria-describedby 关联到 input。
+   ---------------------------------------------------------------- */
+.field__hint {
+  font-size: var(--fs-xs);
+  color: var(--text-tertiary);   /* 5.16 AA */
+  line-height: 1.5;
+}
+
+/* ---------------------------------------------------------------- 错误提示
+   必须满足两件事：
+     1) 有 role="alert" 或 aria-live —— 动态出现时屏幕阅读器会读出来
+     2) 通过 aria-describedby 关联 —— 用户聚焦输入框时能听到"哪里错了"
+   只变红不写文字，等于对屏幕阅读器用户静默失败。
+   ---------------------------------------------------------------- */
+.field__error {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sp-1);
+  font-size: var(--fs-xs);
+  color: var(--danger);   /* 6.26 AA */
+  line-height: 1.5;
+}
+.field__error::before {
+  content: "";
+  flex: none;
+  width: 14px;
+  height: 14px;
+  margin-top: 3px;
+  background: currentColor;
+  /* 叹号圆标 —— 给色盲用户的第二条线索 */
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2.5' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='10'/%3E%3Cpath d='M12 8v5M12 16.5v.5'/%3E%3C/svg%3E") center/contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2.5' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='10'/%3E%3Cpath d='M12 8v5M12 16.5v.5'/%3E%3C/svg%3E") center/contain no-repeat;
+}
+
+/* ---------------------------------------------------------------- 成功态
+   只在"校验有明确通过语义"时用（如"该用户名可用"）。
+   普通输入框加成功态是噪音。
+
+   ⚠️ **本库没有 JS 自动加 `data-state="valid"`** ——
+      `aria-invalid="false"` 由浏览器/你自己维护，这个属性也要自己加。
+      这条规则是给复用者的钩子，不是现成功能。
+   ---------------------------------------------------------------- */
+.field__input[aria-invalid="false"][data-state="valid"] {
+  border-color: var(--success);
+}
+
+/* ---------------------------------------------------------------- 布局变体
+   横向排列（label 在左）。窄屏自动回退为纵向。
+   ---------------------------------------------------------------- */
+.field--row {
+  flex-direction: row;
+  align-items: center;
+  gap: var(--sp-3);
+}
+.field--row .field__label {
+  flex: none;
+  min-width: 88px;
+}
+@media (max-width: 480px) {
+  .field--row { flex-direction: column; align-items: stretch; }
+  .field--row .field__label { min-width: 0; }
+}
+
+/* ============================================================================
+   反模式 —— 库内一律退回
+   =========================================================================
+   1. 用 placeholder 当 label
+      一输入就消失，对比度通常不达标，屏幕阅读器支持不一致。
+
+   2. 只把边框变红表示错误
+      WCAG 1.4.1 禁止只靠颜色传达信息。必须有文字 + 图标。
+
+   3. input 用 :focus-visible
+      鼠标点进去时没有视觉反馈，用户不知道光标在哪。input 用 :focus。
+
+   4. font-size < 16px
+      iOS Safari 会自动放大整个页面。
+
+   5. readonly 做成 disabled 的样子
+      用户会以为值不提交，且不能复制。
+
+   6. 错误提示没有 aria-live / 没有 aria-describedby
+      屏幕阅读器用户完全不知道错了。
+   ========================================================================= */

package/02-primitives/popover/README.md

@@ -0,0 +1,80 @@
+# popover · 气泡卡片
+
+通行系统的必备件。**非模态**——背景仍可交互，这是它与 dialog 的根本区别。
+
+## ⭐ 该用哪一个（记不住就问这句）
+
+> **用户需要"在里面操作"吗？**
+> 不需要 → `tooltip`
+> 需要，但不**打断**当前上下文 → **popover**
+> 需要，且**必须先处理完**才能继续 → `dialog`
+
+| | 能不能放交互内容 | 焦点管理 |
+|---|---|---|
+| `tooltip` | ❌ 只能纯文字 | 无 |
+| **`popover`** | ✅ 表单、按钮、列表都行 | **焦点进入** |
+| `dialog` | ✅ 但**模态**（背景锁死）| focus trap |
+
+参照实现：Radix Popover / MUI Popover / Carbon Popover。
+
+## 启用：DOM 由 JS 建，不用自己写
+
+```js
+const p = Popover.attach(按钮元素, { place: 'bottom', label: '标题' });
+```
+
+`attach()` 会自动：把触发器包进新建的 `.popover-anchor`（定位上下文）、
+建出浮层本体并写好 `role` 与 `aria-label`。
+
+| 参数 | 取值 |
+|---|---|
+| `place` | `bottom`（默认）/ `top` / `start` / `end` |
+| `label` | 浮层的 `aria-label` |
+
+返回的对象有 `open()` / `close()` / `toggle()`。
+
+全局还有两个：
+
+```js
+Popover.closeAll();   // 关掉当前开着的那个
+Popover.current;      // 当前开着的实例（没有则null）
+```
+
+## 内部结构（JS 生成，供你放内容）
+
+```html
+<span class="popover-anchor">
+  <button aria-haspopup="dialog" aria-expanded="false">…</button>
+  <div class="popover popover--bottom" role="dialog"
+       data-open="false" aria-label="标题" inert>
+    <div class="popover__title">…</div>
+    <div class="popover__desc">…可含表单、按钮、列表…</div>
+    <div class="popover__footer">…</div>
+    <span class="popover__arrow" aria-hidden="true"></span>
+  </div>
+</span>
+```
+
+| 部件 | 说明 |
+|---|---|
+| `.popover-anchor` | **定位上下文** —— 箭头与浮层都相对它 |
+| `.popover` + `--top/--bottom/--start/--end` | 浮层与四个方位，箭头自动指回触发器 |
+| `.popover__title` / `__desc` / `__footer` | 内容分区 |
+| `.popover__arrow` | 箭头 |
+
+⚠️ **关闭态用 `inert`，不是 `hidden`** —— `inert` 让内部元素**不可聚焦**
+（`hidden` 只是视觉隐藏，里面还能 Tab 到，这是常见错法）。
+
+## 🔴 四个最容易做错的地方
+
+| # | 要求 | 做错的后果 |
+|---|---|---|
+| ① | **非模态**：背景仍可交互，`role="dialog"` 但**不加 `aria-modal`** | 加了 `aria-modal` ⇒ 语义变成模态，读屏会锁焦点 |
+| ② | 焦点**进入**浮层 | 焦点留在触发器 ⇒ 键盘用户进不去，浮层等于摆设 |
+| ③ | `Esc` 关闭 **+ 焦点归还触发器** | 只关不还 ⇒ 焦点掉到 `<body>`，Tab 从头再来 |
+| ④ | 点**外部**关闭，点**浮层内部不关** | 内部点击也关 ⇒ 表单填到一半全没了（最常见的 bug）|
+
+## 动画
+
+尊重 `prefers-reduced-motion` —— 用户在系统里关了动效，
+组件的过渡也要跟着关。

package/02-primitives/popover/demo.html

@@ -0,0 +1,150 @@
+<!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>气泡卡片 · popover</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="../button/button.css">
+<link rel="stylesheet" href="popover.css">
+<style>
+.demo {
+    background: var(--surface);
+    border: 1px solid var(--border-decor);
+    border-radius: var(--r-md);
+    padding: var(--sp-4);
+    margin-bottom: var(--sp-4);
+  }
+.row { display: flex; gap: var(--sp-3); flex-wrap: wrap; }
+/* ⭐ 四个方向的演示必须**竖排**（跨引擎实测）
+   `end` 方向的浮层挂在锚点右侧（`inset-inline-start: 100%`），
+   横排时第 3 个按钮的浮层会顶到 483px —— 而手机视口是 393px。
+   ⚠️ 这不是"改测试让它过"：溢出是**真的**，Chromium 只是用
+      `innerWidth` 被内容撑大的方式把它量成了"没溢出"（WebKit 不会）。
+      竖排后每个方向都有整行宽度可用 ⇒ 演示成立，也不需要假装组件会翻转。 */
+.row--stack { flex-direction: column; align-items: flex-start; }
+.bad-demo { background: var(--danger-bg); border-color: var(--danger); }
+.bad { color: var(--danger); }
+table { width: 100%; border-collapse: collapse; font-size: var(--fs-sm); }
+td, th { text-align: left; padding: var(--sp-2); border-bottom: 1px solid var(--border-decor); }
+th { font-weight: 600; }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+  <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
+     加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。
+     ⚠️ 试过给 <body> 加 role="main"：axe 明确报 aria-allowed-role（该 role 对 <body>
+        是禁止的），而且也没解决 landmark 违规 ⇒ 已回退。 -->
+
+<h1>气泡卡片 · popover</h1>
+<p class="lede">用户需要<strong>在里面操作</strong>，但不该被强制中断时用。</p>
+
+<h2>1 · 四个方向</h2>
+<div class="demo">
+<div class="row row--stack">
+<button class="btn btn--md btn--secondary" id="p1">下方</button>
+    <button class="btn btn--md btn--secondary" id="p2">上方</button>
+    <button class="btn btn--md btn--secondary" id="p3">右侧</button>
+    <button class="btn btn--md btn--secondary" id="p4">左侧</button>
+  </div>
+  <p class="note">方向用<b>逻辑方向</b>写的（<code>end</code>/<code>start</code>），所以在 RTL 下会自动镜像。</p>
+</div>
+
+<h2>2 · 可以放交互内容（这是与 tooltip 的分界）</h2>
+<div class="demo">
+  <button class="btn btn--md btn--primary" id="p5">筛选条件</button>
+  <p class="note">点开后焦点<b>直接进入</b>浮层，可以立刻操作 —— 键盘用户不用先 Tab 一路走过来。</p>
+</div>
+
+<h2>3 · 带表单的浮层</h2>
+<div class="demo">
+  <button class="btn btn--md btn--secondary" id="p6">快速改备注</button>
+</div>
+
+<h2>怎么选？</h2>
+<div class="demo">
+  <table>
+    <tr><th>组件</th><th>能放交互内容</th><th>背景是否锁死</th><th>用在哪</th></tr>
+    <tr><td><code>tooltip</code></td><td>❌ 只能纯文字</td><td>—</td><td>补充说明、术语解释</td></tr>
+    <tr><td><b><code>popover</code></b></td><td>✅</td><td><b>不锁</b></td><td>筛选、快捷设置、补充表单</td></tr>
+    <tr><td><code>dialog</code></td><td>✅</td><td><b>锁死</b></td><td>危险确认、必须处理完的事</td></tr>
+  </table>
+  <p class="note">记不住就问一句：<b>「用户需要在里面操作吗？」</b>不需要 → tooltip；需要但不打断 → popover；必须先处理完 → dialog。</p>
+</div>
+
+<h2>反例 · 不该这样用</h2>
+<div class="demo bad-demo">
+  <button class="btn btn--md btn--danger" id="bad1">删除这份报告</button>
+  <p class="note bad">
+    <b>危险操作用 popover 是错的。</b><br>
+    二次确认必须用 <code>dialog</code>（模态 + focus trap）——
+    用了 popover，背景仍可点，用户很容易"顺手点掉别的东西"。<br>
+    <b>另外：</b>popover 里只放一行说明文字也不对 —— 那是 tooltip 的活。
+  </p>
+</div>
+
+<script src="popover.js"></script>
+<script>
+/* 演示用内容。真实项目里这些 HTML 应该在服务端或模板里生成。 */
+function demo(btnId, place, html, label) {
+  var el = document.getElementById(btnId);
+  if (!el) return;
+  window.Popover.attach(el, { place: place || 'bottom', html: html, label: label || '示例' });
+}
+
+demo('p1', 'bottom',
+  '<p class="popover__title">出现在下方</p>' +
+  '<p class="popover__desc">最常用。空间不够时应该往上翻。</p>', '方向示例');
+
+demo('p2', 'top',
+  '<p class="popover__title">出现在上方</p>' +
+  '<p class="popover__desc">靠近屏幕底部时用这个方向。</p>', '方向示例');
+
+demo('p3', 'end',
+  '<p class="popover__title">出现在右侧</p>' +
+  '<p class="popover__desc">横向空间富裕时用。</p>', '方向示例');
+
+demo('p4', 'start',
+  '<p class="popover__title">出现在左侧</p>' +
+  '<p class="popover__desc">横向空间富裕时用。</p>', '方向示例');
+
+demo('p5', 'bottom',
+  '<p class="popover__title">筛选条件</p>' +
+  '<p class="popover__desc">下面这些控件在浮层里直接操作。</p>' +
+  '<div class="row" style="gap:var(--sp-2)">' +
+  '<button class="btn btn--sm btn--secondary">近 7 天</button>' +
+  '<button class="btn btn--sm btn--secondary">近 30 天</button>' +
+  '</div>' +
+  '<div class="popover__footer">' +
+  '<button class="btn btn--sm btn--ghost">取消</button>' +
+  '<button class="btn btn--sm btn--primary">应用</button>' +
+  '</div>', '筛选条件');
+
+demo('p6', 'bottom',
+  '<p class="popover__title">改备注</p>' +
+  '<p class="popover__desc">焦点打开时已经在输入框里。</p>' +
+  '<input class="input" type="text" placeholder="写点什么…" ' +
+  'style="width:100%;height:36px;padding:0 var(--sp-2);' +
+  'border:1px solid var(--border-decor);border-radius:var(--r-sm);' +
+  'background:var(--surface);color:var(--text-primary)">' +
+  '<div class="popover__footer">' +
+  '<button class="btn btn--sm btn--ghost">取消</button>' +
+  '<button class="btn btn--sm btn--primary">保存</button>' +
+  '</div>', '快速改备注');
+
+/* 反例：故意用 popover 做危险确认（不要在真实项目里这么写） */
+demo('bad1', 'bottom',
+  '<p class="popover__title">确定删除？</p>' +
+  '<p class="popover__desc">这个操作不可撤销。</p>' +
+  '<div class="popover__footer">' +
+  '<button class="btn btn--sm btn--ghost">取消</button>' +
+  '<button class="btn btn--sm btn--danger">删除</button>' +
+  '</div>', '反面示例');
+</script>
+</main>
+</body>
+</html>

package/02-primitives/popover/popover.css

@@ -0,0 +1,187 @@
+/* ============================================================================
+   popover — 气泡卡片
+   ============================================================================
+   为什么需要它（通行系统的必备件）
+   ---------------------------------------------------------------------------
+   三种"浮层"职责不同，不能互相顶替：
+
+   ┌──────────┬────────────────────────────────────┬──────────┐
+   │          │ 能不能放交互内容                    │ 焦点管理  │
+   ├──────────┼────────────────────────────────────┼──────────┤
+   │ tooltip  │ ❌ 只能纯文字                       │ 无        │
+   │ popover  │ ✅ 表单、按钮、列表都行              │ **焦点进入**│
+   │ dialog   │ ✅ 但**模态**（背景锁死）            │ focus trap│
+   └──────────┴────────────────────────────────────┴──────────┘
+
+   ⭐ 判据（记不住就问这句）：
+     「用户需要**在里面操作**吗？」
+       不需要 → tooltip
+       需要，但**不打断**当前上下文 → **popover**
+       需要，且**必须先处理完**才能继续 → dialog
+
+   参照：Radix Popover / MUI Popover / Carbon Popover
+
+   设计要点
+   ---------------------------------------------------------------------------
+   ① **非模态**：背景仍可交互（这是与 dialog 的根本区别）
+   ② 焦点**进入**浮层（键盘用户能操作里面的内容）
+   ③ Esc 关闭 + 焦点归还
+   ④ 点击**外部**关闭，但**点击浮层内部不关**（常见 bug）
+   ⑤ 箭头：指向触发元素，且跟随位置变化
+   ⑥ 动画尊重 prefers-reduced-motion
+   ============================================================================ */
+
+/* ---------------------------------------------------------------------------
+   触发器
+   --------------------------------------------------------------------------- */
+.popover-anchor {
+  position: relative;      /* 箭头与浮层的定位上下文 */
+  display: inline-block;
+}
+
+/* ---------------------------------------------------------------------------
+   浮层本体
+   --------------------------------------------------------------------------- */
+.popover {
+  position: absolute;
+  z-index: var(--z-popover, 60);
+  min-width: var(--popover-min-w, 200px);
+  max-width: var(--popover-max-w, 320px);
+  padding: var(--popover-p, var(--sp-3));
+  background: var(--surface-raised);
+  color: var(--text-primary);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-md);
+  box-shadow: var(--shadow-2);
+  /* ⚠️ 不用 overflow:hidden —— 会把箭头切掉 */
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity var(--popover-dur, 140ms) var(--ease-out),
+              transform var(--popover-dur, 140ms) var(--ease-out);
+}
+
+/* 打开态 */
+.popover[data-open='true'] {
+  opacity: 1;
+  visibility: visible;
+}
+
+/* ---------------------------------------------------------------------------
+   四个方向（浮层相对锚点的位置）
+   ⚠️ 用逻辑上/下/左/右而不是物理方向，这样 RTL 下自动镜像。
+   --------------------------------------------------------------------------- */
+.popover--bottom { top: calc(100% + var(--popover-gap, 8px)); inset-inline-start: 50%; transform: translateX(-50%); }
+.popover--top    { bottom: calc(100% + var(--popover-gap, 8px)); inset-inline-start: 50%; transform: translateX(-50%); }
+.popover--end    { inset-inline-start: 100%; margin-inline-start: var(--popover-gap, 8px); top: 50%; transform: translateY(-50%); }
+.popover--start  { inset-inline-end: 100%; margin-inline-end: var(--popover-gap, 8px); top: 50%; transform: translateY(-50%); }
+
+/* 打开时的位移（去掉 translate 的那部分，只留"进入"方向） */
+.popover--bottom[data-open='true'] { transform: translateX(-50%) translateY(0); }
+.popover--top[data-open='true']    { transform: translateX(-50%) translateY(0); }
+.popover--end[data-open='true']    { transform: translateY(-50%) translateX(0); }
+.popover--start[data-open='true']  { transform: translateY(-50%) translateX(0); }
+
+/* ============================================================================
+   箭头
+   ============================================================================
+   ⭐ 箭头用**两个叠放的方块**而不是 border 三角：
+   border 三角无法跟随圆角边框，且在深色背景下边缘会有锯齿。
+   ============================================================================ */
+.popover__arrow {
+  position: absolute;
+  width: 10px;
+  height: 10px;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-decor);
+  transform: rotate(45deg);
+}
+
+.popover--bottom .popover__arrow {
+  top: -6px;
+  inset-inline-start: 50%;
+  margin-inline-start: -5px;
+  border-inline-end: none;
+  border-bottom: none;
+}
+.popover--top .popover__arrow {
+  bottom: -6px;
+  inset-inline-start: 50%;
+  margin-inline-start: -5px;
+  border-inline-start: none;
+  border-top: none;
+}
+.popover--end .popover__arrow {
+  inset-inline-start: -6px;
+  top: 50%;
+  margin-top: -5px;
+  border-inline-end: none;
+  border-top: none;
+}
+.popover--start .popover__arrow {
+  inset-inline-end: -6px;
+  top: 50%;
+  margin-top: -5px;
+  border-inline-start: none;
+  border-bottom: none;
+}
+
+/* ============================================================================
+   结构件
+   ============================================================================ */
+.popover__title {
+  font-size: var(--fs-md);
+  font-weight: 600;
+  margin: 0 0 var(--sp-1);
+}
+.popover__desc {
+  font-size: var(--fs-sm);
+  color: var(--text-secondary);
+  margin: 0 0 var(--sp-3);
+}
+/* 最后一个元素不要额外的下边距 */
+.popover__desc:last-child { margin-bottom: 0; }
+
+.popover__footer {
+  display: flex;
+  gap: var(--sp-2);
+  justify-content: flex-end;
+  margin-top: var(--sp-3);
+  padding-top: var(--sp-3);
+  border-top: 1px solid var(--border-decor);
+}
+
+/* 关闭态下的内容不可聚焦（否则 Tab 会跑到"看不见"的地方） */
+.popover:not([data-open='true']) * { pointer-events: none; }
+
+/* ============================================================================
+   减少动态效果
+   ⭐ 只去**位移**，保留 opacity —— 让"出现了"这件事仍然可感知。
+   ⚠️ 与 progress 的教训一致：不要留下任何"位置暗示"（如半截色块）。
+   ============================================================================ */
+@media (prefers-reduced-motion: reduce) {
+  .popover {
+    transition: opacity var(--popover-dur, 100ms) linear;
+    transform: none !important;
+  }
+  .popover[data-open='true'] { transform: none !important; }
+}
+
+/* ============================================================================
+   焦点样式
+   ============================================================================
+   ⚠️ 本库虽然有全局 `:focus-visible` 兜底（focus-ring.css），
+   但契约要求**组件自己声明** ——
+   原因：全局兜底可能被别的样式覆盖，而"浮层里的控件必须可见焦点"
+   是这个组件的**硬需求**（键盘用户要在里面操作）。
+   ============================================================================ */
+.popover :focus-visible,
+.popover-anchor :focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+  border-radius: var(--r-xs);
+}
+/* 浮层容器自身获得焦点时（无可聚焦内容的情况）也要有焦点环 */
+.popover[tabindex='-1']:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}