agentcss 0.0.0-stage → 0.11.3

package/docs/BENCHMARK.md

@@ -0,0 +1,252 @@
+# 对标基准
+
+> 我们抄了谁、故意不抄谁、以及每一条背后的前提。
+>
+> 这份文档存在的唯一理由：**让"这里为什么是这样"有据可查**。
+> 没有它，同一个问题会在半年后被重新争论一遍——而争论的双方都拿不出当时的理由。
+
+---
+
+## 这份文档怎么用
+
+对标一个项目时问三件事，按顺序问：
+
+1. **它做了什么我们没做的？**（事实）
+2. **它的做法依赖什么前提？**（前提）
+3. **我们的前提和它一样吗？**（判定）
+
+只有第 3 问答"一样"，才谈得上"学"。
+**前提不同却硬学，是把别人的约束当成自己的目标**——这是对标最常见的翻车方式。
+
+下面五节的每一节都按这个顺序写，并且把"不学"的理由写得和"学"一样详细。
+理由是：**"不做"也是决策，写下来就不算缺口；不写下来，下次就被当成遗漏。**
+
+---
+
+## 一、Pico CSS —— 产品理念最像我们
+
+### 它是什么
+
+纯 CSS、零构建、零依赖。写语义化 HTML，不用加 class，直接就好看。
+强制明暗色是**纯 CSS** 实现：`[data-theme="dark"]` 覆盖令牌，**不需要 JS**。
+
+### 🔴 我们故意不同：标签选择器
+
+我们**禁止**裸标签选择器（`input { }`）。理由不是偏好，是作用域事实：
+一条 `input { }` 的作用域是**整个文档**，包括使用者的页面。
+详见 `INVARIANT.md` I-1。
+
+> 这条是 Pico 的立身之本，也是我们不能要的那部分。
+> 前提不同：Pico 假设自己就是页面的全部；我们假设自己是**嵌进别人页面的组件**。
+
+### 🟢 学到的：强制暗色不该需要 JS
+
+我们的暗色过去靠 JS 写 27 条 inline 属性实现。代价见 `INVARIANT.md` I-4：
+inline style 压过一切样式表，使用者只能加 `!important` 反击。
+
+**处置**：改为纯 CSS `data-theme`，JS 不再持有任何色值。
+
+---
+
+## 二、Radix —— 复杂行为最值得研究
+
+### 它是什么
+
+无样式的行为原语库。复杂交互（组合框、弹出层、焦点陷阱）的**可访问性行为**由它负责。
+
+### 🟢 学到的：状态是枚举，写在 DOM 上
+
+Radix 把状态写成 `data-state="open"` / `"closed"` / `"indeterminate"`，枚举字符串。
+
+对比另一种写法：状态写成 class（`.is-open`）。
+差别不在于好不好看，在于**它是不是可被观察的事实**：
+
+| | 写在 DOM 属性上 | 写在 class 上 |
+|---|---|---|
+| 取值集合 | 有限、可枚举、可校验 | 无限，拼错不报错 |
+| 能否被查询 | `querySelectorAll('[data-state=open]')` 直接可得 | 只能靠约定 |
+| 出问题时 | 看一眼元素就知道状态 | 要去找哪段 JS 加了这个类 |
+
+**处置**：全库状态表达收敛到 `data-*` 枚举，`is-*` 类不再作为状态来源。
+
+---
+
+## 三、Open Props —— 令牌基础设施
+
+### 它是什么
+
+令牌库。一份设计变量，导出成多种格式供不同消费方使用。
+
+### 🔴 我们故意不同：真值来源的方向反着来
+
+| | 真值来源 | 产物 |
+|---|---|---|
+| Open Props | JS / JSON | CSS（生成出来的） |
+| 我们 | **CSS** | JSON（生成出来的） |
+
+**为什么反着来**：`01-tokens/tokens.css` 里有大量**实测对比度注释**——
+每个色值配着"这个组合实测对比度是多少、为什么这么选"。
+这类注释是知识，不是格式；一旦把 CSS 变成生成产物，它们就无处安放。
+
+**代价与对策**：反着来就意味着 JSON 会漂移（`INVARIANT.md` I-7）。
+对策不是"记得同步"，而是**同步门禁**：CSS 改了不重新生成，门禁红。
+
+### 🟢 学到的：令牌必须有机器可读导出
+
+散文里的令牌对程序不可用。使用者（包括自动化工具）需要的是能读的结构。
+**处置**：`ai/tokens.json` 由 CSS 生成，`--check` 门禁保证不漂移。
+
+---
+
+## 四、Web Awesome —— framework-agnostic 组件 API
+
+### 它是什么
+
+原生自定义元素，在任何框架里行为一致，不需要适配层。
+每个组件按**六类 API 面**文档化：slots / 属性 / 方法 / 事件 / CSS 自定义属性 / CSS parts。
+
+### 🔴 我们故意不同：不做自定义元素
+
+我们的前提是"把组件放进宿主页面"。Shadow DOM 会**切断与宿主令牌的继承**，
+与前提直接冲突。零依赖、零构建是本库存在的理由，不能为了形态一致而牺牲它。
+
+### 🟢 学到的两件事
+
+1. **契约要按面分类**：一个组件不只"有个 class 名"，它有插槽、状态、属性、事件。
+   散文描述不清这些边界。→ 结构化进 `ai/components.json`。
+2. **级联分层**——见下一节，它值得单独讲。
+
+---
+
+## 五、Primer —— 长期治理
+
+### 它是什么
+
+GitHub 的设计系统，跨 React / Rails View Component / Figma 多端。
+
+### 🟢 学到的：成熟度是分级，而且每级有判据
+
+组件有 Alpha → Beta → Stable 的生命周期，每级有**明确判据**。
+
+这条为什么重要：**它让约束可以不是一刀切的。**
+
+- Stable 组件：约束收紧，改它要过全量门禁
+- Alpha 组件：约束放宽，允许快速迭代、允许不兼容变更
+
+⇒ 不再需要"所有东西都按最严的来"，也不再需要"也许以后会放宽"的空头承诺。
+
+**处置**：成熟度进 `ai/components.json`，并且**由门禁算出来，不由人声明**。
+（人声明的成熟度会撒谎——没人会主动把自己的组件标成 alpha。）
+
+### 🟢 学到的：把决策也写下来
+
+Primer 的原话是 "Document decisions as well as outcomes"。
+只记结论不记理由，等于半年后重开一遍争论。这份文档就是这条的实践。
+
+---
+
+## 六、级联分层的决定（`@layer`）
+
+这是五家里技术含量最高、也最容易被误用的一条，所以单独写。
+
+### 它解决什么问题
+
+先问：使用者（或自动化工具）为什么会写 `!important`？
+因为它想改一个样式，**改了不生效**，于是加码。不生效的原因是库的选择器特异性更高。
+
+`@layer` 的解法很干净：**把库样式整体放进分层里**。
+未分层样式**永远**赢过已分层样式，**与特异性无关**。
+⇒ 使用者写一句 `.card { padding: 20px }` 就够了，不需要比特异性、不需要 `!important`、不需要加长选择器。
+
+这直接拆掉三类失控：
+
+1. `!important` 军备竞赛
+2. 选择器越写越长（`.page-3 .card .card__body h3`）
+3. "改不动就去改 `tokens.css`"——因为那是唯一能生效的地方
+
+### 为什么现在不做
+
+**目标环境是移动 WebView，基线没有确认。**
+
+`@layer` 需要 Chrome 99+ / Safari 15.4+ / Firefox 97+。
+在桌面浏览器这不算门槛；在移动 WebView 里，**使用者手里那批机型的基线是未知数**。
+在未知基线上切换层叠模型，等于拿使用者的线上页面去赌。
+
+另外两个真实代价，一并写明：
+
+- 分层后**库内部**的覆盖关系会变（同层内仍按特异性，跨层按层序）⇒ 必须全量视觉回归；
+- 库自己若有 `!important`，分层后它的层序**会反转**——早层里的 `!important`
+  会赢过使用者的 `!important`。所以每一处都得说清"它凭什么必须赢"。
+
+### ⚠️ 因此前提不是「清零」，而是「每一处都能归类」
+
+第一版我们把判据写成「交付 CSS 里 `!important` 必须为 0」。**实测后推翻**：
+
+```
+grep 命中 11 处 ⇒ 真解析后 10 处（1 处是注释里的文本，属假命中）
+10 处全部正当：
+  · 9 处在 @media (prefers-reduced-motion: reduce) 内 —— 无障碍
+  · 1 处是 [hidden] { display: none }              —— 正确性
+```
+
+清零会逼人删掉 `prefers-reduced-motion` 兜底，那是**让门禁去破坏正确性**。
+而且对"操作系统级偏好"来说，分层后它赢过使用者的 `!important` 恰恰是对的。
+
+⇒ 判据改成：**每一处都要能归到一个已批准的理由**，归不了类的才红。
+
+### 切换的前提条件（可判）
+
+三条全绿才切，缺一条不切：
+
+| # | 前提 | 现状 | 怎么判 |
+|---|---|---|---|
+| 1 | 目标 WebView 基线确认支持 `@layer` | ❌ 未确认 | 实测数据落档，不是"应该支持" |
+| 2 | 每处 `!important` 都能归到已批准理由 | ✅ 10/10 | `05-audit/cascade-layer-gate.py` |
+| 3 | 分层后全量视觉回归绿 | ❌ 未执行 | 现有视觉回归基线全过 |
+
+### 现在做了什么
+
+不是"什么都不做"。门控已经就位，它守着三件事：
+
+1. `@layer` 计数（当前 0）；
+2. 每处 `!important` 的分类（当前 10/10 全归类，注释与字符串里的文本不算命中）；
+3. **一旦有人加了第一条 `@layer`，门禁立刻要求前提 1、3 的实测记录落档**
+   （`docs/LAYER-BASELINE.md` 不存在就红）。
+
+⇒ 切换那天不需要重新摸清现状，也不会有人"顺手先切一点"。直接看门禁。
+
+---
+
+## 七、明确不做的事（写了就不算缺口）
+
+| 不做 | 为什么 |
+|---|---|
+| 改成 JSON → CSS（Open Props 方向） | 实测对比度注释是知识，生成会丢。改为 CSS 是真值 + JSON 是导出物 + 同步门禁 |
+| 变成自定义元素库 | Shadow DOM 切断宿主令牌继承，与"嵌进宿主页面"的前提冲突 |
+| 自带运行时框架 / 构建步骤 | 零依赖、零构建是本库的存在理由 |
+| 把幻灯片 / 演示语义做进核心 | 核心只提供组件与契约；呈现形态是适配层的事，见 `adapters/presentation/` |
+| 现在就切级联分层 | 移动 WebView 基线未确认，切换等于拿使用者赌 |
+
+---
+
+## 八、怎么验证这批工作没白做
+
+| 声称 | 验证方式 |
+|---|---|
+| 令牌有机器可读导出且不漂移 | 改 `tokens.css` 不重新生成 ⇒ 门禁红 |
+| 组件契约是结构化数据 | 注入假组件名 ⇒ 校验器拒 |
+| 成熟度不是人写上去的 | 篡改 JSON 里的成熟度 ⇒ 门禁检出与源码不符 |
+| 档位之间有真实区别 | 同一份文档在 strict 下报错数 > creative 下报错数 |
+| 编辑操作不会破坏文档 | 非法操作 ⇒ 文档字节级不变 |
+| 旧版校验器能读新版文档 | 带未知 `extensions` 的文档被忽略而非判非法 |
+| 演示语义没进核心 | 核心目录检索呈现类关键词 ⇒ 0 命中 |
+| 不变式层没被污染 | `INVARIANT.md` 出现组件名 / 令牌名 / 版本号 / 档位名 ⇒ 门禁红 |
+
+---
+
+## 附：这份文档什么时候该改
+
+- **对标了新项目** ⇒ 加一节，按"事实 / 前提 / 判定"三段写
+- **某个"不做"被推翻** ⇒ 不要删行，改成"过去不做，X 起做，因为 Y"——
+  保留推翻的痕迹，否则同样的争论会再来一次
+- **前提条件变了**（比如 WebView 基线确认了）⇒ 改第六节，并按表里的三条判据执行切换

package/docs/GUIDANCE.md

@@ -0,0 +1,154 @@
+# 指引（Guidance）
+
+> **这一层是可以整份推翻的。**
+> 它记录的是「以当前模型的能力，怎么做最不容易翻车」。
+> 模型变强 ⇒ 这一层就该变短。**它变短是好事，不是退步。**
+
+---
+
+## 这一层为什么存在，以及它为什么不该被写死
+
+对照 `INVARIANT.md`：那里写的是**事实**（裸标签选择器的作用域是整个文档），
+这里写的是**补丁**（模型看不全全局 ⇒ 让它改之前先跑影响面报告）。
+
+事实不会变。补丁会失效。
+
+所以：
+
+- ❌ 不要把这一层的内容写进门禁——否则三个月后门禁就在拦一个已经不存在的风险，
+  而且**没人敢删**（因为"它一直在那儿，删了会不会出事？"）。
+- ✅ 这一层应该定期被拿出来问一句：**这条现在还成立吗？**
+- ✅ 判断标准很简单：**"如果模型是无限强的，还需要这条吗？"**
+  不需要 ⇒ 它随时可以删。
+
+---
+
+## 一、当前模型下有效的做法
+
+### G-1 改之前先看影响面
+
+```bash
+python3 05-audit/impact-report.py
+```
+
+**为什么现在需要**：模型倾向于"就改这一处"，看不到它改的文件被谁依赖。
+
+**什么时候可以删**：当模型能在一次上下文里可靠地推导出跨文件依赖时。
+（至今还没观察到，所以保留。）
+
+### G-2 一次只改一个语义单元
+
+改完立刻验证，再改下一个。
+
+**为什么现在需要**：连续改 5 处再验证，出错时无法定位是哪一处。
+PPT 事故的形态就是"14 页一起改，改完一起崩"。
+
+**什么时候可以删**：当验证本身足够快、且失败定位足够精确时。
+
+### G-3 发现自己在写页面级 override ⇒ 停下来
+
+```css
+.slide-3 h1 { ... }   /* ← 这是信号，不是解法 */
+```
+
+**为什么现在需要**：模型遇到"改不动"的本能反应是加特异性，而不是改根因。
+
+> ⚠️ 注意：这条的**根因部分**是 `INVARIANT.md` I-2（特异性只增不减），
+> 那是事实；"停下来"这个动作是建议。**只有后者属于这一层。**
+
+### G-4 优先改组件，而不是改页面
+
+**适用范围**：在 frontend-lib 仓库内改动，或明确按本库范式产出页面时。
+
+本库提供**可选**的组件与骨架，但它不是所有页面的强制实现规范。
+在本库范式内，要表达"两栏""卡片网格"，优先用组件组合而不是手写布局。
+
+组件不适用、或宿主项目已有自己的布局体系时，**用别的实现方式** ——
+不要为了满足本库的实现偏好而牺牲任务结果。
+修改已有网站时，宿主原有的框架、组件和样式体系优先。
+
+**为什么现在需要**：模型容易写出 `width: 612px; margin-left: 37px` 这类 magic number。
+它们既不能被门禁检查，也不能在暗色模式下自适应。
+
+**什么时候可以删**：当模型默认倾向于复用已有抽象时。
+
+### G-5 需要"Esc 关闭 / 点外部关闭 / 焦点归位 / 方向键游走 / 首字母跳转"时，用核，别自己写
+
+真值源在 `01-tokens/behavior/`（现有 `dismissable`、`focus-return`、`roving`、`typeahead`，
+以及工具核 `emit`）。用法：
+
+1. 在组件文件里留出注入标记
+   `/* ==== BEHAVIOR INJECT BEGIN: roving ==== */` … `END`
+2. 跑 `python 05-audit/gen-behavior.py`，把核写进来
+3. 调它（如 `flRoving({ container, items, movable, axis, onMove })`），并在 `destroy()` 里成对销毁
+
+⚠️ 先确认**这个核管的是不是你这件事** —— "看起来像"不等于"是"：
+
+| 你要的 | 用不用核 |
+|---|---|
+| Esc / 点外部关闭 | `dismissable` |
+| 关闭后焦点还给谁 | `focus-return` |
+| 一组项里用方向键**移动 DOM 焦点** | `roving` |
+| 打字母/汉字**跳到**匹配项（不是过滤） | `typeahead` |
+| 组件要**对外发通知** | `emit`（`flEmit(root, 'fl-change', { value })`） |
+| 方向键是**翻页 / 展开收起**这类命令 | **不用** —— 那不是游走，是命令键 |
+| 焦点常驻触发器、靠 `aria-activedescendant` 报位置 | **不用** —— 核靠 `e.target` 判断当前项，这种模式下焦点根本不在项上 |
+| APG 菜单（菜单项按规范全 `tabindex="-1"`） | 用 `roving`，但传 `tabindex: false`（只接管步进，不碰 tabindex） |
+| 有输入框、**打字即过滤** | **不用 `typeahead`** —— 那是过滤，不是跳转 |
+
+**为什么现在需要**：14 个组件 JS 里，Esc 关闭被手写了 10 处、点击外部 7 处、
+roving tabindex 33 处。每多一个副本，就多一个"这处忘了修"的机会 ——
+而且这种漏**不报错**（同一件事在不同组件里手感不一样，只有键盘用户会遇到）。
+
+**什么时候可以删**：当这类行为只剩一处实现时（那正是本条的目的）。
+
+### G-6 贴进 system prompt 的极简版
+
+> 🔴 **先把适用范围说清楚（这段被误读过）**
+>
+> 下面这段的适用范围是：**在 frontend-lib 仓库里改代码**，
+> 或**明确要按本库范式产出页面**这两类任务。
+>
+> 它**不是**所有 HTML / 网站任务的通用规则：
+>
+> - 改一个已有网站时，宿主项目原有的框架、组件和样式体系**优先**；
+> - 本库组件不适用时，用别的实现方式，不要为满足本库的偏好牺牲任务结果；
+> - PPT、文档、邮件等非网页输出形态**不适用**这一段。
+
+```
+维护 frontend-lib 或严格按本库范式写页面时，遵守以下编辑边界：
+1. 不写裸标签选择器（a{} h1{} button{}）——一律挂组件根类
+2. 不新增裸颜色与裸间距——用 tokens
+3. 不改 01-tokens/tokens.css，除非任务明确要求改令牌
+4. 局部改动优先改组件/改令牌；确需页面级 override 时要知道它的代价
+   （特异性只增不减，见 INVARIANT I-2），不是"绝对不许写"
+5. 改组件样式后必须重跑该组件的视觉基线
+6. 改之前先跑 impact-report.py 看影响范围
+7. 需要 Esc 关闭 / 点外部关闭 / 焦点归位 / 方向键游走 / 打字定位 这类行为时，用 01-tokens/behavior/ 里的核，别自己重写
+发现自己在写页面级 override ⇒ 先问一句"根因是不是在组件里"
+```
+
+> 这段是**可替换的**。它是"当前最好用的一段提示词"，不是规范。
+> 换模型、换版本 ⇒ 改这段，不需要改任何门禁。
+> 它的**适用范围**同样可以改 —— 但改之前先想清楚：放宽给谁，会不会又变成别人的天花板。
+
+---
+
+## 二、这一层**不**做的事
+
+| 不做 | 归属 |
+|---|---|
+| 不定义"哪些组件存在" | `ai/components.json`（Contract） |
+| 不定义"strict 档能用什么" | `ai/profiles.json`（Contract） |
+| 不断言"裸选择器会污染宿主" | `INVARIANT.md` I-1（事实） |
+| 不把上面任何一条接进 `check-all.sh` | —— 门禁只管事实和契约 |
+
+---
+
+## 三、维护规则
+
+1. **每条 G-n 必须写明「什么时候可以删」。** 写不出删除条件的，说明它不是指引，
+   要么它其实是 Invariant（搬走），要么它其实什么都没说（删掉）。
+2. **每次模型换代，过一遍这一层。** 能删的就删，删不掉的要写清楚为什么还删不掉。
+3. **这一层的长度是健康指标。** 它越短，说明模型越强、我们的补丁越少。
+   **不要以"这一层写得很全"为荣。**