@q1travel/design-system 0.17.1 → 0.17.3

package/README.md

@@ -1,20 +1,93 @@
 # q1travel Design System
 
-q1travel 产品家族的设计权威上游仓，三件事集于一处：`@q1travel/design-system` npm 包、设计契约（`contracts/`）与公开文档站。下游各仓只读消费已发布的包，并用包内 `q1-design` CLI 同步、校验契约缓存。推荐公开域名：`design.q1lx.com`。
+[![npm version](https://img.shields.io/npm/v/@q1travel/design-system.svg)](https://www.npmjs.com/package/@q1travel/design-system)
 
-**技术栈**：React 19（peerDependency）· TypeScript · Vite 7（文档站 / 库双构建管线）· lucide-react · npm
+`@q1travel/design-system` 提供一套 React 组件、设计 token 与设计契约，用于构建一致、可访问、支持明暗主题的产品界面。
 
-文档站以公开产品标准的口径撰写，信息架构为 `基础`、`品牌`、`组件` 三组。
+## 文档
 
-## Sources
+完整的组件指南、设计基础与使用示例见 [design.q1lx.com](https://design.q1lx.com)。
 
-- 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/context-contrast-migration.md`、`contracts/status-chip-badge-migration.md`、`contracts/pagination-migration.md`、`contracts/table-migration.md`、`contracts/overlay-shadow-migration.md`。独立 HTML 文档的有界 class 词汇表源为 `contracts/design.css`。
-- Generated mirrors（生成镜像，勿手改）：`public/design.md`、`public/design.dark.md` 由 `scripts/sync-design-contracts.mjs` 从契约源逐字节复制；`public/design.css` 由 `scripts/build-design-css.mjs` 把两份契约 frontmatter 的取值注入 `contracts/design.css` 的类词汇后生成，因而自足、可被独立 HTML 页面直接加载。
-- Runtime tokens：`src/styles/tokens.css`（canonical `--q1-*`，仅 `:root` 与 `:root[data-theme='dark']` 两个扁平 selector）。
-- 发布台账：`contracts/releases/`（仅存于仓库，不进 npm 包）。
-- npm 发布与下游自动更新：版本 tag 触发 GitHub Actions OIDC 免令牌发布，详见[发布操作说明](docs/npm-release.md)。
+## 环境要求
+
+- React 19 与 React DOM 19（peerDependency）
+- 支持 ES Module 的构建工具（如 Vite）
+- 使用 `q1-design` CLI 需要 Node.js 22+
+
+## 安装
+
+```bash
+npm install @q1travel/design-system
+```
+
+## 使用
+
+在应用入口引入样式表，然后按需导入组件：
+
+```tsx
+import '@q1travel/design-system/style.css';
+import { Button } from '@q1travel/design-system';
+
+export function SaveAction() {
+  return <Button variant="primary">保存</Button>;
+}
+```
+
+`style.css` 已包含全部设计 token 与组件样式。如果只需要设计 token（例如为自有组件取色、取间距），可以单独引入：
+
+```ts
+import '@q1travel/design-system/tokens.css';
+```
+
+所有 token 以 `--q1-*` 命名，例如 `var(--q1-color-gray-1000)`。
+
+### 主题
+
+组件默认使用浅色主题。在根元素上设置 `data-theme="dark"` 即可切换为深色主题：
+
+```html
+<html data-theme="dark">
+```
 
-## Getting Started
+### 反馈提示
+
+使用 `useToast` 前，需要在应用根部包裹 `ToastProvider`：
+
+```tsx
+import { ToastProvider } from '@q1travel/design-system';
+
+root.render(
+  <ToastProvider>
+    <App />
+  </ToastProvider>,
+);
+```
+
+## CLI
+
+包内附带 `q1-design` 命令行工具，用于查询组件 API 并检查样式用法：
+
+| 命令 | 说明 |
+| --- | --- |
+| `npx q1-design ls` | 列出包内提供的组件与 hook |
+| `npx q1-design doc <组件名>` | 打印组件的公共 API |
+| `npx q1-design lint [路径...]` | 按 `Q1-DS-*` 规则检查样式用法，默认扫描 `src` |
+| `npx q1-design lint --diff <base-ref>` | 只检查相对 `base-ref` 有改动的文件 |
+| `npx q1-design overrides [路径...]` | 统计对组件外观的 `className` 覆写 |
+| `npx q1-design sync` | 将设计契约与 AI 编码指南同步为项目内的只读缓存 |
+| `npx q1-design verify` | 校验缓存未被修改且与已安装版本一致 |
+
+## 设计契约与 AI 编码指南
+
+包内随附设计契约（`contracts/*.md`）与 product-design 编码指南（`.agents/`），可供 AI 编码助手读取，使生成的界面遵循同一套 token 与组件规范。契约文件通过 `@q1travel/design-system/contracts/*` 路径导出，也可以用 `npx q1-design sync` 同步到项目中。
+
+## 版本
+
+历史版本见 npm 的 [Versions](https://www.npmjs.com/package/@q1travel/design-system?activeTab=versions) 页。
+
+## 参与开发
+
+以下内容面向本仓库的贡献者。
 
 前置要求：Node.js 22+（CI 基线 22）与 npm（依赖锁定在 `package-lock.json`）；运行 `check:browser` 需要本机 Chrome（可用 `CHROME_PATH` 指定）。`check:browser` 在本地与 CI 都默认使用 `--headless=new`，不探测 TTY 或 `DISPLAY`；只有显式设置 `Q1_DESIGN_BROWSER_HEADLESS=false` 才切换到 headed 模式。
 
@@ -23,7 +96,17 @@ npm install
 npm run dev
 ```
 
-## Available Scripts
+**技术栈**：React 19 · TypeScript · Vite 7（文档站 / 库双构建管线）· lucide-react · npm
+
+### Sources
+
+- 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/context-contrast-migration.md`、`contracts/status-chip-badge-migration.md`、`contracts/pagination-migration.md`、`contracts/table-migration.md`、`contracts/overlay-shadow-migration.md`。独立 HTML 文档的有界 class 词汇表源为 `contracts/design.css`。
+- Generated mirrors（生成镜像，勿手改）：`public/design.md`、`public/design.dark.md` 由 `scripts/sync-design-contracts.mjs` 从契约源逐字节复制；`public/design.css` 由 `scripts/build-design-css.mjs` 把两份契约 frontmatter 的取值注入 `contracts/design.css` 的类词汇后生成，因而自足、可被独立 HTML 页面直接加载。
+- Runtime tokens：`src/styles/tokens.css`（canonical `--q1-*`，仅 `:root` 与 `:root[data-theme='dark']` 两个扁平 selector）。
+- 发布记录：`contracts/releases/`（仅存于仓库，不进 npm 包）。
+- npm 发布：版本 tag 触发 GitHub Actions OIDC 免令牌发布，详见 `docs/npm-release.md`。
+
+### Available Scripts
 
 | 命令 | 用途 |
 | --- | --- |
@@ -34,15 +117,15 @@ npm run dev
 | `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 check:release-sync` | 发布后 registry 完整性与四仓 Renovate 通知脚本测试 |
+| `npm run check:release-provenance` | 发布记录 vs `CHANGELOG.md`、origin tag 与 npm registry |
+| `npm run check:release-sync` | 发布后 registry 完整性校验与依赖更新通知脚本测试 |
 | `npm run release:verify -- <tarball>` | 只校验 workflow tarball 与 npm registry 完整性 |
-| `npm run release:sync -- <tarball>` | 校验 registry 后通知四仓 Renovate；不具备发布能力 |
+| `npm run release:sync -- <tarball>` | 校验 registry 后发送依赖更新通知；不具备发布能力 |
 | `npm run build:pkg` | 库构建（产物 `dist-pkg/`）+ CSS 拼装 + 包 API 检查（`prepack` 同款） |
 
 本仓没有独立的 test / lint script——规范由 `scripts/` 下的契约门禁脚本守护。
 
-## Project Structure
+### Project Structure
 
 ```
 src/components/ui/     npm 包组件源（入口 index.ts，统一公共导出面）
@@ -50,20 +133,19 @@ src/components/        docs/、layout/、brand/ 文档站结构组件
 src/pages/             文档站页面（组件示例编排）
 src/styles/            tokens.css、foundations.css、components.css 等分桶样式
 src/browser-fixtures/  check:browser 的行为契约 fixture
-contracts/             设计契约源 + releases/ 发布台账
+contracts/             设计契约源 + releases/ 发布记录
 public/                契约镜像与品牌/字体/图标静态资产
 scripts/               契约门禁与构建脚本（check-shell / check-browser / …）
-bin/                   q1-design CLI（消费仓 ls / doc / sync / verify / lint / eval）
+bin/                   q1-design CLI（ls / doc / sync / verify / lint / eval / overrides）
 tooling/               规则清单（Q1-DS-*）与 eval fixture
 .agents/               随包分发的 product-design skill
-docs/  review/         架构骨架、agent 规范、历史决策记录
+docs/  review/         架构说明、agent 规范、历史决策记录
 ```
 
-## Documentation & AI Guidelines
+### Documentation & AI Guidelines
 
-- **AI Agent 必须遵循根目录 `AGENTS.md`**（Claude Code 与 Codex 共用的 canonical 入口：命令速查、红线约束、工作闭环与知识索引）；`CLAUDE.md` 仅为其薄包装。
-- `docs/architecture.md` — 双构建管线、契约生成与下游消费模型、文档站托管与公开契约的缓存策略（含 Cloudflare Cache Rule 与 Purge 运维备忘）、发布溯源链路。
+- AI 编码助手遵循根目录 `AGENTS.md`（命令速查、约束、工作闭环与知识索引）；`CLAUDE.md` 仅为其薄包装。
+- `docs/architecture.md` — 双构建管线、契约生成与消费模型、文档站托管与缓存策略、发布溯源链路。
 - `docs/adr/template.md` — 新 ADR 从此模板开始；早期已接受决策存于 `review/decision-log/`。
-- `docs/token-coverage-gaps.md` — 下游有真实消费需求但本仓未导出的 `--q1-*` 能力缺口登记（待决清单，非契约）。
+- `docs/token-coverage-gaps.md` — 尚未导出的 `--q1-*` 能力缺口登记（待决清单，非契约）。
 - `docs/research/design-md-eval/` — design.md 有/无 对照评测：固定场景、确定性检查、修正队列（研究记录，非契约）。
-- 下游消费方式：安装 `@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` 统计并分类消费方对组件外观的覆写。