openyida 2026.9.21 → 2026.9.22-beta.1

package/yida-skills/skills/yida-design/sub_skill/yida-design-plan/references/build-plan-schema.md

@@ -8,8 +8,6 @@
 
 `schemaVersion=2.0` 时，下文中的摘要、索引字段和标准规则可以不在源 JSON 中出现，由 materialize 确定性补齐；补齐后的完整逻辑结构仍遵守本文约束，派生产物完整度不变。
 
-页面导航策略是[紧凑契约中的派生输出](build-plan-compact-schema.md#派生的页面导航策略)：`pages[].navigationPolicy` 仅存在于 PRD 实施交接，不作为本源 JSON 或 pageSpecHandoff 的输入；旧计划同样从导航归属派生。
-
 ## 顶层结构
 
 ```json
@@ -144,12 +142,12 @@
 
 约束：
 
-- 计划生成前先确定应用范围，导航方式与布局按 [导航设计](../../../../yida-design/references/navigation-decision.md) 写入 brief，用户明确要求优先。视觉候选沿用该导航决策，随整体方案确认。其余必要问题必须有 `interactionId` 和 `writeBackPath`。
+- 计划生成前先确定应用范围与导航类型，再选择视觉方向。范围和导航归属不明时可合并询问，导航选项仅为“宜搭原生导航”和“自定义导航”；原生导航即平台导航，顶部、侧边、L 型等布局由 Agent 按场景确定，不进入 `ask_human`。回答后生成遵守导航决策的视觉候选；每个问题必须有 `interactionId` 和 `writeBackPath`。
 - `questionType` 只取 `single_choice`、`multi_choice`、`free_text` 或最终计划使用的 `confirm`，不设置 AI 代填项中间确认类型。
 - 只有宽泛应用名称且缺少模块、场景、任务、流程和可读需求时才问应用范围。
 - 审批、角色权限、字段、首页、看板、页面和常规流程细节不进入 `ask_human`；用户已提供时承接，未提供时基于业务推断并在最终计划统一呈现。
 - 来源不可读时只生成来源补齐问题。
-- 需要视觉比较时提供两个具体方向与一个自由创意选项；自由创意从业务独立推演。选中后原子写入 `visualDirection`、`internal.selectedTheme`、`colorStrategy` 和 `navigationStyle`，自由创意还须补 `visualStyle.creativeDirection` 与显式 Token；未选候选不写入最终 JSON。详见[应用风格模板与自由创意](../../../references/application-style-library.md)。
+- 视觉问题生成恰好三套完整方向；选中后原子写入 `visualDirection`、`internal.selectedTheme`、`colorStrategy` 和 `navigationStyle`，未选候选不写入最终 JSON。
 
 `askhuman` 保留为 `build-plan.json` 的存储字段名；技能动作和用户交互统一称为 `ask_human`。
 
@@ -158,9 +156,9 @@
 `meta.revision` 是四份产物共享的版本标识，`meta.status` 是当前状态，`meta.planState` 记录展示与确认事实。状态更新遵守 [`ask_human` 交互契约](../../../references/ask-human-interaction-contract.md)。
 
 - `draft`：当前版本正在生成或调整。
-- `awaiting_confirmation`：当前版本准备确认；展示成功后写回 `presentedRevision=meta.revision`，不能仅凭 status 判断已展示。
+- `awaiting_confirmation`：当前版本已通过会话摘要和 `build-plan.html` 展示，`presentedRevision=meta.revision`。
 - `confirmed`：用户已在最终确认交互中确认，`confirmedRevision=meta.revision`、`planConfirmed=true`。
-- 未展示草稿补全保留版本；已展示/确认方案实质变化才升版并清空确认。相同内容及素材进度不升版；旧文件缺 planState 时保守升版。
+- 每次影响计划事实的修改都生成新的 `meta.revision`，并清空旧确认信息。
 - 只有 `meta.status=confirmed`、`planConfirmed=true` 且 `meta.revision=presentedRevision=confirmedRevision` 时，应用生成链路才能消费该计划。
 
 ## overview
@@ -309,24 +307,153 @@
 
 ## visualStyle
 
-业务规划复用已确认的视觉选择；字段格式见 [紧凑契约的视觉事实](build-plan-compact-schema.md#视觉事实)。下表区分模型维护的输入与 CLI 派生内容。
-
-| 字段 | 内容与来源 |
-| --- | --- |
-| evidence | 素材或用户要求的证据数组，每项为 type、value、confidence |
-| constraints | 保留 brandColors、preferredTone、forbiddenColors、avoidPatterns、referenceMaterials、accessibilityLevel |
-| forUser.visualDirection | 已选方向的 label、description、source |
-| forUser.colorStrategy | 项目主色、来源与用法；格式沿用紧凑契约 |
-| forUser.navigationStyle | structure=top/side 由业务导航决定；tone=light/dark 与 toneSource=theme_derived 由 CLI 从所选主题模板派生；另含 source、selectionReason |
-| internal.selectedTheme | themeId、source、customText；label、templatePath 和 summary 由主题索引补齐 |
-| forUser.themeProfile | 由选中主题 token、正文规则和项目视觉选择派生的只读摘要 |
-| forUser.pageApplications | 按 pageId 对应实际页面；最终物化必填 firstScreenFocus/primaryAction/layout/responsive 非空字符串与 acceptanceChecks 非空字符串数组，按需补局部差异；visualMemoryApplications 必须为数组，无适用项填 []；记忆点含 name、renderPolicy、target、reason |
-| forUser.iconSystem | 可选，library 为 lucide-react 或 @ant-design/icons，mappings 记录实际语义到具体组件；沿用 brief，未配置才用默认空映射 |
-| forUser.assetStrategy | 页面图片用途、槽位与缺口，沿用[素材交接契约](../../../../yida-image-assets/references/manifest-contract.md)；保留 materialStatus、pages、missingAssets、notes |
-| forUser 的各项 Summary、styleSource、designMdReady | 从主题、项目选择和生成状态派生；已有项目差异保留 |
-| forDesignMd | designTemplate、pagePatterns、themeStrategy 由 CLI 派生，productTopologyApplication 保留项目形态差异 |
-
-逐页 surface、states 和 visualApplication 可保留公共基准并补项目差异；首屏焦点、主操作及位置、布局、响应式与验收必须是当前页具体决定。缺项草稿可预览，最终物化要求补齐，包括旧计划；纯原生页无逐页设计门槛。最终文档格式与索引只按 [公共输出契约](../../../workflow/output-design.md) 执行。
+```json
+{
+  "evidence": [
+    {
+      "type": "user_explicit | brand_guide | logo | website | image_reference | template | inferred",
+      "value": "用户要求整体克制，不要大面积品牌色",
+      "confidence": "high | medium | low"
+    }
+  ],
+  "constraints": {
+    "brandColors": ["#F26B38"],
+    "preferredTone": ["professional"],
+    "forbiddenColors": [],
+    "avoidPatterns": ["large-kpi-cards", "excessive-whitespace"],
+    "referenceMaterials": [],
+    "accessibilityLevel": "AA"
+  },
+  "forUser": {
+    "visualDirection": {
+      "label": "稳重流程型",
+      "description": "强调流程状态、任务处理和异常识别，界面稳定而不沉闷。",
+      "source": "user_selected | user_explicit | material_extracted | ai_inferred"
+    },
+    "themeProfile": {
+      "tone": "<selectedIndexRecord.defaultProfile.tone>",
+      "surfaceStyle": "<selectedIndexRecord.defaultProfile.surfaceStyle>",
+      "contrastLevel": "<selectedIndexRecord.defaultProfile.contrastLevel>",
+      "brandIntensity": "<selectedIndexRecord.defaultProfile.brandIntensity>",
+      "radiusScale": "<selectedIndexRecord.defaultProfile.radiusScale>",
+      "shadowLevel": "<selectedIndexRecord.defaultProfile.shadowLevel>",
+      "iconStyle": "<selectedIndexRecord.defaultProfile.iconStyle>",
+      "motionLevel": "<selectedIndexRecord.defaultProfile.motionLevel>",
+      "colorStrategy": "<selectedIndexRecord.defaultProfile.colorStrategy>"
+    },
+    "styleSummary": "<已选主题与项目色彩策略的摘要>",
+    "styleSource": "用户选择",
+    "colorStrategy": {
+      "source": "user_selected | user_specified | brand_guide | material_extracted | ai_inferred",
+      "primaryColor": "#F26B38",
+      "primaryColorName": "品牌橙",
+      "usage": "用于主操作、当前状态和少量关键数据，不作为大面积背景",
+      "confidence": "high | medium | low"
+    },
+    "navigationStyle": {
+      "structure": "top | side",
+      "tone": "light | dark",
+      "source": "user_selected | user_explicit | material_extracted | ai_inferred",
+      "selectionReason": "高频流程处理需要稳定入口，深色导航加强模块边界。"
+    },
+    "pageApplications": [
+      {
+        "pageId": "sales-workbench",
+        "pageName": "工作台",
+        "visualApplication": "继承已选主题，在不改变页面模式的前提下说明表面、品牌色、主操作和状态如何呈现。",
+        "surface": "状态摘要和任务区使用轻边框表面，不使用大面积悬浮阴影。",
+        "primaryAction": "品牌色只用于主操作和当前选中对象。",
+        "states": "异常和逾期使用独立语义色、图标和文字共同表达。",
+        "visualMemoryApplications": [
+          {
+            "name": "<选中模板中的视觉记忆组件名称>",
+            "renderPolicy": "adapt_existing_slot | prd_match_only | direct | suggest_only",
+            "target": "<PRD 已有内容槽位>",
+            "reason": "<页面内容满足该记忆点内容契约的依据>"
+          }
+        ],
+        "visualMemories": ["<由 visualMemoryApplications[].name 派生>"]
+      }
+    ],
+    "visualMemories": [
+      {
+        "name": "清楚细边框",
+        "rule": "内容表面主要通过边框和明度差分层。",
+        "userValue": "业务区块边界稳定且易扫描。",
+        "failureMode": "只靠极弱阴影导致白色表面混在一起。"
+      }
+    ],
+    "hierarchySummary": "中性背景承托清楚边界的内容表面，阴影只用于必要浮层。",
+    "componentToneSummary": "组件保持克制，品牌色用于关键操作，状态语义独立。",
+    "stateSummary": "空态、加载、错误、禁用、无权限和选中状态都有文字与视觉反馈。",
+    "responsiveSummary": "移动端保持页面规划中的主任务顺序，控件满足触控尺寸。",
+    "iconSummary": "使用统一线性图标体系，具体图标在开发阶段映射。",
+    "assetStrategy": {
+      "materialStatus": "final | draft | none",
+      "pages": [
+        {
+          "pageId": "page-home",
+          "imageNeed": "required | beneficial | none",
+          "reason": "<图片用途>",
+          "slots": [
+            {
+              "slotId": "home.hero",
+              "usage": "hero | background | product | scene | cover | empty-state",
+              "count": 1,
+              "aspectRatio": "16:9",
+              "minSize": "1600x900",
+              "focus": "主体靠右",
+              "objectFit": "cover | contain",
+              "generationAllowed": true
+            }
+          ]
+        }
+      ],
+      "missingAssets": [],
+      "notes": "素材交给 yida-image-assets；缺口保持草稿"
+    },
+    "designMdReady": "已同步生成 design.md，后续 AI 开发读取完整设计契约。"
+  },
+  "internal": {
+    "selectedTheme": {
+      "themeId": "<selectedIndexRecord.themeId>",
+      "source": "user_selected | user_custom | user_explicit | material_extracted | ai_inferred",
+      "customText": ""
+    }
+  },
+  "forDesignMd": {
+    "designTemplate": {
+      "themeId": "<selectedIndexRecord.themeId>",
+      "templatePath": "<selectedIndexRecord.templatePath>",
+      "instanceRule": "完整读取模板，替换项目变量，注入页面模式与页面视觉应用"
+    },
+    "productTopologyApplication": "<根据 experienceTopology、页面范围和前后台边界生成的主题应用说明，不改变页面规划>",
+    "pagePatterns": [
+      {
+        "pageId": "sales-workbench",
+        "mode": "adapted",
+        "id": "compact-workbench",
+        "adaptations": ["增加持续展开的客户与商机上下文区"],
+        "contentRichness": "rich-but-relevant",
+        "mustKeep": ["高频动作显眼", "首屏至少两层信息"]
+      }
+    ],
+    "themeStrategy": {
+      "colorSource": "user_specified | brand_guide | material_extracted | ai_inferred",
+      "colorRoles": ["主色", "辅助色", "中性色", "语义色"],
+      "notes": "主题色策略与页面模式相互独立。"
+    },
+    "componentRules": [],
+    "stateRules": ["hover", "active", "focus", "disabled", "loading", "empty", "error", "no-permission", "selected"],
+    "responsiveRules": [],
+    "qualityGates": [
+      "视觉主题不得改变页面内容、页面模式和信息密度。",
+      "不使用低密大空白工作台。",
+      "不得编造图片 URL。"
+    ]
+  }
+}
+```
 
 ## 结构约束
 
@@ -336,17 +463,11 @@
 - `businessDomain` 决定业务对象与流程，`experienceTopology` 描述项目结构；两者都不排除或绑定视觉主题。
 - `visualStyle.forUser.pageApplications` 与 `pages.customPageDetails[]` 按 `pageId` 一一对应，只记录项目真实存在的自定义页面。
 - 页面视觉应用先消费全应用 Token 和页面已有组件，再匹配视觉记忆点；新计划不维护一份固定页面类型规则表。
-- 1.x 结构中的 `candidateThemes` 与 `selectedTheme` 必须从 [主题索引](../../../templates/design-themes/index.json) 取得；2.0 不保存任何未选候选，模板路径由 `visualStyle.internal.selectedTheme.themeId` 确定性补齐。
+- 1.x 结构中的 `candidateThemes` 与 `selectedTheme` 必须从 [主题索引](../templates/design-themes/index.json) 取得；2.0 不保存任何未选候选，模板路径由 `visualStyle.internal.selectedTheme.themeId` 确定性补齐。
 - `forDesignMd.designTemplate` 必须与 `visualStyle.internal.selectedTheme` 指向同一模板；生成的 `design.md` 不得残留 `{{...}}` 占位符、Token 推导指令、主题 ID、模板名称或模板路径。
-- 主题 ID 仅保存在 2.0 `build-plan.json` 的内部字段，模板路径由主题索引补齐；用户可见 HTML 按 [展示规范](../assets/README.md#需求确认内容范围) 呈现需求确认内容，完整业务与视觉事实仍保留在源文件和执行文档中。
+- 主题 ID 仅保存在 2.0 `build-plan.json` 的内部字段，模板路径由主题索引补齐；用户可见 HTML 完整展示业务和视觉方案，内部主题 ID 与模板路径保留给执行过程。
 - 视觉变化不得改写 `pages`；页面规划变化时允许重新生成 `visualStyle.forUser.pageApplications`。
 - `prd.md`、`design.md` 和 `build-plan.html` 必须来自同一个 `meta.revision`；用户确认后把 `meta.status` 更新为 `confirmed`。
 - 确认生成应用前，`build-plan.json` 是唯一搭建计划事实源。
 - 旧数据中的 `selectedStyleOption`、`pageVisualPlanning`、`firstScreen`、`signatureMoment` 和 `visualAtmosphere` 仅用于渲染兼容；新计划不得继续写入。
-- 输入只有 `themeId` 时，从当前主题索引的对应记录补齐 `templatePath`；ID 不在当前索引中时，返回 Step 2 选择当前可用主题。
-
-### 紧凑区块输入（schemaVersion 2.0）
-
-`blocks` 支持按优先顺序填写 `{name,purpose}` 数组，两项均为非空文本，每个区块只使用这两个键。CLI 将其转换为区块说明，并在省略时派生 contentPriority 和 contentRichness.contentLayers；明确填写的内容原样保留。旧版字符串数组继续沿用原字段。业务验收条件写入 execution.acceptanceCriteria，与按资源生成的通用检查合并去重。
-
-自由创意（`free-creative`）没有模板导航默认值：在 `navigationStyle.tone` 明确填写项目设计的 `light` 或 `dark`，CLI 标记 `toneSource=project_defined`；此路径可通过 patch 调整 tone，并同步配套导航 Token。命名模板仍按模板派生导航明暗。
+- 旧数据只有 `themeId` 时，ID 仍存在于当前索引 → 通过同一记录补齐 `templatePath`；ID 不存在于当前索引 → 返回 Step 2 重新选择当前主题，不凭印象映射旧主题。

package/yida-skills/skills/yida-design/sub_skill/yida-design-plan/references/visual-design.md

@@ -1,58 +1,137 @@
-# Plan 视觉规划与项目设计生成
+# 视觉规划与 design.md 生成规则
 
-Plan 的源事实保存在 `build-plan.json`，CLI 派生最终 `design.md`。内容构成、frontmatter、五章正文、anchor 与检查只按 [公共输出契约](../../../workflow/output-design.md) 执行；本文件仅规定 Plan 输入如何映射，不重复一份输出格式。
+## 用途与边界
 
-## 运行时输入
-
-1. 当前版本计划：项目、页面、业务约束、已选视觉方向、主色与导航。
-2. [共享主题索引](../../../templates/design-themes/index.json) 的已选记录与一份完整主题。选前只读摘要，选后再读全文，不预读候选。
-3. 每个实际自定义页的具体视觉决定、局部差异、特色配方绑定及素材需求。
-
-PRD 决定页面任务、操作和内容优先级；主题决定这些内容如何呈现。视觉生成不增删业务资源，不改写页面模式、内容优先级与业务信息密度。正常设计不读取主题库维护说明。
-
-## 逐页输入
-
-`visualStyle.forUser.pageApplications` 与 `pages.customPageDetails[]` 按 pageId 一一对应。最终物化前，每页至少填写：
-
-| 字段 | 类型与内容 |
-| --- | --- |
-| `pageId` | 对应真实页面的稳定 ID |
-| `firstScreenFocus` | 非空字符串，进入页面第一眼关注什么及突出方式 |
-| `primaryAction` | 非空字符串，真实主操作、所在位置及触发后的反馈，沿用 PRD 的动作 |
-| `layout` | 非空字符串，真实区块的顺序、主次、宽度/比例、列数、对齐与内容增长安排 |
-| `responsive` | 非空字符串，窄屏重排、折叠、工具栏与表格处理 |
-| `acceptanceChecks` | 非空字符串数组，页面视觉与交互的可检查结果 |
-
-`surface`、`states`、`visualApplication` 可补具体项目差异；公共规则由主题供给，不需要逐页复制。CLI 结合业务页面事实，将这些输入呈现为正文八项要点。没有自定义页时保留空数组，不添加页面。
-
-缺少上述决定的旧计划和新草稿仍可预览；生成最终产物时提示准确缺项，补齐后继续，不用“继承主题”占位替代。仅维护草稿不代表 design.md 已就绪。
+本文件供复杂视觉定制时按需查阅。常规规划使用紧凑契约和 CLI 返回的主题上下文。完整主题模板决定视觉设计内容和文档结构；本文件负责选择结果校验、项目事实融合、页面视觉应用和交付检查。
 
-### 特色配方
+```text
+PRD 决定做什么
+页面规划决定内容如何组织
+完整主题模板决定既定结构如何呈现
+```
 
-`visualMemoryApplications` 仅在真实内容满足主题配方条件时填写，每项含 name、renderPolicy、target、reason。使用 `adapt_existing_slot` 或 `prd_match_only` 绑定已有内容；会新增业务能力、字段、对象或虚构数据的建议标为 `suggest_only`，不进入默认实现。没有匹配项就保留空数组，页面仍继承完整基础语言。
+视觉生成保持 PRD 中的页面核心任务、内容优先级、首屏结构、页面模式和信息密度不变。正常生成应用时不读取 [主题模板维护说明](../templates/design-themes/README.md)；该文件只用于维护主题模板库。
 
-配方来自主题实际核心特征、适用条件、使用方式与无匹配时规则，不要求旧版固定字段或旧章节。`visualMemories` 从绑定名称派生，不重复维护。
-
-按 [页面与导航连续性](../../../references/page-continuity.md) 在 pageApplications.layout/responsive/states 写明布局和往返状态；materialize 同步规则到 design.md。导航明暗不决定占位/叠加。
-
-`forUser.iconSystem` 可记录图标库和业务到组件映射，初始化沿用 brief 中的选择；没有配置时才默认 lucide-react 与空映射。图标尺寸和描边等实现规则保留在正文，不复制进定位索引。
-
-## 配色与导航
-
-项目主色写 `forUser.colorStrategy.primaryColor`，使用 6 位 HEX；平台变量覆盖与项目扩展变量都写入 `visualStyle.tokens`，不受模板现有变量数量或 `--oyd-*` 前缀限制。`themeProfile` 是输出摘要，不以修改摘要代替 token。CLI 组织 application-global 与 custom-page 分组，两组都会写入主题 CSS 的 `:root`；可引用已声明的共享变量，不能循环引用或依赖只在某个页面内定义的变量。
-
-逐项核对已选方向承诺的画布、面板、文字、字体和特色强调是否有对应变量；差异由设计者补齐，不能只写在 description/usage 中。物化后按 [共用主题规则](../../../references/application-theme-consistency.md) 对照生成的 CSS，再交给页面作者。
-
-颜色推导与 Fast 相同，直接使用所选主题的公式和项目 token，不增加 Plan 专用染色规则。应用根渐变写 `--pod-app-root-bg-image`；单页渐变与装饰在页面设计中说明作用区域，按 [背景规则](../../../workflow/output-design.md#背景颜色渐变与图片) 实现。
-
-整体配色与主题的冲突按公共输出契约处理。导航和内容界面的明暗分别描述，导航明暗采用所选主题模板的 `navTheme`，既定入口范围保持不变；前台与后台可改变表达强度，但共享基础变量、字体、状态和组件语言。无法保留已选主题核心特征时回到主题选择，不在页面阶段另建主题。
+## 运行时输入
 
-## 物化与交接
+CLI 生成项目 `design.md` 时读取：
 
-CLI 校验主题绑定、解析变量与项目覆盖，生成正文五章，将项目总结、配色和导航合入对应章节；作者编写步骤、模板身份与未解析占位符不进入最终文件。具体规则仅保留一份，frontmatter 的 sceneRecipes/components/states 只保存显式 anchor 定位信息。
+1. 当前版本 `build-plan.json`：项目事实、产品形态、页面规划、视觉证据、项目视觉方向、主题色、导航选择和内部选中主题。
+2. [主题索引](../templates/design-themes/index.json)：校验内部 `selectedTheme`，取得 `defaultProfile` 和模板路径。
+3. 内部选中主题对应的完整模板：作为项目 `design.md` 的设计底稿。
+4. [page-patterns.md](page-patterns.md)：解释各页面已经确定的页面模式。
 
-`build-plan.json`、PRD、设计与 HTML 对应同一 revision。CLI 调用公共 `check-design` 检查格式、变量和引用后，主题 CSS 使用返回的 `outputs.theme`。页面实现只读取最终 PRD 与 design.md；HTML 按 [展示规范](../assets/README.md#需求确认内容范围) 呈现整体风格、主色、导航与需用户补充的素材，详细逐页视觉规则保留在 design.md。
+CLI 完整读取选中的模板，不假设模板的章节、frontmatter 或内容组织方式。主题模板内部结构由模板自身维护。
 
-页面任务变化时同步逐页应用，主题差异变化时更新 tokens；旧输出不能手改后假装与当前计划一致。普通页面设计不重新发起一轮视觉选择提问，只有新证据造成已选方向冲突时才回到选择阶段。
+## 产物关系
 
-自由创意（`free-creative`）没有模板导航默认值：在 `navigationStyle.tone` 明确填写项目设计的 `light` 或 `dark`，CLI 标记 `toneSource=project_defined`；此路径可通过 patch 调整 tone，并同步配套导航 Token。命名模板仍按模板派生导航明暗。
+| 产物 | 面向对象 | 内容 |
+| --- | --- | --- |
+| `build-plan.html` | 用户确认 | 项目视觉方向、色彩策略、导航选择和素材缺口摘要 |
+| `prd.md` | 后续 AI 开发 | 业务、数据、流程、页面任务、内容优先级、页面模式和权限 |
+| `design.md` | 后续 AI 开发 | 完整主题模板的项目实例、组件状态和逐页视觉应用 |
+
+主题 ID、模板路径等实现身份只保存在 `build-plan.json` 内部或物化内存中。最终 `prd.md`、`design.md` 和 `build-plan.html` 不展示主题模板名称、ID、路径或来源。页面实现阶段只读取最终 `prd.md` 和 `design.md`。
+
+## 生成顺序
+
+1. 校验 `visualStyle.internal.selectedTheme.themeId`，并从索引确定性取得模板路径；兼容旧计划时可读取 `forUser.selectedTheme`。
+2. CLI 完整读取该路径指向的模板；模型使用初始化返回的主题上下文。
+3. 以索引中的 `defaultProfile` 为起点，由 materialize 补齐 `themeProfile`；该摘要只读。模型将用户要求、品牌规范和可访问性约束落实为 `visualStyle.tokens`，主题色写入 `colorStrategy`。
+4. 根据 `meta.experienceTopology`、页面范围和前后台边界生成 `visualStyle.forDesignMd.productTopologyApplication`，说明全应用共享主题基础语言、记忆点按真实页面内容使用；该字段不判断主题是否适用，也不增删页面或业务能力。
+5. 保持 `pages.customPageDetails[]` 中的页面模式、内容优先级、首屏结构和信息密度；模型只生成每页 `visualMemoryApplications`，页面基础视觉应用由 materialize 从主题模板补齐。
+6. 根据 `PRIMARY_COLOR` 推导模板要求的 Brand Token 和自定义页主题衍生色；导航背景按 `light → --color-brand1-3`、`dark → --color-brand1-5` 映射。
+7. 由 materialize 在单一位置注入“项目视觉选择”，写明视觉方向、主题色、导航结构、导航明暗、导航背景 Token 和选择依据；不要求所有主题模板预留空字段。
+8. 按模板自身结构写入其他项目事实、页面模式、页面视觉应用和素材状态；模板定义的占位符全部替换。
+9. 保留模板中的视觉 DNA、消费规则、组件规则和交付检查，同时从最终项目文档移除主题 ID、模板名称、路径等内部身份字段。
+10. 将 `build-plan.json`、`prd.md` 和 `design.md` 写入同一个 `meta.revision`，再执行交付检查。
+
+Step 4 不重新发起常规视觉 `ask_human`。页面规划新暴露品牌素材冲突或前后台表达边界冲突时，返回 Step 2 更新视觉选择。
+
+## 页面级视觉应用
+
+每个自定义页面必须在 `visualStyle.forUser.pageApplications` 中有一条紧凑记录：
+
+```json
+{
+  "pageId": "procurement-workbench",
+  "visualMemoryApplications": [
+    {
+      "name": "<模板中的视觉记忆组件名称>",
+      "renderPolicy": "adapt_existing_slot | prd_match_only | direct | suggest_only",
+      "target": "<PRD 已有的指标、分类、进度、图表或其他内容槽位>",
+      "reason": "<该页面内容满足此记忆点内容契约的依据>"
+    }
+  ]
+}
+```
+
+`pageName`、页面模式引用、基础表面、主操作、状态说明和 `visualMemories` 由 materialize 派生。模型只负责把模板记忆点绑定到真实内容，不改写 `contentPriority`、`firstScreenStructure`、`layoutPattern` 或 `density`。
+
+### 全应用继承与逐页生成
+
+1. 原生表单、流程页面和自定义页面共同消费模板 `tokens.application-global` 中的颜色、字体、间距和圆角；自定义页面再消费模板的 `tokens.custom-page`。
+2. 生成器只遍历 `pages.customPageDetails[]` 中真实存在的自定义页面，不预先枚举工作台、列表、表单、详情等全部可能页面类型。
+3. 每页先绑定主题画布、表面、文字、边界、主操作和状态语言，再读取该页的功能区块与真实组件。
+4. 筛选、输入、表格、列表、图表、指标、状态和操作等组件只在页面规划已经包含对应内容时写入 `visualApplication`、`surface`、`primaryAction` 和 `states`。
+5. 页面基础消费完成后，再按“页面级视觉记忆点应用”匹配主题记忆点；没有匹配记忆点的页面仍完整继承主题基础设计语言。
+6. `{{PAGE_APPLICATIONS}}` 只渲染项目真实页面的应用结果，不输出项目中不存在的页面类型说明。
+
+### 页面级视觉记忆点应用
+
+1. 读取选中模板“视觉记忆点应用策略”中的 `content_contract`、`render_policy`、适配目标和 fallback。
+2. 用当前页面已有的业务内容逐项判断内容契约；匹配时选择 1–3 个主记忆点，无匹配内容时记录空数组，同一页面不要求使用模板的全部记忆点。
+3. `adapt_existing_slot` 和 `prd_match_only` 只绑定 PRD 已有内容；无匹配内容时不渲染该组件，并保留模板配方供后续真实内容使用。
+4. 会新增业务能力、字段、对象或虚构数据的记忆点标记为 `suggest_only`，不进入默认页面实现。
+5. `visualMemories` 由 `visualMemoryApplications[].name` 派生，用于 `prd.md` 和 `build-plan.html` 展示；结构化应用记录用于生成 `design.md`。
+
+## 冲突处理
+
+整体配色选择不能被模板默认灰阶覆盖。`colorStrategy.surfaceTone=brand-tinted` 时，CLI 在 design.md 开头注入项目配色适配，并同步派生浅色表面 token；与下方模板的固定无彩限制冲突时按项目适配执行。保持中性参考用 `theme`，显式 `visualStyle.tokens` 优先，深色表面保留。页面先读项目适配，再读组件配方；不能只消费品牌按钮而漏掉卡片、文字、填充与边界。
+
+按以下优先级合并视觉规则：
+
+```text
+可访问性与真实素材要求
+> 用户明确视觉约束
+> 品牌与参考素材
+> 已选完整主题模板
+> AI 补齐
+```
+
+- 页面任务与主题冲突：保留页面任务和页面模式，调整主题在该页的应用强度。
+- 品牌色与模板示例色冲突：保留品牌色，复用模板的色彩角色和使用策略。
+- 用户要求与模板必须保留特征冲突：返回主题选择阶段，选择更匹配的完整模板。
+- 前后台表达不同：共享主题 Token、字体、图标和状态体系；前台提高品牌强度，后台使用同主题的克制变体。
+
+## build-plan.html 展示边界
+
+`build-plan.html` 只展示用户能判断和调整的视觉结果：
+
+- 一句话视觉主题和确认来源
+- 品牌色或主题色来源与使用强度
+- 表面、对比、圆角、阴影、图标和动效摘要
+- 页面级视觉应用与跨页面视觉记忆点
+- 状态、响应式、可访问性和素材缺口摘要
+
+模板名称、主题 ID、模板路径、模板全文、候选评分和内部实例化过程保存在内部数据中，不进入任何用户可见派生产物。
+
+## 交付检查
+
+- 内部 `selectedTheme` 的 ID 存在于主题索引，物化后的路径与同一索引记录一致。
+- `visualDirection`、`colorStrategy` 和 `navigationStyle` 完整，导航结构与明暗值合法。
+- `design.md` 包含项目视觉选择章节，导航背景 Token 与明暗选择一致。
+- `design.md` 不包含主题 ID、模板名称或模板路径。
+- 物化后的 `themeProfile` 以同一索引记录的 `defaultProfile` 为基础，；用户与品牌的具体 CSS 差异写入 `visualStyle.tokens`，再由 CLI 应用到 `design.md`。
+- `design.md` 没有未解析的 `{{...}}` 占位符、Token 推导指令或无关示例业务数据。
+- `PRODUCT_TOPOLOGY_APPLICATION` 已由产品形态、页面范围和前后台边界生成，且没有改变页面规划。
+- 每个自定义页面都有页面模式摘要和页面视觉应用。
+- 所有页面共享全应用 Token；`PAGE_APPLICATIONS` 只包含项目真实存在的自定义页面。
+- 每条页面视觉应用只消费页面规划中已有的组件和内容。
+- 每个页面只应用满足内容契约的视觉记忆点；无匹配内容时没有虚构指标、分类、进度或图表。
+- 页面视觉应用与 PRD 的内容优先级、首屏结构、页面模式和信息密度一致。
+- 状态覆盖加载、空态、错误、禁用、无权限、选中和移动端。
+- 官网、品牌页和展示页记录真实素材来源或素材缺口。
+- `build-plan.json`、`prd.md` 和 `design.md` 使用同一版本。
+
+具体 token 差异写入 `visualStyle.tokens`（单行字符串值），不能只修改 `themeProfile.radiusScale` 等摘要而期待 CSS 改变。应用主题使用公共模板与 `sample --design-file` 流程；主题 Markdown 模板用于设计规则，不能替代公共 CSS 模板。

package/yida-skills/skills/yida-design/sub_skill/yida-design-plan/references/visual-theme-selection.md

@@ -2,35 +2,49 @@
 
 ## 用途
 
-- 用户已说明想要的风格，就按要求设计。
-- Plan 没有明确完整风格时，读取本文，准备三套配色、表面层次和组件样式方案供用户选择。
-- 用户选界面风格，AI 负责匹配实现用的主题模板。
+首次搭建的风格未明确、需要准备选项时读取；已有风格要求直接沿用。视觉方向是面向当前项目的一组完整决策；主题模板只是内部实现基底，不作为用户选择对象。
 
 ## 核心关系
 
 ```text
 应用场景与视觉证据
   → AI 定义项目视觉方向
-  → 选择命名模板，或自由创意独立推演
+  → 绑定主题索引中的可落地基底
   → 用户选择一套完整方向
-  → 风格、配色和主题选择；导航结构沿用业务规划
-  → 命名模板的导航明暗由模板派生；自由创意明确设计导航明暗
+  → 四组已选视觉事实
   → CLI 读取所选完整模板并生成 design.md
 ```
 
-先按[设计方向比较](../../../references/theme-selection.md#设计方向比较)根据项目需求发展风格，可匹配主题索引中的模板，也可独立推演。按[应用风格与自由创意](../../../references/application-style-library.md)交付。
+执行顺序是“先定义方向，再匹配模板”，但方向必须受主题索引的可落地能力约束。索引中没有核心视觉 DNA 匹配项的方向，不得展示给用户。
 
-应用编排先根据业务需求确定导航结构。视觉设计沿用该结果，设计各页面共用的配色、背景、圆角和组件样式；命名模板的导航明暗采用模板 `navTheme`；自由创意由项目设计明确填写。页面内容、布局和操作顺序按业务规划执行。
+应用导航类型在候选生成前由需求分析与应用编排确定。视觉方向决定跨页面共享的视觉气质、主题色、导航明暗、表面层级和形状语言，不改变页面内容、首屏重点、页面模式、信息密度或操作优先级。
 
-主色按所选主题的公式推导，其他颜色沿用主题。已选方向承诺的画布、卡片、填充、字体或辅助色与模板不同时，将具体差异写入 `visualStyle.tokens`，不等待用户逐个指定色值。`description` 和 `colorStrategy.usage` 只说明用途，不会被编译成配色。按 [共用主题规则](../../../references/application-theme-consistency.md) 完成变量后再交接页面；渐变和图片按公共输出契约处理。Fast 与 Plan 使用相同规则。
+用户确认的是整体色彩氛围时，将其落到 `colorStrategy.surfaceTone=brand-tinted`；不要因为所选模板默认中性灰就降级成仅改强调色。明确仅改强调色或忠实保留参考配色时使用 `theme`，无需为这个实现字段另起提问。
 
-## 公共选型规则
+## 输入与优先级
 
-输入证据优先级、摘要匹配和读取边界统一按 [共享主题选择规则](../../../references/theme-selection.md) 执行。候选使用 [公共主题索引](../../../templates/design-themes/index.json) 或 `openyida design-plan catalog --json` 的 `themes[].styleSummary`；选中后才读取对应的一份完整模板。本文件只规定 Plan 的三套候选、用户可见内容和选择事实写入，不另设评分或主题库。
+候选生成读取已确定导航类型的共享 brief、应用场景事实、视觉证据和 [主题索引](../templates/design-themes/index.json)。视觉证据优先级：
+
+```text
+用户明确视觉要求
+> 品牌规范、Logo、官网、参考图和已有模板
+> 业务场景特征
+> AI 补齐
+```
+
+AI 需要综合判断：
+
+- 关系经营 / 流程执行；
+- 协作 / 执行 / 分析 / 服务；
+- 使用频率、信息密度和主要终端；
+- 产品气质和品牌强度；
+- 已有品牌色、禁止项和参考素材。
+
+CRM 与采购管理可以产生不同推荐方向，但依据不是行业名本身：CRM 更可能强调关系上下文、跟进节奏和信息浏览；采购更可能强调流程状态、批量处理、异常识别和高频执行。实际输入中的模块和任务始终优先于这种常见倾向。
 
 ## 候选结构与约束
 
-生成三项选择：两个具体视觉方向，加一项“自由创意：根据业务重新推演”。用户已明确风格时直接沿用，无需重选。具体方向包含：
+生成恰好三套候选，每套包含：
 
 ```json
 {
@@ -40,7 +54,8 @@
   "themeId": "<有效索引记录，仅内部>",
   "primaryColor": "#6F4E37",
   "primaryColorName": "暖咖啡棕",
-  "contentTone": "light",
+  "navigationStructure": "side",
+  "navigationTone": "dark",
   "recommendationReason": "适合需要持续查看关系历史和推进状态的日常工作。"
 }
 ```
@@ -48,21 +63,19 @@
 规则：
 
 1. 第一项为推荐项。
-2. `directionLabel`、`description` 和 `recommendationReason` 由 AI 根据项目的用户、任务和界面效果编写。
-3. `themeId` 必须来自索引，两个模板方向绑定不同记录，自由创意使用 catalog.creativeOption；模板路径由索引在选择后确定性补齐。
-4. 模板候选保持已确认的导航结构，但不输出 `navigationTone`。候选可以通过不同主题呈现深色或浅色导航差异，这个差异来自主题模板，而不是 AI 单独填写字段；优先至少两项视觉维度不同。用户约束固定的部分保持不变。
-5. 配色依据品牌素材、用户偏好和实际使用场景选择，并写清理由。用户明确菜单明暗时，将其作为主题筛选条件；用户未明确时不推导菜单明暗。
+2. `directionLabel`、`description` 和 `recommendationReason` 由 AI 根据项目生成，不直接复制主题索引的标签或摘要。
+3. `themeId` 必须来自索引，三项绑定不同记录；模板路径由索引在选择后确定性补齐。
+4. 候选保持已确认的导航类型；通过主题基底、主题色、导航明暗形成差异，优先至少两项不同。用户约束固定的部分保持不变。
+5. “企业内部、专业、稳重”不能单独成为蓝色 + 浅色侧边导航的依据。
 6. 用户明确品牌色时保留该颜色，通过主题基底、材质和组件表达形成差异。
-7. 项目色彩和已确定的导航结构可覆盖模板对应输入；导航明暗不得覆盖模板 `navTheme`。用户导航明暗要求或表面层级、形状语言、组件机制等核心视觉特征与模板冲突时必须换一个基底。
-8. 方案缺少匹配模板时走自由创意，填写独立设计决策和 Token。自由创意的导航明暗由项目设计决定，写入 navigationStyle.tone；内容与导航按[主题明暗双轴](../../../references/application-style-library.md#主题明暗双轴)分别设计。
+7. 项目色彩和已确定导航可覆盖模板默认变量；表面层级、形状语言、组件机制等核心视觉 DNA 与模板冲突时必须换一个基底。
+8. 未找到匹配模板的方向在展示前丢弃并重新生成，不能用运行时模板拼接补救。
 
-平台导航沿用 `navigationType` 对应的顶部、侧边或 L 型布局。自定义导航由视觉设计细化顶部、侧边等菜单样式，按该入口已确定的配置范围实施。
+平台顶部或侧边导航候选沿用对应结构；平台L型的最终布局由 `navigationType` 决定，候选不得将其改为单一顶部或侧边导航。自定义导航内部的顶部或侧边形态可由视觉设计细化，保持隐藏平台导航的决策。
 
 ## 用户可见边界
 
-进度说明当前应用正在设计的界面效果。例如：“正在为萌宠社交应用设计配色和界面风格，让宠物动态和互动入口更清晰。”应用名与功能使用当前需求中的内容。方案准备好后，直接提问：“萌宠社交应用的这三种界面风格，你更喜欢哪一种？”
-
-风格确定后，写“设计主题风格为{风格名称}，适合{业务场景}”。名称取项目的视觉方向，场景取当前业务用途；建议阶段使用“建议采用……风格”。
+进度围绕当前应用的用户、主要功能和界面效果说明，不播报读取规则、查找模板或生成候选等内部步骤。需要等待时可说“正在为萌宠社交应用设计配色和界面风格，让宠物动态和互动入口更清晰”，应用名与功能必须来自当前需求。方案准备好后直接询问“萌宠社交应用的这三种界面风格，你更喜欢哪一种？”，紧接选择问题时省略额外进度说明。
 
 用户只看到：
 
@@ -71,7 +84,7 @@
 - `recommendationReason`；
 - 第一项的“推荐”标记。
 
-`themeId`、`templatePath` 和模板匹配结果保存在内部实施记录中。
+用户不看到主题索引标签、`themeId`、`templatePath`、模板来源和内部匹配过程。
 
 ```json
 {
@@ -92,9 +105,9 @@
       "description": "<second.description> <second.recommendationReason>"
     },
     {
-      "value": "free-creative",
-      "label": "自由创意",
-      "description": "根据这项业务重新推演构图、材质和表单布局，不从现成模板选取。"
+      "value": "<third.directionId>",
+      "label": "<third.directionLabel>",
+      "description": "<third.description> <third.recommendationReason>"
     }
   ],
   "allowCustom": true,
@@ -102,7 +115,7 @@
 }
 ```
 
-## 一次保存选择结果
+## 选择后的原子写入
 
 选中一套方向后，一次写入四组事实：
 
@@ -123,8 +136,9 @@
     },
     "navigationStyle": {
       "structure": "side",
+      "tone": "dark",
       "source": "user_selected",
-      "selectionReason": "持续工作场景需要稳定的侧边入口；导航明暗由所选主题模板确定。"
+      "selectionReason": "持续工作场景需要稳定入口，深色导航加强模块边界。"
     }
   },
   "internal": {
@@ -137,18 +151,18 @@
 }
 ```
 
-`build-plan.json` 保存选中方案；完整候选保留在 `ask_human` 问答历史中。命名模板由 CLI 补入 `navigationStyle.tone` 和 `toneSource=theme_derived`；自由创意在 visual.json 中明确编写 tone=light|dark，CLI 标记 toneSource=project_defined，后续可通过 patch 修改该 tone。上例只展示选择事实，已选方向需要的画布、字体、辅助色等差异还须写入同级 `tokens`，见 [共用主题示例](../../../references/application-theme-consistency.md#先把风格落到变量)。
+未选中的候选只保留在 `ask_human` 问答历史，不保存到最终 `build-plan.json`。
 
 ## 直接选择与自定义输入
 
-- 只有用户已明确完整视觉风格、指定现有主题，或要求严格继承可信品牌/模板时，AI 才直接匹配一个有效基底并写入，`source=user_explicit | material_extracted`。单独的主题色、导航结构或导航明暗只作为候选约束，不视为已给出完整风格；导航明暗也不另存为可覆盖模板的输入。
-- 用户在三套候选中明确采用推荐方案时，选择第一项，`source=user_selected`。
-- 用户自由描述新方向时，先匹配核心视觉特征最近且不违反硬约束的模板。能够匹配则记录原文为 `customText` 并写入项目覆盖项。
-- 所有模板都不支持时，沿用自由创意选项，从已确认业务独立推演并继续规划。
+- 用户已明确主题色、导航结构和导航明暗，或要求严格继承可信品牌/模板时，AI 匹配一个有效基底并直接写入，`source=user_explicit | material_extracted`。
+- 用户明确采用推荐方案或不再提问时，选择第一项，`source=ai_inferred`。
+- 用户自由描述新方向时，先匹配核心视觉 DNA 最近且不违反硬约束的模板。能够匹配则记录原文为 `customText` 并写入项目覆盖项。
+- 所有模板都不支持时，只问一次：采用最接近的可用基底，或返回三套方向重新选择。收到选择后继续规划。
 
 ## 运行时读取边界
 
-- Step 2 读取本规则和主题索引中的精简风格摘要，不读取候选模板全文。
+- Step 2 只读取本规则和完整主题索引，不打开任何主题 Markdown。
 - 候选阶段只提供方向名称、配色与体验说明。
-- 用户选择后保存选中方向、内部主题绑定、导航结构和实现该方向所需的 token 差异；CLI 从模板读取导航明暗。
-- 用户确认主题后，规划时读取 CLI 返回的主题上下文；CLI 仅按已确认的 selectedTheme.themeId 读取选中的完整模板生成文档。
+- 用户选择后只保存选中方向和内部主题绑定。
+- 规划时读取 CLI 返回的主题上下文；CLI 按 selectedTheme.themeId 读取完整模板生成文档。