openyida 2026.9.21 → 2026.9.22-beta.2

package/yida-skills/skills/yida-canvas-custom-page/references/canvas-style-implementation-guide.md

@@ -1,18 +1,10 @@
 # YidaCodeCanvas 组件样式实现指南
 
-按本指南把 `design.md` 的布局、材质、密度、图表和控件样式写入 Canvas 页面。业务事实来自 `yida-prd` 输出的 `prd.md`，视觉事实来自 `yida-design` 输出的 `design.md`。
+本文件是 `YidaCodeCanvas` 组件的样式实现适配指南，不是新的设计系统，也不产出配色、视觉 DNA 或页面风格。业务事实来自 `yida-prd` 输出的 `prd.md`，视觉事实来自 `yida-design` 输出的 `design.md`。`YidaCodeCanvas` 页面只在 `YidaComp` 内消费当前应用的主题 token，并把布局、材质、密度、图表、控件状态和背景规则落到组件内部。
 
-应用主题通过 app-theme.css 配置，页面样式限定在 `YidaComp` 内。`--pod-page-*`、`--pod-card-*`、`--color-brand1-*` 和 `--color-group` 等是平台基础角色；页面还可消费项目定义的材质、布局、字体、动效和组件状态变量。平台负责应用壳、原生表单和详情页的主题，新变量需要显式消费或映射后才会影响这些组件。
+`app-theme.css` 只在应用级配置，平台负责应用壳、原生表单、详情页和 `YidaCodeCanvas` 外层的主题一致性。Canvas Page 宿主的 `contentBgColor`、`pageStyle.backgroundColor` 和 `contentBgColorMobile` 使用 `var(--pod-page-bg-color, var(--color-white, #fff))`，保证平台宿主背景一致；自绘导航页的内部画布允许采用下文的局部背景方案。
 
-开发前按 [应用与自定义页面共用主题](../../yida-design/references/application-theme-consistency.md) 核对风格与变量。纯 DOM 页面也必须引用应用主题；省略 antd Provider 不等于可以另写固定色盘。已确认风格缺少变量时先补设计源并重新生成主题，不在每页用 `--canvas: #…`、`--ink: #…` 复制一套基础配色。
-
-CLI 将 Canvas 宿主的 `contentBgColor`、`pageStyle.backgroundColor`、`contentBgColorMobile` 设为 `var(--pod-page-bg-color, var(--color-white, #fff))`。自绘导航页的内部画布按下方规则设置局部背景。
-
-## 导航、画布与切换
-
-先按[管理页面边界](navigation-and-entry-guide.md#平台导航下的管理页面)确认本页是否拥有导航。平台导航管理页只实现业务内容，不套带菜单的内容壳；以下自绘导航的背景与切换规则仅适用于已确认的独立入口或应用级自绘导航。
-
-按 [页面与导航连续性](../../yida-design/references/page-continuity.md) 实现共同背景、滚动和切换；沉浸展示页不套业务工作区。加载/错误保留导航和画布，验收首屏、第二屏和窄屏菜单。
+宿主属性绑定不是主题注入。严禁生成 `body` 背景 CSS，也严禁 `YidaComp` 修改 `document.documentElement`、`document.body`、父页面或平台容器的主题变量。组件自己的背景、卡片和控件样式留在 `YidaComp` 内，并使用 `--pod-page-*`、`--pod-card-*`、`--color-brand1-*` 和 `--color-group`。
 
 ## 嵌入页面的宿主高度
 
@@ -42,66 +34,65 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 
 | 冲突现象 | 处理方式 |
 | --- | --- |
-| 导航选中态与页面按钮、指标颜色不同 | 对照 `design.md` 的颜色角色；已设计的协调配色可以保留，临时硬编码或误用变量才需要修正，不以同色为验收标准 |
-| design.md 的操作色或指标色与品牌色不同 | 按已定义的用途和表面使用项目变量，同时检查与画布、图片及状态色的关系；未说明搭配时先补设计，不自动降为装饰或改回品牌色 |
+| 左侧平台导航选中态是应用主题色，页面主按钮 / 标题强调 / 卡片选中态用了另一套主色 | 页面主操作、链接、选中态、重点标签和图表主序列改回应用主题 `--color-brand1-*` |
+| design.md 生成了青绿、紫色、蓝色等辅助色，但当前应用主题是橙色或其他色 | 保留 `design.md` 的布局、卡片、密度、图表语言，把生成色彩降为辅助色、浅底背景、分组色或第二图表序列 |
 | 用户要求导航和内容一起换色 | 交给 `yida-design` 更新应用主题设计 |
 | 页面是沉浸页、自绘壳、独立官网、活动页或公开落地页 | 仍消费应用主题变量；页面差异通过布局、材质、素材、构图和辅助色表达，不覆盖品牌 token |
 
-实现时读取 `themeProfile` 的主色与交付方式，以及正文中的颜色角色。品牌、操作和信息强调可以用不同颜色，但必须属于同一份项目设计，不能在页面中另配一套色盘。
+实现时先读取 `themeRelation`。默认值是 `跟随应用主题`，不是 `跟随生成色盘色相`。
 
 ## 工作台卡片密度红线
 
 工作台、门户首页、业务首页默认是“进入应用后马上处理事情”的工具页，不是通用 SaaS 展示页。实现工作台页面时：
 
-- 禁止使用“4 个等宽大 KPI 白卡 + 彩色图标盒 + 大数字 0”作为首屏主体；统计摘要按主题采用紧凑条、分段摘要或实际需要的小面板，未定义时可参考 64-88px。
+- 禁止使用“4 个等宽大 KPI 白卡 + 彩色图标盒 + 大数字 0”作为首屏主体；统计摘要只能作为 64-88px 的圆润紧凑条、分段摘要或右侧小面板。
 - 禁止把状态摘要做成横跨整页但内容稀疏的空矩形；如果占满宽度，必须放入趋势、更新时间、筛选、主操作或风险状态。
 - 禁止用 160px 以上的大空态白卡显示“暂无数据”；空态应是薄行、列表内空态或右侧提示条，并带登记/发布/刷新等下一步动作。
 - 快捷入口不要做孤立图标大卡片阵列；高频动作放按钮组、工具条或 40-56px 的紧凑入口，低频动作折叠到更多。
 - 首屏必须至少有一个任务/动态/最近记录/待处理列表承接真实工作流；若当前没有记录，显示可执行空态，而不是把空白面积留给装饰。
 - 页面整体推荐包含 8-10 个有业务目的的区块以上；这些区块应通过密度、主次、分栏和列表节奏形成丰富度，不通过重复大卡片形成面积。区块数量不是实现准出硬门槛，窄场景或用户要求精简时可以更少。计数按区块组算，KPI 子项、快捷入口子项和列表行不能分别计数。
 
-## 主题形状、密度与呼吸感落地
+## 默认圆润高密与呼吸感落地
 
-把 `design.md` 正文中的圆角、密度与分组节奏落实为 CSS 与 antd token。选中主题和页面明确决定优先；下列数值仅在对应项未定义时兜底，不是所有主题的硬门槛。缺少可实现设计时先修设计源事实，不在源码里凭感觉补。
+YidaCodeCanvas 必须把 `design.md` 的 `roundedRule`、`densityRule` 和 `breathingRule` 落成具体 CSS 与 antd token。若 design.md 未写明数值，先回写 design.md，不要在源码里凭感觉补。
 
-- 业务卡片可参考 `20px-24px` 圆角，控件可参考 `10px-14px`；主题采用微圆、胶囊或不同档位时按其用途分工实现，不统一改为大圆角。
-- 页面 padding 可参考 `20px-28px`、卡片 gap `12px-18px`、卡片 padding `22px-28px`；主题明确的 `16px` 内距或 `24px` 间距同样有效。
-- 页面布局必须有呼吸感：用主题的组内/组间间距、对齐与边界形成层次；文字、按钮和标签保留内容安全内距。
-- 列表行、高频按钮、摘要高度按实际内容与主题确定；未定义时可参考 `44px-56px`、`36px-40px`、`64px-88px`。
-- 空态可参考 `88px-120px`，更多空间需承载解释、主操作或真实图示；不得以大块纯空白撑版面。
-- 出现大面积空内容时优先压缩容器，或放入已有任务、动态、风险、负责人和下一步动作，不虚构业务内容。
+- 卡片 `border-radius` 范围 `0px-32px`，业务面板 / 卡片默认 `20px-24px`，主面板、抽屉和重点容器默认 `22px-32px`。
+- Button、Input、Select、DatePicker 等控件 `borderRadius` 默认 `10px-14px`；状态标签和徽标使用 `999px` 胶囊。
+- 页面 padding 默认 `20px-28px`，卡片和卡片的 gap 默认 `12px-18px` 且必须小于 `20px`，卡片 padding 默认 `22px-28px` 且必须大于 `20px`。
+- 页面布局必须有呼吸感：主区、右侧上下文、工具条和列表之间通过 `12px-18px` 的紧凑 gap 和清晰分组形成节奏；列表行内部 `10px-12px`，文字、按钮和标签不能贴边。
+- 列表行高 `44px-56px`，高频按钮高度 `36px-40px`，状态摘要高度 `64px-88px`。
+- 空态默认高度 `88px-120px`；超过 `120px` 必须有说明、主操作或配置入口，超过 `160px` 的纯空白不通过。
+- 大圆角和呼吸感只负责形状性格与阅读节奏，不负责撑版面；出现大面积空白时，优先压缩容器或补任务、动态、风险、负责人、下一步动作。
 
 ## 视觉落地顺序
 
-先读取 PRD 与 design.md，再通过 `pageSpecHandoff.designRefs` 查询 frontmatter 的 anchor 索引，定位当前页八项要点与共享组件规则。索引只负责定位，不以旧 `visualScaffold` 字段是否存在决定能否实现。
+页面实现不要从“高级、简洁、好看”等形容词直接写 CSS。先读取 `prd/<项目名>/design.md`，再用 PRD 的 `pageSpecHandoff.designRefs` 定位当前页面要遵守的 `visualScaffold`，按固定顺序落地：
 
-1. 按页面任务、首屏焦点与布局确定真实区块的顺序、主次和分栏。
-2. 按表面与组件规则选择开放区、细线面板、连续列表、表格与必要容器。
-3. 通过主题 token 与明确局部差异落实圆角、间距、层次和阅读节奏。
-4. 实现主操作、状态反馈与恢复入口；按具体响应式决定安排窄屏。
-5. 对照当前页验收检查业务内容、焦点、主题、交互和布局，区块数量不作为硬门槛。
+1. `layoutRecipe`：先确定页面骨架和分栏比例。
+2. `surfaceMap`：决定每个区块是无框、细线面板、浅底条、列表行、表格、右侧栏还是抽屉。
+3. `sectionRhythm` / `breathingRule`：确定首屏主次、区块间距、阅读顺序、组内/组间节奏和移动端折叠间距。
+4. `densityRule`：控制卡片高度、列表行高、按钮尺寸和信息密度。
+5. `componentRecipe`：统一按钮、入口、标签、图标、列表、图表、空态和弹层。
+6. `acceptanceChecks`：逐项检查 contentBlocks 是否支撑业务目标、无大空白卡、主色跟随应用主题、KPI/快捷入口子项不计数、移动端不挤压；区块数量不作为硬门槛。
 
 ## 背景与导航的关联
 
 背景职责统一：Shell 的 `--pod-shell-bg-color-light/white/gray/dark` 承载外层氛围；原生页面与自定义页面的基础底色统一消费 `--pod-page-bg-color`；卡片、表格外壳和面板消费 `--pod-card-bg-color`，回退 `--color-white`。渐变、纹理和图片作为页面局部装饰层叠加，不另设应用基础背景变量。
 
-应用根背景已提供 `--pod-app-root-bg-color` 和 `--pod-app-root-bg-image`，后者可表达图片或 CSS 渐变。它们只影响实际消费这些变量的根容器；不透明页面和卡片仍显示各自底色。全应用背景由主题 CSS 配置，单页渐变在本页根容器用 `background-image` 实现；颜色变量不放渐变，页面代码不向父页面 body 注入样式。Fast 与 Plan 共用这套规则，详见 [背景作用范围](../../yida-design/workflow/output-design.md#背景颜色渐变与图片)。
-抽屉外壳背景默认使用 `--pod-shell-theme-bg-color`，回退 `--color-white`；标题栏、正文容器透明承接外壳，不铺 `--pod-card-bg-color`。抽屉内独立业务卡片才使用卡片 token。
-
 导航布局和页面底色分别配置。隐藏应用导航不自动把 Canvas 改为透明；深色或明确的应用底色在 `design.md` 的平台 token 中定义，生成 `app-theme.css` 后统一生效。页面局部视觉不能通过修改应用 token 影响其他页面。
 
 普通 Canvas 根背景默认使用 `background: var(--pod-page-bg-color, var(--color-white, #fff));`。自绘应用导航页的内部画布按下节设计，不要求可见底色与平台宿主相同。
 
-顶部导航默认贴顶通栏；首屏有背景图时透明叠加、滚动加遮罩、回顶透明，规则见 [页面与导航连续性](../../yida-design/references/page-continuity.md)。仅明确选择浮导时留外侧间距。Canvas 宿主的 flow-root 无法阻止内部根节点 margin 折叠；内部根也须用 flow-root 或 flex/grid，文字安全区不推下背景。测量宿主、页面根与导航的 top；不用 overflow:hidden 修复，不改平台父容器。
+浮导距顶部的留白放在自定义页根节点内部。发布层的 `.yida-code-canvas{display:flow-root}` 只保护宿主，不能阻止 `.doll-page` / `.oy-page-root` 等内层根节点与导航的 margin 折叠。页面根必须使用 `display:flow-root`（已有 flex/grid 可保留），或用根容器 padding 承载顶部间距；不能仅给 Canvas 宿主加 flow-root。验收时分别测量宿主、页面根与导航的 top：宿主和页面根贴齐，导航仍保留设计间距。不要用 overflow:hidden 修复，它可能影响 sticky 和弹层；不要向平台父容器写负 margin 抵消。
 
 ## 自定义导航页的独立画布
 
 **MUST** 区分平台宿主与自绘应用画布：宿主继续使用平台背景 token；内部导航壳可按 `design.md` 使用浅灰、浅彩、低饱和渐变或局部纹理，不强制使用 `--pod-page-bg-color` 作为唯一可见底色。`design.md` 明确 `canvasBackground`、`navigationSurface` 和 `cardSurface`，仅在当前页面根选择器实现，不修改 body、父页面或全局变量。
 
-导航底色按首屏、滚动和展开状态设计，不因浅色画布强制白色浮导。浅彩画布上的白卡可无框，白画布上的白卡用细边框或投影；Logo、选中态和主操作按项目颜色角色搭配，不要求同色。渐变低饱和、集中于局部；深色画布独立设计对比。
+浅色非白或渐变画布，顶部浮导默认白色或近白半透明、柔和投影；白卡默认无框，品牌色留给 Logo、导航选中态和主操作。白色画布上的白卡用细边框或投影。深色画布按独立对比方案设计，不强制白色浮导。渐变应低饱和、集中于顶部或局部，内容区域保持安静，不能遮挡文字或滚动内容。
 
 ```css
-/* 明确选择浮导时的局部示例，色值由 design.md 确认。 */
+/* 自定义导航页局部设计示例，色值由本页 design.md 确认。 */
 .custom-nav-canvas {
   min-height: 100dvh;
   display: flow-root;
@@ -113,11 +104,7 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 }
 ```
 
-验收覆盖首屏、滚动底部、窄屏和导航切换：画布铺满内容区，无意外白边；导航与卡片边界清楚，品牌色不过度铺满导航；原生 iframe 不被跨框样式修改。工作台同时压缩重复操作条、等权大指标卡和过高空态，不能仅靠渐变声称完成设计优化。
-
-## 分组标题与分割线
-
-执行 [分组标题与分割线选型](../../yida-design/references/application-theme-consistency.md#分组标题与分割线)：按当前页用途、密度和主题选形态，不把所有页面都写成左竖条或一条实线。同页同层级使用同一实现与配色，不同业务页面优先使用不同且合适的形态。平台 Divider 的选型表可作为外观参考；Canvas 使用自己的标题/CSS 实现，不导入未提供的原生表单组件。表格网格和卡片边框不套用章节装饰。
+验收覆盖首屏、滚动底部、窄屏和导航切换：画布铺满内容区，无意外白边；浮导与卡片边界清楚，品牌色不过度铺满导航；原生 iframe 不被跨框样式修改。工作台同时压缩重复操作条、等权大指标卡和过高空态，不能仅靠渐变声称完成设计优化。
 
 ## 同色表面的卡片边界
 
@@ -151,7 +138,7 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 
 ## 背景层实现规则
 
-实现 `design.md` 中的背景设计时，先考虑页面根画布，再做内容面板。不要先堆白卡片再临时补装饰。展示型页面、工作台、看板、门户、官网、登录页和空状态页推荐有非纯空白的画布；近白画布可通过主题的边界、留白与信息组织成立，不强制增加装饰。如果 `design.md` 指定 `topIrregularWash`、`radialGlowWash`、`flowLight` 或 `organicNoise`，必须在源码里落成对应 CSS。
+实现 `design.md` 的 `backgroundLayer` 时，先考虑页面根画布，再做内容面板。不要先堆白卡片再临时补装饰。展示型页面、工作台、看板、门户、官网、登录页和空状态页推荐有非纯空白的画布；近白画布可以保留，但要通过淡渐变、细线、星芒、局部装饰、素材或内容密度形成背景感。如果 `design.md` 指定 `topIrregularWash`、`radialGlowWash`、`flowLight` 或 `organicNoise`，必须在源码里落成对应 CSS。
 
 推荐结构：
 
@@ -218,7 +205,7 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 
 落地要求：
 
-- 普通页面和业务卡片按上述主题契约实现；自绘应用导航页的局部画布、导航按下述独立画布规则实现，不覆盖平台或原生内页主题。
+- 普通页面和业务卡片按上述主题契约实现；自绘应用导航页的局部画布、浮导按下述独立画布规则实现，不覆盖平台或原生内页主题。
 - `softTintCanvas`：根节点使用低饱和浅底、带弱渐变的近白画布或深色舞台；不要为了背景感强行铺满高饱和色。
 - `topIrregularWash`：用 `::before`、`clip-path`、局部 SVG 背景或伪元素形成顶部波浪、斜切、有机边界、细线曲线或图形标记；内容层固定在规则栅格上。
 - `radialGlowWash`：使用大面积柔和径向光或光洗，禁止离散装饰圆球、bokeh 和随机漂浮点。
@@ -227,7 +214,7 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 
 ## 源码结构验收
 
-页面源码不能只堆 section 或 Card。下列 primitive 名称用于理解实现职责，不是设计文档的必填字段；只检查当前业务实际需要的项。写完 `.canvas.jsx` 后自检：
+页面源码不能只堆 section 或 Card。写完 `.canvas.jsx` 后，按下面结构自检：
 
 - 文件输入：实现前已读取 `prd.md` 和 `design.md`；视觉规则来自 `design.md`，业务区块和数据来源来自 PRD。
 - `rootShell`：有页面根类、背景带、内容宽度、平台导航可见时的宽度处理。
@@ -235,10 +222,10 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 - `statusPrimitive`：有紧凑状态摘要、数据在线、更新时间、主健康分或状态胶囊。
 - `actionPrimitive`：主按钮、次按钮、高频动作条或批量动作条能触发真实路径。
 - `contentPrimitive`：有表格、列表、任务流、事件流、排行、时间线、图表或详情预览之一作为主要承接。
-- `contextPrimitive`：业务需要时承接已有洞察、风险、负责人、下一步建议或关联对象，不为补齐结构新增侧栏。
+- `contextPrimitive`：有右侧洞察、风险、负责人、下一步建议或关联对象，避免页面只有左到右平铺卡片。
 - `statePrimitive`：loading、empty、error、未接数据都有薄空态、刷新、登记或补录动作。
 - `responsiveRule`：移动端分栏退化为单列，关键状态、动作和主内容保留，不让文字和按钮挤压。
-- 表面与组件：源码还原正文指定的背景、边界、材质、色彩角色、圆角和分组节奏；同色画布可以通过主题的边界与留白成立，玻璃、渐变和装饰按需采用。
+- `backgroundLayer` / `surfaceMaterial` / `colorRoles` / `depthRule` / `roundedRule` / `densityRule` / `breathingRule`：源码按 `design.md` 落地分层背景、半透明玻璃或细线面板、明确辅助色角色、深度规则、大圆角、紧凑密度和呼吸节奏；近白画布可接受，但应有渐变、装饰、素材焦点或内容密度支撑。
 
 缺少 `prioritySurface`、`contentPrimitive` 或 `statePrimitive` 任意一项，不能交付为“已打磨页面”。
 要求玻璃感但源码只有普通白底和纯白不透明卡片，也不能交付为“已打磨页面”；如果选择极简近白背景，需要在截图和源码中体现细节层次。
@@ -251,10 +238,9 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 | token | design.md 语义 | YidaCodeCanvas 使用方式 |
 | --- | --- | --- |
 | `--color-brand1-6` | 主色 | 主按钮、链接、选中态、信息强调、图表主序列 |
-| `--color-brand1-1` | 品牌交互悬停色 | 品牌控件 hover，不用作常驻指标背景 |
-| `--color-brand1-2` / `--color-brand1-3` | 品牌派生浅色 | 按主题定义用于选中底、提示块和弱强调背景 |
-| `--color-brand1-5` | 品牌派生深色 | 按主题定义用于深色导航或强调表面 |
-| `--color-brand1-9` / `--color-brand1-10` | 激活 / 禁用色 | 分别用于 pressed / disabled，不用作普通标题、指标或默认按钮背景 |
+| `--color-brand1-1` / `--color-brand1-2` / `--color-brand1-3` | 浅底色阶 | 标签浅底、提示块、筛选选中底、弱强调背景 |
+| `--color-brand1-5` / `--color-brand1-9` | 交互色阶 | hover / active / pressed 状态 |
+| `--color-brand1-9` / `--color-brand1-10` | 深色阶 | 深色标题、深底按钮、深色主题强调 |
 | `--color-brand-1` ~ `--color-brand-4` | 移动端品牌色阶 | 当前自定义页面的移动端布局和品牌状态 |
 | `--color-group` | 平台图表色组 | 多系列折线、柱状、排名、环形图配色 |
 | `--oyd-control-selected-bg` | 页面级选中浅底 | 下拉选中项、Tabs 选中底、轻量筛选块 |
@@ -295,18 +281,16 @@ body.pod-premium.page-type-workbench .vc-page-yida-pure-container:has(> .vc-root
 
 ## 统一主题适配
 
-antd 页面统一使用 [CanvasThemeProvider](canvas-theme-provider.md) 读取应用主题。纯 DOM 页面直接使用 CSS 变量。
+新 antd 页面使用 [CanvasThemeProvider 脚本](canvas-theme-provider.md)，不再复制变量映射、读取 hook 或监听代码。纯 DOM 页面直接使用 CSS 变量。
 
-`openyida sample openyida-page-template canvas-theme` 输出同一份 Provider；表单抽屉、批量表格和趋势图示例已自动装配。已有页面按脚本指南统一接入。
+旧页面已有 `useCanvasTheme` 和 `ConfigProvider` 时可继续维护；不要再叠加新的 Provider。迁移时按脚本指南替换整条主题接入链路。旧示例和 `openyida sample openyida-page-template canvas-theme` 仅保留供存量维护，不作为新页面起点。
 
 ### 按钮语义与优先级
 
-- 按 `design.md` 的[指标卡与按钮配色](../../yida-design/references/application-theme-consistency.md#指标卡与按钮配色)实现背景、文字、图标和状态。指标区检查外层容器的背景，按钮检查内部图标的 `currentColor`、描边和透明度；换背景时一起调整前景。跨应用复用页面后，删除旧主题变量和深色兜底，使用当前设计声明的颜色角色；不能只换品牌色值。
-- 内容面板切换用 Tabs，类别单选用 Segmented/Radio.Group，主动作才用实心 Button。按 [默认控件状态](canvas-theme-provider.md#默认控件状态) 接入 Provider：中性普通项、轻底选中项、清晰文字与独立禁用态；不把分类筛选做成一排主操作，不以主色文字叠加同色实心底。
-- 主按钮、链接、选中态消费项目为相应角色定义的 token，可与品牌色不同；同类操作跨页面保持一致，普通按钮保持次要层级。
+- 主按钮、链接、选中态跟随应用品牌 token；普通按钮使用中性表面、文字和边框。
 - 删除、失败、成功、警告保留语义色，不能把所有按钮和提示都染成品牌色。
 - 原生 DOM 按钮直接消费 CSS 变量；antd 控件使用 `ConfigProvider` 的解析值，保留库的 disabled/loading/focus 行为。
-- 应用 token 优先于 design.md 兜底。内层 `ConfigProvider` 或按钮行内 `background/color` 会覆盖外层主题；按已设计的组件配色局部适配，引用项目变量并覆盖完整交互状态，不能复制固定蓝色或黑色按钮。
+- 应用 token 优先于 design.md 兜底。内层 `ConfigProvider` 或按钮行内 `background/color` 会覆盖外层主题；仅在明确的业务语义或用户要求下覆盖，不能复制固定蓝色主按钮。
 - 浮层保持 React provider 上下文；CSS 变量还取决于实际挂载 DOM。优先使用声明式 Modal/Drawer 和上下文内的消息 API，避免静态调用绕过主题；根据滚动和裁剪情况选择弹层容器并验收。
 - 页面差异通过布局、密度、圆角、材质和素材实现，默认不创建另一套页面品牌色。
 
@@ -319,7 +303,7 @@ antd 页面统一使用 [CanvasThemeProvider](canvas-theme-provider.md) 读取
 | colorPrimary / colorLink | --color-brand1-6，主操作、链接与选中焦点 |
 | colorBgLayout | --pod-page-bg-color，回退 --color-white；与页面根容器一致 |
 | colorBgContainer | --pod-card-bg-color，回退 --color-white |
-| colorBgElevated | --pod-card-bg-color，普通浮层表面；Drawer 通过组件级 colorBgElevated 单独使用 --pod-shell-theme-bg-color，回退 --color-white |
+| colorBgElevated | --pod-card-bg-color，浮层的可读表面；有独立浮层设计时使用其已确认 token |
 | colorText / colorTextHeading | --color-text1-4，正文与标题 |
 | colorTextSecondary / colorTextDescription | --color-text1-3，辅助说明 |
 | colorTextPlaceholder | --color-text1-10，表头与 placeholder 层级 |
@@ -329,13 +313,13 @@ antd 页面统一使用 [CanvasThemeProvider](canvas-theme-provider.md) 读取
 
 这些映射不改变业务数据和操作。表格表头、卡片外壳、自绘文字等 CSS 同步消费对应 token；外壳卡片使用 `background: var(--pod-card-bg-color, var(--color-white, #fff))` 与主题卡片边框；卡片边界按上文背景搭配选择细边框、投影或无框，不能只映射 antd 而遗漏自绘表面。
 
-颜色解析和刷新由 Provider 处理。上表是默认映射，不是配色限制；项目明确采用独立操作色时，读取对应项目变量，在 Button 等目标组件范围配置背景、前景和交互状态，不修改全局品牌色或无关组件。扩展变量不会自动被 Provider 消费，必须显式适配。当前脚本也不自动映射尺寸、圆角、字体、图表色组或完整 CSS 选择器，布局与圆角仍按 design.md 实现。
+颜色解析和刷新由 Provider 处理。当前脚本不自动映射尺寸、圆角、字体、图表色组或完整 CSS 选择器，也不会把平台所有组件样式转换成 antd 样式。布局与圆角仍按 design.md 实现；需要 antd 局部配置时仅覆盖所需的尺寸、圆角等属性，保留外层颜色主题。
 
 应用主题模式主色缺失时为 missing、解析抛异常时为 error；其他缺失颜色保留 antd 默认值；这不代表主题验收通过。本地快照只在显式 preview 模式下使用。
 
 ## 默认 light 模式避免灰黑主题
 
-业务列表、协同表、数据管理页、工作台和门户默认都是 light 模式。正文使用深色保证可读性；主操作、选中态、筛选焦点、批量操作和信息标签按项目颜色角色表达主次，卡片与浮层边界按所在表面选择中性或协调的浅彩色，不强制使用品牌混色。用户明确要求暗色大屏、夜间模式或高对比风格时使用深色主视觉。
+业务列表、协同表、数据管理页、工作台和门户默认都是 light 模式。正文使用深色保证可读性；主操作、选中态、筛选焦点、批量操作和信息标签使用平台品牌色或当前页面确认的品牌色；卡片边框、表格分割线和下拉浮层边框使用浅色品牌混合，例如 `#DCE6F2`、`color-mix(in srgb, var(--oy-brand) 16%, #DDE8F4)`。用户明确要求暗色大屏、夜间模式或高对比风格时使用深色主视觉。
 
 ## 控件焦点态与下拉浮层 reset
 
@@ -385,12 +369,12 @@ Canvas 节点在页面 DOM 树内，Tailwind 运行时对普通元素直接用 a
 ```jsx
 // 主色文字 / 背景 / 边框，直接引平台变量，跟随 App 主题
 <div className="text-[var(--color-brand1-6)] border border-[var(--color-brand1-3)]">…</div>
-<button className="bg-[var(--color-brand1-6)] hover:bg-[var(--color-brand1-1)] text-[var(--oyd-on-action-color)] rounded-lg px-4 py-2">
+<button className="bg-[var(--color-brand1-6)] hover:bg-[var(--color-brand1-5)] text-white rounded-lg px-4 py-2">
   主操作
 </button>
 ```
 
-本例要求当前设计已声明并核对 `--oyd-on-action-color`，项目已有同义前景变量时直接复用。色阶以 `design.md` 为准：主色 `brand1-6`、品牌 hover 使用 `brand1-1`、按下使用 `brand1-9`、禁用使用 `brand1-10`、选中/标签浅底使用 `brand1-2`；默认与悬停背景都要能读清文字。
+色阶对应以 `design.md` 和 yida-design 主题 token 语义为准：主色 `brand1-6`、填充按钮 hover 使用 `brand1-5`、按下使用深色档 `brand1-9`、通用浅色 hover 底使用 `brand1-1`、选中/标签浅底使用 `brand1-2`。
 
 ## 图表 / recharts：用解析后的品牌色组
 

package/yida-skills/skills/yida-canvas-custom-page/references/canvas-theme-provider.md

@@ -1,39 +1,50 @@
-# Canvas 页面接入应用主题
+# 脚本生成 CanvasThemeProvider
 
-antd 页面用 CanvasThemeProvider 包住业务组件；图表通过 useCanvasThemeContext 取色。纯 DOM 页面直接使用应用 CSS 变量。
+用于现有 CodeCanvas 运行时。主题适配由本技能的脚本生成，业务页面无需复制变量映射、颜色解析或更新监听。不需要修改 vc-deep-yida，也不新增运行时依赖包。
 
-## 1. 选择接入方式
+## 选择接入方式
 
-`@canvas-theme-provider` 和 `.themed.canvas.jsx` 仅用于第 2 节的脚本装配路线，不是所有顶部导航、背景图或 Canvas 页面的必经步骤。已有 Provider 的页面直接编译原文件；不要重复插入 Provider 或增加标记。
-
-| 页面情况 | 操作 |
+| 当前情况 | 做法 |
 | --- | --- |
-| 用 `sample` 生成表单抽屉、批量表格或趋势图页面 | 已接好主题，继续编写业务内容 |
-| 自己编写页面，直接使用应用主题 | 按下方命令提取 Provider，合并到页面 |
-| 有本地 app-theme.css，需要生成完整页面或预览 | 按第 2 节运行主题脚本 |
-| 维护 .oyd.jsx / 平台 Jsx 页面 | 使用 yida-custom-page |
+| 新 antd 页面，有本地主题文件 | 用本脚本装配 Provider |
+| 没有本地主题文件 | 先取得当前应用的主题文件；暂保留原接入，不凭 URL 编造配色 |
+| 纯 DOM 页面 | 直接消费平台 CSS 变量，不引入 Provider |
+| 已有 useCanvasTheme 页面 | 保留原链路继续维护，或按下方步骤完整迁移；不叠加 Provider |
+| 存量 .oyd.jsx / 平台 Jsx 页面 | 继续使用 yida-custom-page；本脚本不负责迁移运行时 |
+| 只测试本地主题 | 生成默认测试页，保留 preview；不要求发布 |
+
+## 设计与主题来源
+
+1. 从 design.md 生成或定点更新应用 app-theme.css。页面基础背景是 --pod-page-bg-color，卡片是 --pod-card-bg-color；不另定义页面品牌色。
+2. 应用级上传与保存仍走 create-app/update-app --theme-file。主题 URL 必须来自真实上传结果或应用配置回读，不能根据文件名拼接。保存的 URL 与当前本地 CSS 应是同一次主题产物。
+3. 调用本技能 scripts/build-canvas-theme.js。`<skill-dir>` 使用当前实际安装技能目录，不要硬编码开发者路径。
+
+脚本不上传或下载主题。URL 作为来源标识和已加载 link 的加载事件匹配条件；页面由平台加载应用 CSS。SHA256 标识本地生成快照，不证明远端文件与本地一致。
+
+## 先生成测试页
 
 ```bash
-openyida sample openyida-page-template canvas-theme --output <项目目录>/canvas-theme.jsx
+node <skill-dir>/scripts/build-canvas-theme.js \
+  --theme-file <项目目录>/app-theme.css \
+  --theme-url <已上传主题的HTTPS地址> \
+  --output <项目目录>/pages/src/theme-preview.canvas.jsx
 ```
 
-将片段与业务代码合并到同一 Canvas 文件，React 和 ConfigProvider 的 import 各保留一份。把业务内容放进 PageContent，在 YidaComp 中用 CanvasThemeProvider 包住 PageContent。已有页面用它替换自带的主题 hook 和配色 ConfigProvider。
-
-组件结构固定为 `YidaComp → CanvasThemeProvider → PageContent`。主题上下文和 Provider 定义放在模块顶层；`useCanvasThemeContext()` 放在 PageContent 或其子组件中；通过 `<PageContent />` 渲染业务内容。
+未上传时可省略 --theme-url。输出是可独立编译的 Canvas 页面，默认开启 `preview`：把本地 CSS 的顶层 :root token 快照放在当前 Provider 容器上，供本地预览。不会插入全局样式表、修改 body 或加载完整平台 CSS。快照保留变量引用，不携带选择器、媒体查询、字体资源等完整 CSS 行为。
 
-## 2. 用本地主题文件生成页面
+测试主按钮、次按钮、危险按钮、禁用和确认弹窗。`preview` 只验证快照；验证应用真实主题时移除 `preview`，由当前应用样式驱动。
 
-先按 design.md 准备 app-theme.css。应用主题使用 `openyida update-app <appType> --theme-file <app-theme.css>` 上传保存；页面由平台加载该 CSS。
+## 业务页面接入
 
-在业务源文件的模块顶层保留一个标记：
+源文件保留一个模块级标记，让脚本展开 Provider：
 
 ```jsx
 /* @canvas-theme-provider */
 import { Button } from 'antd';
 
 function PageContent() {
-  const { token } = useCanvasThemeContext();
-  return <section style={{ color: token.colorText }}><Button type="primary">新增</Button></section>;
+  // 普通按钮自动继承；图表可在此组件内调用 useCanvasThemeContext() 取色。
+  return <Button type="primary">新增</Button>;
 }
 function YidaComp() {
   return <CanvasThemeProvider><PageContent /></CanvasThemeProvider>;
@@ -49,63 +60,30 @@ node <skill-dir>/scripts/build-canvas-theme.js \
   --output <项目目录>/pages/src/workbench.themed.canvas.jsx
 ```
 
-- `<skill-dir>` 是当前安装的技能目录。
-- `--theme-file`、`--output` 必填。输出使用独立文件，保留业务源文件和主题 CSS。
-- `--theme-url` 可省略；填写时使用该 CSS 的真实上传地址或应用配置回读结果。
-- 标记只写一次。脚本会插入 React、ConfigProvider、CanvasThemeProvider 和 useCanvasThemeContext；业务代码共用这些声明，hooks 使用 `React.useState` 等。
-- 后续修改写入业务源文件或 app-theme.css，再运行脚本。编译和发布使用输出的 `.themed.canvas.jsx`。
-
-需要本地主题预览时，省略 `--page`，将 `--output` 指向 `theme-preview.canvas.jsx`。生成的测试页默认开启 `preview`，使用 CSS 顶层 `:root` 变量；完整选择器、媒体查询和字体资源在实际应用中验证。测试真实应用主题时移除 `preview`。
-
-## 3. 接入控件和图表
-
-### 默认控件状态
+生成片段已声明 React、ConfigProvider、CanvasThemeProvider 和 useCanvasThemeContext。源文件不要重复声明这些名字；React hooks 使用 `React.useState` 等。标记必须恰好出现一次，输出不能覆盖输入。修改主题或业务代码后重新运行脚本，只编译 `.themed.canvas.jsx`；需要发布时也使用这个文件。不要直接编辑派生文件，否则下次生成会覆盖手动修改。含标记的输入不能直接发布。
 
-按用途选择组件：内容面板切换用 Tabs（默认线条型）；作品类别等互斥筛选用受控 Segmented，长文案或需换行时用 Radio.Group/自绘筛选组；主业务操作才用实心主按钮。不要把一排分类选项都做成抢眼的主按钮。antd 运行时为 5.23.3，不使用 5.24 才引入的 Segmented.shape。
+## 旧页面迁移
 
-标准 Provider 给 Tabs、Segmented、Radio.Button 和 Button 提供组件级默认色：普通项用可读中性文字；筛选选中项用当前品牌色与表面混合出的轻底色，文字优先品牌色、对比不足时回到清晰正文色；Tabs 以指示线表达选中，不铺浓重底色。不要假设 `--color-brand1-1` 永远是浅底，也不要把同一主色同时用作选中文字和实心背景。
+1. 先保留原页面用于对照。业务内容提取到 PageContent，清除旧 useCanvasTheme/readThemeColor、旧根 ref 和负责配色的 ConfigProvider；尺寸或圆角等独立配置可以保留。
+2. 按上方示例加一个标记和一个 CanvasThemeProvider。Provider 已提供页面最小高度和底色，内容层不再重复设置整页 min-height；业务 padding、卡片和装饰仍保留。
+3. 用脚本输出独立文件，编译并对照原页面验证。旧示例中的 Modal.useModal holder 仍须放在新 Provider 下。
+4. 既有主题若使用旧页面背景别名 `--oyd-page-background`，先比对其与 --pod-page-bg-color 的值；有差异时在 design.md 确认共享底色再定点修改主题。脚本不会自动迁移旧主题文件、Schema 或已发布页面。
 
-对可解析的不透明 sRGB 色值，选中项及实心主按钮文字按至少 4.5:1 的对比度选择。实心按钮检查常态、悬停、按下共用文字的可读性；应用 hover/active 色阶对比不足时保留主色背景，避免文字消失。透明色、其他色彩空间与图片背景保留组件库默认策略，需实页检查。禁用项使用独立禁用 token；危险、成功与警告保留语义色。
+脚本只装配已维护的 Provider，不改写业务逻辑或主题 CSS。源码只读要求仍然优先。三个旧示例继续使用原 hook，供存量维护；直接拿来创建新页面时，必须按上述步骤替换主题链路。
 
-Provider 上下文的 `controls` 返回同一组 surface/text/selectedBg/selectedColor/hoverBg/activeBg 等解析值，可供自绘胶囊筛选使用；未能解析时为 null，继续使用 CSS 变量或组件库默认值。选中不是 disabled：保留点击、键盘操作与清晰焦点，单选筛选用受控值或 aria-pressed，真正面板切换才用 tab/tabpanel 语义。圆角、尺寸与间距仍按 design.md，不统一把所有控件改成胶囊。
+## 运行契约
 
-照片分类这类场景建议一行轻量筛选：未选中项中性底与正文色，选中项轻品牌底与清晰文字，选中状态不改变宽度；与说明文字、作品网格分别留出组间距。窄屏按设计横向滚动或换行，不压缩文字至难以辨认。
-
-### 接入规则
-
-- 先提取标准 Provider 再写 Button、Tabs、Segmented、Typography.Link 等业务控件；业务组件整体放在 Provider 内。本页切换时保持 Provider 挂载，新增视图也消费同一主题，不按 Tab 重建硬编码配色的 ConfigProvider。
-- antd 主按钮使用 `type="primary"`，链接使用 `type="link"` 或 Typography.Link；Tabs 保留默认主题交互色。调整内层 ConfigProvider 时只覆盖所需尺寸、圆角，颜色读取上下文解析值。`token.colorPrimary/colorLink`、Tabs 的 inkBarColor/itemSelectedColor 等不要填固定品牌色，也不要直接填未解析的 `var(...)`。
-- 自绘按钮、链接及 Tab 的 normal/hover/active/selected/focus/disabled 都消费应用 CSS 变量；优先提取 `canvas-nav-tabs` 作为受控 Tab 片段。选中逻辑与颜色分开，不能仅初始态跟随主题、点击后切成固定蓝色或 Tailwind 的 `bg-blue-*`。状态色与装饰色仍按业务语义使用。
-- 页面背景使用 `--pod-page-bg-color`，卡片使用 `--pod-card-bg-color`。Provider 已提供根节点背景和最小高度，业务内容负责布局、卡片和装饰。
-- Drawer 的组件级背景单独读取 `--pod-shell-theme-bg-color`，回退 `--color-white`；外壳文字读取 `--pod-page-header-text-color`，回退 `--color-text1-4`。外壳跟随应用框架更新，内部 iframe 继续使用平台页面主题；卡片和通用浮层保留各自底色。
-- Provider 内置表格和 Spin 加载遮罩的防闪边样式：边框固定为零，只对透明度做过渡，避免整页刷新时延迟加载的基础样式触发黑边动画。保留这段样式，不要改回 `transition: all`。旧页面需更新 Provider 并重新发布，修改主题 CSS 不会自动更新页面里的 Provider。
-- antd 自动接收主色、表面、文字、填充和边框色，并应用上述控件状态默认值。成功、警告和错误使用 antd 默认色；尺寸、圆角、字体和图表色组按 design.md 设置。
-- 图表在 PageContent 内调用 `useCanvasThemeContext()` 获取解析后的 token。
-- 弹窗使用 `Modal.useModal`，消息使用上下文 API，holder 放在 Provider 内。
-- 弹层默认使用 antd 的挂载位置。需要继承局部 CSS 时设置 `getPopupContainer`，并检查弹层是否被容器裁剪。
-
-## 4. 检查主题和发布结果
-
-先执行 `openyida compile <输出文件> --json`，再检查实际页面的主色、按钮状态、确认弹窗、延迟加载和换肤效果。用户要求发布时，执行 `openyida publish <输出文件> <appType> <formUuid>`。
-
-编译会检查主题容器是否挂载、入口是否提前读取主题、主题上下文是否放在模块顶层。报错包含位置和调整方法，按提示修正后再次编译。发布后实际打开页面，检查首屏和主题交互；`--health-check` 用于核对保存内容，页面能否正常运行以浏览器结果为准。
-
-编译还会拦截 ConfigProvider 中可确定的固定品牌色覆盖，报 `OPENYIDA_CANVAS_THEME_FIXED_BRAND`。按提示改为标准 Provider 或上下文解析值；仅把色值提到常量中不算修复。动态表达式、自绘 CSS、组件是否实际被 Provider 包住及宿主主题加载仍需验证，静态检查通过不能证明全部控件跟随主题。
-
-验收至少切换两种不同应用主色，再逐一操作主按钮、链接、每个 Tab、禁用控件与弹层，检查选中/悬停/按下/焦点状态；再检查切页返回、异步内容出现后的颜色。只测默认蓝色无法发现写死蓝色的问题。记录实测项，无法使用真实页面时明确保留待验收项。
-
-原始文件仍有 `/* @canvas-theme-provider */` 时，编译和发布会报 `OPENYIDA_CANVAS_THEME_NOT_ASSEMBLED`。按第 2 节生成独立输出文件后编译该输出；不要仅删除标记掩盖尚未接入的 Provider。
-
-Context 返回 `token/status/source/revision`：
-
-| status | 含义与处理 |
-| --- | --- |
-| loading | 正在读取主题 |
-| ready | 已读到应用主色，继续检查页面效果 |
-| preview | 使用本地变量快照，实际应用效果另行验证 |
-| missing | 未读到主色，检查应用 CSS 是否加载 |
-| error | 解析失败，检查主题变量和运行错误 |
+- 默认模式：读取 Provider 实际作用域中的应用变量，由统一 ConfigProvider 传给 antd；不把本地快照覆盖到线上应用。
+- `preview` 模式：使用本地 :root 快照，仅作用于当前页面；移除此属性后恢复应用主题。
+- Context 提供 `token/status/source/revision`；状态为 loading、ready、preview、missing、error。ready 表示读到了主色，不代表整套主题完成视觉验收。revision 是生成快照的 SHA256，不是平台实时版本。
+- 主色未读到时为 missing，解析抛异常时为 error；其他缺失颜色保留 antd 默认值。页面仍可渲染，但 missing/error 不能当成主题验收通过。
+- 当前只自动适配主色、表面、文字、填充和边框。成功/警告/错误沿用 antd 默认；尺寸、圆角、字体、图表色组和完整 CSS 选择器不自动转换。
+- 页面根背景由 Provider 提供；内容区只决定布局、卡片和装饰。不要再包带固定主色的 ConfigProvider。
+- 如需弹层继承局部 CSS，给 Provider 传 getPopupContainer，并验证目标容器不会裁剪浮层；默认保留 antd 的挂载位置。
+- 弹窗使用上下文内 Modal.useModal，消息使用上下文 API，保留 holder 在 Provider 下。不要用静态调用绕过主题。
+- 主题通过祖先属性、head 样式变化、匹配 URL 的 link load 和 resize 更新。CSSOM 更新方需要显式派发 `openyida:theme-change`；平台尚未承诺该事件。
+- 当前适配层不会修改底层 CodeCanvas。将来底层能力验证通过后再迁移，不能提前删掉兼容实现。
 
-其他缺失颜色使用 antd 默认值。`source` 是生成时提供的 URL，`revision` 是本地 CSS 的 SHA256；直接提取的应用主题片段中这两项为空。
+## 验收
 
-Provider 会监听祖先属性、head 样式、主题 link 加载和窗口尺寸变化。用 CSSOM 修改样式的代码需主动派发 `openyida:theme-change`；该事件由修改方负责。
+先 compileCanvasLocal 检查生成页面；再分别验证 preview 和应用主题模式、主题延迟加载、换肤、按钮交互态、确认弹窗、缺失和异常状态。解析色值与颜色对比度仍需实际浏览器验证，脚本成功和编译成功不能替代视觉验收。

package/yida-skills/skills/yida-canvas-custom-page/references/component-library-guide.md

@@ -6,7 +6,7 @@
 
 | 场景 | 推荐库 | 何时使用 | 使用要点 |
 | --- | --- | --- | --- |
-| B 端业务界面 | `antd` | 表格、表单控件、按钮、弹窗、Tabs、Tag、Dropdown、分页 | 按 [CanvasThemeProvider 接入方式](canvas-theme-provider.md) 统一主题；资源加载交给 YidaCodeCanvas runtime |
+| B 端业务界面 | `antd` | 表格、表单控件、按钮、弹窗、Tabs、Tag、Dropdown、分页 | 通过 [CanvasThemeProvider 脚本](canvas-theme-provider.md) 统一接入主题；资源加载交给 YidaCodeCanvas runtime |
 | 图表看板 | `recharts` | 折线、柱状、面积、饼图、简单仪表盘 | 容器必须有稳定高度；颜色用品牌色和语义色，不硬编码默认蓝 |
 | 复杂可视化 | `d3` | 自定义关系图、力导向、桑基、特殊坐标系 | 只在 Recharts 覆盖不了时使用；自己管理 DOM/cleanup |
 | 图标 | `lucide-react`，必要时 `@ant-design/icons` | 按钮、操作、状态、导航等功能性图标 | 默认使用 `lucide-react` named import；antd 语境可使用 `@ant-design/icons` Outlined 图标 |
@@ -73,18 +73,6 @@ import { SearchOutlined, PlusOutlined, EyeOutlined } from '@ant-design/icons';
 
 同一页面选择一套主图标语言。默认主图标语言是 `lucide-react`；选择 `@ant-design/icons` 时，快捷入口、按钮、状态和导航仍然使用具体组件映射。
 
-## 运行时图标校验
-
-图标与底盒分别使用设计中的前景和背景变量，按 [主题一致性门禁](../../yida-design/references/page-quality-gates.md#4-主题一致性门禁) 验收。Lucide 用 `color` / `currentColor` 控制描边，Ant Design 图标用 `color`；不要统一覆盖全页 SVG 的 `fill`，也不要通过父级 opacity 弱化整组图标。
-
-`openyida compile <源文件.canvas.jsx> --json` 和 Canvas 发布前编译都会离线检查 `lucide-react`、`@ant-design/icons` 的实际运行时导出。支持 named import（含别名）、命名空间的静态成员、解构和不可变别名；报错 `OPENYIDA_CANVAS_ICON_EXPORT_UNAVAILABLE` 包含 `packageName`、`exportName`、源码行列、`runtimeAsset` 和 `suggestions`。
-
-不要根据业务词拼造组件名，也不要把最新版 npm / 官网图标目录当成宜搭运行时清单。例如当前运行时没有 `Museum`，可按语义选 `Landmark`；保留原 JSX 名称时写 `import { Landmark as Museum } from 'lucide-react'`。CLI 不会自动替换业务图标。
-
-动态配置应先映射到明确导入的组件：`const Icon = actionIconMap[action] || AlertCircle`。任意 `Icons[name]` 的运行时值不在静态校验保证范围内；优先使用上面的显式映射，不能用动态取值或手写 window 全局绕过报错。默认导入的 `DynamicIcon` 及其既有用法保持兼容，仍需验证实际名称和渲染结果。
-
-导出清单随 CLI 分发，编译不访问 CDN。平台升级图标包时维护者需重新核对运行时资产并更新清单。编译通过和发布回读均不代表浏览器渲染验收通过。
-
 ## emoji 报错时的图标修复
 
 OpenYida 禁止页面源码和 page-spec 中出现 emoji。遇到 `contains emoji` 时，先判断该符号是否承担图标语义：