@lark-apaas/coding-steering 0.1.52-alpha.20260916121812 → 0.1.52

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.52-alpha.20260916121812",
+  "version": "0.1.52",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -20,5 +17,8 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  }
+}

package/steering/nestjs-react-fullstack/skills/app-init-feasibility-guide/SKILL.md

@@ -71,7 +71,7 @@ available-agents:
 | 实时多人编辑、毫秒级协同 | 弱实时刷新、提交后同步 |
 | 原生 App、桌面端、浏览器插件 | Web 应用、响应式页面 |
 | 服务端持久写本地文件 | 平台文件服务、数据库、临时 `/tmp` |
-| 服务启动时下载大文件、全量同步或批量迁移 | 采用异步处理，避免阻塞服务启动 |
+| 在 `constructor`、`onModuleInit`、`onApplicationBootstrap` 中执行或直接发起下载大文件、全量同步或批量迁移 | 使用平台支持的独立异步任务或外部触发机制；不得在钩子内用 `void Promise`、异步 IIFE、定时器等方式后台发起 |
 | 无凭证调用受限第三方系统 | 要求用户提供 API、凭证或授权方式 |
 | 自建账号体系绕过平台登录 | 使用平台内置身份与权限 |
 | 多语言 i18n、深浅色主题切换（非平台内置） | 需自行实现并计入工作量；规格中先确认是否必要 |
@@ -113,6 +113,7 @@ available-agents:
 - 角色权限：查看、创建、编辑、删除、导出、配置等操作的分配。
 - 集成点：飞书、多维表格、AI、内网接口、OpenAPI、自动化触发。
 - 边界与限制：不支持的能力、外部依赖、数据权限边界。
+- 启动约束：若有下载大文件、全量同步或批量迁移，规格中明确由平台支持的独立异步任务或外部触发机制执行；不得在 `constructor`、`onModuleInit` 或 `onApplicationBootstrap` 中执行或直接发起，声明为 `async`、使用 `void Promise`、异步 IIFE 或定时器均不符合要求。
 - 交给 Code agent 时标明需要加载的专项 skill（表格、表单、图表、插件、权限、文件、自动化）。
 - 需要 native addon 时：确认它提供覆盖 linux-x64 / glibc 的预编译二进制并记录包名与版本；没有预编译二进制、装的时候要现场编译的不能用。
 

package/steering/nestjs-react-fullstack/skills/coding-guide/SKILL.md

@@ -139,6 +139,11 @@ shared/ # 前后端共享的目录
 - **import 类型前必须确认实际导出**：先读取文件确认类型名称存在且拼写一致，禁止臆造类型名
 - 属性统一 camelCase（禁止 snake_case），server 端 schema 的 snake_case 不应泄漏到接口类型
 - shared 目录是前后端共享文件，**禁止反向引用** `@server/*`、`@client/*` 等路径别名
+- **请求 DTO 中的 shared 字符串联合别名**：`shared/api.interface.ts` 是前后端契约权威。带 `class-validator` 的 NestJS 请求 DTO 字段若对应 shared 字符串字面量联合 `type` alias，不把 imported alias 直接写在 DTO 属性上；改用等价 inline literal union + `@IsString()` + `@IsIn([...])`，DTO class 仍 `implements` shared 请求接口。
+  - ❌ `type!: ExpressionElementType`
+  - ✅ `@IsString()` + `@IsIn(['tile', 'operator'])` + `type!: 'tile' | 'operator'`
+  - **机械核对**：先数 shared alias 字面量个数 N，inline union 和 `@IsIn` 数组都必须恰好 N 个，且每个字面量完全一致；数量或名称不等就是错，不能只写“不得窄于”。
+  - 边界：shared 真实 `enum` 用 `@IsEnum(EnumName)`；嵌套 DTO 用 `@ValidateNested()` + `@Type(() => XxxDto)`；普通对象字段用 `@IsObject()`；Date 转换按 `@Type(() => Date)` 处理。禁止用 `@Type(() => String)` 只为绕过 lint。
 
 ## 代码质量约束
 
@@ -210,6 +215,16 @@ dev server 只代理 `/api`、`/openapi`、`/__innerapi__`（外加 legacy 的 `
 
 另外，`UserSelect` 弹层是**搜索驱动**的：不输关键词时列表为空属预期行为，不是接口挂了。
 
+## 应用访问入口（404 / 白屏先看这里）
+
+沙箱内页面入口、API 入口、NestJS 端口不是一回事，禁止用 `5173/3000/8001/8080` 枚举猜测。
+
+- **看页面 / 白屏 / 交互**：优先用截图、视觉检查或 E2E 工具，并只传相对路径；工具会打开沙箱真实预览入口（E2E 走 8080 nginx/openresty 鉴权代理）。不要用 `curl` 拿 HTML 判断页面是否渲染。
+- **测后端接口**：优先用接口测试工具，只传以 `/api` 或 `/openapi` 开头的业务路径；工具会自动拼 `CLIENT_BASE_PATH`、选择正确 dev 端口，并补 CSRF 与用户身份。
+- **必须手写 curl 调 `/api/*` 时**：打 client dev server，不要打 NestJS `SERVER_PORT`；URL 必须带 `$CLIENT_BASE_PATH`，并同时带 `Cookie: suda-csrf-token=<X>` 与 `X-Suda-Csrf-Token: <X>`（两值字面相等）。漏 basePath 是 404，漏 CSRF 是 403，都不是业务代码 bug，不要为此改 csrf 中间件或给接口加白名单。
+- **不要直连 NestJS 端口**：会绕过 dev server / 网关注入，`x-larkgw-suda-webuser` 缺失后 `userContext.userId` 为空，依赖身份的接口会误判。
+- **判断服务是否启动**：看 `client-devserver` / `server-devserver` 日志的 ready / 编译成功。裸端口访问返回 404 或连不上（只监听 IPv6 等）都不能当服务故障的依据；同一 URL 连续两次同状态码就换排查方向，不要 `sleep` + curl 重试。
+
 ## 质量保障流程
 
 通用提交前检查（代码检查 / 接口测试 / 读日志确认无错误）见系统任务流程约束；本栈具体落点：
@@ -263,10 +278,9 @@ dev server 只代理 `/api`、`/openapi`、`/__innerapi__`（外加 legacy 的 `
 - **三方集成**：调用第三方 API 需在后端实现，使用 @nestjs/axios
 - **能力边界**：服务端不支持文件上传（FaaS 限制），前端用 dataloom SDK 上传，服务端仅保存元信息
 - **环境判断**：`process.env.NODE_ENV === "production"` 表示生产环境
-- **文件系统**：临时文件、下载内容和处理中间产物统一写入 `/tmp` 下的独立目录，用完后清理
-- **启动关键路径**：`bootstrap`、`onModuleInit` 和 `OnApplicationBootstrap` 只做必须的同步装配，不得执行 DDL、全量数据同步、长轮询或无界外部请求。应用应尽早 `listen()`；非关键预热放到后台任务，外部调用必须有超时、错误日志和降级路径
+- **运行时文件系统（CRITICAL）**：生产 FaaS 中 `process.cwd()` 指向只读部署目录 `/opt/bytefaas`；禁止在该目录或项目目录下创建或写入 `uploads`、`logs`、缓存等，也禁止“先写工作目录，失败再回退 `/tmp`”。临时文件、下载内容和处理中间产物必须直接写入 `/tmp` 下的独立目录
 - **服务端运行时资源文件**（字体 / 证书 / 模板 / wasm 等需在运行时读取的非代码文件，CRITICAL — 发布后静默失效根因）：① 必须在 `nest-cli.json` 的 `assets` 中声明（如 `{"include": "assets/<dir>/**/*", "outDir": "dist/server"}`），否则不会进 `dist/` 构建产物；② 路径用 `__dirname` 相对**编译产物**定位（如 `path.join(__dirname, "../assets/...")`），**禁止 `process.cwd()` 相对源码路径**——dev 跑源码能命中、发布跑 `dist/` 会落空；③ 资源缺失或加载失败必须 **fail-loud**（抛错或明确错误日志），禁止 `catch` 后静默返回残缺产物
-- **启动生命周期**：`constructor`、`onModuleInit` 和 `onApplicationBootstrap` 应快速完成，避免在其中下载大文件、全量同步或批量迁移；仅将钩子声明为 `async` 仍会被等待，无法缩短启动时间
+- **启动生命周期**：`bootstrap`、`constructor`、`onModuleInit` 和 `onApplicationBootstrap` 都位于服务启动或就绪关键路径，应快速完成，只做必要且确定的装配、内存初始化和配置校验；不得在其中执行或直接发起 DDL、下载大文件、全量同步、批量迁移、长轮询或无界外部请求。仅将钩子声明为 `async`，或在钩子内用 `void Promise`、异步 IIFE、定时器等 fire-and-forget 写法启动任务，都不算移出启动流程；耗时工作必须由平台支持的独立异步任务或外部触发机制执行
 
 ## 日志约定
 
@@ -368,7 +382,11 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 - **Drizzle raw `sql` 参数不走列 encoder**：绑定 schema 列的 helper 会编码；raw `sql` 的 `${...}` 只是 driver 参数。Date / custom type 进 raw SQL 前先转 driver-safe 标量（时间用 ISO string）或改回 helper；`user_profile` 仍按上一小节专表处理。
 - raw SQL 聚合、`filter (...)`、`CASE WHEN`、窗口函数或复杂 where 涉及 Date / custom type 时，按 `raw-sql-boundary-audit` 审计，并实际调用对应 API 验证 HTTP 200，避免隐藏 500。
 
-- **时间列跨网络后都是 string**：`date` 列 `$inferSelect` 就是 `string`（原样透传，禁止 `new Date()` 包装）；`timestamp` / `timestamptz` 是 `Date`，**必须在 service 出口 `.toISOString()`**。两类在 `shared/api.interface.ts` 中统一声明为 `string`，前端需要 Date 时手动 `new Date(value)`。
+- **时间字段：写库前查 `schema.ts`，别按 SQL 列名猜**（drizzle-date-boundary-v1）。用 `typeof table.$inferInsert` / `$inferSelect` 看这列在 TS 里是 `Date` 还是 `string`——custom type 会改掉默认映射。
+  - 列是 `Date`、DTO 给字符串 → 转成 `Date` 再写，非法值抛 `BadRequestException`，update 保留 `null`。
+  - 列是 `string` → 原样写，别转 `Date`。
+  - 读出 `Date` → 出口 `.toISOString()`；读出 `string` → 原样返回。`shared/api.interface.ts` 里两类都声明为 `string`。
+  - `toDriver` 收得比应用类型宽，但 `.values()` / `.set()` 只认 `$inferInsert`；别靠放宽 custom type 消错。
 
 - **禁止删类型注解消除报错**（`as unknown as T` 同禁）：典型症状是「改完 service，错误跑到 controller 了」——错误没有转移，是校验点被往外推了一层；推到最外层删完，报错归零而契约失守。
 
@@ -627,11 +645,6 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 // ✅ axiosForBackend.get('/api/users') / .post(...) 等实例方法（axiosForBackend 是 axios.create 返回的实例）
 ```
 
-- `axiosForBackend.get<T>()` 等方法的 `T` 是完整 HTTP response body，即 `response.data` 的类型。
-- 调用前核对 controller、service 返回值和 `shared` 类型；信息不足时，依据实际运行响应决定提取层级。
-- 具名 flat body 读取 `response.data`；仅当具名合同明确声明 `{ data: T }` envelope 时，才读取 `response.data.data`。
-- 不要临时添加匿名内联 wrapper 适配提取代码，也不要全局替换或禁止 `response.data.data`；按接口合同提取。
-
 - **前后端联调**：编写前端 API 对接代码前**必须先读取后端接口定义**，禁止对后端接口请求进行兜底和过度封装
 - **全栈项目禁止 mock 数据**：只要有服务端接口就当全栈对待，严禁 mock。纯前端项目（静态展示、无后端）可以使用 mock
 - **提交前检查 mock 残留**：禁止硬编码用户 ID、项目 ID 等 mock 数据。提交前确认无 `"user_xxx"`、`"project_1"` 等占位值

package/steering/nestjs-react-fullstack/skills/design-guide/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: design-guide
+description: 写第一个页面、组件或样式文件之前确定并记录视觉方向：沿用已有设计、遵循用户指定、匹配预置风格，或交给 frontend-design 自行设计。
+steering: true
+steering-topic: frontend_design
+match-template-name: nestjs-react-fullstack
+control-by-feature-ab: true
+hook: SessionStart
+available-agents:
+  - Code
+metadata:
+  display-names:
+    zh-CN: 设计指南
+    en-US: Design Guide
+---
+
+# 设计指南
+
+写第一个页面、组件或样式文件之前，先确定应用要呈现什么样子。设计要有明确特点，并适合当前产品。
+
+仅修改现有应用的数据、功能或局部内容，且用户没有要求调整整体视觉时，沿用已有设计，不重新匹配风格，也不改写已有设计方向。新增页面或组件本身不代表需要换风格。
+
+需要确定新的视觉方向时，先理解产品做什么、给谁使用、最重要的任务是什么，以及用户期望的氛围和使用感受。设计元素可以来自产品相关的材料、工具、物品和常用说法。推断必须有用户需求或已知上下文作为依据，不补写用户没有表达的审美偏好。
+
+## 选择设计方向
+
+按以下顺序判断：
+
+### 1. 遵循用户明确指定的方向
+
+用户点名某个预置风格时，直接采用该风格。用户要求还原或沿用某个参考设计，或已经给出足以确定整体视觉方向的配色、排版与组件形态时，按用户指定执行。
+
+“高级一点”“有科技感”“活泼一些”“偏深色”等属于偏好线索，不是完整方案；“深色背景”“绿色主色”等局部要求需要保留，但仍应在这些要求内继续匹配预置风格或自行设计。截图、附件或产品链接只有在用户明确要求参考其视觉时，才作为视觉方向；只用于提供功能或内容时，不据此判断用户指定了风格。
+
+### 2. 匹配预置风格
+
+用户没有给出完整方案时，不要看到某类应用就固定选择一种风格。先从下面四方面找出 2–4 个都可能合适的预置风格：
+
+1. 页面主要用途：操作、分析数据、阅读内容、填写表单或展示产品。
+2. 用户想要的感觉：冷静或亲和、克制或张扬、明亮或深色、现代或杂志感。
+3. 实际使用情况：频繁操作或沉浸浏览、内容紧凑或留白较多、主要在电脑使用或经常在窄屏使用。
+4. 产品自身特点：所属行业、常见物品、材料、目标用户和常用说法能否自然融入该风格。
+
+索引只帮助初步选择，不表示某类应用只能使用某个风格。同一种应用通常有多个合理候选。比较候选时，先按主要界面机制缩小范围，而不是按行业名称决定：
+
+- 高频操作、表格和表单为主：区分标准组件化软件、温和紧凑的指标工作台、开阔的数据分析画布、绿色轻影的任务与指标面板。
+- 报告、知识和连续阅读为主：区分冷静的纸面规格文档、人文研究编辑界面、杂志式纸张层次、新闻印刷结构。
+- 强视觉展示或沉浸浏览为主：区分深色技术面板、毛玻璃舞台、明暗叙事区块、粗边硬影或漫画拼贴。
+- 轻量查询、填写或个人工具：只有大留白、超大圆角、自然色和稀疏结构确实适合主要操作时，才使用对应的有机方向；需要密集表格或连续高频操作时，回到操作型候选。
+
+在相邻候选之间，按下面的视觉机制完成最后比较；这些差异只解释已有索引，不改变各风格含义：
+
+- 明亮操作与数据界面：区分标准化中圆角组件与完整明暗模式、暖米白细边无影的紧凑指标台、绿色轻影指标卡、开阔浅蓝分析区域、直角蓝线编号结构和工程图纸标记。
+- 深色技术与分析界面：区分绿色终端语法、蓝黑圆角嵌套面板、紫色紧凑直角面板、红色毛玻璃舞台和明暗交替的深红叙事区块。
+- 文档与编辑界面：区分冷灰蓝单栏规格纸、人文奶油研究界面、旋转纸卡杂志层次和黑白新闻印刷结构。
+- 轻量与表达型界面：区分白底超大圆角自然留白、暖黄渐变与深浅卡片、手写纸张、黑白橙粗边硬影和高饱和漫画拼贴。
+
+采用一个风格，需要能说明需求中的哪些特征与该风格的布局密度、组件几何、主要配色关系、排版、材质、交互方式或标志性细节相呼应。清晰层级、熟悉控件、现代、专业、简洁、易用和响应式属于所有合格界面的基础质量，只用于检查可用性，不能单独作为区分预置风格的证据。一个颜色、一个形容词，或登录、保存、增删改查、统计等单个普通功能也不能单独决定风格。
+
+如果多项操作共同决定了主界面的长期结构，例如持续使用的表格与表单、筛选和批量操作、多角色工作区、审批与状态流转、排期与资源分配、看板拖拽，那么由此形成的布局密度、组件形态和交互节奏属于呈现约束，可以作为候选的正向证据；仍需比较相邻候选，不能只按企业应用类别决定。
+
+同一组中的候选如果仍只能用共同的业务用途或基础质量解释，无法用上述视觉或结构证据区分，就使用 frontend-design。否则选择差异证据最具体、同时不影响使用效率的一项；如果最初只找到一个候选，再找一个用途相近和一个感觉相近的候选进行比较，不要随机选择。
+
+选定后，完整读取对应的 `references/<风格英文名>.md` 和 `references/token-mapping.md`。允许根据实际内容调整信息密度、间距、尺寸和局部布局；决定风格辨识度的主要配色关系、核心材质和标志形态应保持一致。需要替换这些主要元素才能适配时，不采用该风格。
+
+### 3. 使用 frontend-design
+
+没有明确贴合的预置风格，或核实完整规格后发现需要替换主要视觉元素才能满足需求时，直接读取 `references/frontend-design.md`，按其中的方法确定产品主题、质感、配色和最有辨识度的设计元素。保留用户已经表达的局部要求和偏好。
+
+frontend-design 只需定下基础设计要素（主题、质感、配色、签名元素），不要在 `design.md` 里展开成预置风格那样的完整规格文档；具体色值、字体、组件样式变量落进主题样式文件，`design.md` 与 `AGENTS.md` 只保留精简概述。
+
+不需要为了召回而选出一个风格，也不需要逐一排除全部预置风格。
+
+## 保存设计方向
+
+命中预置风格时，用 `bash` 工具把你刚完整读取的那个风格文件**复制**成应用根目录的 `design.md`，并在首行加入受管标识 `<!-- miaoda-design-guide: managed preset=<风格英文名> -->`。不要用 `write` 逐字重写整份规格——既浪费上下文，也容易和源文件产生偏差。复制命令示例（`<刚读取的风格文件路径>` 用你实际读取的那个 references 路径替换）：
+
+```bash
+{ printf '<!-- miaoda-design-guide: managed preset=<风格英文名> -->\n'; cat "<刚读取的风格文件路径>"; } > design.md
+```
+
+覆盖前先检查现有 `design.md`：
+
+- 文件不存在时直接生成。
+- 首行是受管标识时，可以用上面的命令重新生成；切换风格时同样用新风格文件完整覆盖。
+- 首行没有受管标识时，将它视为用户文件，不覆盖；停止写入并说明冲突。
+
+frontend-design 自定义方向没有可复制的源文件，只把基础设计要素写进 `design.md`，不要展开成预置风格那样的完整规格。
+
+后续只引用项目中的 `design.md`。先确认 `design.md` 写入成功，再更新 `AGENTS.md`。
+
+需要确定新视觉方向时，在 `AGENTS.md` 中保留唯一一个简短的 `## 设计方向` 章节。已有章节时更新，不重复追加；已有多个同名章节时停止并说明冲突。根据实际情况选择一种格式：
+
+```markdown
+## 设计方向
+
+- 预置风格：`design.md`（<风格中文名>）
+```
+
+```markdown
+## 设计方向
+
+- 用户指定：<一句话说清用户给的方向与来源，如“用户附件设计稿：深蓝主色 + 卡片式布局”>
+```
+
+```markdown
+## 设计方向
+
+- 自定义：产品主题 <一句话> / 质感 <一句话> / 配色 <主色与基础色，给色值> / 辨识度设计 <一句话>
+```
+
+用户点名预置风格时使用“预置风格”格式。完整的自定义视觉方案使用“用户指定”格式。frontend-design 生成的方向使用“自定义”格式。具体颜色和样式变量写入主题样式文件，不写入 `AGENTS.md`。
+
+## 页面适配底线
+
+- 先让桌面宽屏拥有完整的信息层级和合理密度，再设计窄屏重排；不要把桌面端做成放大的手机单列页。
+- 页面宽度要跟随窗口变化并设置最大宽度；网格要能自动增减列数；在内容排不下时切换布局。主要布局不要写死宽高。
+- 窄屏优先改变排列、折叠次要信息和收纳导航，不缩小到不可读；除数据表格等必要区域外，不产生整页横向滚动。
+- 生成持续可见的桌面左侧菜单时，最好增加收起和展开操作，并优先复用模板已有的侧栏组件；用户明确要求固定菜单时除外。
+- 按钮和其他可点击区域要足够大。固定侧栏、悬浮装饰、超大标题和多栏内容在窄屏都要有明确的调整方式。
+
+界面图形和状态标识不使用 emoji，使用项目现有图标或文字。
+
+## 风格索引
+
+索引只概括视觉特征，不限定业务场景。具体规格与例外以对应风格文件为准。
+
+- `phosphor-hud` **赛博光幕**
+  视觉：近黑背景与深灰表面，霓虹绿通过透明度变化建立层级 / 等宽正文、超粗标题、全大写标签与方括号语法 / 主体组件零圆角，细线边框、L 型转角与发光效果 / CRT 扫描线、胶片噪点、终端式标记 / 机械、冷峻、工业化
+
+- `industry` **工业图纸**
+  视觉：冷灰白图纸底与单一钢蓝构成技术色调，深钢蓝仅作分节强调 / Barlow Condensed 压缩标题搭配 Barlow 正文和等宽标记 / 直角发丝线框，卡片与图框可带四角套准十字 / 内容照片双色化、工程编号和制图标记增强识别 / 冷静、工程化、精确
+
+- `cybernetic-vault-terminal` **赛博机库**
+  视觉：深蓝黑画布、藏蓝表面、白色主文字与灰色辅助文字，天蓝和亮蓝用于主要行动 / Inter 中等字重大标题与常规正文，JetBrains Mono 承载小型技术标签 / 24px 圆角卡片与细边框，控件采用约 23px 圆角或胶囊形态 / 紧凑的嵌套面板与突出数值 / 冷峻、理性
+
+- `nexuscore-analytics` **核心分析**
+  视觉：近黑画布与深灰表面，白色主文字、灰色辅助文字，紫色集中于主要行动 / Inter 中等字重大标题与常规正文，JetBrains Mono 承载小型标签 / 8px 圆角卡片与控件，细边框区分嵌套表面 / 紧凑的模块化面板、清晰的信息层级与数值强调 / 冷静、紧凑
+
+- `crimson-frosted-glass` **暗黑毛玻璃**
+  视觉：黑底叠加模糊背景图与渐变遮罩，白色文字、亮红强调 / 超大粗体无衬线标题，紧字距，大数值突出 / 半透明白色毛玻璃卡片，24px 大圆角与细边框，卡片不依赖投影分层 / 透景层次、大幅图卡与数据块组合 / 沉浸、鲜明、具有空间深度
+
+- `nebula-crimson` **深红星云**
+  视觉：白色、浅灰与近黑大面积交替，暗酒红用于品牌区块和重点信息 / 超粗巨型标题与紧字距，全大写宽字距小标签 / 中到大圆角面板，暗区半透明玻璃容器，局部柔和或品牌色投影 / 全幅明暗交替、网格线、局部碳纤维纹理与深红模糊光斑 / 庄重、浓烈、富有叙事节奏
+
+- `dashboard` **陶土净台**
+  视觉：暖米白底、纯白卡片与暖黑文字，陶土橙集中于主按钮和主图表，次级图表采用中性色 / 系统无衬线字体，常规正文与中等字重小标题，大数字收紧字距，小标签全大写宽字距 / 10px 圆角卡片、6px 圆角控件，1px 暖灰边框，无投影 / 疏朗的指标面板与细线表格，以灰度、大小写和字距建立层级 / 温润、干净、克制
+
+- `minimal-jade` **简约翡翠**
+  视觉：浅灰蓝底、纯白卡片、草绿主强调，次级图表系列用灰阶，深绿和红色用于限定的趋势与状态表达 / 无衬线粗体大标题，JetBrains Mono 等宽数字与表格数字对齐 / 12px 圆角白卡、浅阴影，边框悬停时由透明转浅灰 / 卡片轻微上浮，首要图表系列草绿、其余按黑色透明度递减，局部草绿装饰条 / 简洁、清晰、理性
+
+- `metabase` **湖光蓝调**
+  视觉：纯白与极浅蓝平面，深蓝墨字，明亮蓝色用于主按钮和交互焦点 / Lato 人文无衬线字体，粗体标题与常规正文形成清晰层级 / 小到中圆角，1px 半透明中性边框，平铺卡片轻投影，浮层采用更深漫射阴影 / 浅蓝静区、实底蓝主按钮与描边次按钮 / 通透、清爽、平和
+
+- `corporate-blueprint` **蓝图**
+  视觉：冷浅灰画布、白色卡片、深蓝主强调，图表以蓝色深浅层级为主，状态标签保留语义色 / 无衬线大标题与小号全大写宽字距标签，数值列等宽对齐 / 主卡片零圆角、顶部 3px 深蓝边线，配轻阴影与细分隔线 / 深蓝渐变头部、斜切几何装饰与编号章节 / 秩序、严谨、精确
+
+- `pm-spec` **规格蓝本**
+  视觉：冷灰蓝底、白色纸面与深墨文字，靛紫用于小面积结构性强调 / Charter 衬线标题与引用，无衬线正文，等宽体承载全大写微标签 / 10px 圆角卡片、1px 细边框，无投影，引用块配强调色左边线 / 单栏纸面文档流、紧凑正文、元信息条与局部分栏信息块 / 严肃、克制、秩序感
+
+- `claude-editorial-research` **陶色书卷**
+  视觉：暖奶油画布、米色卡片与暖近黑产品面，陶土珊瑚用于主按钮和强调色块 / 常规字重衬线展示标题配负字距，人文无衬线正文，代码采用等宽体 / 中等圆角、发丝边框，层次主要来自表面色差，投影稀疏 / 奶油与深色表面交替，整块珊瑚强调卡与深色代码窗 / 温和、沉思、社论感
+
+- `digital-e-guide` **暖陶刊物**
+  视觉：暖陶粉径向渐变背景，奶油纸卡与暖黑文字，马克红主强调、暖橙少量辅助 / Cormorant 大衬线标题与斜体强调，DM Serif Text 衬线正文，等宽体承载元信息 / 4px 微圆角纸卡、长柔阴影与发丝分隔线 / 纸卡交替微旋，双栏正文、外缘引文卡与圆贴纸形成摊开杂志的层次 / 温暖、文艺、印刷感
+
+- `broadsheet` **新闻大报**
+  视觉：纸白与近黑墨色为主，青、洋红和工艺黄只作克制点色 / Source Serif 4 衬线字体贯穿标题、正文和控件，主要靠字阶与留白建立层级 / 1–4px 微圆角、细线分隔，卡片仅用于真正离散的条目 / CMYK 套印偏移、网点图像和印版标记形成新闻印刷签名 / 理性、编辑感、公共信息气质
+
+- `organic-minimalism` **有机极简**
+  视觉：纯白画布与浅暖灰绿表面，柔和石灰绿强调激活态、按钮和结果 / 简洁无衬线排版，标题与数值通过字重和字号区分 / 40–48px 超大圆角主卡片，极淡边框与浅阴影 / 大留白、极简线性图标、稀疏装饰 / 自然、轻盈、松弛
+
+- `warm-elegance` **暖调精致**
+  视觉：暖米、暖灰与暖黄渐变背景，白色卡片与深灰黑反转区，黄色点缀主行动和活跃信息 / 无衬线标题与正文，轻字重大数值、等宽辅助数据，局部斜体小标签 / 32px 主卡片与 24px 深色嵌入卡片，浅区轻投影，深区更强投影与局部光晕 / 深浅卡片对比，纤细胶囊柱图、环形进度与磨砂玻璃标签 / 温暖、柔和、安心
+
+- `flowbite` **Flowbite**
+  视觉：白色与浅灰表面、深灰标题，蓝色主按钮和链接，支持对应暗色配色 / Inter 无衬线排版，超粗大标题配紧字距，正文常规字重 / 规整中圆角，以 8px 为主，1px 浅边框与轻投影 / 实底蓝按钮、浅蓝徽章、浅灰输入框，组件形态统一 / 清晰、规整、务实
+
+- `handwritten-sketch` **手绘草稿**
+  视觉：米黄纸底、白色卡片与墨黑文字，标记笔红、钢笔蓝和便利贴黄点缀 / Kalam 手写标题与 Patrick Hand 手写正文，中文使用系统字体兜底 / 不规则弯曲圆角、3px 墨黑粗边与零模糊偏移硬阴影 / 圆点纸纹、微旋卡片、透明胶带、图钉和波浪下划线，局部黑板反色 / 亲和、轻松、手工感
+
+- `wild-orange` **橙色野性**
+  视觉：纯白画布、黑色文字与粗边，橙色主强调搭配少量浅橙和灰阶 / 粗体大写无衬线标题，Playfair 斜体衬线点缀装饰文字与小数值 / 直角卡片、2–4px 黑色粗边、4–8px 零模糊硬阴影 / 几何装饰圆、橙色横幅、圆形编号，卡片按压式位移与阴影收缩 / 自信、大胆、图形感
+
+- `pop-art` **波普艺术**
+  视觉：明亮黄色主背景，白色卡片，红、绿、蓝高饱和色块搭配纯黑 / 漫画展示字体、超粗标题与醒目标签，中文使用无衬线兜底 / 粗黑描边、零模糊偏移硬阴影，大圆角卡片与胶囊按钮搭配直角色块 / 半色调网点、轻微倾斜的拼贴标题、按压位移交互 / 热烈、直接、漫画感
+
+这份列表只用于初步选择。选定后，颜色、圆角、字号、组件样式和例外情况一律以对应风格文件为准。

package/steering/nestjs-react-fullstack/skills/design-guide/references/broadsheet.md

@@ -0,0 +1,311 @@
+---
+version: alpha
+name: broadsheet
+name_zh: 新闻大报
+description: 网页新闻纸风格：纸白底、Source Serif 4 衬线字与近黑墨色构成主体，青与洋红仅作克制点色；页面层级主要依靠字阶和留白，图像可使用 CMYK 套印偏移与网点处理。
+colors:
+  bg: "#f3f2f2"
+  surface: "#eae9e9"
+  text: "#201e1d"
+  accent: "#0088b0"
+  accent-dark: "#006786"
+  accent-2: "#d6006c"
+  process-yellow: "#edbb00"
+  neutral-dark: "#2d2b2b"
+typography:
+  heading:
+    fontFamily: "'Source Serif 4', 'Noto Serif SC', 'Songti SC', system-ui, serif"
+    fontWeight: "600"
+  body:
+    fontFamily: "'Source Serif 4', 'Noto Serif SC', 'Songti SC', system-ui, serif"
+    fontSize: "15px"
+    lineHeight: "1.5"
+  h1:
+    fontSize: "42px"
+  h2:
+    fontSize: "32px"
+  h3:
+    fontSize: "25px"
+spacing:
+  space-1: "5px"
+  space-2: "10px"
+  space-3: "15px"
+  space-4: "20px"
+  space-6: "30px"
+  space-8: "40px"
+rounded:
+  sm: "1px"
+  md: "2px"
+  lg: "4px"
+components:
+  primary-button:
+    background: "{colors.accent}"
+    color: "{colors.bg}"
+    fontFamily: "{typography.heading.fontFamily}"
+  card:
+    background: "{colors.surface}"
+    description: "仅用于真正离散的条目，不作为页面布局容器"
+  cmyk-image:
+    description: "CMYK 分色印版错位叠印与网点处理；完整结构和依赖见来源规格"
+anchors:
+  - id: paper-and-ink
+    type: token
+    desc: 纸白底与近黑墨色形成新闻纸基调
+  - id: serif-everywhere
+    type: token
+    desc: 标题、正文与界面控件统一使用衬线字族
+  - id: restrained-process-colors
+    type: pattern
+    desc: 青与洋红只作小面积点色，同一组件不同时出现
+  - id: whitespace-hierarchy
+    type: pattern
+    desc: 页面结构主要依靠字阶与留白，不依赖框盒
+  - id: cmyk-registration
+    type: component
+    desc: 图像使用套印偏移分色版与新闻纸网点
+  - id: square-paper-components
+    type: component
+    desc: 组件圆角接近零，维持印刷纸面感
+gaps:
+  - 原始 styles.css、print-plates.js、_ds_bundle.js 与模板资产未随 markdown 提供；CMYK 签名效果的完整滤镜代码无法从二手描述还原，接入时需使用来源资产。
+  - 暗色模式未定义。
+exceptions:
+  - 工艺黄仅用于 CMYK 分色、印版数字等印刷处理，不进入正文或界面 chrome。
+  - 卡片仅用于真正离散的列表条目，不作为页面结构容器。
+---
+
+## Overview
+
+网页上的新闻纸：纸白、墨色、衬线字阶和通透留白构成主体，青与洋红作为印刷点色，CMYK 套印图像提供签名视觉。
+
+## Colors
+
+页面使用 {colors.bg} 纸底与 {colors.text} 墨色；{colors.accent} 和 {colors.accent-2} 小面积点色，同一小组件只使用其中一种。段落级青字使用 {colors.accent-dark}。
+
+## Typography
+
+@import url('https://miaoda.feishu.cn/fonts/css2?family=Noto+Serif+SC:wght@400;600&family=Source+Serif+4:ital,wght@0,400;0,600;1,400&display=swap');
+
+HARD REQUIREMENT：字体加载与字体族分工禁止替换。标题、正文和界面 chrome 均使用 {typography.heading.fontFamily}；中文多行标题行高不低于 1.05，正文不低于 1.5，中文负字距归零。
+
+## Layout
+
+内容左对齐并保留宽松右侧留白，主要依靠字号层级和间距组织，不用卡片或分割线搭建页面结构。
+
+## Elevation & Depth
+
+使用源规格的墨色调柔投影；页面结构主要依靠留白，离散条目需要分层时才使用投影。
+
+## Shapes
+
+圆角接近零，保留纸张与印刷物的硬朗边缘；图片可使用 CMYK 套印偏移和网点处理。
+
+## Components
+
+按钮、标签、原生表单、离散条目卡片、表格和对话框的精确规格见下方“来源规格”。CMYK 图像依赖来源中的 print-plates.js 与滤镜资产。
+
+## Hard Rules
+
+- 同一小组件只使用青或洋红中的一种。
+- 正文青色使用 {colors.accent-dark}；工艺黄只进入印刷处理。
+- 页面结构由字阶与留白组织，卡片仅承载真正离散的条目。
+- Source Serif 4 真斜体随正文字重加载，不使用合成斜体。
+
+## Exceptions
+
+- 工艺黄只用于 CMYK 分色、印版数字等印刷处理。
+- 真正离散的列表条目可使用 surface 卡片与源规格投影。
+
+## Source Specification
+
+以下内容从用户提供的原始 design.md 原样保留，仅将标题层级下调以纳入 DSM v1 单文件结构。
+
+### 一句话定位
+
+网页上的新闻纸。纸白底上全篇 Source Serif 4 近黑墨色，四色印刷的青与洋红作为**点色**小面积、克制地用（印刷处理里再补一个工艺黄）。页面结构**不用框、不用分割线**——层级只来自衬线字阶和留白。唯一印线的地方是头版活件：landing 上日期栏两侧的粗-细线对，满墨强度。图片按自己的**套印偏移印版**输出。
+
+---
+
+### 1. 颜色
+
+#### 基础角色
+
+| Token | 值 | 用途 |
+| --- | --- | --- |
+| `--color-bg` | `#f3f2f2` | 纸白底 |
+| `--color-surface` | `#eae9e9` | 卡片 / 面板填充 |
+| `--color-text` | `#201e1d` | 墨色正文 |
+| `--color-accent` | `#0088b0` | 青 —— 交互元素专用 |
+| `--color-accent-2` | `#d6006c` | 洋红 —— 更罕用的第二点色 |
+| `--color-process-yellow` | `#edbb00` | 第三道工艺墨，**仅印刷处理**用（CMYK 分色、印版数字）；正文与界面 chrome 永不取它 |
+| `--color-divider` | `text` 16% 混合 | 1px 细线 |
+
+**双点色，但不许同框**：一个小组件里不能同时出现青和洋红。
+
+#### 色阶（OKLCH 同一感知明度轴，同 step 视觉重量一致）
+
+**Neutral** `#f8f4f4` · `#eae7e7` · `#d7d3d3` · `#bab6b6` · `#9b9797` · `#7d7979` · `#605d5d` · `#444141` · `#2d2b2b`
+
+**Accent（青）** `#e9f8ff` · `#cbeeff` · `#99e0ff` · `#62c5ee` · `#38a6cf` · `#1186ac` · `#006786` · `#004961` · `#0a303e`
+
+**Accent-2（洋红）** `#fff1f4` · `#ffdee6` · `#ffc0d0` · `#ff90b1` · `#ff458e` · `#d82071` · `#aa0b56` · `#790e3d` · `#4b1528`
+
+用法规则：
+- 100–300 → 浅色填充、hover 底、细边框
+- 500 → 该角色基准
+- 700–900 → 浅色填充上的文字、按下态
+- 优先取色阶 step，不要临时 `color-mix()`
+
+#### 对比度红线
+
+accent 对纸底只到 **3:1** —— 够图标、大字号、界面 chrome，**不够正文**。段落级青字必须用 `--color-accent-700`（`#006786`）。
+
+---
+
+### 2. 字体
+
+| Token | 值 |
+| --- | --- |
+| `--font-heading` | `"Source Serif 4", system-ui, sans-serif` |
+| `--font-heading-weight` | `600` |
+| `--font-body` | `"Source Serif 4", system-ui, sans-serif` |
+
+单一字族，字重 400 / 600 分层，**真斜体按正文字重载入**（引言和强调走衬线的斜体声音，绝不用合成倾斜）。
+
+从 Google Fonts 载入：`Source+Serif+4:ital,wght@0,400;0,600;1,400`
+
+#### 字号阶梯
+
+| 元素 | 字号 | 备注 |
+| --- | --- | --- |
+| h1 | 42px | |
+| h2 | 32px | |
+| h3 | 25px | |
+| h4 | 20px | |
+| h5 | 16px | |
+| h6 | 13px | **全大写**，letter-spacing 0.08em |
+| body | 15px | |
+| figcaption | 11px | text 55% |
+| `.card-title` | 17px | heading 族 600 |
+| `.card-kicker` | 10px | 大写，ls 0.1em，青色 |
+| `.btn` / `.input` | 14px | 刻意同字号——注册行里两者并排 |
+| `.tag` | 11px | |
+| `.table th` | 11px | 大写，ls 0.08em，text 60% |
+
+**不许为界面 chrome 引入无衬线字**——衬线本身就是 chrome。
+
+---
+
+### 3. 间距与圆角
+
+密度 **1.25×**（宽松，已烘进变量）：
+
+```
+--space-1: 5px    --space-2: 10px   --space-3: 15px
+--space-4: 20px   --space-6: 30px   --space-8: 40px
+```
+
+圆角几乎为零：`--radius-sm: 1px` / `--radius-md: 2px` / `--radius-lg: 4px`
+
+**不许压缩这套通透的间距**。
+
+### 4. 阴影
+
+```
+--shadow-sm: 0 1px 2px  (#2d2b2b 14%)
+--shadow-md: 0 3px 10px (#2d2b2b 16%)
+--shadow-lg: 0 12px 32px (#2d2b2b 22%)
+```
+
+墨色调柔投影，已针对纸底调过。工具类 `.elev-sm / -md / -lg`。不要自造 box-shadow。
+
+---
+
+### 5. 布局方向
+
+- **左对齐、不对称**：标题齐左，内容贴左边缘，留白留在右侧
+- **区块之间只用留白**，不用分割线、不用卡片
+- deck 分节页 = 印版的打样余白：**页面保持纸白**（本系统没有深色面**）**，靠印刷活件承担断点——右侧一片套印偏移的网点场、`.cmyk-num` 印版数字、十级黑白灰梯、八格色标、一个星形套准标
+- 多数幻灯片把第一笔墨锚在同一个左上角落点，真正的套准标记落在纸张边缘
+
+### 6. 图像处理
+
+| 类名 | 说明 |
+| --- | --- |
+| `.cmyk` | **主打处理** —— 照片印成四张套印偏移的分色版。结构：`figure.cmyk` 内五份同图，第一份作布局尺子（`opacity:0`，保留在无障碍树里承载 alt），其余四份分别标 `.sep-c/.sep-m/.sep-y/.sep-k`；分色由 `print-plates.js` 的 SVG `feColorMatrix` 实时抽取，错开数像素后 multiply 叠到纸底，最后过一层 3px 网点 |
+| `.cmyk` + `.print` | 单图版本：`figure.cmyk > .print > image-slot`，用一个复合滤镜 `#sep-all` 处理可替换的单张图。hover 时印版回套准（印刷工在灯台上验套准），reduced-motion / 触屏下退化为直接切到清晰原图 |
+| `.cmyk-num` | 印版数字：**只三版 C/M/Y，没有黑版** —— 暗部完全来自三色 multiply 叠加，边缘毛刺就是套印漂移。结构：`.cmyk-num` 内一个 `.paper` span（纸白，用偏移 text-shadow 拼出字形并集）+ 三个 `.plate` span；自带 `--cmyk-num-ground` 兜底纸底 |
+| `.halftone` | 简版新闻纸网点（`grayscale(.35) contrast(1.15)` + 3px 径向网点 multiply），**给界面截图用** |
+
+`.cmyk` 依赖 `print-plates.js` 的 filter defs 在文档里。模板页通过编译好的 `_ds_bundle.js` 自动拿到；直接 link `styles.css` 的页面要自己在样式表旁加 `<script src="print-plates.js"></script>`（data-URI 滤镜引用在 Chromium 下不成立，外部文件引用跨引擎不可靠）。
+
+### 7. 组件
+
+| 类名 | 说明 |
+| --- | --- |
+| `.btn` + `.btn-primary / -secondary / -ghost / -icon / -block` | primary 是实心青填充，文字 `--color-bg`；字体用 heading 族 600 / 14px；`.btn-icon` 36×36 |
+| `.tag` + `.tag-accent / -accent-2 / -neutral / -outline` | 色阶染色小标签（100 底 + 800 字） |
+| `.field` + `label` / `.input` / `.radio` + `.dot` / `.seg` + `.seg-opt` | 原生元素表单，无脚本。`.input` 36px 高、surface 底、caret 用青；placeholder 明确定为 text 65%（实测 4.8:1，浏览器默认灰过不了小字 4.5:1） |
+| `.card` + `.card-kicker / -title / -body / -meta`；`.elev-sm/md/lg` | surface 填充卡。**只用于真正离散的条目**（如列表项），绝不用来搭布局 |
+| `.nav` + `.nav-brand` | 顶栏，`border-bottom: none`（刻意） |
+| `.table` | 大写细字表头 + 8% 墨行线，hover 行底 4% |
+| `.dialog-backdrop` + `.dialog`（`-title / -body / -actions`） | 最高层模态 |
+| `.hr` | 1px 细线，存在但本系统偏好留白——**避免使用** |
+| `.text-muted` | text 55% |
+
+#### 交互态（已内建，不要逐页重写）
+
+- `.btn-primary` hover → `--color-accent-600`；active → `--color-accent-700`
+- `.btn-secondary` hover → text 7%；active → 14%
+- `.btn-ghost` hover → 青 10%；active → 18%
+- `.input:hover` → 边框 text 45%；`:focus-visible` → 青边框，`outline-offset: 0`
+- `.radio input:checked + .dot` → 青填充 + `inset 0 0 0 4px var(--color-bg)` 做出内圈
+- `.seg-opt:has(input:checked)` → 青底 + 纸色字
+- 键盘焦点：`:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px }`
+- `::selection` → 青 30%
+- disabled → `opacity: 0.45` + `cursor: not-allowed`
+- `a` → 青，`text-underline-offset: 3px`；`.nav a:hover` / `[aria-current=page]` → 青
+
+### 8. 图标
+
+Phosphor（phosphoricons.com），**统一用 duotone 字重**。
+
+---
+
+### 禁止清单
+
+1. 用线、边框或框盒搭页面结构 —— 页面是一张摊开的大报
+2. 同一个小组件里同时用青和洋红
+3. 压缩间距（密度 1.25× 是刻意的）
+4. 为界面 chrome 引入无衬线字
+5. `.card` 当布局容器
+6. `.hr` 当主要分隔手段
+7. 正文级文字用 `--color-accent` 本值（要用 `-700`）
+8. 工艺黄出现在正文或界面 chrome 里
+9. 合成斜体（用真斜体）
+10. 硬编码 hex / 字体名 / px（token 里已有的）
+
+### 接入方式
+
+```html
+<helmet>
+  <link rel="stylesheet" href="_ds/broadsheet-fed8f2ec-b6d6-4630-b717-2d074781ac94/styles.css">
+  <script src="_ds/broadsheet-fed8f2ec-b6d6-4630-b717-2d074781ac94/_ds_bundle.js"></script>
+</helmet>
+```
+
+组件直接在模板里挂载：
+
+```html
+<x-import component-from-global-scope="Broadsheet_broads.Button" hint-size="auto,40px">Label</x-import>
+```
+
+### 可用模板
+
+- `templates/deck/` —— 23 页演示起点：封面、目录、分节页、分栏、四宫格、数据表、SVG 图表、分色印版页、出血图、引言、结尾
+- `templates/landing/` —— 单页落地页（虚构产品 Daybreak，晨间新闻摘要）：衬线 hero、日期栏与索引头、功能分栏、分色照片、注册收尾
+
+## Do's and Don'ts
+
+- Do：按上述 token 与签名组件实现视觉语言，并根据用户内容组织信息。
+- Don't：不要为套用示例而改变用户内容的业务语义。