@q1travel/design-system 0.30.9 → 0.30.11

package/README.md

@@ -69,8 +69,8 @@ root.render(
 
 | 命令 | 说明 |
 | --- | --- |
-| `npx q1-design ls` | 列出包内提供的组件与 hook |
-| `npx q1-design doc <组件名>` | 打印组件的公共 API |
+| `npx q1-design ls` | 列出包内提供的组件、hook 与应用模板 |
+| `npx q1-design doc <组件名>` | 打印组件的公共 API；`doc app-base` 查看应用基础样式模板 |
 | `npx q1-design lint [路径...]` | 按 `Q1-DS-*` 规则检查样式用法，默认扫描 `src` |
 | `npx q1-design lint --diff <base-ref>` | 只检查相对 `base-ref` 有改动的文件 |
 | `npx q1-design overrides [路径...]` | 统计对组件外观的 `className` 覆写 |
@@ -79,7 +79,17 @@ root.render(
 
 ## 设计契约与 AI 编码指南
 
-包内随附设计契约（`contracts/*.md`）与 product-design 编码指南（`.agents/`），可供 AI 编码助手读取，使生成的界面遵循同一套 token 与组件规范。契约文件通过 `@q1travel/design-system/contracts/*` 路径导出，也可以用 `npx q1-design sync` 同步到项目中。
+包内随附设计契约（`contracts/*.md`、`contracts/app-base.css`）与 product-design 编码指南（`.agents/`），可供 AI 编码助手读取，使生成的界面遵循同一套 token 与组件规范。契约文件通过 `@q1travel/design-system/contracts/*` 路径导出，也可以用 `npx q1-design sync` 同步到项目中。
+
+基础层归应用所有。运行 `npx q1-design sync` 后，模板位于
+`.claude/skills/product-design/contracts/app-base.css`（只读缓存，纳入 `verify` 哈希校验）。首次接入时复制为应用自己的文件：
+
+```bash
+mkdir -p src/styles
+cp .claude/skills/product-design/contracts/app-base.css src/styles/app-base.css
+```
+
+在应用入口先引入 `@q1travel/design-system/tokens.css`（已引入 `style.css` 时无需重复），再引入 `./styles/app-base.css`。应用可修改该副本或在之后加载覆盖样式；升级并重新 `sync` 后自行审阅模板差异再采纳，CLI 不覆盖应用副本。模板只包含盒模型、页面边距与最小高度、画布文字字体与字体平滑、点按高亮、原生表单字体继承；根容器、读屏工具与组件运动/触控行为由各自所属层管理。
 
 ## 版本
 
@@ -102,7 +112,7 @@ npm run dev
 
 ### 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`。
+- 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`。应用自有基础样式模板源为 `contracts/app-base.css`（非运行时样式导出）。独立 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 包）。

package/bin/q1-design.mjs

@@ -854,10 +854,21 @@ function runList(consumerRootDir) {
     console.log(`\n工具与 hook (${hooks.length})`);
     console.log(`  ${hooks.join('  ')}`);
   }
+  console.log('\n应用模板：app-base（q1-design doc app-base）');
   console.log(`\n查看某个组件的 API：q1-design doc <名称>`);
 }
 
 function runDoc(consumerRootDir, requestedName) {
+  if (requestedName === 'app-base') {
+    const packageRootDir = resolveInstalledPackageRoot(consumerRootDir) ?? resolve(dirname(fileURLToPath(import.meta.url)), '..');
+    const templatePath = join(packageRootDir, 'contracts/app-base.css');
+    if (!existsSync(templatePath)) {
+      console.error('当前安装的设计系统版本不含应用基础样式模板，请升级后重试');
+      process.exit(1);
+    }
+    console.log(readFileSync(templatePath, 'utf8'));
+    return;
+  }
   if (!requestedName) {
     console.error('Usage: q1-design doc <组件名>');
     process.exit(1);

package/contracts/app-base.css

@@ -0,0 +1,38 @@
+/*
+ * q1-design sync 生成此模板缓存；复制到应用样式目录后归应用所有。
+ * 应用可按需修改或在其后覆盖；不要修改只读契约缓存。
+ * 先加载 @q1travel/design-system/tokens.css，再加载应用基础样式。
+ * 更新包并重新 sync 只更新模板，应用自行审阅并采纳差异。
+ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+}
+
+body {
+  min-height: 100%;
+  background: var(--q1-color-bg-canvas);
+  color: var(--q1-color-text-primary);
+  font-family: var(--q1-font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+html {
+  height: 100%;
+  -webkit-tap-highlight-color: transparent;
+}
+
+button,
+input,
+textarea,
+select {
+  font: inherit;
+}

package/dist-pkg/design-system.d.ts

@@ -2337,10 +2337,12 @@ export declare function Separator({ orientation, decorative, className, }: {
 
 export declare type SeparatorOrientation = 'horizontal' | 'vertical';
 
-export declare function Sheet({ open, onClose, title, side, size, dismissable, mobileFullscreen, children, footer }: {
+export declare function Sheet({ open, onClose, title, description, side, size, dismissable, mobileFullscreen, children, footer }: {
     open: boolean;
     onClose: () => void;
     title: string;
+    /** 标题下方的导语；通过 aria-describedby 关联，不传则不渲染。 */
+    description?: ReactNode;
     side?: SheetSide;
     size?: SheetSize;
     dismissable?: boolean;