create-yss-spec 3.5.2 → 3.5.4

package/template/.pi/skills/ytable-usage/references/table-pagination-examples.md

@@ -0,0 +1,170 @@
+# YTable 列表与远程分页示例
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 标准代码骨架
+
+```typescript
+import type { YTableActionConfig, YTableColumn } from '@yss-ui/components';
+
+/** 列表行数据。 */
+export interface ItemRow {
+  id: string;
+  name: string;
+  status: string;
+}
+
+/** 状态字典。 */
+export const STATUS_OPTIONS = [
+  { label: '启用', value: '1' },
+  { label: '停用', value: '0' },
+];
+
+/** 列表固定列配置。 */
+export const TABLE_COLUMNS: YTableColumn[] = [
+  { type: 'seq', title: '序号', width: 70 },
+  { field: 'name', title: '名称', minWidth: 180 },
+  { field: 'status', title: '状态', width: 120, isTransform: true },
+  { type: 'action', title: '操作', width: 180 },
+];
+
+/** 按组件 Hook 提供的回调创建操作列配置。 */
+export const createActionConfig = (handlers: {
+  onEdit: (row: ItemRow) => void;
+  onDelete: (row: ItemRow) => Promise<void>;
+}): YTableActionConfig => ({
+  width: 180,
+  fixed: 'right',
+  buttons: [
+    { value: 'edit', label: '编辑', type: 'link', click: ({ row }) => handlers.onEdit(row) },
+    {
+      value: 'delete',
+      label: '删除',
+      type: 'link',
+      isConfirm: true,
+      confirmProps: { title: '确认删除该数据吗？', okText: '确定', cancelText: '取消' },
+      click: ({ row }) => handlers.onDelete(row),
+    },
+  ],
+});
+```
+
+## 远程分页 Hook 关键模式
+
+```typescript
+import { ref } from 'vue';
+import type { YTablePagination } from '@yss-ui/components';
+import type { ItemRow } from '../constant';
+
+/** 列表 API 依赖，由当前项目的 Orval 函数适配。 */
+export interface ItemListApi {
+  queryPage: (params: { pageIndex: number; pageSize: number }) => Promise<{
+    list?: ItemRow[];
+    totalCount?: number;
+  }>;
+  deleteItem: (params: { id: string }) => Promise<unknown>;
+}
+
+/** 管理 YTable 远程分页和删除刷新。 */
+export const useItemList = (api: ItemListApi) => {
+  const dataList = ref<ItemRow[]>([]);
+  const loading = ref(false);
+  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
+  const pagination = ref<YTablePagination>({ current: 1, pageSize: 20, total: 0, remote: true });
+
+  /** 查询当前页；错误提示由 mutator 统一处理。 */
+  const loadList = async () => {
+    loading.value = true;
+    try {
+      currentParams.value = {
+        ...currentParams.value,
+        pageIndex: pagination.value.current,
+        pageSize: pagination.value.pageSize,
+      };
+      const result = await api.queryPage(currentParams.value);
+      dataList.value = result.list ?? [];
+      pagination.value = { ...pagination.value, total: result.totalCount ?? 0 };
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  /** 同步 YTable 分页状态并重新查询。 */
+  const handlePageChange = async ({ current, pageSize }: { current: number; pageSize: number }) => {
+    pagination.value = { ...pagination.value, current, pageSize };
+    await loadList();
+  };
+
+  /** 删除后刷新列表；不重复弹出 API 错误。 */
+  const handleDelete = async (row: ItemRow) => {
+    await api.deleteItem({ id: row.id });
+    await loadList();
+  };
+
+  return { currentParams, dataList, loading, pagination, loadList, handlePageChange, handleDelete };
+};
+```
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { YButton, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { createActionConfig, STATUS_OPTIONS, TABLE_COLUMNS, type ItemRow } from './constant';
+import { useItemList, type ItemListApi } from './hooks/useItemList';
+
+/** 列表实例的 API 依赖。 */
+interface Props {
+  api: ItemListApi;
+}
+
+const props = defineProps<Props>();
+const emit = defineEmits<{
+  create: [];
+  edit: [row: ItemRow];
+}>();
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
+const { dataList, loading, pagination, loadList, handlePageChange, handleDelete } = useItemList(props.api);
+const actionConfig = createActionConfig({
+  onEdit: row => emit('edit', row),
+  onDelete: handleDelete,
+});
+
+onMounted(loadList);
+</script>
+
+<template>
+  <div ref="tableAreaRef" class="table-area">
+    <YTable
+      :data="dataList"
+      :columns="TABLE_COLUMNS"
+      :action-config="actionConfig"
+      :loading="loading"
+      :options-map="{ status: STATUS_OPTIONS }"
+      :row-config="{ keyField: 'id', useKey: true }"
+      :height="tableHeight"
+      pageable
+      v-model:pagination="pagination"
+      @page-change="handlePageChange"
+    >
+      <template #toolbar-right>
+        <YButton type="primary" @click="emit('create')">新增</YButton>
+      </template>
+    </YTable>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.table-area {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+```

package/template/.template-spec/agents/README.md

@@ -18,7 +18,7 @@
 | `issue-tracker.md` | Ticket / Spec / triage 在 Local Markdown、GitLab Issues 与 GitHub Issues 间路由的操作约定 |
 | `triage-labels.md` | 标准五态 triage 标签与含义 |
 | `domain.md` | 领域文档读取和维护规则 |
-| `skills-maintenance.md` | Engineering Skills 的安装、升级和验证说明 |
+| `.template-source/agents/skills-maintenance.md`（仅模板源） | 模板源的技能安装、升级和验证说明；项目实例无需此维护文档 |
 | `yss-skill-registry.yaml` | 技能分层、别名与运行时入口（active；不替代锁文件） |
 | `gitlab-workflow-skills.md` | GitLab、MR、CI 和自动 gitworks 的技能配置与使用规则 |
 

package/template/.template-spec/agents/digital-human-roles.yaml

@@ -75,8 +75,8 @@ roles:
     contract_version: 1
     title: YSS 需求经理
     stages: [ stage.plan, stage.spec-architecture ]
-    draft_artifact_ids: [ artifact.plan-record, artifact.spec ]
-    core_skills: [ grilling, domain-modeling, yss-research, competitive-intelligence, grill-with-docs ]
+    draft_artifact_ids: [ artifact.plan-record, artifact.spec, artifact.business-ticket-set ]
+    core_skills: [ grilling, domain-modeling, yss-research, competitive-intelligence ]
     forbidden_skills: [ yss-ui, yss-domain, yss-web-controller, yss-repository, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, yss-frontend-scaffold-generator, implement, tdd ]
     description: >-
       Own Plan language, users, MVP, non-goals, success criteria, test seams, and Spec prose. Propose CONTEXT.md glossary entries. Do not freeze visual prototypes, OpenAPI, or code. Do not guess unconfirmed business rules. Hand off to the orchestrator when the frontier is empty.
@@ -87,7 +87,7 @@ roles:
     contract_version: 1
     title: YSS 产品经理
     stages: [ stage.plan, stage.spec-architecture, stage.product-design, stage.verification-release-retrospective ]
-    draft_artifact_ids: [ artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation-v2 ]
+    draft_artifact_ids: [ artifact.business-ticket-set, artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation-v2 ]
     core_skills: [ yss-design-system, yss-prototype-stage, prototype-review, yss-research, competitive-intelligence ]
     forbidden_skills: [ yss-ui, yss-domain, yss-repository, yss-web-controller, yss-ddd-scaffold-generator, yss-layered-mvc-scaffold-generator, implement, tdd ]
     description: >-

package/template/.template-spec/agents/issue-tracker.md

@@ -1,6 +1,7 @@
 ---
 tracker:
   lifecycle_tracking_version: 1
+  business_ticket_version: 1
   platform: local-markdown
   root: docs/.scratch
   legacy_roots:
@@ -56,7 +57,7 @@ docs/.scratch/<feature>/
 └── issues/01-<slug>.md
 ```
 
-- `parent-ticket.md` 汇总 Spec、设计、契约、门禁、阻塞边和阶段证据。
+- `parent-ticket.md` 保存 Ticket 五态、业务说明、Spec / 设计 / 契约及会签入口，并明确引用实际 checkpoint。阶段、门禁摘要、阻塞与下一工作单元通过 `scripts/lifecycle-status` 按需读取，不另填第二张状态表。批准依据仍在批准记录中。
 - `issues/01-<slug>.md` 等文件是垂直切片或 Wayfinder 子 Ticket；不得把多个 Ticket 合并成一个文件。
 - 每个 Ticket 在顶部附近使用 `Status:` 记录 Matt 五态之一：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
 - 评论和对话追加在 `## Comments` 下；状态变化必须保留原因、证据引用和下一步。
@@ -142,3 +143,11 @@ Ticket 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平
 新初始化默认启用 `tracker.lifecycle_tracking_version: 1`。已有项目的 attach / sync 保留原配置；缺省保持旧模式，按 [阶段工作追踪](../process/stage-tracking.md) 执行 check → plan → apply。
 
 Plan / Spec / Design 的小工作记录在 checkpoint.stage_tracking；独立工作项使用 `work-items/<id>.md`，不占用业务票 / 实现切片的 `issues/`。执行进度只由 checkpoint 保存，父票和 map 引用；阶段工作项不得设置 `ready-for-agent`。
+
+## 业务拆分版本
+
+新项目 business_ticket_version: 1，按 `../process/business-tickets.md` 执行。每票位于功能包 business-tickets/，business-ticket-set.yaml 汇总引用与覆盖；issues/ 保留实现 Slice。缺少版本的旧实例进入兼容诊断，显式迁移前不自动启用；同步保留用户配置。
+
+## 父 Ticket 精简与临时输入
+
+新父 Ticket 使用引用式模板。旧票先保存原文和精确差异，只迁移明确指定文件；发现与 checkpoint 冲突时报告双方值，不修改 checkpoint 或自动裁决。清理规则、外部计划与恢复操作见 [功能资产整理](../process/feature-assets.md)。

package/template/.template-spec/agents/skill-migrations.md

@@ -98,3 +98,18 @@ DDD 脚手架的 Parent 工程约束由 `yss-ddd-scaffold-generator/references/e
 - 独立低保真评审：`prototype-review`
 
 已关闭的 Prototype Evidence schema v1/v2/v3、旧 artifact ID、AntD CLI、浏览器验证和确认记录只读保留。在途 UI 工作迁移到 Prototype Evidence schema v4、Visual Baseline schema v1 与 `artifact.prototype-deliverable` 后再关闭门禁；无 UI 影响不创建空包。不得创建同名兼容目录或删除历史证据。
+
+## 2026-09-28 入口收敛
+
+以下旧 Skill ID 已硬退役：新调用返回 `skill-retired` 和迁移提示，不能自动执行替代入口或改变阶段状态。历史证据只读保留。
+
+| 旧入口 | 承接位置 |
+|---|---|
+| wait-what | 普通解释对话，按文档写作规范或 i-have-adhd 调整表达 |
+| grill-with-docs | 当前生命周期的 work-unit.plan-requirements，保留 Context 校验、对账和退出判定 |
+| to-questionnaire | 当前生命周期外部输入问卷，保留 external-input-required 与答案回流合同 |
+| improve-codebase-architecture | codebase-design 显式架构审计模式及可选 HTML 报告 |
+
+Data Analytics 平台包从本模板及 frontend 分发退出；不卸载用户另装插件。frontend-commit / java-backend-commit 保留专项入口并读取内部 git-commit-core。prototype 仅做逻辑与状态试验；正式 UI 由生命周期产品设计阶段承接。
+
+存量实例先预览同步计划。只按旧版本基线移除未修改的受管文件，用户修改保留并报告冲突；不自动迁移历史审批、问卷或快照。

package/template/.template-spec/agents/yss-skill-registry.yaml

@@ -190,6 +190,10 @@ recipes:
   - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  frontend-commit:
+    - { skill: git-commit-core, type: context-required }
+  java-backend-commit:
+    - { skill: git-commit-core, type: context-required }
   yss-backend-spec-review:
     - { skill: alibaba-java-code-style, type: context-required }
     - { skill: yss-implementation-contract-compiler, type: coordination-only }
@@ -273,6 +277,7 @@ skill_dependencies:
     - { skill: yss-openapi-governance, type: context-conditional, when: regeneration }
 invocation_contract:
   schema_version: 2
+  runtime_metadata_version: 1
   scope: discovery-only
   required_fields: [invocation_mode, trigger_conditions, exclusion_conditions, primary_output]
   allowed_invocation_modes: [user, model, both]
@@ -307,6 +312,46 @@ invocation_contract:
       trigger_conditions: [impact:prototype]
       exclusion_conditions: [no-product-design-impact]
       primary_output: artifact.prototype-deliverable
+    git-commit-core:
+      invocation_mode: user
+      trigger_conditions: [public-commit-entry-dependency]
+      exclusion_conditions: [standalone-task-selection]
+      primary_output: internal-commit-contract
+    frontend-commit:
+      invocation_mode: both
+      trigger_conditions: [frontend-commit-assistance]
+      exclusion_conditions: [no-commit-related-request]
+      primary_output: frontend-commit-guidance
+    java-backend-commit:
+      invocation_mode: both
+      trigger_conditions: [backend-commit-assistance]
+      exclusion_conditions: [no-commit-related-request]
+      primary_output: backend-commit-guidance
+    prototype:
+      invocation_mode: both
+      trigger_conditions: [prototype-request]
+      exclusion_conditions: [production-implementation-request]
+      primary_output: prototype-evidence
+    writing-for-agents:
+      invocation_mode: both
+      trigger_conditions: [agent-document-writing]
+      exclusion_conditions: [unrelated-document]
+      primary_output: agent-document
+    using-git-worktrees:
+      invocation_mode: both
+      trigger_conditions: [authorized-workspace-task]
+      exclusion_conditions: [outside-authorized-scope]
+      primary_output: workspace-guidance
+    yss-skill-source-index-refresh:
+      invocation_mode: both
+      trigger_conditions: [authorized-source-index-maintenance]
+      exclusion_conditions: [outside-authorized-scope]
+      primary_output: source-index-evidence
+    handoff:
+      invocation_mode: user
+      trigger_conditions: [explicit-handoff-request]
+      exclusion_conditions: [no-handoff-request]
+      primary_output: session-handoff
 agent_runtime_roots:
   codex: .codex/skills
   cursor: .cursor/skills
@@ -361,12 +406,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [discovery]
-  - id: grill-with-docs
-    layer: compatibility
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [discovery]
   - id: grilling
     layer: core
     maturity: supported
@@ -391,12 +430,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [lifecycle]
-  - id: improve-codebase-architecture
-    layer: compatibility
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [quality]
   - id: llm-wiki
     layer: core
     maturity: verified
@@ -457,12 +490,6 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [quality]
-  - id: to-questionnaire
-    layer: maintainer-only
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [discovery]
   - id: to-spec
     layer: compatibility
     maturity: supported
@@ -487,12 +514,6 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [setup]
-  - id: wait-what
-    layer: maintainer-only
-    maturity: supported
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [setup]
   - id: wayfinder
     layer: maintainer-only
     maturity: supported
@@ -751,6 +772,12 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [frontend]
+  - id: git-commit-core
+    layer: maintainer-only
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [template-maintenance]
   - id: frontend-commit
     layer: maintainer-only
     maturity: supported
@@ -788,11 +815,6 @@ skills:
     aliases: []
     impacts: [frontend]
 platform_skills:
-  - id: data-analytics
-    root: .codex/skills
-    layer: maintainer-only
-    instance_default_discoverable: false
-    aliases: []
   - id: product-design
     root: .codex/skills
     layer: specialist

package/template/.template-spec/architecture/README.md

@@ -26,33 +26,9 @@
 
 ---
 
-## AI 四种角色
-
-### 方案生成器
-```python
-delegate_task(
-    goal="为'[功能]'生成 3 种技术方案并做 trade-off 对比",
-    context="评估维度：复杂度/安全/性能/扩展性/契合度/开发成本"
-)
-```
-
-### 预审者 — 六维度审查
-```python
-delegate_task(
-    goal="从可扩展性、安全性、性能、可靠性、可维护性、成本六个维度预审此方案",
-    context="每个维度打分 1-5，评分<3 给出替代方案"
-)
-```
-
-### ADR 记录者
-```python
-delegate_task(
-    goal="根据技术讨论记录，自动生成 ADR",
-    context="使用 .template-spec/templates/adr-template.md 模板"
-)
-```
+## 方案比较与审查
 
----
+存在真实取舍时比较候选方案，按业务风险说明依据，不固定方案数量或评分阈值。审查和批准只消费生命周期注册表及流程裁剪规则；本说明不增加架构师签字或进入实现的独立条件。ADR 仅记录难以回滚、非显而易见且存在真实取舍的决定。
 
 ## 六维度审查清单 (39项)
 
@@ -71,7 +47,7 @@ delegate_task(
 
 ## Deep Module 治理
 
-当出现模块难改、测试 seam 不清晰、逻辑散落、Agent 难以理解代码路径时，优先使用 `improve-codebase-architecture` 和 `codebase-design`。
+当出现模块难改、测试 seam 不清晰、逻辑散落、Agent 难以理解代码路径时，优先使用 `codebase-design` 的显式架构审计模式。
 
 落地产物：
 
@@ -82,10 +58,3 @@ delegate_task(
 架构讨论必须使用统一术语：`module`、`interface`、`seam`、`adapter`、`depth`、`leverage`、`locality`。
 
 ---
-
-## AI-Human Loop
-
-```
-需求 → AI 3方案对比 → 架构师选方向 → AI 详细方案
-→ AI 六维预审 → 架构师签字 → ADR 记录 → 进入实现
-```

package/template/.template-spec/design/README.md

@@ -8,7 +8,8 @@
 - `.template-source/design/design-system-sync.yaml`：主模板与可独立分发的战略设计模板之间的共享章节版本与 SHA-256 同步摘要。
 - `.template-spec/design/design.md`：YSS 设计治理、双轨运行时、生命周期和验证说明；不与规范源重复定义 token。
 - `.template-spec/design/tokens/`：随仓库保存的主题、亮色 / 暗色 / 紧凑 token 和 CSS 变量快照，后续实现不得依赖本机 Downloads 目录或原始 Less。
-- 默认工作界面密度：`theme.json` 使用 default algorithm，与 Data Quality 的 32px 控件、14px 正文、20px Card 内距一致；仅显式紧凑模式叠加一次 compact algorithm；暗色紧凑模式组合 dark 与 compact algorithm，禁止重复压缩。
+- 新原型默认浅色 compact，按根 `DESIGN.md` 的命名变体选择桌面、窄屏与 comfortable；生产默认主题及可选 compact 算法与原型密度分别管理。暗色仅保留历史快照入口，未完成当前规范验证。
+- `.template-source/design/preview.html`：模板维护仓内的主题与组件状态展示（不随产品实例分发），支持密度切换和本地演示；原型技能另提供可运行组件展示及五类页面模式。
 
 Token 或组件视觉变体变更必须先修改 `DESIGN.md`，再更新派生快照；治理说明不得复制具体值。业务状态、API、权限和交互验收继续使用 Spec、交互说明及状态矩阵。
 
@@ -25,7 +26,7 @@ Token 或组件视觉变体变更必须先修改 `DESIGN.md`，再更新派生
 - 表单、表格、弹窗、抽屉、步骤流等交互说明。
 - loading、empty、error、readonly、disabled、no-permission、conflict 等状态矩阵。
 - 页面字段、筛选条件、操作按钮和权限规则。
-- 原型交付物默认路径为 `docs/.scratch/<feature>/design/prototypes/index.html`，交付为离线资源包。H1/H2 默认采用 HTML/CSS/JavaScript；H2 的复杂交互影响评审结论时，可按集成说明选择真实 AntD 预构建，接收者无需 Node。真实 Vue 3 + YSS UI/AntDV 组件只在批准后的前端实现和实现还原验证中使用。产出后必须记录 Prototype Evidence schema v4、Visual Baseline schema v1、根 `DESIGN.md` digest 与 Token digest，并获得用户确认。
+- 原型交付物默认路径为 `docs/.scratch/<feature>/design/prototypes/index.html`，交付为离线资源包。高保真 H1/H2 优先采用 shadcn-vue + Vue 3 预构建，React 作者库已移除，旧包仅历史只读，轻量局部修改可用原生 HTML，接收者无需 Node。React AntD 原型生成路线已退役，历史证据只读。真实 Vue 3 + YSS UI/AntDV 组件只在批准后的前端实现和实现还原验证中使用。产出后必须记录 Prototype Evidence schema v4、Visual Baseline schema v1、根 `DESIGN.md` digest 与 Token digest，并获得用户确认。
 
 这些资产用于反推 API 影响、契约草案、OpenAPI 请求 / 响应字段、错误结构、分页筛选、权限状态和前端验收标准。
 
@@ -58,3 +59,7 @@ docs/.scratch/<feature>/design/prototypes/
 docs/.scratch/<feature>/architecture/diagrams/
 docs/.scratch/<feature>/plan/diagrams/
 ```
+
+## 企业工作区原型
+
+新企业页面使用原型技能的 `references/enterprise-workspace.md`；五类 Vue 模式、统一多页工作区和组件状态页由 export-vue-patterns.mjs 导出。密度与应用壳尺寸以根 DESIGN 为准。构建、模型单测与浏览器/人工离线验收分别记录，不能相互替代。

package/template/.template-spec/design/design.md

@@ -35,17 +35,17 @@
 
 ## 原型设计依据的优先级
 
-当前原型以项目根 `DESIGN.md` 为视觉规范源，`.template-spec/design/design.md` 解释治理规则，`.template-spec/design/tokens/*` 是派生实现视图。需要真实 AntD 控件辅助评审时，上游资料只提供组件事实，不覆盖项目规范；在 `prototype-evidence.yaml` 中记录根规范与 Token digest，不把上游默认直接写回项目实现。
+当前原型以项目根 `DESIGN.md` 为视觉规范源，`.template-spec/design/design.md` 解释治理规则，`.template-spec/design/tokens/*` 是派生实现视图。使用 shadcn-vue 或 shadcn/ui 组件辅助评审时，上游资料只提供组件事实，不覆盖项目规范；在 `prototype-evidence.yaml` 中记录根规范与 Token digest，不把上游默认直接写回项目实现。
 
 项目覆盖与官方默认的差异直接读取根 `DESIGN.md` 并用 `design-md diff` 核验；本文件不复制差异值。上游预设色板可以保留其自身颜色谱，但**色板预设 ≠ 品牌 seed**。
 
 Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以根 `DESIGN.md` 为 source visual truth，并用 `.template-spec/design/tokens/*` 复核实际投影；不得回退到上游默认或历史品牌值。执行清单见 `.agents/skills/yss-design-system/references/design-qa-theme.md`。
 
-原型 H1/H2 默认使用 `html-css-js`，以本地 Token CSS 保留 YSS 企业后台视觉语言；复杂交互影响评审结论时可按集成说明选用 `react-antd-prebuilt`。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已有项目中冻结的组件库原型及其事实证据保持只读；模板不再预置 Antdv Next fact pack，也不生成新的 Provider 事实包。
+高保真 H1/H2 优先使用 `vue-shadcn-prebuilt`，`react-shadcn-prebuilt` 仅历史只读，轻量局部修改可保留 `html-css-js`；二者以本地 Token CSS 保留 YSS 企业后台视觉语言。React AntD 原型生成路线已退役。生产实现只在目标工程按 lockfile 核验组件 API；原型阶段不调用 `yss-ui`。已有项目中冻结的组件库原型及其事实证据保持只读；模板不再预置 Antdv Next fact pack，也不生成新的 Provider 事实包。
 
 ### HTML 与生产主题的映射
 
-HTML 直接使用 DESIGN.md 当前默认尺寸与主题 CSS，不要求 ConfigProvider 或组件库算法。生产库若使用 `defaultAlgorithm`、`darkAlgorithm`、`compactAlgorithm`，仍按其版本合同执行，避免把 compact 结果当 seed 再压缩。暗色能力只在派生 Token 和浏览器状态均核验后声明。
+HTML 直接使用 DESIGN.md 中已选择的组件变体与主题 CSS，不要求 ConfigProvider 或组件库算法。新高保真原型默认选择已有紧凑变体，窄屏使用普通控件；既有页面保持当前密度。共享主题与核验规则见 `.agents/skills/yss-design-system/references/prototype-default-theme.md`。生产库若使用 `defaultAlgorithm`、`darkAlgorithm`、`compactAlgorithm`，仍按其版本合同执行，避免把 compact 结果当 seed 再压缩。暗色能力只在派生 Token 和浏览器状态均核验后声明。
 
 ## 设计原则
 
@@ -128,9 +128,9 @@ HTML 直接使用 DESIGN.md 当前默认尺寸与主题 CSS，不要求 ConfigPr
 - 表单、筛选区、工具栏、表格和详情页应优先使用密集但有节奏的布局。
 - 不使用任意 magic number；如确需新增尺寸，应先判断是否要扩展 token。
 
-### 默认密度与可选紧凑密度
+### 原型默认密度与生产主题边界
 
-原型和前端工程默认采用 Data Quality 全局主题：浅色、14px 正文、32px 控件、20px Card 内距，不默认开启 compact。下表仅用于明确选择紧凑模式的页面；紧凑模式消费 `tokens.compact.json`，不得再次压缩。
+新高保真原型默认浅色 compact，桌面使用根 `DESIGN.md` 的命名紧凑控件和 Card 变体，窄屏使用普通控件与窄屏间距角色；正文始终使用 body。comfortable 保留普通变体。既有页面局部修改遵守保持项。生产默认主题与可选算法仍按实现合同消费，不由原型密度推导。
 
 | 场景 | Padding | Margin / Gap | 说明 |
 | --- | --- | --- | --- |
@@ -141,7 +141,7 @@ HTML 直接使用 DESIGN.md 当前默认尺寸与主题 CSS，不要求 ConfigPr
 | 表格 / 列表 | 容器 `0` 或 `spacing.sm` | 工具栏与表格 `spacing.xs` | 表格内部 cell padding 使用组件紧凑规格，不用页面 CSS 逐列覆盖 |
 | Modal / Drawer | `spacing.md` | 内容区块 `spacing.sm`；操作区 `spacing.xs` | 复杂多步流程不塞入 Modal，改用独立页面或 Drawer 分区 |
 
-紧凑模式的计算值以 `.template-spec/design/tokens/tokens.compact.json` 为准，它来自 `.template-spec/design/tokens/theme.json` 的 seed 叠加一次 compact algorithm。业务页面只消费计算后的语义层级，不复制外部样例中的 `.m-*` / `.p-*` utility class，也不再次缩放。
+原型命名紧凑变体不等于生产 `tokens.compact.json` 的完整算法结果；原型仅使用 `DESIGN.md` 派生的角色变量，不应用生产 compact algorithm。生产显式紧凑主题才消费对应计算快照，且只应用一次算法。页面不照抄上游 utility 尺寸。
 
 Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之间优先由父级 `gap` 管理；只有文档流语义或无法使用布局容器时才使用 margin，并仍限定在 `spacing.*` 阶梯内。禁止用负 margin 修补布局。
 
@@ -157,24 +157,13 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 
 ### 圆角
 
-| Token | 值 | 用途 |
-| --- | --- | --- |
-| `borderRadiusXS` | 2 | 极小元素 |
-| `borderRadiusSM` | 4 | 小标签、小控件 |
-| `borderRadius` | 6 | 默认控件圆角 |
-| `borderRadiusLG` | 8 | Card、大容器 / 浮层 |
+控件引用 `rounded.sm/md`，容器引用 `rounded.lg`；具体值仅在根 `DESIGN.md` 维护。
 
 保持“控件圆角小于或等于容器圆角”：控件使用 `rounded.sm/md`，Card 与普通容器使用 `rounded.lg`。更大的 panel 圆角属于局部产品扩展，不作为紧凑型默认值；确需使用时必须先登记规范角色，不能让同一页面任意混用。实现时以根 `DESIGN.md` 与 `.template-spec/design/tokens/tokens.default.json` 为默认基线。
 
 ### 动效
 
-| Token | 值 | 用途 |
-| --- | --- | --- |
-| `motionDurationFast` | `0.1s` | hover、focus、press |
-| `motionDurationMid` | `0.2s` | 折叠、淡入淡出、控件内部状态 |
-| `motionDurationSlow` | `0.3s` | Modal、Drawer 等表层变化 |
-| `motionEaseInOut` | `cubic-bezier(0.645, 0.045, 0.355, 1)` | 默认进出场 |
-| `motionEaseOut` | `cubic-bezier(0.215, 0.61, 0.355, 1)` | 出场 / 展开 |
+消费现有派生 Token 的 `motionDurationFast/Mid/Slow` 与 `motionEaseInOut/Out` 角色，分别用于即时反馈、内部状态与浮层变化；不在治理文档复制数值。
 
 动效规则：
 
@@ -193,7 +182,7 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 | Menu | 选中态使用淡蓝背景 + 主色文本，保证导航位置明确 |
 | Tabs | 激活态使用主色文本 + Provider semantic indicator，不使用背景填充 |
 | Table | 表头使用浅表面色和 600 字重；默认不做斑马纹，hover 再强调行 |
-| Tag | 用于分类标签，不用于关键状态或错误提示 |
+| Tag | 用于分类或已打开页面导航；页面 Tag 激活与关闭动作分开，当前项使用主色浅底和描边。不用于关键状态或错误提示 |
 | Alert | 用于语义反馈，状态由图标、浅色背景和文案共同表达 |
 | Badge | 可表达紧凑状态点，但不能替代可读文本 |
 | Tooltip | 用于补充解释，黑色反相浮层，位置交给框架处理 |
@@ -217,13 +206,13 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 
 | 档位 | 用途 | 技术边界 | 最低验证 |
 |---|---|---|---|
-| H1 `visual-review` | 布局、密度、层级、文案和少量关键交互 | 语义 HTML/CSS/最小 JS 或设计工具导出；无需 Node、package、lockfile 或 AntD CLI | desktop/narrow 非空渲染、项目 Token、console、关键交互、基础键盘/焦点/对比度；zoom/reduced-motion 按影响 |
-| H2 `flow-review` | 主流程、权限、失败恢复、复杂联动和冲突 | 浏览器可运行流程；默认 HTML/CSS/JavaScript 离线资源包，场景可重复触发和重置 | H1 共同证据 + 主流程、关键异常、zoom/reduced-motion；视觉回归按风险 |
+| H1 `visual-review` | 布局、密度、层级、文案和少量关键交互 | shadcn-vue 离线预构建，或轻量原生 HTML/设计工具导出；接收者无需 Node、package、lockfile 或组件 CLI | desktop/narrow 非空渲染、项目 Token、console、关键交互、基础键盘/焦点/对比度；zoom/reduced-motion 按影响 |
+| H2 `flow-review` | 主流程、权限、失败恢复、复杂联动和冲突 | 浏览器可运行流程；主要使用 shadcn-vue 预构建离线资源包，场景可重复触发和重置 | H1 共同证据 + 主流程、关键异常、zoom/reduced-motion；视觉回归按风险 |
 
-- H1 不得为了“显得完整”创建空 `package.json`、lockfile 或 AntD 证据。H2 不得声明真实目标组件已验证。
+- H1 不得为了“显得完整”创建空 `package.json`、lockfile 或空组件证据。H2 不得声明真实目标组件已验证。
 - 原型中识别出的生产组件假设与待验行为写入 `implementation_handoff`，由 `frontend_implementation_plan` 和 `frontend_implementation_verification` 承接；不得在原型阶段引入 `yss-ui`、目标 lockfile 或 Storybook。
 - 新视觉方向、信息架构不确定或有多个合理方案时执行三方案 ideation；复用已批准视觉模式时记录 source visual 与 `not-applicable` 理由。
-- 默认使用 Data Quality 的32px控件与20px Card内距，紧凑模式显式选择；页面 padding、gap、Card 圆角、Card padding 和控件高度必须在浏览器计算样式中可复核。
+- 新原型默认使用根 `DESIGN.md` 的 compact 命名变体，comfortable 可显式选择；页面 padding、gap、Card 圆角、Card padding 和控件高度必须在浏览器计算样式中可复核。
 - Design QA、浏览器验证和视觉目标使用同一视口与同一状态；默认 desktop `1440×900`、narrow `390×844`。
 - Design QA 统一覆盖 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再复制第二份检查清单。
 - 交付包包含所有实际使用的本地资源和 Token 副本，登记摘要；复制到独立目录后以 `file://` 无网络复验。模板结构检查不替代浏览器证据。
@@ -261,16 +250,18 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 表格密集场景应明确移动端替代形态，如卡片列表、关键列优先或详情抽屉。
 - 文字不得溢出按钮、标签、表头、卡片和弹窗。
 
-## 前端实现建议
+## 历史来源与适用实现说明
+
+以下 React AntD 说明仅用于历史来源或明确采用该运行时的生产实现；该原型生成路线已经退役，不能作为新原型指南。生产 Vue/YSS 继续使用自身实现合同与主题映射。
 
-如果前端使用 React + Ant Design：
+如果已批准的生产实现使用 React + Ant Design：
 
 - 使用 `ConfigProvider` 注入 `.template-spec/design/tokens/theme.json` 中的 theme 配置。
 - 默认采用 Data Quality 浅色与 32px 控件；仅显式紧凑模式使用 `compactAlgorithm`；暗色工作界面组合 `darkAlgorithm` 与 `compactAlgorithm`。seed 与计算结果分别从 `theme.json`、`tokens.compact.json` 读取。
 - 组件样式优先通过 Ant Design token、component token、CSS variables 或主题算法表达。
 - 消息、通知、Modal 静态方法应使用 `App`、hook API 或 context holder，避免主题上下文丢失。
 - 暗色模式使用 `darkAlgorithm` 或 `.template-spec/design/tokens/variables.dark.css`，不要手工反转颜色。本轮只同步了暗色的字体栈和圆角 seed；完整暗色色板仍是历史算法结果，启用暗色前应再派生一次。
-- 紧凑模式默认使用 `compactAlgorithm` 或 `.template-spec/design/tokens/tokens.compact.json`，不要逐组件压缩高度；选择紧凑模式的原型交付物按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
+- 紧凑模式默认使用 `compactAlgorithm` 或 `.template-spec/design/tokens/tokens.compact.json`，不要逐组件压缩高度；这不适用于新原型的命名 compact 变体。
 
 H1/H2 原型使用 HTML/CSS/JavaScript：
 
@@ -295,20 +286,24 @@ H1/H2 原型使用 HTML/CSS/JavaScript：
 - 表单字段、筛选条件、表格列、批量操作、详情字段是否能反推 API schema。
 - 主操作是否唯一且清楚，次级操作是否降级。
 - 是否存在硬编码颜色、任意间距、重复自造控件或与系统冲突的交互。
-- 是否覆盖关键响应式断点。
+- 是否覆盖关键响应式断点、实际点击区域及相邻间距；是否验证 Field 错误关联、InputGroup 内层样式、Sheet/Menu 焦点及分页选择一致性。
 - Codex `$design-qa` 是否按项目覆盖对照主色、错误色、背景、文本、圆角和字体栈。
 
-## 后续落地 TODO
+## 当前能力导航与待办
 
-- 将 `.template-spec/design/tokens/theme.json` 作为 Data Quality 默认主题接入原型主题配置。
-- 将 `.template-spec/design/tokens/variables.css` 中的 `--brand-*` 与运行时别名纳入项目 token 管理。
-- 如果项目启用暗色模式，用 `darkAlgorithm` 按新 seed 重派生 `.template-spec/design/tokens/tokens.dark.json`，并补充截图验收。
-- 让 H1/H2 原型适配器默认接入项目 Token，并在浏览器证据中记录实际计算后的 padding、gap、Card 圆角和控件高度。
+- H1/H2 已默认接入根 `DESIGN.md` 派生的本地 CSS、规范及资源摘要；见设计系统技能 `references/prototype-default-theme.md` 与 `references/shadcn-vue-integration.md`。
+- 构建、来源摘要及浏览器计算样式检查已有工具；页面仍须执行适用六轴 QA，不能用工具存在代替结果。
+- 主题与组件状态展示入口：`.template-source/design/preview.html`；不是可批准的产品原型。组件及页面配方见原型技能 `references/component-recipes.md`。
+- 暗色快照保留历史参考入口，未完成当前规范验证。未来启用需按当前 seed 重派生并补齐截图、对比度与交互验收，本轮不执行。
 
 ## HTML 原型补充基线
 
 参见 `.agents/skills/yss-prototype-stage/references/html-prototype-practices.md`。复用现有六轴 QA 与 Visual Baseline，新增能力只补充其执行方式，不另建交接文档。原生语义优先，弹窗与自定义控件的 ARIA 属性必须对应真实键盘/焦点行为。样式采用项目 Token，关键反馈保留可读文本，场景重置后再采集浏览器证据。
 
-## AntD 条件预构建
+## shadcn-vue 主要路线
+
+高保真按原型技能的 `references/shadcn-vue-integration.md` 优先使用 `vue-shadcn-prebuilt`，`react-shadcn-prebuilt` 仅历史只读；简单局部修改可保留原生 HTML。交付格式与视觉权威不变；Vue 作为随包浏览器运行时，作者依赖与构建工具不交付给接收者。
+
+## 企业原型应用壳
 
-高保真默认原生 HTML；简化模拟影响关键评审结论时，按原型技能的 `references/antd-integration.md` 条件使用 `react-antd-prebuilt`。交付格式与视觉权威不变；React 仅作为随包浏览器运行时，作者依赖与构建工具不交付给接收者。
+新企业高保真默认使用根 DESIGN 的 workspace 角色：模块、分组侧栏、可关闭页面 Tag 和流式工作区，标题采用 workspace-title。表单内部保留阅读宽度，详情按选择出现，窄屏使用 Sheet，旧批准页面仍遵守保持项。页面 Tag 使用导航语义及 aria-current，页内视图切换才使用 Tabs；收起导航的图标居中，提示框及箭头使用一致的反相表面。多页缓存仅保留当前文档内存；关闭修改页须确认，场景切换/重置销毁全部临时状态。原型技能 `references/enterprise-workspace.md` 提供作者接口和教学场景；不改变生产默认主题或增加生命周期门禁。