agentcss 0.0.0-stage → 0.11.2

package/03-patterns/content/README.md

@@ -0,0 +1,103 @@
+# content —— 内容渲染样式
+
+| 字段 | 内容 |
+|---|---|
+| **来源** | 依据 CommonMark 0.31.2 与 GFM 扩展，**不发明任何结构** |
+| **实测** | 由 `05-audit/md-render.py` 渲染 `04-recipes/longform/content.md` 验证 |
+| **适用** | 精简档 / B / C，纯 CSS |
+| **依赖** | `01-tokens/tokens.css` + `01-tokens/page.css`（页面骨架：`.wrap` / `.lede` / `.note`） + `01-tokens/typography.css` |
+| **规范** | 见本文件「内容渲染约定」一节|
+
+---
+
+## 一句话原则
+
+> **结构用标准，样式用 token。**
+
+元素和类名由 CommonMark / GFM 决定；颜色、字号、间距由 token 决定。
+**两者之间不需要发明任何东西。**
+
+所以 `content.css` 按**元素选择器**接管，**不给每个元素加类**：
+
+```css
+.prose > h2 { ... }
+.prose > pre > code { ... }
+.prose > table { ... }
+```
+
+结果：**从任何 CommonMark 兼容渲染器拿到的 HTML，不需要任何后处理就能正确显示。**
+
+唯一的自定义类名是 `.prose`——它不改变语义，只是"这块是正文"的标记。
+
+---
+
+## 三层能力，不能混为一谈
+
+| 层 | 表格 | 删除线 | 任务列表 |
+|---|---|---|---|
+| **CommonMark** | ❌ 不支持 | ❌ | ❌ |
+| **GFM**（生态事实标准）| ✅ | ✅ | ✅ |
+| 本库自定义 | 证据等级标记（`<sup class="evi">`）|
+
+🔴 **纯 CommonMark 项目里表格会直接失效**（渲染成 `<p>`）。
+要表格就必须用 GFM，这是硬依赖，不能假装有。
+
+本库的 CSS **两层都支持**，用不用由渲染器决定——**样式不挑食**。
+
+---
+
+## 🔴 两个实测踩到的坑
+
+### 1. 不同渲染器的输出**不完全一致**
+
+| 语法 | GitHub/GFM | markdown-it 实测 |
+|---|---|---|
+| `~~删除线~~` | `<del>` | **`<s>`** |
+
+两者都合法但语义不同（`<s>`=不再准确，`<del>`=已删除），
+所以 CSS **必须同时支持**，否则换渲染器就掉样式。
+
+> 这证明了一件事：**不存在"唯一正确的输出"，只有"规范允许的输出范围"。**
+> CSS 要覆盖那个范围，而不是假设某一种。
+
+### 2. `data:` URI 被渲染器拒绝 —— **不要"解决"它**
+
+想把图片内联进单文件（精简档 硬要求），自然会想到 data URI。
+但 markdown-it 的默认 `validateLink` 把 `data:` 列入黑名单（防 XSS），
+于是 `![x](data:image/svg+xml;base64,...)` **原样输出成文本**。
+
+🔴 **关掉 `validateLink` 就是降安全性**，正是本规范反对的"自己发挥"。
+
+替代方案：图片用真实相对路径（`04-recipes/longform/agc-memory.svg` 就是例子），
+或在构建阶段把图片转 base64 注入 HTML（渲染后处理，不在 Markdown 里写 data URI）。
+
+---
+
+## 怎么用
+
+```bash
+# Markdown → 自包含单文件 HTML（精简档）
+python 05-audit/md-render.py 内容.md -o out.html --title "标题"
+
+# 只跑检查，不输出
+python 05-audit/md-render.py 内容.md --check
+```
+
+`md-render.py` 做三件事：
+1. 用 markdown-it 渲染（commonmark preset + table + strikethrough）
+2. 检查标题层级 / `img` alt / 表格语义
+3. 内联 `tokens.css` + `content.css`，输出精简档 单文件
+
+---
+
+## 反模式
+
+- ❌ **给每个元素加类**（`.prose h2`、`.prose p2`…）—— 渲染器输出没有这些类
+- ❌ **`<div class="code-block">` 装代码** —— 用 `<pre><code class="language-x">`
+- 🔴 **`<div class="table">` 模拟表格** —— **最严重**：辅助技术会当普通 div 念，
+  屏幕阅读器用户拿不到行列关系。必须用 `<table>`
+- ❌ **`<div class="heading">` 代替标题** —— 文档大纲全废，"跳到标题"失效
+- ❌ **缩进代码块硬加 `class="language-"`** —— CommonMark 规定它没有 class
+- ❌ **`<b>` / `<i>` 代替 `<strong>` / `<em>`** —— `<b>` 只是视觉加粗，无语义
+- ❌ **hr 不清 `height` 和 `border-top`** —— 默认有 inset 边框，会出双线
+- ❌ **不排除代码块内的 `<code>`** —— 代码块每行都会带上行内代码的边框和底色

package/03-patterns/content/content.css

@@ -0,0 +1,286 @@
+/* ============================================================================
+   frontend-lib / 03-patterns / content / content.css
+   内容渲染样式 —— 接管 CommonMark / GFM 的标准输出
+
+   依赖：01-tokens/tokens.css
+   版本：A ✅ / B ✅ / C ✅
+
+   🔴 本文件最重要的设计决定：**不发明任何类名**。
+
+      结构由渲染器（CommonMark / GFM 规范）决定，
+      样式由本文件按**元素选择器**接管。
+      所以从任何 CommonMark 兼容渲染器拿到的 HTML，
+      **不需要任何后处理**就能正确显示。
+
+      只有一个自定义类名：`.prose` —— 用于限定作用域。
+      它不改变任何语义，只是"这块是正文"的标记。
+
+   依据：本文件顶部列出的渲染约定
+   ========================================================================= */
+
+.prose {
+  /* 正文行长：走语言感知令牌。
+     🔴 0.8.9 修（外部审计 P0-1b 发现）：原来这里硬写 `max-width: 68ch`，
+        而 68ch 是 tokens.css 里**拉丁语系**那一档的值
+        （中文下 --measure-prose 是 34em，拉丁下才是 68ch）
+        ⇒ 中文读者拿到的是拉丁的行宽，正文一行太长，扫视吃力。
+        ⇒ measure-gate 把扫描范围从 *.html 扩到 *.css 之后
+           才第一次看见这处硬写。 */
+  max-width: var(--measure-prose);
+  color: var(--text-primary);
+}
+
+/* ---------------------------------------------------------------- 元素间距
+   用兄弟选择器统一控制，不给每个元素写 margin。
+   这是"接管"的正确姿势 —— 渲染器不排版，排版归我们。 */
+.prose > * + * { margin-top: var(--sp-4); }
+
+/* ---------------------------------------------------------------- 标题
+   结构必须是 <h1>-<h6>，不能是 <div class="heading">。
+   层级不跳级由 a11y.py 门禁检查。 */
+.prose > h1,
+.prose > h2,
+.prose > h3,
+.prose > h4,
+.prose > h5,
+.prose > h6 {
+  font-family: var(--sans);
+  font-weight: 500;
+  line-height: var(--lh-tight);
+  letter-spacing: -0.008em;
+  margin: var(--sp-7) 0 0;
+}
+.prose > h1 { font-size: var(--fs-2xl); margin-top: 0; }
+.prose > h2 {
+  font-size: var(--fs-lg);
+  padding-top: var(--sp-5);
+  border-top: 2px solid var(--accent);
+  /* 短线段 + 通栏细线：既有分隔又不像卡片那样"框住" */
+  max-width: 92%;
+}
+.prose > h3 { font-size: var(--fs-md); }
+.prose > h4, .prose > h5, .prose > h6 {
+  font-size: var(--fs-base);
+  color: var(--text-secondary);
+}
+
+/* ---------------------------------------------------------------- 段落与行内 */
+.prose > p { margin: 0; line-height: 1.75; }
+
+/* 行内代码：衬线底 + 细边
+   ⚠️ 中文正文里的 `code` 通常是函数名/参数名，用等宽更清楚。 */
+.prose > code,
+.prose > li > code,
+.prose > td > code,
+.prose > th > code {
+  font-family: var(--mono);
+  font-size: 0.88em;
+  background: var(--surface-sunken);
+  border: 1px solid var(--border-decor);
+  border-radius: 3px;
+  padding: 0.05em 0.3em;
+}
+
+/* 🔴 代码块内的 <code> 必须排除行内样式。
+   CommonMark 两种代码块都输出 <pre><code>，不排除的话
+   代码块里的每行都会带上行内代码的边框和底色。 */
+.prose > pre > code,
+.prose > pre {
+  font-family: inherit;
+  font-size: inherit;
+  background: none;
+  border: none;
+  padding: 0;
+  border-radius: 0;
+}
+
+/* ---------------------------------------------------------------- 列表
+   CommonMark 的嵌套列表是 <li> 内直接嵌 <ul>，靠缩进表达层级。 */
+.prose > ul,
+.prose > ol { padding-inline-start: 1.5em; margin: 0; }
+.prose > ul { list-style: disc; }
+.prose > ol { list-style: decimal; }
+.prose li + li { margin-top: var(--sp-2); }
+.prose li > ul,
+.prose li > ol { margin-top: var(--sp-2); }
+.prose li > ul { list-style: circle; }   /* 二级用空心圆，三级会自动变方块 */
+
+/* ---------------------------------------------------------------- 引用
+   CommonMark 输出 <blockquote><p>…</p></blockquote> */
+/* 🔴 为什么这里**保留**竖条（0.8.4 · 全库竖条政策）
+   本库的整体立场是「去掉纯装饰的竖条」（见 typography.css / form-validation.css
+   各自的删除记录）：竖条在页面上拉出一条与内容无关的硬边。
+   ⇒ 但**引语与代码块是例外**，因为它们的竖条是**内容属性**、不是装饰：
+     · 引语 = "这是别人说的话" → 竖条是引用边界的视觉标记，
+       与学术排版的惯例一致，读者已经建立这个预期
+     · 代码块 = "这是原文"→ 同理，与 Markdown/Pandoc 的渲染结果一致
+   去掉它们，用户反而要靠缩进去猜"这段是引的还是正文"。*/
+.prose > blockquote {
+  margin: var(--sp-5) 0;
+  padding: 0 0 0 var(--sp-4);
+  border-inline-start: 3px solid var(--accent);
+}
+.prose > blockquote > p {
+  color: var(--text-secondary);
+  font-size: var(--fs-md);
+  line-height: 1.6;
+}
+/* 引用里再套引用 */
+.prose > blockquote > blockquote { margin: var(--sp-3) 0; }
+
+/* ---------------------------------------------------------------- 代码块
+   两种都输出 <pre><code>；围栏的带 class="language-xxx"，缩进的不带。
+   🔴 不给缩进代码块硬加 class —— 规范说它没有。 */
+/* 🔴 同上：代码块保留竖条的理由见上方 .prose > blockquote 的注释
+   （竖条在这里表示"这是原文"，属内容标记而非装饰）。*/
+.prose > pre {
+  margin: 0;
+  padding: var(--sp-4);
+  background: var(--surface-sunken);
+  border-inline-start: 3px solid var(--border-decor-str);
+  border-radius: 0 var(--r-sm) var(--r-sm) 0;
+  overflow-x: auto;
+  font-family: var(--mono);
+  font-size: var(--fs-xs);
+  line-height: 1.6;
+  tab-size: 4;
+  -webkit-overflow-scrolling: touch;
+}
+/* 缩进代码块没有左边框语言标记，给个更淡的，暗示"这是次要代码" */
+/* 🔴 逻辑属性：与上面 .prose > pre 的 border-inline-start 同侧。 */
+.prose > pre:not([class]) { border-inline-start-color: var(--border-decor); }
+
+/* ---------------------------------------------------------------- 表格（GFM）
+   🔴 必须是 <table>，不能用 div 模拟 —— div 会让屏幕阅读器读不出行列关系。 */
+.prose > table {
+  width: 100%;
+  border-collapse: collapse;
+  table-layout: auto;          /* ⚠️ 有 <colgroup> 时改用 fixed */
+  font-size: var(--fs-sm);
+}
+.prose > table th,
+.prose > table td {
+  text-align: start;
+  padding: var(--sp-2) var(--sp-4) var(--sp-2) 0;
+  border-bottom: 1px solid var(--border-decor);
+  vertical-align: top;
+}
+.prose > table th {
+  font-weight: 500;
+  font-size: var(--fs-xs);
+  color: var(--text-secondary);
+}
+.prose > table tbody tr:last-child td { border-bottom: 1px solid var(--border-decor-str); }
+
+/* ---------------------------------------------------------------- 其他元素 */
+.prose > hr {
+  margin: var(--sp-7) 0;
+  border: 0;
+  border-top: 1px solid var(--border-decor);
+  height: 0;                /* 🔴 hr 默认有 inset 边框，必须清掉 */
+}
+
+.prose > img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+  /* 🔴 每个 img 必须有显式宽高（CLS）——
+     这条由 viewport.py 门禁检查，本 CSS 不兜底 */
+  border-radius: var(--r-sm);
+}
+/* 🔴 必须是**后代**选择器，不是 `> a`：正文链接几乎都在 `<p>` 里，
+   `> a` 只覆盖直接子链接 ⇒ 段落里的链接落到浏览器默认蓝，
+   暗色下对比度 1.91:1（`dark-contrast` 实测抓到）。 */
+.prose a {
+  color: var(--accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
+}
+@media (hover: hover) and (pointer: fine) {
+.prose a:hover { color: var(--text-primary); }
+}
+.prose a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+/* 外链可访问性：新窗口打开必须告知 */
+.prose > a[target="_blank"]::after {
+  content: " ↗";
+  font-size: 0.8em;
+  vertical-align: 0.1em;
+}
+
+/* GFM 删除线
+   🔴 实测：markdown-it 输出 `<s>`，GitHub/GFM 规范规定 `<del>`。
+      两者都是合法 HTML（`<s>`=不再准确，`<del>`=已删除）但语义不同。
+      ⇒ 样式必须同时支持，否则换渲染器就掉样式。
+      查证所用渲染器：markdown-it-py（commonmark preset + strikethrough）。 */
+.prose > del,
+.prose > s,
+.prose > li > del,
+.prose > li > s { color: var(--text-tertiary); }
+
+/* GFM 任务列表
+   CommonMark 核心不产出这个，GFM 扩展才有：
+   <li class="task-list-item"><input type="checkbox" disabled> … */
+.prose .task-list-item { list-style: none; margin-inline-start: -1.5em; }
+.prose .task-list-item input[type="checkbox"] {
+  margin-inline-end: var(--sp-2);
+  vertical-align: middle;
+}
+.prose .task-list-item input[disabled] {
+  /* disabled 的复选框不可改，但必须仍能看出状态 —— 不用 opacity */
+  accent-color: var(--accent);
+}
+
+/* ---------------------------------------------------------------- 无障碍兜底 */
+.prose :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+/* ============================================================================
+   反模式
+   =========================================================================
+   1. 给每个元素加类（.prose h2、.prose p2 …）
+      渲染器输出没有这些类，样式接不上。**按元素选择器接管**。
+
+   2. <div class="code-block"> 装代码
+      渲染器不认。用 <pre><code class="language-x">。
+
+   3. <div class="table"> 模拟表格
+      🔴 最严重：辅助技术会当普通 div 念，屏幕阅读器用户拿不到行列关系。
+
+   4. <div class="heading"> 代替标题
+      文档大纲全废，屏幕阅读器的"跳到标题"功能失效。
+
+   5. 缩进代码块硬加 class="language-"
+      CommonMark 规定它没有 class。
+
+   6. <b> / <i> 代替 <strong> / <em>
+      <b> 只是"视觉加粗"，无语义。
+
+   7. hr 不清 height 和 border-top
+      默认 hr 有 inset 边框，会出现双线。
+
+   8. 依赖行内 <code> 样式而不排除代码块内的
+      代码块每行都会带上边框和底色。
+   ========================================================================= */
+
+/* ============================================================================
+   链接
+   ============================================================================
+   暗色下浏览器默认链接蓝只有 1.91:1，几乎看不见 ⇒ 需要设 color。
+
+   🔴🔴 但**必须限定作用域**，不能写裸 `a {}`
+      裸标签选择器会命中**宿主页面的每一个链接** ——
+      也就是说：使用者引入本库后，自己站点所有 <a> 的颜色都会被改掉。
+      这正是「改一处、全库变样」的污染源之一。
+
+      正解：挂到本组件自己的根选择器上。作用域与组件一致，组件外完全不受影响。
+
+   🔴 修：这里原写 `.content a`，而本组件根类是 **`.prose`** ——
+     `.content` 全库 0 处出现 ⇒ 整段是死规则，而注释还写着它是根类。
+     文档说一套、代码是另一套 ⇒ "链接已处理"这个判断一直是假的。
+   ============================================================================ */
+.prose a:visited {
+  color: var(--accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}

package/03-patterns/content/demo.html

@@ -0,0 +1,88 @@
+<!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>content · 正文渲染 · frontend-lib</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="content.css">
+<style>
+.demo-note {
+    max-width: 42rem; margin: 0 auto var(--sp-6);
+    padding: var(--sp-3) var(--sp-4);
+    background: var(--surface-sunken);
+    border-radius: var(--r-sm);
+    font-size: var(--fs-sm); color: var(--text-secondary);
+  }
+</style>
+</head>
+<body class="page page">
+
+<main>
+<p class="demo-note">
+  <strong>content</strong> 接管 Markdown 渲染出来的元素：<b>结构用标准</b>（CommonMark/GFF 决定），
+  <b>样式用令牌</b>（颜色/字号/间距全部来自 tokens.css）。
+  所以它按<strong>元素选择器</strong>工作，不给每个元素加类。
+</p>
+
+<!-- 🔴 新建：此前本组件只有 content.css + README.md，**没有 demo.html**，
+     ⇒ 契约脚本拿不到页面、量不到任何东西（等于契约在空跑）。
+     这份 demo 同时作为「标题层级不跳级」的活样本。 -->
+<div class="prose">
+  <h1>季度经营分析</h1>
+  <p class="lede">
+    本节演示正文容器接管 <code>&lt;h1&gt;</code>～<code>&lt;h3&gt;</code>、
+    段落、列表、表格、引用、代码块的样子。层级刻意按 h1→h2→h3 顺序排，
+    供 <code>content-check.js</code> 检查「不跳级」。
+  </p>
+
+  <h2>1 · 关键指标</h2>
+  <p>下面是三个核心指标。<strong>加粗</strong>与<em>斜体</em>都走令牌，不写死样式。</p>
+  <ul>
+    <li>营业收入：同比 +12.4%</li>
+    <li>毛利率：<code>62.1%</code>（用等宽字体，数字对齐）</li>
+    <li>经营现金流：转正</li>
+  </ul>
+
+  <h3>1.1 · 分季度明细</h3>
+  <table>
+    <caption>2025–2026 分季度经营数据（单位：万元）</caption>
+    <thead>
+      <tr><th scope="col">季度</th><th scope="col">收入</th><th scope="col">毛利率</th></tr>
+    </thead>
+    <tbody>
+      <tr><th scope="row">2025 Q3</th><td class="num">4,120</td><td class="num">60.8%</td></tr>
+      <tr><th scope="row">2025 Q4</th><td class="num">4,586</td><td class="num">61.5%</td></tr>
+      <tr><th scope="row">2026 Q1</th><td class="num">4,903</td><td class="num">62.1%</td></tr>
+    </tbody>
+  </table>
+
+  <h2>2 · 风险提示</h2>
+  <blockquote>
+    <p>应收账款周转天数环比恶化 6 天，需在下季度收紧信用政策。</p>
+  </blockquote>
+  <ol>
+    <li>对账期 &gt; 60 天的新客户改为预付</li>
+    <li>逾期 &gt; 30 天暂停发货</li>
+  </ol>
+
+  <h2>3 · 术语</h2>
+  <dl>
+    <dt>EBITDA</dt>
+    <dd>息税折旧摊销前利润</dd>
+    <dt>CAC</dt>
+    <dd>客户获取成本</dd>
+  </dl>
+
+  <h2>4 · 代码与链接</h2>
+  <pre><code>const f = (x) =&gt; x * 2;   // 纯 ES5 时代写法</code></pre>
+  <p>详细口径见 <a href="#main">内部数据字典</a>。</p>
+</div>
+
+</main>
+
+</body>
+</html>

package/03-patterns/drawer/README.md

@@ -0,0 +1,79 @@
+# drawer · 抽屉
+
+依据 **APG Dialog 模式** —— 抽屉就是"从侧边滑进来的 Dialog"。
+
+**与 dialog 的差别只有"从哪进来"，三条硬要求完全一样。**
+
+## 🔴 三条硬要求（一条都不能少）
+
+| # | 要求 | 做错的后果 |
+|---|---|---|
+| ① | **焦点陷阱**：Tab 在抽屉内循环 | Tab 跑到背景上去，抽屉等于没锁 |
+| ② | `Esc` 关闭 | 键盘用户出不来 |
+| ③ | **关闭后焦点归位**（回到触发它的那个按钮）| 键盘用户被"扔"回页面顶部，得从头 Tab 一遍 |
+
+③ 最容易漏、**影响最大**。所以本组件的焦点归位走共享微行为核
+`01-tokens/behavior/focus-return.js` 注入，不是各组件各写一遍。
+
+## ⚠️ 抽屉是模态：背景必须 inert
+
+```js
+// 只把 body 的直接子元素（除抽屉容器）设 inert
+```
+
+不设 `inert` / `aria-hidden` 的后果：**读屏会同时读到抽屉与背景**
+（业内叫"双重朗读"）—— 用户听到一半不知道自己在听哪。
+
+## 结构
+
+```html
+<aside class="drawer drawer--right" role="dialog" aria-modal="true"
+       aria-label="标题">
+  <header class="drawer__head">
+    <h2 class="drawer__title">…</h2>
+    <button class="drawer__close" type="button">✕</button>
+  </header>
+  <div class="drawer__body">…</div>
+  <footer class="drawer__foot">…</footer>
+</aside>
+```
+
+| 部件 | 说明 |
+|---|---|
+| `--right`（默认）/ `--left` / `--top` / `--bottom` | 四个进入方向 |
+| `.drawer__head` / `__title` / `__close` | 头部与关闭按钮 |
+| `.drawer__body` | 内容 |
+| `.drawer__foot` | 底部操作区 |
+
+## 启用
+
+```js
+Drawer.open({ place: 'right' });   // 默认就是 right
+```
+
+全局只导出 `open`（不是 `create`）—— DOM 由 JS 建。
+
+### 🔴 焦点必须在插入 DOM **之前**记
+
+```js
+// ⭐ 记住"打开那一刻的焦点" —— 必须在插入 DOM 之前，
+//    否则会记到刚建出来的新节点上（那就等于没记）
+```
+
+抽屉没有 fallback：打开它的元素若被删了，就**维持现状不动**，
+不假装"还回去了"（那样会把焦点送到一个已经不存在的地方）。
+
+## 嵌套用锁计数
+
+背景 `inert` 用 `lockCount` 计数管理 ⇒ 抽屉里再开抽屉时，
+外层的锁不会因为内层关闭而被提前解掉。
+
+## 成熟度：beta（两条行为债，如实列出）
+
+| 债 | 现在的后果 |
+|---|---|
+| `dismissable:manual` | 点遮罩关闭是手写的，不是统一机制 |
+
+## 门禁
+
+`05-audit/drawer-check.js`

package/03-patterns/drawer/demo.html

@@ -0,0 +1,101 @@
+<!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>drawer · 抽屉 · frontend-lib</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/focus-ring.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="../../02-primitives/button/button.css">
+<link rel="stylesheet" href="drawer.css">
+<style>
+.row { display: flex; gap: var(--sp-3); flex-wrap: wrap; }
+.log {
+    margin-top: var(--sp-4); padding: var(--sp-3);
+    background: var(--surface-sunken); border-radius: var(--r-sm);
+    font-family: var(--mono); font-size: var(--fs-xs);
+    color: var(--text-secondary); min-height: 3.4em;
+  }
+ul.demo-list { padding-left: var(--sp-5); color: var(--text-secondary); }
+ul.demo-list li { margin: var(--sp-1) 0; }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+
+<h1>drawer · 抽屉</h1>
+<p class="note">
+  依据 <strong>APG Dialog</strong>。与对话框的差别只是「从哪进来」，
+  三条硬要求完全一样：<strong>焦点陷阱</strong>（Tab 不跑出抽屉）·
+  <code>Esc</code> 关闭 · <strong>关闭后焦点归位</strong>（回到触发按钮）。
+  <br>⚠️ 抽屉是<strong>模态</strong>：背景设 <code>inert</code>，
+  否则读屏会同时读到抽屉与背景（"双重朗读"）。
+</p>
+
+<h2>1 · 四个方向</h2>
+<div class="row">
+  <button class="btn" data-place="right">右侧</button>
+  <button class="btn" data-place="left">左侧</button>
+  <button class="btn" data-place="top">顶部</button>
+  <button class="btn" data-place="bottom">底部</button>
+</div>
+<div class="log" id="log">（关闭后会显示焦点是否归位）</div>
+
+<h2>2 · 初始焦点可指定</h2>
+<div class="row">
+  <button class="btn btn--primary" id="b2">打开（焦点落在第二个按钮）</button>
+</div>
+
+</main>
+
+<script src="drawer.js"></script>
+<script>
+(function () {
+  var log = document.getElementById('log');
+
+  var BODY = '<ul class="demo-list">' +
+    '<li>可以在这里放任意内容</li>' +
+    '<li>背景已被设成 inert（读屏不会重复读）</li>' +
+    '<li>连按 Tab 试试：焦点在抽屉里循环</li>' +
+    '<li>按 Esc 关闭，焦点会回到刚才那个按钮</li>' +
+    '</ul>';
+
+  document.querySelectorAll('[data-place]').forEach(function (b) {
+    b.addEventListener('click', function () {
+      var place = b.getAttribute('data-place');
+      var dr = Drawer.open({
+        place: place,
+        title: '从' + place + '进来的抽屉',
+        content: BODY,
+        actions: [
+          { label: '取消' },
+          { label: '确定', variant: 'primary' },
+        ],
+        onClose: function () {
+          log.textContent = '已关闭 · 焦点现在在「' +
+            (document.activeElement ? document.activeElement.textContent.trim().slice(0, 12) : '?') +
+            '」' + (document.activeElement === b ? ' ✅ 已归位' : ' 🔴 没归位');
+        },
+      });
+    });
+  });
+
+  document.getElementById('b2').addEventListener('click', function () {
+    Drawer.open({
+      place: 'right',
+      title: '初始焦点在「取消」',
+      content: BODY,
+      initialFocus: '.drawer__foot .btn:not(.btn--primary)',
+      actions: [
+        { label: '取消' },
+        { label: '确定', variant: 'primary' },
+      ],
+    });
+  });
+})();
+</script>
+</body>
+</html>