agentcss 0.25.1 → 0.25.2

package/02-primitives/button/README.md

@@ -46,6 +46,13 @@
 变体：`primary` / `secondary` / `ghost` / `danger`
 尺寸：`sm`(32) / `md`(44) / `lg`(52)
 
+> ⚠️ `.btn--icon.btn--sm` 是 **32×32**，只满足 WCAG 2.2 的 AA（24px），
+> **不满足 44px 的 AAA**。它只适用于表格行、标签条这类鼠标为主、相邻控件
+> 本身就很密的位置；触屏主流程请用 `md`。
+> （所以演示页不放它：`button-check` 第 ③ 条要求整页可点元素 ≥44px，
+> 放进来必然红 —— 那个红是对的。同类取舍见 `upload` 的 32px 移除按钮，
+> 它在 `05-audit/tap-target.js` 里是**登记过的**例外。）
+
 ---
 
 ## 🔴 最关键的一个判断：`disabled` 还是 `aria-disabled`

package/02-primitives/button/demo.html

@@ -16,6 +16,8 @@
 .cell p { margin: 0 0 var(--sp-4); font-size: var(--fs-xs);
              color: var(--text-tertiary); line-height: 1.55; }
 .row { display: flex; gap: var(--sp-3); flex-wrap: wrap; align-items: center; }
+/* 给 btn--block 一个"容器边界"，否则它会铺满整页、看不出"占满容器"这件事 */
+.narrow { max-width: 280px; }
 /* 反例演示用 */
 .btn--naive { height: 44px; padding: 0 var(--sp-5); border: none; border-radius: var(--r-sm);
                 background: var(--accent); color: #fff; cursor: pointer; font-size: var(--fs-sm);
@@ -126,6 +128,56 @@
     sm 只在表格行内等鼠标场景用。
   </p>
 
+  <h2 class="rule-bottom">两种形态：方形图标按钮 / 占满一行</h2>
+  <div class="grid">
+    <div class="cell">
+      <h3><code>.btn--icon</code> · 只有图标</h3>
+      <p>
+        宽高相等（<code>--md</code> 44、<code>--lg</code> 52、<code>--sm</code> 32），所以图标必须是<strong>唯一内容</strong>。
+        ⇒ 读屏读不到文字，必须显式给 <code>aria-label</code>，
+        否则念出来只有"按钮"两个字。
+      </p>
+      <div class="row">
+        <button class="btn btn--md btn--secondary btn--icon" aria-label="刷新数据">
+          <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor"
+               stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+               aria-hidden="true" focusable="false"><path d="M21 12a9 9 0 1 1-2.6-6.4M21 3v6h-6"/></svg>
+        </button>
+        <button class="btn btn--md btn--primary btn--icon" aria-label="新建">
+          <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor"
+               stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+               aria-hidden="true" focusable="false"><path d="M12 5v14M5 12h14"/></svg>
+        </button>
+        <button class="btn btn--md btn--secondary btn--icon" aria-label="收起侧栏">
+          <svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor"
+               stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+               aria-hidden="true" focusable="false"><path d="M15 6l-6 6 6 6"/></svg>
+        </button>
+      </div>
+      <p style="margin-top:var(--sp-3); font-size:var(--fs-xs); color:var(--text-tertiary)">
+        <code>.btn--icon.btn--sm</code> 是 32×32：只够 WCAG 2.2 的 AA（24px），
+        <strong>不满足 44px 的 AAA</strong> ⇒ 所以这里<strong>故意不演示</strong>它。
+        它只该出现在表格行、标签条这类鼠标为主、相邻控件本身就很密的地方；
+        触屏主流程请用 md。契约第 ③ 条要求本页所有可点元素 ≥44px，
+        放一颗 32px 的按钮进来就会红 —— 那个红是对的。
+      </p>
+    </div>
+    <div class="cell">
+      <h3><code>.btn--block</code> · 占满容器</h3>
+      <p>
+        不是 <code>width:100%</code> 的按钮，而是 <code>display:flex</code> 的容器
+        ⇒ 内容自动居中，多个子元素（图标 + 文字）也不会各靠一边。
+      </p>
+      <div class="narrow">
+        <button class="btn btn--md btn--primary btn--block">提交审批</button>
+      </div>
+      <p style="margin-top:var(--sp-3); font-size:var(--fs-xs); color:var(--text-tertiary)">
+        外面这个 280px 的框就是它的容器：按钮正好铺满，不多不少。
+        宽度来自容器而不是按钮自己 ⇒ 放进窄侧栏、弹窗底部都不会溢。
+      </p>
+    </div>
+  </div>
+
   <h2 class="rule-bottom">对比：常见的错写法 vs 本库写法</h2>
   <div class="cmp cmp--wide-first">
     <div class="cmp__pane cmp__bad" data-bad="button|gw|>=3">

package/02-primitives/card/README.md

@@ -5,7 +5,7 @@
 | **来源** | 原创。2px 抬起一条来自对 `animal-island-ui` 的观察（那套设计里最认同的一条） |
 | **实测** | `states.py` 零缺失（card 形态：focus HIGH / hover LOW） |
 | **适用** | 精简档 / B / C，纯 CSS |
-| **依赖** | `01-tokens/tokens.css`  + `01-tokens/typography.css`（`.note` 提示框） + `01-tokens/page.css`（页面骨架：`.wrap` / `.lede` / `.note`） |
+| **依赖** | `01-tokens/tokens.css`  + `01-tokens/typography.css`（`.note` 提示框） + `01-tokens/page.css`（页面骨架：`.wrap` / `.lede` / `.note`）。底栏要放**按钮**时再加 `02-primitives/button/button.css`（本目录 demo 已引入） |
 
 ---
 
@@ -71,6 +71,11 @@
 </div>
 ```
 
+> 底栏右侧放**按钮**也行（dense 列表里更常见），但要额外引入
+> `02-primitives/button/button.css` —— 卡片本身不定义按钮样式。
+> ⚠️ 别放**裸链接**当主操作：文字链接的命中区只有一行高（约 17px），
+> 触屏上点不中；卡片契约第 ③ 条要求可点元素 ≥44px，会直接红。
+
 依赖：`01-tokens/tokens.css` + `01-tokens/typography.css`（正文）+
 `01-tokens/page.css`（`.wrap` / `.small` 等页面骨架）。
 

package/02-primitives/card/demo.html

@@ -9,6 +9,9 @@
 <link rel="stylesheet" href="../../01-tokens/typography.css">
 <link rel="stylesheet" href="../../01-tokens/page.css">
 <link rel="stylesheet" href="card.css">
+<!-- 底栏里的动作按钮：卡片本身不定义按钮样式，演示页直接引 button.css
+     （同一个库里的组件组合，不是复制一份按钮样式）。 -->
+<link rel="stylesheet" href="../button/button.css">
 <style>
 p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6; }
 .grid3 { display: grid; gap: var(--sp-4); grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
@@ -113,6 +116,16 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
         <p class="card__desc">用 inset box-shadow 做内描边，不是改 border-width —— 同样为了不跳动。</p>
       </div>
     </div>
+    <div class="card card--compact">
+      <div class="card__body">
+        <h3 class="card__title">compact</h3>
+        <p class="card__desc">内边距 24→16、标题降到正文大小。用在"一屏要放十几张"的清单里。</p>
+      </div>
+      <div class="card__footer">
+        <span class="small">更新于 09-12</span>
+        <button class="btn btn--md btn--secondary">查看</button>
+      </div>
+    </div>
   </div>
 
   <h2 class="rule-bottom">整卡可点：Tab 一下试试</h2>

package/02-primitives/choice/choice.css

@@ -59,6 +59,11 @@
   min-height: 44px;               /* 触摸目标 44px：视觉方框只有 20px */
   cursor: pointer;
   user-select: none;
+  /* 🔴 0.25.2 补：`.choice__hint` 要能落到标签**下方**（README 的承诺）。
+     没有 wrap 时，它作为第三个 flex item 会被挤到标签右侧、
+     还因为 label 是 flex:1 而被推到最右边 —— 文档写"下方"，实际在右边。
+     只有存在 hint 时才换行，单子元素的既有布局一个像素都不动。 */
+  flex-wrap: wrap;
 }
 
 .choice__label {
@@ -187,6 +192,11 @@
   font-size: var(--fs-xs);
   color: var(--text-tertiary);
   line-height: 1.5;
+  /* 独占一行，并与标签**文字**左对齐：
+     缩进 = 勾选框 20px + label 内 gap（--sp-2）。
+     （20px 与 `.choice__mark` 的 width 是同一个值，改一处要连着改。） */
+  flex: 1 0 100%;
+  margin-inline-start: calc(20px + var(--sp-2));
 }
 
 /* ============================================================================

package/02-primitives/choice/demo.html

@@ -63,6 +63,21 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
     <p class="small" style="margin-top:var(--sp-3)">
       整个 label 都能点（input 透明铺满了它），但视觉方框只有 20px——<strong>触摸目标是 44px</strong>。
     </p>
+
+    <div class="choice choice--checkbox">
+      <input class="choice__input" type="checkbox" id="c1b" aria-describedby="c1b-hint">
+      <label class="choice__label" for="c1b">
+        <span class="choice__mark"></span>
+        <span>订阅月度报告</span>
+      </label>
+      <span class="choice__hint" id="c1b-hint">每月 1 日发一封，可随时退订</span>
+    </div>
+    <p class="small" style="margin-top:var(--sp-3)">
+      <code>.choice__hint</code> 是<strong>解释</strong>，不是标签的一部分：
+      它排在标签下方、和文字左对齐，并且用 <code>aria-describedby</code> 关联 ——
+      读屏念"订阅月度报告，复选框"，再补一句说明。
+      （写进 label 里会变成名字的一部分，念起来像"订阅月度报告每月1日发一封可随时退订"。）
+    </p>
   </div>
 
   <h2 class="rule-bottom">indeterminate（第三态）</h2>
@@ -169,6 +184,29 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
       <span class="kbd">↑</span><span class="kbd">↓</span> 选择、<span class="kbd">Enter</span> 确认、Esc 关闭全部保留。
       箭头写了 <code>pointer-events:none</code>，否则它会吃掉点击。
     </p>
+
+    <!-- 选项文字会换行 / 多选列表：高度必须放开，否则第二行被裁掉 -->
+    <div class="field" style="margin-top:var(--sp-5)">
+      <label class="field__label" for="s2">导出字段（可多选）</label>
+      <div class="select">
+        <select class="select__control select__control--auto" id="s2" multiple size="4"
+                aria-describedby="s2-hint">
+          <option selected>科目编码</option>
+          <option selected>科目名称</option>
+          <option>期初余额（跨年调整后，含上年重分类的说明会换行）</option>
+          <option>本期发生额（借贷方分开列示，便于与总账核对）</option>
+          <option>期末余额</option>
+        </select>
+      </div>
+      <span class="field__hint" id="s2-hint">
+        按住 <span class="kbd">Ctrl</span> / <span class="kbd">⌘</span> 多选
+      </span>
+    </div>
+    <p class="small" style="margin-top:var(--sp-3)">
+      <code>.select__control--auto</code>：固定 44px 高度遇到换行文字会把第二行<strong>裁掉</strong>，
+      所以多选列表 / 长选项要把高度放开（<code>height:auto</code> + <code>min-height:44px</code>）。
+      这是原生 select，箭头就不需要了 —— 它本来就不是"点开下拉"的交互。
+    </p>
   </div>
 
   <h2 class="rule-bottom">disabled</h2>

package/02-primitives/date-range/README.md

@@ -37,7 +37,7 @@
 | `[data-dr-error]` | 错误容器，`role="alert"` |
 | `[data-dr-summary]` | 选中区间的摘要（如「共 92 天」）|
 | `[data-dr-clear]` | 清除，**不可省** |
-| `.drange--disabled` | 整体禁用 |
+| `.drange--disabled` | 视觉禁用（预设与清除置灰、hover 不变色）。**它只管观感** —— 真正不可用还要给内部 `input` / `button` 加原生 `disabled`，见 demo 第 3 节 |
 
 ⚠️ 标记名是 **`data-dr-*`**（`dr` 缩写），不是 `data-drange-*`。
 

package/02-primitives/date-range/demo.html

@@ -76,6 +76,36 @@
   <div class="log" id="log2">（试着填一个 2019 年或 2027 年 ⇒ 会报错）</div>
 </div>
 
+<h2 class="rule-bottom">3 · 只读区间：<code>drange--disabled</code> + 原生 <code>disabled</code></h2>
+<p class="note">
+  <strong>一件事要拆成两半做，缺一半就假。</strong>
+  <br>· <code>.drange--disabled</code> 负责<strong>观感</strong>：预设与清除置灰、hover 不再变色；
+  <br>· 原生 <code>disabled</code> 属性负责<strong>行为</strong>：点不动、Tab 跳过、
+  读屏念"不可用"。
+  <br>只有类名 ⇒ 看着灰但点得动（最糟的一种）；只有属性 ⇒ 灰得不对，hover 还会亮。
+</p>
+<div class="pad">
+  <div class="drange drange--disabled" id="d3">
+    <div class="drange__field">
+      <label class="drange__label" for="f3">开始</label>
+      <input class="drange__input" type="date" id="f3" data-dr-from value="2026-01-01" disabled>
+    </div>
+    <span class="drange__sep" aria-hidden="true">→</span>
+    <div class="drange__field">
+      <label class="drange__label" for="t3">结束</label>
+      <input class="drange__input" type="date" id="t3" data-dr-to value="2026-03-31" disabled>
+    </div>
+    <button class="drange__clear" type="button" data-dr-clear disabled>清除</button>
+    <div class="drange__error" data-dr-error role="alert" hidden></div>
+    <div class="drange__summary" data-dr-summary aria-live="polite"></div>
+    <div class="drange__presets" data-dr-presets></div>
+  </div>
+  <p class="small">
+    这一块是<strong>已发布报表的冻结区间</strong>：读者要看懂区间，但不能改它。
+    留着可编辑只会让人以为自己填错了。
+  </p>
+</div>
+
 
 
   <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
@@ -131,9 +161,19 @@
     presets: ['thisQ', 'lastQ', 'lastM', 'yoy'],
     onChange: function (v, ok) {
       log2.textContent = 'from=' + (v.from || '(空)') + '  to=' + (v.to || '(空)') +
-                         '  valid=' + ok + '（范围 2020-01-01 ~ 2026-12-31）';
+                        '  valid=' + ok + '（范围 2020-01-01 ~ 2026-12-31）';
     },
   });
+
+  /* 只读区间：先 create（预设按钮是 JS 生成的），再把内部控件逐个设 disabled。
+     ⚠️ 顺序不能反 —— 反了的话 bindPresets 会重建一批可点的按钮，
+     类名还在、却又能点了（"看着灰但点得动"那种假禁用）。 */
+  var d3 = document.getElementById('d3');
+  DateRange.create(d3, { presets: ['thisQ', 'lastQ'] });
+  Array.prototype.forEach.call(
+    d3.querySelectorAll('input, button'),
+    function (el) { el.disabled = true; }
+  );
 })();
 </script>
 </body>

package/02-primitives/input/README.md

@@ -124,8 +124,9 @@ python 05-audit/states.py 02-primitives/input/input.css
 | `.field__input--sm` | 小尺寸（表格 / 紧凑栏） | 表格行内、侧栏等密度高的场景 |
 | `.field__input--textarea` | 多行：`height:auto` + `min-height:88px` + `padding:--sp-3` + `resize:vertical` | 备注、说明、地址等会换行的输入；直接拿 `.field__input` 配 `<textarea>` 会被 44px 固定高度裁掉 |
 
-> ⚠️ **demo 里没有演示这一档** —— 它是留给复用者的钩子，
-> 不是"看起来有其实没有"。要用就自己加类。
+> 这三档在 demo 的「尺寸与布局」一节里都有实例。
+> 早先这里写的是"demo 里没有演示" —— 那是个坏主意：没有渲染过的 CSS
+> 等于没人验证过（`--textarea` 一旦被别的规则盖掉，谁都不会发现）。
 
 ## 🔴 移动端必填：inputmode 与 autocomplete
 

package/02-primitives/input/demo.html

@@ -106,6 +106,48 @@
 
   </div>
 
+  <h2 class="rule-bottom">尺寸与布局：小尺寸 / 多行 / 标签在左</h2>
+  <p class="note">
+    这三档不是"好看的选项"，是<strong>三种不同的约束</strong>：
+    密度（表格行内）、行数（会换行的说明）、方向（标签在左的表单）。
+    写错哪一个都是"内容被裁掉"或"标签跑到控件上面"。
+  </p>
+  <div class="grid">
+
+    <div class="cell">
+      <h3><code>field__input--sm</code></h3>
+      <p>视觉 36px、命中区仍 <strong>44px</strong>（min-height 兜底）。用在表格行内、侧栏这类密度高的地方。</p>
+      <div class="field">
+        <label class="field__label" for="sm1">科目编码</label>
+        <input class="field__input field__input--sm" id="sm1" value="1122" autocomplete="off">
+      </div>
+    </div>
+
+    <div class="cell">
+      <h3><code>field__input--textarea</code></h3>
+      <p>直接拿 <code>.field__input</code> 配 <code>&lt;textarea&gt;</code> 会被 44px 固定高度<strong>裁掉</strong>。这一档放开高度、留 88px 起，并允许纵向拉伸。</p>
+      <div class="field">
+        <label class="field__label" for="ta1">备注</label>
+        <textarea class="field__input field__input--textarea" id="ta1" rows="3"
+                  placeholder="差异原因、审批说明…"></textarea>
+      </div>
+    </div>
+
+    <div class="cell">
+      <h3><code>field--row</code></h3>
+      <p>标签在左、控件在右，标签宽度固定 88px ⇒ 一列输入框的<strong>起点能对齐</strong>。480px 以下自动回退纵向。</p>
+      <div class="field field--row">
+        <label class="field__label" for="rw1">账期</label>
+        <input class="field__input" id="rw1" value="2026-09" autocomplete="off">
+      </div>
+      <div class="field field--row">
+        <label class="field__label" for="rw2">口径</label>
+        <input class="field__input" id="rw2" value="合并报表" autocomplete="off">
+      </div>
+    </div>
+
+  </div>
+
   <h2 class="rule-bottom">对比：常见写法 vs 本库写法</h2>
   <div class="cmp cmp--wide-first">
     <div class="cmp__pane cmp__bad" data-bad=".field__error|count|=0">

package/03-patterns/accordion/demo.html

@@ -158,6 +158,119 @@ p { margin: 0 0 var(--sp-3); }
     </div>
   </div>
 
+  <h2 class="rule-top">面板里怎么排：分列 / 表格 / 标题下的一句话</h2>
+  <p class="note">
+    这一块同时演示四个"藏在面板里"的类，所以<strong>四个都展开</strong>（多开模式）：
+    <br>· <code>.accordion--flush</code> 去掉外框，融进已有卡片或侧栏
+    <br>· <code>accordion__hint</code> 在标题下写"展开后有什么"，减少无谓展开
+    <br>· <code>cols-2</code> / <code>cols-3</code> / <code>cols-auto</code> 给面板内容分列（≥720px 才分列）
+    <br>· <code>.acc-table</code> 面板里的表格：窄屏<strong>横向滚动</strong>，不挤压换行
+  </p>
+  <div class="accordion accordion--flush" data-accordion data-accordion-multi>
+    <div class="accordion__item">
+      <h3 class="accordion__heading">
+        <button class="accordion__trigger" aria-expanded="true">
+          <span class="accordion__label">
+            指标口径
+            <span class="accordion__hint">展开可看 4 个字段的定义（不展开也能看到这句）</span>
+          </span>
+          <span class="accordion__marker" aria-hidden="true"></span>
+        </button>
+      </h3>
+      <div class="accordion__panel">
+        <div class="accordion__panel-inner cols-2">
+          <p><strong>营业总收入</strong>：含主营业务与其他业务收入，不含投资收益。</p>
+          <p><strong>营业成本</strong>：与收入同口径，不含期间费用。</p>
+          <p><strong>期间费用</strong>：销售、管理、研发、财务四项之和。</p>
+          <p><strong>归母净利润</strong>：扣除少数股东损益后的净利润。</p>
+        </div>
+      </div>
+    </div>
+
+    <div class="accordion__item">
+      <h3 class="accordion__heading">
+        <button class="accordion__trigger" aria-expanded="true">
+          <span class="accordion__label">
+            三期对比
+            <span class="accordion__hint">三列并排，适合"同类不同期"</span>
+          </span>
+          <span class="accordion__marker" aria-hidden="true"></span>
+        </button>
+      </h3>
+      <div class="accordion__panel">
+        <div class="accordion__panel-inner cols-3">
+          <p><strong>2024</strong><br>收入 1,284,300 万元</p>
+          <p><strong>2025</strong><br>收入 1,402,110 万元</p>
+          <p><strong>2026</strong><br>收入 1,536,880 万元</p>
+        </div>
+      </div>
+    </div>
+
+    <div class="accordion__item">
+      <h3 class="accordion__heading">
+        <button class="accordion__trigger" aria-expanded="true">
+          <span class="accordion__label">
+            自适应列
+            <span class="accordion__hint">按内容宽度自动分列，窄了自己塌成一列</span>
+          </span>
+          <span class="accordion__marker" aria-hidden="true"></span>
+        </button>
+      </h3>
+      <div class="accordion__panel">
+        <div class="accordion__panel-inner cols-auto">
+          <p>字段：证券代码</p>
+          <p>字段：行业分类</p>
+          <p>字段：上市日期</p>
+          <p>字段：交易所</p>
+          <p>字段：审计机构</p>
+        </div>
+      </div>
+    </div>
+
+    <div class="accordion__item">
+      <h3 class="accordion__heading">
+        <button class="accordion__trigger" aria-expanded="true">
+          <span class="accordion__label">
+            附表：近三期数据
+            <span class="accordion__hint">表格不换行，窄屏横向滚动</span>
+          </span>
+          <span class="accordion__marker" aria-hidden="true"></span>
+        </button>
+      </h3>
+      <div class="accordion__panel">
+        <div class="accordion__panel-inner">
+          <table class="acc-table">
+            <caption>营业总收入与同比（单位：万元）</caption>
+            <thead>
+              <tr>
+                <th scope="col">期间</th>
+                <th scope="col" class="num">营业总收入</th>
+                <th scope="col" class="num">同比</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <th scope="row">2024 年度</th>
+                <td class="num">1,284,300</td>
+                <td class="num">—</td>
+              </tr>
+              <tr>
+                <th scope="row">2025 年度</th>
+                <td class="num">1,402,110</td>
+                <td class="num up">+9.17%</td>
+              </tr>
+              <tr>
+                <th scope="row">2026 年度</th>
+                <td class="num">1,536,880</td>
+                <td class="num up">+9.61%</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </div>
+
   <h2 class="rule-top">结构要求（APG 原文）</h2>
   <div class="box">
     <p><strong>heading 包住 button</strong>，不是 button 套 heading：</p>

package/03-patterns/content/demo.html

@@ -81,6 +81,23 @@
   <h2>4 · 代码与链接</h2>
   <pre><code>const f = (x) =&gt; x * 2;   // 纯 ES5 时代写法</code></pre>
   <p>详细口径见 <a href="#main">内部数据字典</a>。</p>
+
+  <h2>5 · 待办清单</h2>
+  <p>Markdown 的 <code>- [x]</code> 语法渲染成的样子。它是<strong>正文里的一行</strong>，
+     所以只去掉列表圆点、把勾选框对齐到行的左缘，其余跟普通列表一致。</p>
+  <ul>
+    <li class="task-list-item">
+      <label><input type="checkbox" checked disabled> 核对 2026 Q1 收入口径</label>
+    </li>
+    <li class="task-list-item">
+      <label><input type="checkbox" checked disabled> 补齐 26 家公司的三张表</label>
+    </li>
+    <li class="task-list-item">
+      <label><input type="checkbox" disabled> 复核应收账款周转天数</label>
+    </li>
+  </ul>
+  <p><strong>为什么勾选框要带 <code>disabled</code></strong>：这是<em>已渲染的正文</em>，
+     不是可填的表单。可点的复选框会让读者以为"改了会保存"。</p>
 </div>
 
 

package/03-patterns/drawer/README.md

@@ -40,11 +40,21 @@
 
 | 部件 | 说明 |
 |---|---|
-| `.drawer--right`（默认）/ `.drawer--left` / `.drawer--top` / `.drawer--bottom` | 四个进入方向。左右是侧栏（宽度由 `--drawer-w` 定），上下是**抽屉式面板**（`min(60vh, 420px)` 高、整宽），适合移动端底部操作区 |
+| `.drawer--right`（默认）/ `.drawer--left` / `.drawer--top` / `.drawer--bottom` | 四个进入方向。左右是侧栏（宽度由 `min(420px, 92vw)` 定），上下是**抽屉式面板**（`min(60vh, 420px)` 高、整宽），适合移动端底部操作区 |
 | `.drawer__head` / `__title` / `__close` | 头部与关闭按钮 |
 | `.drawer__body` | 内容 |
 | `.drawer__foot` | 底部操作区 |
 
+> ⚠️ **左右是逻辑轴，不是物理轴**：`--left` = 内联起点、`--right` = 内联终点。
+> LTR 下就是字面意思；`dir="rtl"` 时整个外壳镜像（`--right` 会出现在左边）。
+> 抽屉是"布局家具"，整页镜像时必须跟着镜像 —— 只有"指向某侧的箭头"
+> （如 tooltip 的小三角）才该保持物理方向。
+> JS 另外接受 `start` / `end` 两个别名，落到同两个类，这样跨方向写一份配置就够。
+
+> 🔴 0.25.2 修：`.drawer--left` / `--bottom` **此前只改了边框和动画，位置没动** ——
+> 两个方向都出现在和默认方向一样的位置上，不报错、控制台干净，
+> 因为四个方位**从来没有判据量过落位**。现在 `drawer-check` 逐个量矩形贴哪条边。
+
 ## 启用
 
 ```js

package/03-patterns/drawer/drawer.css

@@ -26,7 +26,10 @@
      统一走令牌后，暗色跟随自动生效。 */
   background: var(--scrim);
   display: flex;
-  /* 抽屉从右侧滑入（可改成 left / top / bottom）*/
+  /* 默认停在内联终点侧（LTR 右 / RTL 左）。
+     🔴 0.25.2 修：原来只有这一条，于是 `--left` / `--bottom` **只改了边框和动画、
+     位置一点没动**。1280×800 实测：left 的 left=860（应 0）、bottom 的 top=0（应贴底）。
+     两个方向是错的，却控制台干净、契约全绿。⇒ 落位交给各方向的 auto margin / align-self。 */
   justify-content: flex-end;
 }
 
@@ -44,11 +47,24 @@
   overflow: hidden;
 }
 
-.drawer--left  { border-inline-start: 0; border-inline-end: 1px solid var(--border-decor); }
-.drawer--top   { width: 100%; height: min(60vh, 420px); border-inline-start: 0;
-                border-bottom: 1px solid var(--border-decor); }
-.drawer--bottom { width: 100%; height: min(60vh, 420px); border-inline-start: 0;
-                border-top: 1px solid var(--border-decor); }
+/* ---------- 四个方向 ----------
+   ⚠️ 名字沿用 0.x 的物理叫法（left / right），**实现是逻辑轴**：
+     `--left` = 内联起点（LTR 左 / RTL 右），`--right` = 内联终点。
+   抽屉是"布局家具"，整页镜像时必须跟着镜像；只有"指向某侧的箭头"
+   （tooltip 的小三角）才该保持物理方向。本文件本来写的就全是逻辑属性
+   （border-inline-start/end），语义一直是逻辑的，这里只是让它落地。
+
+   落位靠抽屉自己的 auto margin / align-self（容器是 flex row）：
+     主轴 auto margin 吃掉剩余空间（优先于 justify-content）；
+     交叉轴 align-self 把固定高度的抽屉推到上/下边。
+   `--right` 不需要额外规则：容器默认的 `justify-content: flex-end`
+   就落在内联终点侧 —— 这也解释了为什么它一直是唯一没坏的方向。 */
+.drawer--left   { margin-inline-end: auto;   /* 推到内联起点 */
+                  border-inline-start: 0; border-inline-end: 1px solid var(--border-decor); }
+.drawer--top    { align-self: flex-start; width: 100%; height: min(60vh, 420px);
+                  border-inline-start: 0; border-bottom: 1px solid var(--border-decor); }
+.drawer--bottom { align-self: flex-end;   width: 100%; height: min(60vh, 420px);
+                  border-inline-start: 0; border-top: 1px solid var(--border-decor); }
 
 /* ---------- 头 ---------- */
 .drawer__head {

package/03-patterns/drawer/drawer.js

@@ -188,9 +188,24 @@
     }
   }
 
+  /* 方位 ⇒ 类名。两个理由都用完整字面量，不拼 `'drawer--' + place`：
+     ① 拼出来的名字源码里 grep 不到，改 CSS 时无法反查谁在用，
+        覆盖率门禁也认不出（4 个方位因此长期被记成"只被 README 认领"）。
+     ② 它是**白名单**：`{place:'tp'}` 原本会拼出 `drawer--tp`，没有任何 CSS
+        命中 ⇒ 抽屉按默认规则贴右侧、**不报错**。现在未知值退回 right。
+     `start`/`end` 是逻辑别名，落到同两个类（见 drawer.css「四个方向」）。 */
+  var PLACE_CLASS = {
+    right:  'drawer--right', end:   'drawer--right',
+    left:   'drawer--left',  start: 'drawer--left',
+    top:    'drawer--top',
+    bottom: 'drawer--bottom'
+  };
+
   function open(opt) {
     opt = opt || {};
     var place = opt.place || 'right';
+    var placeCls = PLACE_CLASS[place];
+    if (!placeCls) placeCls = PLACE_CLASS.right;
 
     /* ⭐ 记住"打开那一刻的焦点"—— 关闭时要还回去。
        （必须在插入 DOM **之前**记录，否则会记到新节点上。）
@@ -206,7 +221,7 @@
     if (opt.label) host.setAttribute('aria-label', opt.label);
 
     var d = document.createElement('aside');
-    d.className = 'drawer drawer--' + place;
+    d.className = 'drawer ' + placeCls;
     d.setAttribute('role', 'dialog');
     d.setAttribute('aria-modal', 'true');
     if (!d.id) d.id = 'drawer-' + (new Date()).getTime();

package/03-patterns/dropdown/README.md

@@ -26,11 +26,13 @@
   <button class="dd__btn" data-dd-btn aria-haspopup="menu" aria-expanded="false">
     <span>操作</span><span class="dd__caret" aria-hidden="true"></span>
   </button>
-  <div class="dd__menu" data-dd-menu role="menu">
-    <button class="dd__item" role="menuitem" data-value="edit">编辑</button>
-    <hr class="dd__sep" data-dd-sep role="separator">
-    <button class="dd__item" role="menuitem" data-value="del">删除</button>
-  </div>
+  <!-- ⚠️ 必须是 ul + li：JS 按 `li` 逐个补 role="menuitem" / tabindex="-1"。
+       写成 <div>/<button> 的列表，键盘导航会整个失效（没有可被 JS 接管的项）。 -->
+  <ul class="dd__menu" data-dd-menu hidden>
+    <li data-value="edit">编辑</li>
+    <li data-dd-sep></li>
+    <li data-value="del">删除</li>
+  </ul>
 </div>
 ```
 
@@ -38,9 +40,9 @@
 |---|---|
 | `.dd` | 根 |
 | `.dd__btn` / `[data-dd-btn]` | 触发按钮 |
-| `.dd__menu` / `[data-dd-menu]` | 菜单本体，**必需** |
-| `.dd__item` | 菜单项，带 `data-value` |
-| `.dd__sep` / `[data-dd-sep]` | 分隔线 |
+| `.dd__menu` / `[data-dd-menu]` | 菜单本体（`<ul>`），**必需** |
+| `.dd__item` | 菜单项（`<li>`），带 `data-value`。**类名由 JS 自动补**，不用手写 |
+| `.dd__sep` / `[data-dd-sep]` | 分隔线。只写 `data-dd-sep` 即可：`role="separator"` + `aria-hidden` + `.dd__sep` 都由 JS 补（漏写类名时它渲染高度是 **0px**，两组菜单项直接贴着） |
 | `.dd__check` | 多选勾选位 |
 | `.dd--end` | 菜单右对齐 |
 

package/03-patterns/dropdown/demo.html

@@ -61,6 +61,11 @@
     </ul>
   </div>
   <div class="log" id="log">（选中项会显示在这里）</div>
+  <p class="small">
+    菜单里的那条<strong>分隔线</strong>只写 <code>data-dd-sep</code> 就行：
+    <code>role="separator"</code> 与 <code>.dd__sep</code> 由组件补。
+    方向键会跳过它 —— 分隔线不是可选项，让它能被"选中"是错的。
+  </p>
 </div>
 
 <h2>2 · 带勾选（选中性不只靠颜色）</h2>