agentcss 0.16.0 → 0.24.0

package/index.html

@@ -26,7 +26,7 @@ li a:active { background: var(--surface-sunken); }
 <main id="main" class="wrap">
   <h1>agentcss · 演示</h1>
   <p class="lede">
-    37 个组件，每一页都能直接打开看。
+    40 个组件，每一页都能直接打开看。
     <strong>手机上也一样</strong> —— 布局、触控尺寸、暗色都是按移动端调的。
   </p>
 
@@ -48,6 +48,8 @@ li a:active { background: var(--surface-sunken); }
 <li><a href="02-primitives/separator/demo.html">separator · 分隔线</a><span class="r__p">分隔线，可带中间文字</span></li>
 <li><a href="02-primitives/skeleton/demo.html">skeleton · 骨架屏</a><span class="r__p">加载占位骨架</span></li>
 <li><a href="02-primitives/switch/demo.html">switch · 开关</a><span class="r__p">开关切换</span></li>
+<li><a href="02-primitives/timeline/demo.html">timeline · 时间轴</a><span class="r__p">时间轴：按时间排的事件序列（公告 / 大事记 / 版本记录）。顺序即信息，用 ol；状态交给 badge，颜色在</span></li>
+<li><a href="02-primitives/upload/demo.html">upload · 文件上传</a><span class="r__p">文件上传：零 JS 的原生形态 + 拖放/多文件/校验的增强形态</span></li>
 </ul>
 
 <h2 class="rule-top">模式</h2>
@@ -73,6 +75,7 @@ li a:active { background: var(--surface-sunken); }
 <p class="r__d">一整页的排版约定，给&quot;有结论、有数据&quot;的材料用。</p>
 <ul>
 <li><a href="04-recipes/analysis-report/demo.html">analysis-report · 组合型研究报告</a><span class="r__p">组合型研究报告页面：正文与辅助栏并排，窄屏自然退回单栏</span></li>
+<li><a href="04-recipes/app-shell/demo.html">app-shell · 应用外壳</a><span class="r__p">应用外壳：侧栏 + 顶栏 + 主区三段式；sticky 侧栏自滚、min-width 防撑破、窄屏收走侧栏</span></li>
 <li><a href="04-recipes/detail-page/demo.html">detail-page · 实体详情页骨架</a><span class="r__p">实体详情页骨架：字段齐全 / 部分缺失 / 无数据三种状态同构，无数据是一等状态</span></li>
 <li><a href="04-recipes/report/demo.html">report · 报告版式系统 v1</a><span class="r__p">报告版式系统 v1：共享基础 + 三套版式（杂志/科研技术/金融研究），只换一个 rep--* 类即可切换取舍</span></li>
 <li><a href="04-recipes/table/demo.html">table · 专业数据表格</a><span class="r__p">数据表格：排序/加载/空/错误四态；三种用途预设（财务/学术/统计）</span></li>
@@ -94,7 +97,7 @@ li a:active { background: var(--surface-sunken); }
   </p>
 </main>
 <footer class="wrap">
-  <p class="note">0.16.0 · 零第三方运行时依赖</p>
+  <p class="note">0.24.0 · 零第三方运行时依赖</p>
 </footer>
 </body>
 </html>

package/llms-full.txt

@@ -0,0 +1,153 @@
+# agentcss — full reference (one file)
+
+> Generated from `ai/components.json` + `ai/pitfalls*.json` + `ai/behaviors.json` at version **0.24.0**.
+> Do not edit by hand: run `python 05-audit/gen-llms.py` (freshness is gated).
+> Short version: `llms.txt`. Machine contract: `ai/*.json`.
+
+Mobile-web CSS component library. Tokens + components + optional behaviour scripts.
+No build step, no framework, no third-party runtime dependency. Class names are the API.
+
+## 1 · Query instead of guessing
+
+```bash
+npx agentcss ai components --json                     # 39 components, joined with pitfalls
+npx agentcss ai components --json --maturity=stable
+npx agentcss ai pitfalls --json --component=table
+npx agentcss ai tokens --json --set=dark
+npx agentcss ai tree --json --set=dark --cat=color
+npx agentcss ai validate <file> --schema=components --json
+npx agentcss ai check <doc.json> --profile=strict --json
+```
+
+Every subcommand accepts `--json`; failures print `{"ok":false,...}` and exit non-zero.
+
+## 2 · Components (40)
+
+`class` is the root class you put on the element; `js` is the behaviour script (`—` = CSS only).
+
+| id | class | tier | maturity | css | js | what it is | pitfalls |
+|---|---|---|---|---|---|---|---|
+| `bar` | `bar` | asset | stable | 5.3 KB | `bar.js` | 柱状图：堆叠/分组两种语义、超量程裁剪、图例 | `chart-multiline-label` |
+| `model-viewer` | `mv` | asset | stable | 4.0 KB | `model-viewer.js` | 3D 模型查看器：令牌驱动样式，不含渲染库本体 | — |
+| `scientific-plot` | `splot` | asset | stable | 3.9 KB | `scientific-plot.js` | 二维科学绘图：折线/区间带/对数轴，纯令牌驱动、零依赖 | `chart-multiline-label` |
+| `sparkline` | `sparkline` | asset | stable | 7.2 KB | `sparkline.js` | 迷你趋势图：无坐标轴、纯形状，适合表格内嵌的一行走势 | `chart-multiline-label` |
+| `accordion` | `accordion` | pattern | stable | 18.0 KB | `accordion.js` | 可折叠分组 | — |
+| `content` | `prose` | pattern | stable | 11.1 KB | — | 长文排版容器（标题/段落/列表/引用/代码） | `single-scroll-container` `line-height-constant-sync` |
+| `drawer` | `drawer` | pattern | stable | 4.5 KB | `drawer.js` | 侧边抽屉，含遮罩 | `fixed-element-inventory` |
+| `dropdown` | `dd` | pattern | stable | 3.9 KB | `dropdown.js` | 下拉菜单 | `popover-measure-after-render` |
+| `form-validation` | `form` | pattern | stable | 11.0 KB | — | 表单校验反馈与错误汇总 | — |
+| `list` | `list` | pattern | stable | 6.1 KB | `flip.js` | 键值列表/条目列表 | `empty-state-no-decoration` `text-injection-xss` |
+| `nav` | `nav` | pattern | stable | 12.1 KB | `nav.js` | 顶部导航与目录 | — |
+| `overlay` | `toast` | pattern | stable | 12.0 KB | `overlay.js` | 吐司提示与模态遮罩 | `fixed-element-inventory` |
+| `pagination` | `pagination` | pattern | stable | 7.7 KB | `pagination.js` | 分页控件 | — |
+| `reveal` | `reveal` | pattern | stable | 4.0 KB | `reveal.js` | 入场动效：一个 data-reveal 属性六个方向，无 JS 时内容全可见 | — |
+| `states` | `state` | pattern | stable | 10.1 KB | — | 空/加载/错误/成功四种整块状态 | `empty-state-no-decoration` `text-injection-xss` |
+| `tabs` | `tabs` | pattern | stable | 5.9 KB | `tabs.js` | 选项卡切换 | — |
+| `tooltip` | `tooltip` | pattern | stable | 3.5 KB | `tooltip.js` | 悬停/聚焦提示 | `popover-measure-after-render` `fixed-element-inventory` |
+| `tree` | `tree` | pattern | stable | 4.0 KB | `tree.js` | 可展开树形结构 | — |
+| `badge` | `badge` | primitive | stable | 6.1 KB | — | 状态标签：计数、分类、结果标记 | — |
+| `button` | `btn` | primitive | stable | 15.7 KB | — | 动作触发：主/次/危险/纯文字四档 | — |
+| `card` | `card` | primitive | stable | 10.4 KB | — | 内容容器：媒体+正文+操作区三段 | — |
+| `choice` | `choice` | primitive | stable | 16.8 KB | — | 单选/多选/原生 select 外观的统一控件 | — |
+| `combobox` | `combo` | primitive | stable | 7.0 KB | `combobox.js` | 可搜索 + 可多选标签的输入控件 | — |
+| `date-range` | `drange` | primitive | stable | 6.0 KB | `date-range.js` | 日期区间选择，含预设快捷范围 | — |
+| `delta` | `delta` | primitive | stable | 5.5 KB | — | 变化量：涨跌方向 + 符号 + 颜色。只描述往哪边变，不判断好坏（等于好恶是 … | — |
+| `input` | `field` | primitive | stable | 10.6 KB | — | 文本输入及其标签/帮助/错误三件套 | — |
+| `metric` | `metric` | primitive | stable | 6.8 KB | — | 指标块：一个标签 + 一个值 + 一句上下文。数字等宽、单位分离、缺数是一等状态 | — |
+| `popover` | `popover` | primitive | stable | 7.8 KB | `popover.js` | 锚定到触发元素的浮层 | `popover-measure-after-render` |
+| `progress` | `progress` | primitive | stable | 11.1 KB | — | 进度条与进度环 | — |
+| `select` | `select` | primitive | stable | 4.4 KB | `select.js` | 自定义下拉选择（非原生） | `popover-measure-after-render` |
+| `separator` | `separator` | primitive | stable | 2.7 KB | — | 分隔线，可带中间文字 | — |
+| `skeleton` | `skeleton` | primitive | stable | 4.3 KB | — | 加载占位骨架 | — |
+| `switch` | `switch` | primitive | stable | 20.5 KB | — | 开关切换 | — |
+| `timeline` | `timeline` | primitive | stable | 7.1 KB | — | 时间轴：按时间排的事件序列（公告 / 大事记 / 版本记录）。顺序即信息，用 … | — |
+| `upload` | `upload` | primitive | stable | 20.5 KB | `upload.js` | 文件上传：零 JS 的原生形态 + 拖放/多文件/校验的增强形态 | — |
+| `analysis-report` | `report` | recipe | stable | 8.4 KB | — | 组合型研究报告页面：正文与辅助栏并排，窄屏自然退回单栏 | `empty-layout-min-height` |
+| `app-shell` | `shell` | recipe | stable | 24.9 KB | `shell-nav.js` | 应用外壳：侧栏 + 顶栏 + 主区三段式；sticky 侧栏自滚、min-wi… | `empty-layout-min-height` `fixture-demo-split-truth` |
+| `detail-page` | `detail-page` | recipe | stable | 5.7 KB | — | 实体详情页骨架：字段齐全 / 部分缺失 / 无数据三种状态同构，无数据是一等状态 | `empty-layout-min-height` |
+| `report` | `rep` | recipe | stable | 15.7 KB | — | 报告版式系统 v1：共享基础 + 三套版式（杂志/科研技术/金融研究），只换一… | — |
+| `table` | `table` | recipe | stable | 18.1 KB | — | 数据表格：排序/加载/空/错误四态；三种用途预设（财务/学术/统计） | `single-scroll-container` `empty-state-no-decoration` `table-overflow-wrapper` `text-injection-xss` |
+
+## 3 · Known failure modes (32)
+
+Each one has actually shipped at least once. Full text: `npx agentcss ai pitfalls --json`.
+
+**Component (8)**
+
+- `popover-measure-after-render` — 浮层定位必须在可见状态下测量 · positioning, overlay
+- `fixed-element-inventory` — 新增全局悬浮元素前先盘点既有悬浮层 · fixed, z-index
+- `single-scroll-container` — 多个滚动容器必然导致行号/表头漂移 · scroll, sticky
+- `empty-state-no-decoration` — 空态不要留装饰性元素 · empty, state
+- `table-overflow-wrapper` — 表格必须有自己的横向滚动容器 · mobile, overflow, a11y
+- `chart-multiline-label` — SVG 的 <text> 不认换行符 · svg, chart
+- `line-height-constant-sync` — 用常量算行高时，常量必须与 CSS 同源 · css, sync
+- `text-injection-xss` — 动态内容一律走 DOM API，不拼 innerHTML · security, escaping
+
+**Layout (3)**
+
+- `empty-layout-min-height` — 空态时主列矮于侧栏会留下大片空白 · layout, empty
+- `self-contained-page-budget` — 自包含页面的体积预算要一开始就定 · performance, mobile, images
+- `tokens-not-hardcoded` — 系列化产出先把设计令牌抽成一组常量 · tokens, consistency
+
+**Process (9)**
+
+- `dom-stub-smoke` — 语法检查通过 ≠ 交互能跑 · testing, interaction
+- `parallel-edits-verify` — 同一文件的多处修改要串行，并逐条 grep 复核 · tooling, verification
+- `stale-server-verify` — 调试前先确认你连的不是旧进程 · debugging, verification
+- `field-name-from-definition` — 消费方写的字段名必须对着定义抄 · integration, testing
+- `human-semantic-review` — 语义正确性只有人眼能查 · review, semantics
+- `evidence-grading` — 措辞强度必须与证据等级匹配 · writing, evidence
+- `long-doc-consistency` — 长文里同一结论会被说三遍，还可能自相矛盾 · writing, consistency
+- `counterfactual-model-drift` — 反事实推演最容易偷偷换掉前面的模型 · writing, reasoning
+- `fixture-demo-split-truth` — 门禁测 fixture、示例教另一套：两份标记各说各话 · gate, docs, a11y
+
+**Writing / publishing (12)**
+
+- `demo-must-prove-the-claim` — 演示要证明的是正文那句话，不是「能动就行」 · demo, narrative
+- `identifiers-from-source` — 编号、常量、行号、API 名一律回源检索，检索不到就降级表述 · evidence, citation
+- `prerender-when-host-strips-scripts` — 目标平台会剥 <script>/<style> 时，架构一开始就得是构建期预渲染 · publishing, prerender
+- `two-output-formats` — 「能进任何知识库」要两种载体：自包含 HTML + Markdown · publishing, output
+- `source-graded-by-citation` — 来源按「有没有引注」分级，自标缺引注的要明写不作定论 · evidence, sources
+- `unverified-source-not-authoritative` — 核不实的来源就降级，别挂权威名头 · evidence, sources
+- `md-table-cell-no-pipe` — Markdown 表格单元格里不能出现竖线 · markdown, table
+- `declare-what-you-did-not-decode` — 记法不统一时，写「本册不解码」比硬猜值钱 · evidence, scope
+- `majority-of-independent-evidence` — 注释与数据冲突时，数独立证据的票，并注明残留 · evidence, conflict
+- `plain-language-pass` — 定稿前做一遍「说人话」校对 · prose, editing
+- `reproducible-over-descriptive` — 从「有什么」升级到「怎么算」：控制流 + 可手算算例 + 版本固定 · prose, reproducibility
+- `counterfactual-worked-example` — 讲「为什么这样选」，就把被否掉的方案算死 · prose, argument
+
+## 4 · Tokens
+
+Light 112 / dark 35. Two exports, same values:
+
+- `ai/tokens.json` — DTCG shape (`$value` / `$type`), feed to design tools
+- `ai/tokens.tree.json` — grouped, `value` / `type` without `$`, feed to build tools
+
+Restyle by overriding CSS variables (`--accent`, `--paper`, `--sp-4`, …).
+Never rewrite a component selector: it wins on specificity today and breaks silently later.
+
+## 5 · Behaviour cores
+
+| core | global | what it does |
+|---|---|---|
+| dismissable | `flDismissable` | Esc 关闭 + 点击浮层之外关闭 |
+| focus-return | `flFocusReturn` | 记住打开时的焦点，关闭时还回去 |
+| roving | `flRoving` | 方向键在一组项里移动 DOM 焦点（roving tabindex） |
+| typeahead | `flTypeahead` | 打字母/汉字跳到匹配项（不是过滤） |
+
+These are shared by drawer / tabs / dropdown / overlay / combobox — do not re-implement them.
+
+## 6 · Conventions that are actually gated
+
+- 44×44 px touch targets; `:focus-visible` only, never `outline: 0`.
+- States must survive forced-colors: backgrounds are dropped, borders and text are kept.
+- Logical properties only (`margin-inline`, `inset-block`) — RTL is not a special case.
+- `prefers-reduced-motion` shortens or removes every animation.
+- Wide content gets its own `overflow-x` container with `tabindex="0"`.
+
+## 7 · Docs and language
+
+- `README.md` — English quickstart · `README.zh-CN.md` — Chinese detail
+- `ai/START-HERE.md` — Chinese navigation for agents
+- `demo.html` in each component directory — the ground truth for markup
+- Prose docs are Chinese; JSON keys, CLI flags and this file are English.

package/llms.txt

@@ -0,0 +1,55 @@
+# agentcss
+
+> A mobile-web CSS component library with a machine-readable contract: 40 components,
+> design tokens (light/dark), RTL and forced-colors support. No build step, no framework,
+> zero third-party runtime dependency. **Class names are the API.**
+
+Query the contract instead of guessing:
+
+- `ai/components.json` — id, tier, maturity, root class, slots, variants, states, ARIA, file paths
+- `ai/pitfalls.json` — known failure modes, keyed by component
+- `ai/pitfalls-writing.json` — failure modes of prose/demos/publishing (no component key)
+- `ai/tokens.json` · `ai/tokens.tree.json` — DTCG tokens, light + dark
+- `ai/behaviors.json` — five behaviour cores (Esc / focus return / roving / typeahead / scroll lock)
+
+## CLI (works without installing)
+
+```bash
+npx agentcss ai components --json                    # all 40 components
+npx agentcss ai components --json --maturity=stable  # only stable
+npx agentcss ai tokens --json --set=dark
+npx agentcss ai pitfalls --json --component=table
+npx agentcss ai validate ai/components.json --schema=components --json
+npx agentcss ai check page.json --profile=strict --json
+```
+
+Every subcommand accepts `--json`. On failure it prints
+`{"ok":false,"command":"…","error":{"kind":"…","message":"…"}}` and exits non-zero,
+so a pipeline can never mistake an error for data.
+
+`pitfalls` needs `agentcss@0.21.0+`: `npx` resolves the *published* version, which can lag
+this repository. If a subcommand is missing, check `npx agentcss --version` first.
+
+There is **no MCP server**: the CLI is the whole interface (read-only queries, no daemon,
+no second copy of the contract to keep in sync). See `ai/START-HERE.md` §7.
+
+## Use it in a page
+
+1. `<link rel="stylesheet" href="node_modules/agentcss/dist/01-tokens/tokens.css">`
+2. add `typography.css` / `page.css` only if you use the page skeleton
+3. add the component's own CSS, then copy its markup from `demo.html`
+4. restyle with tokens (CSS variables); do not rewrite component selectors
+
+## Rules that prevent most breakage
+
+- **Copy markup from `demo.html`** — it is the ground truth, not the prose.
+- 44×44 px minimum touch target; `:focus-visible` only, never `outline: 0`.
+- Every state must stay readable without colour — forced-colors drops backgrounds.
+- Tables and other wide content need their own scroll container.
+- Behaviour (drawer / tabs / overlay) needs its JS; the CSS alone is not interactive.
+
+## Docs
+
+`README.md` (English) · `ai/START-HERE.md` (Chinese navigation) · `llms-full.txt` (one-page reference with every component).
+
+**Language:** prose docs (component READMEs, demos) are Chinese; JSON keys, CLI flags and this file are English.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcss",
-  "version": "0.16.0",
+  "version": "0.24.0",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",
@@ -58,6 +58,9 @@
     "docs/",
     "README.md",
     "README.zh-CN.md",
+    "AGENTS.md",
+    "llms.txt",
+    "llms-full.txt",
     "START-HERE.md",
     "API.md",
     "SUPPORT.md",