@wneng/create-keel 0.2.0 → 0.3.0

package/src/standards/templates/coding-style-rust.md.eta

@@ -0,0 +1,52 @@
+# Rust 编码规范
+
+> 真值是 `rustfmt` + `clippy` 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `clippy` job 阻断违规。
+
+config: agent/rustfmt.toml
+
+## 命名规范
+
+- crate / 模块：`snake_case`
+- 类型 / trait / 枚举：`PascalCase`；变体也是 `PascalCase`
+- 函数 / 变量 / 字段：`snake_case`；常量 / 静态：`UPPER_SNAKE_CASE`
+- 生命周期：单字母 `'a` 起步，复杂时表义 `'session`
+
+## 格式化
+
+- `cargo fmt` 单一权威；CI 中 `cargo fmt --check` 阻断
+- 行宽 100（rustfmt 默认）；4 空格缩进
+- import 顺序：标准库 → 第三方 → 本 crate；rustfmt 处理
+
+## 错误处理
+
+- 业务函数返回 `Result<T, E>`；禁止 `unwrap()` / `expect()` 在 release 路径
+- 错误类型：库代码用 `thiserror`；应用代码用 `anyhow::Result`
+- `?` 是 happy path；想日志或转换错误时用 `.context("...")` (`anyhow`) 或 `.map_err(...)`
+- panic 仅在不可恢复（断言违反、初始化失败）时用
+
+## 所有权与并发
+
+- 优先 borrow，其次 `Clone`，再次 `Arc`；`Rc` 仅在单线程
+- `unsafe` 必须有 `// SAFETY: ...` 注释解释不变量
+- 跨线程数据走 `Send + Sync`；共享可变状态走 `Arc<Mutex<T>>` 并尽量缩小锁粒度
+- async：`tokio` 单一运行时；不要混 async-std
+
+## 依赖与模块
+
+- `Cargo.toml` 钉版本（`= "x.y.z"`），与 `tech-stack-agent.md` 对齐
+- workspace：跨 `apps/*` 在 multi-app 模式下走顶层 `crates/<shared>`，禁止直接 path import 兄弟 app
+- 第三方 crate 引入前确认 license 与维护活跃度
+
+## 注释与文档
+
+- 导出 item 必须有 `///` doc comment；crate 根写 `//!` 模块级 doc
+- `// Why:` 段说明非显然的决策
+- `cargo doc --no-deps` 在 CI 中验证 doc 不报错
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| rustfmt | `agent/rustfmt.toml` | `format-check` |
+| clippy | `agent/Cargo.toml` 中 `[lints.clippy]` 段 | `clippy` |
+| cargo deny | `agent/deny.toml` | `security` |

package/src/standards/templates/coding-style-typescript.md.eta

@@ -0,0 +1,50 @@
+# TypeScript 编码规范
+
+> 真值是 ESLint / Prettier 配置；本文件解释 *为什么* 与 *如何调整*。机器校验在 CI 中 `eslint` job 阻断违规。
+
+config: web/.eslintrc.cjs
+
+## 命名规范
+
+- 文件：`kebab-case.ts`，组件文件除外 → `PascalCase.tsx`
+- 类型 / 接口 / 类：`PascalCase`，禁止 `I` 前缀
+- 变量 / 函数：`camelCase`，常量级（模块顶部全大写枚举）：`UPPER_SNAKE_CASE`
+- React 组件：`PascalCase`；hooks：`use<Name>`
+
+## 格式化
+
+- Prettier 单一权威；本仓库不在评审里讨论分号 / 引号 / 行宽
+- 行宽 100；2 空格缩进；尾随逗号 `all`
+- import 顺序：node 内置 → 第三方 → 别名 (`@/...`) → 相对路径，每段空行隔开
+
+## 错误处理
+
+- 业务函数返回 `Result<T, E>` 或抛出 `ScaffolderError` 子类；禁止裸 `throw new Error(...)`
+- `try / catch` 必须 narrow `unknown`：`catch (e)` 后用 `instanceof` 或 type guard
+- async 函数禁止吞错；`Promise.allSettled` 用于刻意聚合失败
+
+## 类型用法
+
+- 严格模式：`tsc --noEmit` 在 CI 阻断；本地禁止 `// @ts-ignore`，必要时用 `@ts-expect-error` 并解释
+- 优先 `interface` 描述对象形状；`type` 用于联合 / 映射 / 函数签名
+- 禁止 `any`；不可避免时用 `unknown` 加 type guard
+
+## 依赖与导入
+
+- 单 app：相对路径；多 app：路径别名 `@apps/<name>` 或 `@contracts/...`
+- 跨 `apps/*` import 在 multi-app 模式下被 `dependency-cruiser` 阻断
+- 第三方依赖必须在 `tech-stack-<env>.md` 钉版本表中存在
+
+## 注释与文档
+
+- TSDoc：导出符号必须有一行说明；复杂逻辑加 `Why:` 段说明意图
+- 对外 API：`@param` `@returns` `@throws` 完整
+- 禁止注释掉的代码；用 git 历史
+
+## lint 配置真值
+
+| 工具 | 配置文件 | CI job |
+|------|---------|--------|
+| ESLint | `web/.eslintrc.cjs`（前端）/ `server/.eslintrc.cjs`（后端） | `lint` |
+| Prettier | `.prettierrc` | `format-check` |
+| TypeScript | `tsconfig.json` | `typecheck` |

package/src/standards/templates/dependency-cruiser.config.cjs.eta

@@ -0,0 +1,57 @@
+/**
+ * dependency-cruiser configuration — engineering-standards module boundaries.
+ *
+ * Generated by `@wneng/create-keel` (engineering-standards plan).
+ * Edit with care; the rules here are referenced by:
+ *   - docs/03-工程规范与研发基础设施/module-boundaries.md (narrative truth)
+ *   - tools/governance-lint/checks/stack-pinning.js (exit code mapping)
+ */
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: 'GOV.BOUND.CROSS_APP',
+      severity: 'error',
+      comment:
+        'apps/<X> must not directly import from apps/<Y>. Move shared code to contracts/ or packages/<shared>/.',
+      from: { path: '^(?:[^/]+)/apps/([^/]+)/' },
+      to: { path: '^(?:[^/]+)/apps/(?!\\1)([^/]+)/' },
+    },
+    {
+      name: 'GOV.BOUND.CIRCULAR',
+      severity: 'error',
+      comment: 'Circular dependencies make the build graph unstable.',
+      from: {},
+      to: { circular: true },
+    },
+    {
+      name: 'no-orphans',
+      comment: 'Orphan modules (no incoming edges) usually indicate dead code.',
+      severity: 'warn',
+      from: {
+        orphan: true,
+        pathNot: [
+          '(^|/)\\.(?:eslint|prettier|babel|tsconfig)',
+          '\\.d\\.ts$',
+          '(^|/)src/index\\.[jt]sx?$',
+        ],
+      },
+      to: {},
+    },
+  ],
+  options: {
+    doNotFollow: { path: 'node_modules' },
+    tsConfig: { fileName: 'tsconfig.json' },
+    enhancedResolveOptions: {
+      exportsFields: ['exports'],
+      conditionNames: ['import', 'require', 'node'],
+    },
+    reporterOptions: {
+      err: {
+        // Standard error format consumed by governance-lint
+        showRules: true,
+      },
+    },
+  },
+};

package/src/standards/templates/design-tokens.ts.eta

@@ -0,0 +1,37 @@
+/**
+ * Design tokens — generated by `@wneng/create-keel` (engineering-standards).
+ *
+ * The exported constant *names* here MUST exactly match the token name
+ * column in `docs/05-前端客户端详细设计/ui-design-system.md`. The
+ * governance-lint `ui-token-drift` check enforces this; mismatches
+ * surface as `GOV.UI.TOKEN_DRIFT` in CI.
+ *
+ * Edit values, not names. Renaming a token requires a coordinated PR
+ * that touches both this file and the manifest's token table in the
+ * same commit.
+ */
+
+// Colors ---------------------------------------------------------------
+
+export const colorPrimary = '#2563EB';
+export const colorSurface = '#FFFFFF';
+export const colorTextDefault = '#0F172A';
+export const colorTextMuted = '#64748B';
+export const colorBorder = '#E2E8F0';
+export const colorDanger = '#DC2626';
+
+// Spacing --------------------------------------------------------------
+
+export const space1 = '4px';
+export const space2 = '8px';
+export const space3 = '12px';
+export const space4 = '16px';
+export const space6 = '24px';
+export const space8 = '32px';
+
+// Typography -----------------------------------------------------------
+
+export const fontHeading1 = { fontSize: '32px', lineHeight: 1.25, fontWeight: 600 } as const;
+export const fontHeading2 = { fontSize: '24px', lineHeight: 1.3, fontWeight: 600 } as const;
+export const fontBody = { fontSize: '14px', lineHeight: 1.5, fontWeight: 400 } as const;
+export const fontCaption = { fontSize: '12px', lineHeight: 1.4, fontWeight: 400 } as const;

package/src/standards/templates/module-boundaries.md.eta

@@ -0,0 +1,82 @@
+# 模块引用边界
+
+> 本文件给出仓库内的引用方向规则。机器侧守门交给 `dependency-cruiser` / `archunit` / `gomodguard` 等工具；本文件解释**为什么**有这些边界，以及**如何**调整。
+
+config: <% if (it.standards.multiApp) { %>dependency-cruiser.config.cjs<% } else { %>(单 app 模式无机器守门，仅本文件叙事)<% } %>
+
+## 总原则
+
+依赖**只**沿允许的方向流动。违反方向的 import / require / require_once 会导致以下后果之一：
+
+1. 短期：编译能过，但循环依赖让构建图不稳定
+2. 中期：模块边界腐烂，重构难度指数上升
+3. 长期：单一模块测试不再独立，整仓 CI 时长翻倍
+
+为防止这种漂移，本文件 + `dependency-cruiser`（multi-app 模式下）一起做硬约束。
+
+## 命名规范
+
+边界检查中用到的几个稳定标识：
+
+- `apps/<name>/` —— 多 app 模式下的应用根
+- `contracts/` —— 跨执行环境的机器可消费契约
+- `packages/` —— 多 app 共享的代码（root 级，可选）
+
+## 错误处理
+
+import 违规会被 dependency-cruiser 报告为以下错误码：
+
+- `GOV.BOUND.CROSS_APP` —— `apps/A` 直接引用了 `apps/B` 的代码
+- `GOV.BOUND.CIRCULAR` —— 模块循环依赖
+
+修复路径：把共享代码挪到 `contracts/`（机器可消费契约）或 `packages/<shared>/`（根级可选 workspace）。
+
+## 格式化
+
+- 模块导出文件按 layer 命名：`index.ts` 是公共入口，`internal/` 下是私有
+- 跨包 import 必须经过 `index.ts`，**禁止**深路径 `from "@app/internal/foo"`
+
+<% if (it.standards.multiApp) { %>## 多 app 模式（当前启用）
+
+仓库已切换到多 app 模式，`<env>/apps/<name>/` 下每个目录是独立应用。
+
+**禁止**：
+- `apps/A/` 中的代码 import `apps/B/` 中的任何文件（任何深度）
+- 跨 app 共享 utility 直接放在某个 app 内部
+
+**允许**：
+- 通过 `contracts/` 共享 schema / 错误码 / 状态机
+- 通过根 `packages/<name>/` 共享代码（需要在 PR 中说明为什么不能放契约层）
+
+机器守门：[`dependency-cruiser.config.cjs`](../../dependency-cruiser.config.cjs) 在 CI 中阻断违规 import。
+
+## 调整流程
+
+1. 改 `dependency-cruiser.config.cjs` 中的 forbidden 规则前，必须在 ADR 中说明
+2. 同 PR 改本文件正文部分（这是双写，让 review 看到边界变化）
+3. CI 跑 dependency-cruiser；不通过就改回去
+4. 真要破例：在违规处添加 `// eslint-disable-next-line import/no-restricted-paths` 并 PR 描述给出理由
+<% } else { %>## 单 app 模式（当前启用）
+
+仓库目前是单 app 模式，`<env>/` 下直接放一份工程文件，没有 `apps/` 子目录。
+
+**约束**：
+- 跨执行环境（如后端 server/ ↔ 前端 web/）必须通过 `contracts/` 共享类型与契约
+- 不要在 server/ 中 import web/ 的文件，或反之
+
+**没有机器守门**：单 app 模式下不强制 dependency-cruiser；这是有意为之，因为单 app 模式工程量小，引入额外工具收益不抵成本。
+
+## 升级到多 app 模式
+
+如果将来仓库需要容纳第二个应用：
+
+1. `mkdir <env>/apps/<原应用名>` 并 `git mv` 全部源码
+2. 同 PR 启用 `--multi-app` 选项，重新生成本文件 + `dependency-cruiser.config.cjs`
+3. 在 ADR 中记录"为什么从单 app 升级"
+4. 完整 promote / add-app 流程见 [`docs/governance/git-workflow.md`](../governance/git-workflow.md)
+<% } %>
+
+## 关联
+
+- 编码规范：见 `coding-style-<lang>.md` 系列
+- 部署：跨 app 共享配置走 `deploy/`，不要让一个 app 依赖另一个 app 的 deploy 制品

package/src/standards/templates/tech-stack-agent.md.eta

@@ -0,0 +1,35 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 桌面 / Agent 技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **桌面端发布周期长**：用户桌面上的版本几个月不更新很正常；不可重现的依赖会让远程 debug 极其痛苦
+- **平台二进制兼容**：Tauri / Electron 的原生模块在 Windows / macOS / Linux 表现不一致，主版本变化最容易触发签名失败
+
+## policy 三档
+
+policy 语义与 [tech-stack-server.md](tech-stack-server.md) 一致。桌面端常用 `minor` 起步，对 `tokio` / `serde` 一类基础设施级依赖也只用 `minor`（Rust 生态的 SemVer 通常守得住）。
+
+## Rust crate 特有的考虑
+
+- workspace 中所有 crate 的同名依赖必须钉同一版本（`Cargo.toml` 中 `[workspace.dependencies]` 段）
+- 与 C / C++ 共享库通过 FFI 交互的 crate（如 `openssl-sys`）：标 `major-only`，因为底层 ABI 变化会导致 panic
+- `unsafe` 较多的 crate：标 `major-only`，每次升级都人工 review CHANGELOG
+
+## 关联
+
+- 编码规范：[coding-style-rust.md](coding-style-rust.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/tech-stack-miniapp.md.eta

@@ -0,0 +1,34 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 小程序技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **平台 SDK 审核期长**：宿主（微信 / 支付宝 / 抖音）的基础库版本不在本表；本表管的是 npm 侧依赖
+- **小程序包大小限制**：依赖增删都影响 2 MB / 8 MB 包限制；钉版本帮助定位"哪次升级把包撑爆了"
+
+## policy 三档
+
+policy 语义与 [tech-stack-server.md](tech-stack-server.md) 一致。小程序场景常用 `minor` + 严选第三方包。
+
+## 宿主基础库
+
+- 微信：`miniapp/project.config.json` 中的 `libVersion` 是宿主版本，非 npm 依赖；不进本表
+- 自定义组件库（如 vant-weapp）：进本表，policy 标 `minor`
+
+## 关联
+
+- 编码规范：[coding-style-typescript.md](coding-style-typescript.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/tech-stack-mobile.md.eta

@@ -0,0 +1,36 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 移动端技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **应用商店审核失败回溯**：移动端经常因第三方 SDK 更新触发审核拒绝；版本钉死能精确定位
+- **多设备一致性**：CI 与开发机装出同一份依赖
+- **离线场景**：移动端不像服务端能随时回滚镜像，钉版本是唯一保险
+
+## policy 三档
+
+policy 语义、调整流程，与 [tech-stack-server.md](tech-stack-server.md) 一致。
+
+## 移动端特有的考虑
+
+- iOS 系统 API / Android SDK 不归本表管，由 `mobile/ios/Podfile` 与 `mobile/android/build.gradle` 中的对应版本约束
+- React Native / Flutter SDK 主版本升级常涉及原生模块重新链接；务必标 `major-only`
+- 推送、地图、支付 SDK：标 `major-only`（合规要求强约束）
+
+## 关联
+
+- 编码规范：[coding-style-<%= it.standards.language %>.md](coding-style-<%= it.standards.language %>.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/tech-stack-server.md.eta

@@ -0,0 +1,50 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 后端技术栈钉版本表
+
+> 这个文件的 **frontmatter 是机器真值**：CI 中的 `governance-lint` 会把上面 `dependencies` 数组与 `<%= it.standards.manifestPath %>` 的实际版本逐条对比。
+>
+> 本文件正文是**为什么**这样选 + **如何调整**。机器无法回答这两个问题。
+
+## 为什么钉版本
+
+- **审计可追溯**：哪天升级、为什么升级、谁拍板，都留在这个文件的 git 历史里
+- **可重现构建**：六个月后回到这个 commit，依赖能装出同一棵树
+- **AI 不擅自升级**：scaffolder 的 governance-lint 把"未走 PR 的 minor / major 漂移"当作 CI 失败
+
+## policy 三档
+
+| policy | 含义 | 何时使用 |
+|--------|------|----------|
+| `free` | 任意漂移都不报 | 工具链辅助包（如类型 stub），版本变化不影响业务 |
+| `minor` | minor / patch 漂移 → warning；major → error | 默认。绝大多数 runtime 框架与库 |
+| `major-only` | 任何漂移（含 patch）→ error | 安全敏感库（加密、token 验证、SSO） |
+
+## 调整流程
+
+1. 改 `<%= it.standards.manifestPath %>` 中的版本（或让包管理器自动 bump）
+2. 同 PR 改本文件 frontmatter 的对应行；这是**双写**有意为之，让 PR review 必须看到版本变化
+3. CI 中 `governance-lint` 验证两边一致；不一致就阻断
+4. PR 描述中说明：升级动机（功能 / 安全 / 性能）+ 兼容性影响
+
+## 何时**不**钉
+
+- 仅开发期使用的 lint / format / 测试工具：可以放在 `devDependencies` 但**不**进本表
+- 容器基础镜像版本：在 `deploy/Dockerfile` 里钉，本表不重复
+- 系统包（apt / yum）：交给运行时镜像维护者
+
+## 关联
+
+- 编码规范：[coding-style-<%= it.standards.language %>.md](coding-style-<%= it.standards.language %>.md)
+- 依赖安全：[../governance/security.md](../governance/security.md)
+- 升级流程模板：参考最近的 PR 历史 `git log --grep="bump"`

package/src/standards/templates/tech-stack-web.md.eta

@@ -0,0 +1,36 @@
+---
+runtime: <%= it.standards.env %>
+language: <%= it.standards.language %>
+packageManager: <%= it.standards.packageManager %>
+manifestPath: <%= it.standards.manifestPath %>
+lastReviewed: <%= it.standards.lastReviewed %>
+dependencies:
+<% for (const dep of it.standards.dependencies) { %>  - name: "<%= dep.name %>"
+    version: "<%= dep.version %>"
+    policy: <%= dep.policy %>
+<% } %>---
+
+# 前端 / Web 技术栈钉版本表
+
+> frontmatter 是机器真值；governance-lint 会把上面 `dependencies` 与 `<%= it.standards.manifestPath %>` 的实际版本逐条比对。
+
+## 为什么钉版本
+
+- **审计可追溯**：升级历史进 git，PR review 看得到
+- **可重现构建**：CI cache 一致；六个月后能装出同一棵 lockfile
+
+## policy 三档
+
+policy 字段的语义、调整流程、不钉的例外，与 [tech-stack-server.md](tech-stack-server.md) 一致。本文件不重复。
+
+## Web 特有的考虑
+
+- React / Vue 的 minor 升级常带 hooks API 改动；新增 `policy: minor` 表示"先发 warning，看到再合"
+- `typescript` 单独列为 minor：tsc 主版本变化几乎一定要改代码
+- bundler（Vite / Webpack）和 polyfill 工具链版本若进 production bundle，必须钉；纯 dev 工具不进本表
+
+## 关联
+
+- 编码规范：[coding-style-typescript.md](coding-style-typescript.md)
+- UI 设计系统：[../05-前端客户端详细设计/ui-design-system.md](../05-前端客户端详细设计/ui-design-system.md)（启用 design 角色或 full 档时存在）
+- 依赖安全：[../governance/security.md](../governance/security.md)

package/src/standards/templates/ui-design-system.md.eta

@@ -0,0 +1,70 @@
+# UI 设计系统
+
+> 这是 UI / 视觉真值的入口。设计稿仍在 Figma；本文件 + `web/src/design-tokens.ts` 是工程侧能消费的版本。
+>
+> governance-lint 的 `GOV.UI.TOKEN_DRIFT` 检查会比对本文件 token 表与 `design-tokens.ts` 的 export 名集合，发现差异即阻断。
+
+## Token 表
+
+下面三类 token 是 design-tokens.ts 的真值；改一项，必须同 PR 改 ts 文件中对应 export。
+
+### 颜色
+
+| name | 值 | 用途 |
+|------|-----|------|
+| `colorPrimary` | `#2563EB` | 主操作按钮、链接 |
+| `colorSurface` | `#FFFFFF` | 卡片 / 模态背景 |
+| `colorTextDefault` | `#0F172A` | 默认文本 |
+| `colorTextMuted` | `#64748B` | 次要 / 辅助文本 |
+| `colorBorder` | `#E2E8F0` | 分隔线 / 输入框边框 |
+| `colorDanger` | `#DC2626` | 错误状态、危险操作 |
+
+### 间距（spacing scale）
+
+按 4px 基线倍数；**禁止**使用任意像素值。
+
+| name | 值 | 用途 |
+|------|-----|------|
+| `space1` | `4px` | 紧凑（图标到文字） |
+| `space2` | `8px` | 表单字段内 |
+| `space3` | `12px` | 默认内边距 |
+| `space4` | `16px` | 卡片内边距 |
+| `space6` | `24px` | 卡片间距 |
+| `space8` | `32px` | 区块间距 |
+
+### 字号（typography）
+
+| name | 值 | 用途 |
+|------|-----|------|
+| `fontHeading1` | `32px / 1.25 / 600` | 页面 H1 |
+| `fontHeading2` | `24px / 1.3 / 600` | 区块标题 |
+| `fontBody` | `14px / 1.5 / 400` | 正文 |
+| `fontCaption` | `12px / 1.4 / 400` | 辅助说明 |
+
+## 组件命名
+
+组件库统一前缀，避免与第三方库冲突：
+
+- `KButton` —— 主按钮 / 次按钮 / 危险按钮三态由 prop 切换
+- `KModal` —— 模态对话框；标题 / 内容 / footer 三槽位
+- `KFormItem` —— 表单单项；label + 控件 + 错误提示
+
+新增组件命名遵循同前缀；超过组件库范围（业务组件）走 PascalCase 不加前缀。
+
+## 调整流程
+
+1. 设计在 Figma 改 token；导出 SVG / PNG 到 `docs/design/figma-exports/`
+2. 同 PR 改本文件 token 表 + `web/src/design-tokens.ts` 中对应 export
+3. CI 跑 `governance-lint`：本表 token 名集合必须等于 design-tokens.ts 的 export 集合
+4. 若故意要让两边不同（极少见），删除本文件，改用其他 token 真值（需要新 ADR）
+
+## 何时**不**用本系统
+
+- 第三方组件库自带的 token：直接用；不要 wrap 一层把它们重命名成 K 前缀
+- 一次性的展示页（活动 banner、营销页）：可以脱离本系统，但不要把脱离的 token 散播到通用组件中
+
+## 关联
+
+- 配色无障碍要求：所有 `colorText*` 与对应 `colorSurface*` 的对比度必须 ≥ 4.5:1（WCAG AA）
+- 设计稿源：`docs/design/figma-exports/`
+- 二进制 Figma 源文件：走 LFS（见 [`docs/governance/assets.md`](../governance/assets.md)）

package/src/templates/docs-skeleton/files/usage-quickstart.md

@@ -35,9 +35,20 @@ npx @wneng/create-keel create my-full \
   --agent rust-desktop --deploy kubernetes --contract rest+events \
   --ai kiro --license apache-2.0 --gitLfs --integrations \
   --ci github --roles qa,field,data,legal-security,marketing,design \
+  --engineering-standards full \
   --yes
 ```
 
+### 0.1.1 工程规范是另一个正交维度
+
+档位决定 *目录与角色* 的启用范围；`--engineering-standards <tier>` 决定 *栈版本钉死、编码风格、模块边界、UI 设计系统* 的生成范围：
+
+| `--engineering-standards` | 启用 | 默认 |
+|---|---|---|
+| `lite` | 仅每语言 `coding-style-<lang>.md` + 对应 lint 配置 | —— |
+| `standard` | + `tech-stack-<env>.md` + `module-boundaries.md` + （multi-app + JS/TS）`dependency-cruiser.config.cjs` | ✓ `--yes` 默认 |
+| `full` | + `ui-design-system.md` + `web/src/design-tokens.ts`（启用 frontend 时） | —— |
+
 **已有项目升档**：
 
 | 升档动作 | 操作 |