@q1travel/design-system 0.9.1 → 0.11.0

package/.agents/skills/product-design/references/review-component.md

@@ -16,8 +16,22 @@ Use this workflow when reviewing this repository's component implementation or d
 3. Check the rendered local component in light and dark themes. Cover sparse, dense, loading, error, focus, disabled, and reduced-motion states that the component can reach.
 4. Probe every element that appears interactive. Verify semantics, accessible names, keyboard behavior, focus, state announcement, disabled behavior, cleanup, and provider independence where applicable.
 5. Compare the implementation with the matching local component family before proposing a new page-local pattern.
-6. Run the verification command routed by `AGENTS.md`. Keep tool limitations separate from product findings.
-7. Report findings by severity with contract, current evidence, impact, and the smallest corrective direction. If there are no findings, state the remaining evidence limits.
+6. Run the section-coverage pass below. It is a separate dimension from steps 3 and 4, not a summary of them.
+7. Run the verification command routed by `AGENTS.md`. Keep tool limitations separate from product findings.
+8. Report findings by severity with contract, current evidence, impact, and the smallest corrective direction. If there are no findings, state the remaining evidence limits.
+
+## Section Coverage
+
+Visual and interaction review answers whether the built thing looks and behaves right. It cannot surface a capability or documented section that is missing altogether, because a missing section renders nothing to inspect. Run this as its own pass.
+
+1. List the target's own outline: every `SpecSection` title in its documentation page, plus the exported props and states backing them.
+2. Build the comparison outline from the authority for this review — the matching `contracts/` entry and the component's public API. Add an external reference's named sections only when the user explicitly asked for that comparison.
+3. Compare by capability, not by string. Local titles are Chinese and reference titles are English; a section counts as covered when the capability exists under any name.
+4. Compare named functional sections such as default, sizes, states, disabled, prefix and suffix, position, best practices, and accessibility. Skip anatomy, playground, code-display containers, and page chrome such as feedback blocks, pager links, and sidebar navigation. A heading that renders a demo is often itself a capability, so do not skip it for being a demo.
+5. Give each compared section one verdict: missing, uncertain and needing human confirmation, covered under a different title, or deliberately not followed with a recorded reason. Leave uncertain items uncertain instead of forcing them toward missing or covered.
+6. Report each verdict with its evidence — a local line or section title against the compared section — and the smallest corrective direction.
+
+A different underlying implementation structure is not a coverage gap when both satisfy the local contracts. This pass covers capability and section coverage only.
 
 ## Evidence Pitfalls
 

package/.agents/skills/product-design/references/rules.md

@@ -4,7 +4,7 @@
 
 **稳定 ID 清单**:`tooling/scripts/evals/rules-checklist.json`(种子已建;每条带稳定 ID + canonical 出处 + `kind`:deterministic 可静态强制 / judgment 留给 skill·Review)。
 
-**现状(coverage gap)**:`q1-design lint` 已实现 `Q1-DS-001`(`--ds-*`)/`Q1-DS-401`(`transition: all`)/`Q1-DS-501`(裸颜色字面量)三条纯机械规则,`q1-design eval` 已实现;其余规则(含带判断成分的 deterministic 规则与全部 judgment 规则)待后续批次。eval 种子见 `tooling/scripts/evals/`(fixtures.json + before/after)。
+**现状(coverage gap)**:`q1-design lint` 已实现 `Q1-DS-001`(`--ds-*`)/`Q1-DS-401`(`transition: all`)/`Q1-DS-404`(裸 duration/easing)/`Q1-DS-501`(裸颜色字面量)四条纯机械规则,`q1-design eval` 已实现;其余规则(含带判断成分的 deterministic 规则与全部 judgment 规则)待后续批次。eval 种子见 `tooling/scripts/evals/`(fixtures.json + before/after)。
 
 首批种子规则(取自 `interface-guidelines.md` / `token-naming.md` 的确定性条目):
 

package/README.md

@@ -1,29 +1,63 @@
 # q1travel Design System
 
-Design system documentation site for q1travel.
+q1travel 产品家族的设计权威上游仓，三件事集于一处：`@q1travel/design-system` npm 包、设计契约（`contracts/`）与公开文档站。下游各仓只读消费已发布的包，并用包内 `q1-design` CLI 同步、校验契约缓存。推荐公开域名：`design.q1lx.com`。
 
-Recommended public domain: `design.q1lx.com`.
+**技术栈**：React 19（peerDependency）· TypeScript · Vite 7（文档站 / 库双构建管线）· lucide-react · npm
 
-The site is written as a public product standard. Avoid internal-only or narrow business positioning in user-facing copy.
+文档站以公开产品标准的口径撰写，信息架构为 `基础`、`品牌`、`组件` 三组。
 
 ## Sources
 
-- Source contracts: `contracts/design.md`, `contracts/design.dark.md`, `contracts/token-naming.md`, `contracts/button-api-compatibility.md`, `contracts/interface-guidelines.md`, `contracts/design-engineering-principles.md`, and `contracts/implementation-map.md`.
-- Repository-only release provenance lives under `contracts/releases/` and is intentionally excluded from the npm package to avoid shipping mutable or self-referential ledger state.
-- Generated mirrors: `public/design.md` and `public/design.dark.md`.
-- Runtime tokens: `src/styles/tokens.css`.
-- Runtime UI: `src/components` owns shared structure; `src/pages` composes documentation examples.
-- Scripts: `scripts/sync-design-contracts.mjs` publishes contract mirrors; `scripts/check-shell.mjs` verifies source and contract boundaries; `scripts/check-browser.mjs` verifies built UI behavior; `scripts/check-package-api.mjs` verifies the built package declarations and runtime API. Run both `npm run check` and `npm run build:pkg` for Button API changes.
-
-## v1 scope
-
-- Documentation site
-- Token specification
-- Component visual samples
-
-## Not in v1
-
-- npm component package
-- q1travel-web migration
-- Storybook deletion
-- Chrome extension integration
+- Source contracts（设计契约源，canonical）：`contracts/design.md`、`contracts/design.dark.md`、`contracts/token-naming.md`、`contracts/icon-system.md`、`contracts/button-api-compatibility.md`、`contracts/interface-guidelines.md`、`contracts/design-engineering-principles.md`、`contracts/implementation-map.md`、`contracts/overlay-foundation.md`，以及迁移契约 `contracts/status-chip-badge-migration.md`、`contracts/pagination-migration.md`、`contracts/table-migration.md`、`contracts/overlay-shadow-migration.md`。
+- Generated mirrors（生成镜像，勿手改）：`public/design.md`、`public/design.dark.md`，由 `scripts/sync-design-contracts.mjs` 从契约源复制。
+- Runtime tokens：`src/styles/tokens.css`（canonical `--q1-*`，仅 `:root` 与 `:root[data-theme='dark']` 两个扁平 selector）。
+- 发布台账：`contracts/releases/`（仅存于仓库，不进 npm 包）。
+
+## Getting Started
+
+前置要求：Node.js 22+（CI 基线 22）与 npm（依赖锁定在 `package-lock.json`）；运行 `check:browser` 需要本机 Chrome（可用 `CHROME_PATH` 指定）。
+
+```bash
+npm install
+npm run dev
+```
+
+## Available Scripts
+
+| 命令 | 用途 |
+| --- | --- |
+| `npm run dev` | 文档站本地开发服务器 |
+| `npm run build` | 契约镜像同步 + `tsc -b` + 文档站构建（产物 `dist/`） |
+| `npm run preview` | 预览文档站构建产物 |
+| `npm run check` | 全量门禁：build + `check:shell` + `check:browser` + `build:pkg`（含 `check:package-api`） |
+| `npm run check:shell` | 结构与源码契约断言 + token 包检查 + 发布溯源检查 |
+| `npm run check:browser` | 基于 CDP 的浏览器行为契约（含 StrictMode 前置轮） |
+| `npm run check:package-api` | 已构建包的声明与运行时 API + 组件契约 `node --test` 套件 |
+| `npm run check:release-provenance` | 发布台账 vs `CHANGELOG.md`、origin tag 与 npm registry |
+| `npm run build:pkg` | 库构建（产物 `dist-pkg/`）+ CSS 拼装 + 包 API 检查（`prepack` 同款） |
+
+本仓没有独立的 test / lint script——规范由 `scripts/` 下的契约门禁脚本守护。
+
+## Project Structure
+
+```
+src/components/ui/     npm 包组件源（入口 index.ts，统一公共导出面）
+src/components/        docs/、layout/、brand/ 文档站结构组件
+src/pages/             文档站页面（组件示例编排）
+src/styles/            tokens.css、foundations.css、components.css 等分桶样式
+src/browser-fixtures/  check:browser 的行为契约 fixture
+contracts/             设计契约源 + releases/ 发布台账
+public/                契约镜像与品牌/字体/图标静态资产
+scripts/               契约门禁与构建脚本（check-shell / check-browser / …）
+bin/                   q1-design CLI（消费仓 ls / doc / sync / verify / lint / eval）
+tooling/               规则清单（Q1-DS-*）与 eval fixture
+.agents/               随包分发的 product-design skill
+docs/  review/         架构骨架、agent 规范、历史决策记录
+```
+
+## Documentation & AI Guidelines
+
+- **AI Agent 必须遵循根目录 `AGENTS.md`**（Claude Code 与 Codex 共用的 canonical 入口：命令速查、红线约束、工作闭环与知识索引）；`CLAUDE.md` 仅为其薄包装。
+- `docs/architecture.md` — 双构建管线、契约生成与下游消费模型、发布溯源链路。
+- `docs/adr/template.md` — 新 ADR 从此模板开始；早期已接受决策存于 `review/decision-log/`。
+- 下游消费方式：安装 `@q1travel/design-system` 后 import 组件与 `style.css` / `tokens.css`；`npx q1-design sync` 把包内 skill 与契约物化为只读缓存，`q1-design verify` 校验缓存未被改动，`q1-design lint` 执行 `Q1-DS-*` 机械规则；`q1-design ls` 列出随包组件，`q1-design doc <组件名>` 打印其公共 API（两者现推自随包的 `.d.ts`，不另存清单）；`q1-design overrides` 统计并分类消费方对组件外观的覆写。