openyida 2026.9.19 → 2026.9.21

package/yida-skills/skills/yida-create-form-page/references/form-field-properties.md

@@ -18,30 +18,28 @@
 
 ---
 
-## 表单展示/布局组件
+## 表单组件与布局
 
-字段 JSON 中可使用的展示/布局组件如下；生成表单时只从这张清单里选择，不要编造新的布局组件名。
+表单支持在顶部、左侧、主体、右侧和字段之间组合 Tab、按钮组、图片、状态区、`Divider`、`ColumnContainer` 与业务字段。`create-form` 字段 JSON 使用下表中的结构组件；更新表单时保留其他已有组件。
 
-| 组件 | 用法 | 典型场景 |
+| 结构组件 | 用法 | 典型场景 |
 | --- | --- | --- |
 | `Divider` | 作为独立字段插入字段数组，用 `title` 表达章节标题，按页面用途显式选择 `dividerType` | 普通业务分组、章节分隔、字段较多时提升可读性 |
 | `ColumnContainer` | 用二维 `children` 表达多列，每个子数组是一列；内部字段仍按普通字段 JSON 写 | 开始/结束日期、姓名/工号、部门/岗位、金额/币种、联系人/电话等短字段成组 |
-| `GroupContainer` / `PageSection` | 作为容器包住一整块 `children`，标题写 `title`，映射到 `PageSection` | 需要折叠、边框、整块隐藏、整块权限或平台分组容器语义的少量特殊分组 |
-
-默认结构是 `Divider` 做章节标题和分隔，`ColumnContainer` 做局部左右/多列布局。普通业务分组不要用 `GroupContainer` / `PageSection`，它们不是普通章节标题的替代品。
 
 ### 布局决策规则
 
-默认表单是单列。不要为了“更高级”默认把整表改成双列，也不要用 `GroupContainer` / `PageSection` 做普通分组。
+先按业务任务确定区域、组件作用和响应式行为，再选择单列、局部多列、全局双列、卡片或章节布局。不要从字段数量机械推导固定结构，也不要把 `Divider` 当成每个分组的必选组件。
 
-- 默认单列：字段较少、流程表单、移动端优先、长文本、说明、附件、地址、子表、审批意见、需要逐项认真填写的字段。
+- 单列：适合字段较少、流程表单、移动端优先、长文本、附件、地址、子表、审批意见或需要逐项认真填写的内容。
 - 局部多列：短字段且天然成对或成组时使用 `ColumnContainer`，例如开始/结束日期、姓名/工号、部门/岗位、金额/币种、联系人/电话。
-- 全局 `--layout double`：只有用户明确要求“整个表单双列”时才使用；一般更推荐在字段 JSON 内用 `ColumnContainer` 做局部多列。
-- 语义分组：按业务含义分段，不按字段数量平均分。常见分组包括“基本信息”“业务信息”“时间计划”“补充材料”“审批信息”。
+- 全局布局：`--layout single|double|card|section` 设置整表布局起点；按业务和设备选择，再结合页面内容调整组件位置。
+- 语义结构：按业务含义组织区域和层级。普通业务分组和章节分隔使用 `Divider`。
 
-推荐结构：
+常用结构示例：
 
 ```text
+ColumnContainer > Field
 Divider > ColumnContainer > Field
 Divider > Field
 ```
@@ -105,7 +103,7 @@ OpenYida 支持以下 **23 个可见样式**，不接受 `none`（无分割线
 
 `form-fields` 示例仅演示布局，其中的分割线不代表推荐默认值；复用示例时按当前页面重新选择。
 
-把“页面 → 样式 → 选择理由”写在现有 `design.md` 对应页面说明里，Fast 与 Plan 使用同一规则。原生表单通过字段 JSON 配置，Canvas 分组标题参考相同外观原则手写，不向原生表单注入 CSS。
+把“页面 → 样式 → 选择理由”写在现有 `design.md` 对应页面说明里，Fast 与 Plan 使用同一规则。表单结构通过组件树配置，Canvas 分组标题按相同外观原则实现。
 
 未提供样式时 CLI 以 `bold-with-thin` 兜底，不替 AI 决定业务风格。显式的不支持值会报错，不静默替换。`dividerType` 写入 `props.type`；也接受历史别名 `dividerStyle`、`styleType`、`typeStyle` 和 `props.type`，按此前顺序取值，新生成统一用 `dividerType`。
 
@@ -114,7 +112,7 @@ OpenYida 支持以下 **23 个可见样式**，不接受 `none`（无分割线
 | 属性 | 默认值 | 说明 |
 | --- | --- | --- |
 | `behavior` | `"NORMAL"` | 默认状态，支持 `"NORMAL"` / `"HIDDEN"` |
-| `dividerType` | `"bold-with-thin"`（遗漏时兜底） | 从上表按页面选型，写入 Schema 的 `props.type`，不是 CLI 参数 |
+| `dividerType` | `"bold-with-thin"`（遗漏时兜底） | 从上表按页面选型，写入 `Divider.props.type`，不是 CLI 参数 |
 | `showTitle` | `true` | 是否显示标题 |
 | `title` | `"标题"` | 分割线标题，写入 `props.title` |
 | `description` | `""` | 标题描述，写入 `props.description` |
@@ -135,32 +133,11 @@ OpenYida 支持以下 **23 个可见样式**，不接受 `none`（无分割线
 | `rowGap` | `"16px"` | 多行场景行间距，写入 `props.rowGap` |
 | `display` | `"VERTICAL"` | 移动端排列方式，支持 `"VERTICAL"` / `"HORIZONTAL"` |
 | `mobileRowGap` | `"0px"` | 移动端垂直布局行间距 |
-| `children` | `[]` | 二维数组，每个子数组是一列内的字段或展示组件 |
-
-### GroupContainer / PageSection
-
-`GroupContainer` 是 `PageSection` 的别名，映射到 `componentName: "PageSection"`。标题写入 `props.title`，不会写 `props.label`。
+| `children` | `[]` | 二维数组，每个子数组是一列内的字段或其他表单组件 |
 
-默认不要为了普通字段分段而使用本组件。普通分段应写成 `Divider` + 后续字段，横向字段排布应写成 `Divider` + `ColumnContainer`。只有当整块内容需要作为一个容器被折叠、加边框、整体隐藏或承接平台分组样式时，才使用 `GroupContainer` / `PageSection`。
+### 分组组件
 
-| 属性 | 默认值 | 说明 |
-| --- | --- | --- |
-| `behavior` | `"NORMAL"` | 默认状态，支持 `"NORMAL"` / `"HIDDEN"` |
-| `label` / `title` | `"分组"` | 分组标题，写入 `props.title` |
-| `showHeader` | `true` | 是否显示头部 |
-| `tooltip` / `tips` | `""` | 用户提示，写入 `props.tooltip` |
-| `showHeadDivider` | `true` | 是否显示头部分割线 |
-| `sectionHeaderStyle` | `"origin"` | 分组头部样式 |
-| `sectionHeaderBgColor` | `"#0089ff"` | 头部背景配色 |
-| `sectionHeaderTitleColor` | `"#171A1D"` | 标题颜色 |
-| `pcStyle` | `{ "value": "origin" }` | PC 端布局样式 |
-| `showBorder` | `false` | PC 端显示边框 |
-| `withMargin` | `false` | PC 端外边距 |
-| `withPadding` | `true` | PC 端内边距 |
-| `mobileStyle` | `{ "value": "origin" }` | Mobile 端布局样式 |
-| `showBorderMobile` | `false` | Mobile 端显示边框 |
-| `withMarginMobile` | `false` | Mobile 端外边距 |
-| `withPaddingMobile` | `false` | Mobile 端内边距 |
+普通业务分组和章节分隔使用 `Divider`，横向字段排布使用 `ColumnContainer`。
 
 ---
 

package/yida-skills/skills/yida-design/SKILL.md

@@ -3,14 +3,16 @@ name: yida-design
 description: >
   当用户要做完整应用视觉设计、单页 UI 改造、主页面视觉设计、应用主题色或全局换肤时使用。
   完整应用读取共享需求：Fast 并行输出 design.md，Plan 维护视觉事实后由 CLI 生成 design.md。
-  design.md 写主题 token、布局、材质、圆角、密度、呼吸感、组件和状态规则。
+  将导航、应用框架、表单、记录详情和自定义页面一起设计，在 design.md 写入统一的主题 token、布局、材质、形状、间距与状态规则。
 ---
 
 # yida-design
 
 宜搭应用和页面视觉设计技能，输出 `design.md`。
 
-平台变量是必须保留的基础契约，项目主题可按实际需求扩展材质、布局、字体、动效及组件状态变量。先设计效果，再决定变量及其消费位置，不把现有清单当作上限；见 [主题扩展规则](references/application-theme-consistency.md#平台变量是基础项目主题按需扩展)。
+宜搭平台基础变量是平台提供的应用主题基础变量框架。项目主题在这套基础变量上按需扩展材质、布局、字体、动效和组件状态变量。先确定设计效果，再写入对应变量和消费位置；见 [主题扩展规则](references/application-theme-consistency.md#平台基础变量是应用主题基础框架)。
+
+设计导航时，把菜单圆角、三态边框、选中阴影、项高、内距和间距一起写入主题，并在访问态的数据管理页与业务页面检查效果，见 [导航形状与密度的案例经验](references/application-theme-consistency.md#导航形状与密度的案例经验)。
 
 确定风格前，按[设计方向比较](references/theme-selection.md#设计方向比较)以第一直觉为参照，发展两个更有表现力的方向，在当前规划轮次内选定。已有明确视觉要求时，在其范围内完善设计。
 
@@ -64,15 +66,15 @@ Fast、Plan 和单页设计使用相同的 UI 设计规则、主题变量和质
 3. **默认保留平台应用导航**：普通自定义页、页面内 tab、分段、筛选和快捷入口都不触发 `yida-nav-shell`。PRD 的应用工作区选择自定义导航，或用户明确要求自绘应用级导航、隐藏应用导航时，写 `appBlueprint.hideAppNav: 'y'` 并交给 `yida-nav-shell`。独立前台选择自己的菜单时，同样进入 `yida-nav-shell`，但只配置该页独立展示，保留后台应用导航。用户只说全屏、无导航或 `isRenderNav=false` 时，只写页面级隐藏配置。
 4. **同应用页面入口归导航**：同应用页面优先放入平台导航或导航分组；自定义页内容区放当前页动作、原生表单新建/查看、外部链接和跨应用资源。
 5. **表单入口响应式**：新增/提交页 URL 默认使用页面级隐藏导航的 `submission/{formUuid}?isRenderNav=false`；详情页 URL 默认使用 `formDetail/{formUuid}?formInstId={formInstId}&navConfig.layout=1180&isRenderNav=false`，且 `formInstId` 必须来自真实数据记录并优先取 `row.formInstId`；PC 端默认在侧边抽屉中用 iframe 承载宜搭原生表单，抽屉默认半屏 `50vw`，提交页和详情页使用同一宽度规则；移动端整页或新页打开。
-6. **主题文件**：Plan 使用 CLI 返回的 `outputs.theme`；Fast 和已有主题调整按 [主题文件生成与更新](workflow/output-design.md#cli-token-契约fast--plan-共用) 执行。按 [共用主题规则](references/application-theme-consistency.md) 将已选风格落实为 token，并核对生成的 CSS。修改变量要回到设计源后重新生成、上传；仅 CLI 未覆盖且已核实选择器的样式覆盖可在 CSS 末尾小范围追加，不另写脚本生成或重写主题文件。
+6. **主题文件**：主题目录统一包含设计、CSS、表单布局三个文件，导出和生成参数见 [命令与参数](references/application-style-library.md#命令与参数)。Plan 使用 CLI 返回的 `outputs.theme`；Fast 和已有主题调整按 [主题文件生成与更新](workflow/output-design.md#cli-token-契约fast--plan-共用) 执行。按 [共用主题规则](references/application-theme-consistency.md) 将已选风格落实为 token，并核对生成的 CSS。修改变量要回到设计源后重新生成、上传；仅 CLI 未覆盖且已核实选择器的样式覆盖可在 CSS 末尾小范围追加，不另写脚本生成或重写主题文件。
 7. **默认主题先做业务判断**：工作台、门户、列表、详情、普通看板和数据大屏默认都是浅底 / light 模式，但主色不固定为 `podBlue` 或 #1677ff；先根据行业、品牌、业务情绪和视觉目标做创意色彩判断，主题色可以是任意合法 CSS 颜色。只有用户明确说暗色/深色/夜间/高对比时才用深色沉浸。
 8. **页面布局要到可实现粒度**：每个页面至少写清顶部/左侧/主体/右侧/底部区域、核心组件、信息密度、主操作位置、PC/移动端差异和空/载/错态。
 9. **页面丰富度建议**：工作台、首页、门户、看板、展示页和业务入口页推荐规划 8-10 个有业务目的的区块以上，例如上下文标题、状态摘要、主操作、筛选、任务列表、最近记录、动态流、洞察、提醒、空态行动、右侧上下文和底部辅助信息。区块数量不是硬门槛，窄场景、单任务页面或用户明确要求精简时可以更少，但要写清每个区块的业务目的和取舍原因。计数按“区块组”算，不按子项算：`KPI 卡片: 学生总数, 课程总数, 出勤率, 平均分` 只能算 1 个状态摘要区块，`快捷入口: 录入学生/登记成绩/记录考勤/管理课程` 只能算 1 个动作区块；不能用重复 KPI 卡、重复快捷入口或大空白卡凑数量。
 10. **工作台禁低密大卡片套路**：工作台 / 业务首页不能用“标题 + 4 个等宽大 KPI 白卡 + 图标快捷卡 + 大空态白卡”撑首屏。默认改成紧凑状态摘要条、任务/动态列表、最近记录、右侧上下文面板和高频动作；没有真实数据时也展示薄空态行 + 登记入口，不铺大块空白卡片。
 11. **按主题保持形状、密度与呼吸感**：`design.md` 正文写清圆角、密度与呼吸节奏的具体消费方式和必要数值，优先采用选中主题的容器/控件形状与内距、组间距、列表行高。通用业务页参考值只补主题未定义项，不能用固定大圆角、padding 或 gap 覆盖主题。呼吸感来自对齐、分组、层级和节奏，不来自超宽空 KPI 框或空白卡。
 12. **背景与内容层次清晰**：正文说明主题如何用色差、细边界、共容器、留白或材质区分内容。同色画布与面板可通过明确边界和分组成立；渐变、玻璃、阴影按主题规则启用，不强制添加。
-13. **设计风格先选后定制**：先按业务任务、信息拓扑选择风格，再按用户确认的色彩氛围协调页面、卡片、导航、填充、边界和交互。布局、圆角与材质可保留，模板固定灰阶和品牌色面积限制不能覆盖用户要求。“自然绿意”等整体风格不能缩减成只有按钮和 logo 变绿；明确只改强调色或忠实中性参考时才保持原画布。文字保留可读的中性层级，状态保留独立语义。
-14. **应用主题统一**：`app-theme.css` 只在应用级配置，由平台统一作用于应用壳、原生表单、详情页和自定义页面外层。`YidaCodeCanvas` 页面只在 `YidaComp` 内消费 `--color-brand1-*`、`--color-group` 和 `--pod-*`；严禁页面代码修改或向上层注入主题变量。
+13. **模板与自由创意并列**：始终支持[自由创意](references/application-style-library.md)，根据业务独立推演，不要求从模板选择。使用模板时，先按业务任务、信息拓扑选择风格，再按用户确认的色彩氛围协调页面、卡片、导航、填充、边界和交互。布局、圆角与材质可保留，模板固定灰阶和品牌色面积限制不能覆盖用户要求。“自然绿意”等整体风格不能缩减成只有按钮和 logo 变绿；明确只改强调色或忠实中性参考时才保持原画布。文字保留可读的中性层级，状态保留独立语义。
+14. **应用主题统一**：按 [整体主题规则](references/application-theme-consistency.md#导航与应用框架) 一起设计导航、应用框架、提交/编辑表单、记录详情和自定义页面。`app-theme.css` 保存完整主题变量与消费样式。`YidaCodeCanvas` 页面只在 `YidaComp` 内消费 `--color-brand1-*`、`--color-group` 和 `--pod-*`；严禁页面代码修改或向上层注入主题变量。应用包含表单或详情页时，读取 [表单风格规则](references/native-form-styles.md)，将组件布局和只读详情样式写入 `design.md`；视觉值写入应用主题 CSS，结构写入表单配置。
 15. **参考转成可执行选择**：参考 Dribbble / 优秀案例时，落到主色、背景素材、首屏构图、信息密度、动线、区块数量和反默认点。
 16. **页面文案和图标使用专业表达**：渲染文案使用纯文本；图标只使用 `lucide-react` 或 `@ant-design/icons` 的具体组件，默认选择 `lucide-react`，并在 `design.md` 的 `iconSystem` 中写清业务动作、状态、导航和空态到图标组件的映射。emoji 不能改成 CSS 形状、字母占位、Unicode 符号或临时 SVG；如果需要图标，必须映射到上述两类库的具体组件。
 17. **实现交接明确**：设计产物只定义页面结构、视觉系统和验收标准；常规业务图表使用 `yida-rechart`；ECharts 例外只用于用户明确要求复杂 ECharts option 或维护旧图表。

package/yida-skills/skills/yida-design/references/application-style-library.md

@@ -0,0 +1,93 @@
+# 应用风格模板与自由创意
+
+先决定应用的整体设计语言，再让导航、应用框架、首页、自定义页面、提交/编辑表单与记录详情共同使用它。按 [导航与应用框架](application-theme-consistency.md#导航与应用框架) 同时设计表面、状态、边界、形状、文字和间距。模板提供可执行的起点；**自由创意是同等可用的独立路径**，从业务推演，不要求先匹配模板。已有应用沿用其设计，不为单页重选风格。
+
+## 找到和导出
+
+`openyida design-plan catalog --json` 返回模板 `themes` 与独立的 `creativeOption`。全部 34 个主题入口统一采用三文件目录，均可用 `application-style` 导出；其中 18 套应用风格与自由创意仍保留 `collection: application-styles` 分类。目录元数据提供完整设计、CSS 和原生布局的相对路径，可直接定位对应文件。
+
+```bash
+openyida sample yida-design application-style --style-id app-executive --output prd/my-app/style-start
+openyida sample yida-design application-style --style-id free-creative --output prd/my-app/creative-start
+```
+
+每套导出 `design.md`、`app_theme.css`、`form-layout.json`；目标目录中任一同名文件已存在时，CLI 报错并保留原文件。每份 `design.md` 同时包含自定义页面的逐页设计引导，以及表单的组件位置、布局、样式、状态和响应式引导。设计与 CSS 中的品牌颜色保留占位：`--color-brand1-6` 使用 `{{PRIMARY_COLOR}}`，`--color-brand1-1` 按主色生成悬停色，其余品牌档位保持同源。项目占位符与空字段布局是项目化起点；使用时替换真实项目内容、完成最终设计并生成项目主题与表单布局。上传主题时使用项目实际生成的 CSS 路径，`app-theme.css` 与 `app_theme.css` 均可。
+
+## 命令与参数
+
+| 步骤 | 命令与参数 | 输入与结果 |
+| --- | --- | --- |
+| 查询主题 | `openyida design-plan catalog --json` | 从 `themes[].themeId` 或 `creativeOption.themeId` 取值 |
+| 导出三文件 | `openyida sample yida-design application-style --style-id <themeId> --output <目录>` | `--style-id` 必填，支持目录中的全部主题；`--output` 缺省为当前目录下 `.cache/samples/application-style` |
+| 生成或更新 CSS | `openyida sample yida-design app-theme --design-file <design.md> --output <CSS路径>` | 设计中的品牌色和派生颜色先填成实际值；同路径更新保留自定义 CSS，并维护旁边的 `<CSS路径>.tokens.md` 更新记录 |
+| 绑定应用 | `openyida update-app <appType> --theme-file <CSS路径> --nav-theme <light或dark> --layout <side或top或l_shape> --show-app-nav` | 上传后分别核对主题和导航回读，再检查页面实际效果；应用级自绘导航改用 `--hide-app-nav` |
+
+`--style-id` 只用于三文件导出，`--design-file` 只用于主题生成。`--var KEY=VALUE` 用于其他代码示例的占位替换；应用主题的品牌色和导航值写入 `design.md`。`app-theme` 的 `--output` 缺省为 `.cache/samples/app-theme.css`；省略 `--design-file` 会用公共模板重置目标 CSS。三文件导出中的占位 CSS 先经过主题生成，再上传。
+
+`--nav-theme` 选择平台导航明暗，`--layout` 选择结构。平台兼容参数还接受 `white` / `gray`，正式设计使用模板派生的 `light` / `dark`。菜单圆角、普通/悬停/选中边框、选中阴影、项高、内距与间距是[导航 token](application-theme-consistency.md#导航与应用框架)，在 Fast 的设计 token 或 Plan 的 `visualStyle.tokens` 中填写。CLI 读取设计文件后生成消费样式；这些值没有单独的命令行开关。较早的 CSS 在设计提供菜单边框 token 后会补齐缺失的菜单形状规则。四种差异明显的组合及访问态验收方式见[案例经验](application-theme-consistency.md#导航形状与密度的案例经验)。
+
+## 主题明暗双轴
+
+`contentTone` 表示页面画布、卡片、表单、详情、自定义页面和浮层采用浅色或暗色界面；`navTheme` 表示平台导航框架采用浅色或深色。两者是独立维度；命名模板从模板元数据派生导航明暗，自由创意由项目明确设计并配套导航 Token。两者独立选择：深色导航可以搭配浅色内容，浅色导航也可以搭配暗色内容。模板名中的“深色侧栏”描述 `navTheme`，应用整体明暗以 `contentTone` 为准。
+
+## 18 个应用方向
+
+| ID | 风格 | 构图与表单差异 |
+| --- | --- | --- |
+| app-wire | 精密线框 | 工具带、细边界、稳定双列 |
+| app-paper | 奶油手账 | 窄幅纸页、题签、单列长阅读 |
+| app-sage | 植物浮雕 | 柔绿分区、轻内凹、宽松双列 |
+| app-pop | 波普印刷 | 大标题、粗边与硬阴影、二比一布局 |
+| app-neon | 午夜霓虹 | 暗色技术工作区、局部微光、双列 |
+| app-line | 极简下划线 | 窄单列、纯文字标题、强调线 |
+| app-glass | 雾面玻璃 | 雾紫衬底、轻透层次、舒展双列 |
+| app-ticket | 复古票据 | 票据抬头、双线、窄幅键值阅读 |
+| app-editorial | 杂志编辑 | 左侧衬线大标题与导语、右侧正文 |
+| app-terminal | 终端像素 | 等宽标题、点线、紧凑记录集合 |
+| app-platinum | 铂金商务 | 铂灰细线、合同摘要、均衡双列 |
+| app-executive | 墨金行政 | 香槟金标题、左介绍栏、右单列章节 |
+| app-finance | 金融蓝图 | 编号章节、水平标签、紧凑双列 |
+| app-nordic | 北欧云白 | 大段间距、柔白、单列服务流程 |
+| app-teal | 青岚运营 | 状态带、主次二比一、任务流 |
+| app-amber | 琥珀工单 | 三列短字段、长字段跨栏、紧凑工单 |
+| app-graphite | 石墨数据 | 暗色连续表格、细行线、双列 |
+| app-plum | 绛紫咨询 | 衬线导语、双线章节、七比五分栏 |
+
+按业务任务、品牌和使用环境选择风格。暗色方向仅在用户或使用环境明确需要时选择。单行控件的半径、高度、边界、状态与布局一起设计。装饰使用平台已验证的组件和样式能力。
+
+## Fast 与 Plan 如何消费
+
+- **Fast**：选定方向后导出一套起点，按唯一输出契约补成最终 `design.md`；保留模板已有的 `applicationStyle` 消费标记，删除模板 `themeId`，填入真实项目、颜色、页面与引用，完成 `check-design`。然后运行 `openyida sample yida-design app-theme --design-file <design.md> --output <app_theme.css>`。共享生成器会携带这组应用风格的语义类配方，后续重生成保留配方之外的自定义 CSS。
+- **Plan**：`design-plan init` 使用目录中的 `themeId`（`--theme-id`），项目差异放 `visualStyle.tokens`，各页布局写入已有逐页设计。CLI 物化时生成正式 `design.md` 与返回路径中的 `app-theme.css`；文件名沿用 Plan 契约，不另生成第二份应用主题。
+- **实现**：应用级上传一次项目 CSS。导航读取完整的 `tokens.application-global.appearance.navigation`，平台导航保留原变量消费关系，自定义导航由组件明确引用。Canvas 读取设计里的 Token，并可使用 `.oyd-style-workspace`、`.oyd-style-intro`、`.oyd-style-section`；框架、表单和详情应用同一主题。自定义页面落实具体构图。
+- **表单**：先在 `design.md` 写清各区域使用的组件、列比例、间距、长字段整行和移动端重排。`form-layout.json` 提供字段与分栏的初始结构；在各列填入 PRD 字段，并按设计调整布局。`--theme compact` 等参数只设置密度，应用 CSS 负责视觉样式。
+
+表单支持在顶部、左侧、主体、右侧和字段之间放置 Tab、按钮组、图片或图形、标题与 `Divider`、分栏、状态区、辅助内容和字段。各组件分别负责导航切换、操作入口、视觉焦点、状态反馈、内容组织或数据采集。普通业务分组和章节分隔使用 `Divider`，横向字段组合使用 `ColumnContainer`。
+
+编辑已有表单时保留现有组件。列比例按内容与宽度确定；抽屉和 iframe 按实际宽度重排。
+
+## 自由创意必须能独立完成
+
+选择 `free-creative` 表示**不选择任何现成视觉模板**。基础文件只是平台合法 Token 的编写骨架，没有被选中的风格；不要把模板改名充当自由设计。比较候选时必须提供“自由创意：根据这项业务重新推演”这一项；已委托 AI 的 Fast 可直接采用它，不追加无必要确认。
+
+Plan 将下列对象写入 `visualStyle.creativeDirection`；Fast 写入最终设计 frontmatter 的 `creativeDirection`。用真实、具体的项目决策替换说明文字：
+
+```json
+{
+  "businessRationale": "用户、使用频率、业务重点，以及为何采用此视觉方向",
+  "composition": "导航、标题区、主体、上下文区域的位置和宽度",
+  "typography": "正文、标题、数字的字体、层级和对齐关系",
+  "material": "画布、内容面、边界、阴影与状态的关系",
+  "formLayout": "提交、编辑、详情的组件树、顶部/左侧/主体/右侧区域、列比例、间距、底栏和窄屏重排"
+}
+```
+
+Plan 的 `visualStyle.tokens` 必须显式提供：画布 `--pod-page-bg-color`、表面 `--pod-card-bg-color`、文字 `--color-text1-4`、控件 `--form-element-medium-corner` / `--form-element-medium-height`、底栏 `--pod-page-footer-bg-color` / `--pod-sticky-footer-box-shadow`，以及自定义页面 `--oyd-content-width` / `--oyd-content-padding` / `--oyd-field-gap` / `--oyd-heading-font` / `--oyd-heading-size` / `--oyd-rule-style`。其余角色同样按完整设计配套，数据管理外层底栏与按钮内层分别决定。Fast 将这些值写入设计的 Token 分组。缺少决策或关键值时生成器报错，不自动选一套模板。
+
+自由创意还需显式写入 [六个基础导航色](application-theme-consistency.md#导航与应用框架) 与 `navTheme`，并按业务布局设计框架、菜单形状、文字、间距及状态。Fast 与 Plan 使用同一完整主题文件。
+
+## 验收与维护
+
+看应用整体，覆盖导航、自定义页、提交、编辑、详情、数据管理内嵌、抽屉和移动端，核对正文/底栏对齐、背景连续、hover/focus、禁用/错误和窄屏布局。应用主题与表单组件树共同作为验收基线。
+
+维护既有主题时修改对应目录的 `design.md` 与 `form-layout.json`；维护导航时修改 `templates/navigation-styles.json`，维护应用风格预设时修改 `templates/application-styles.json` 与共用配方，再运行 `node scripts/build-application-styles.js`；随后运行模板、Plan/Fast、原生布局测试及 `check:skills`。该脚本仅用于仓库维护，应用搭建使用上述 CLI。

package/yida-skills/skills/yida-design/references/application-theme-consistency.md

@@ -1,10 +1,49 @@
-# 应用与自定义页面共用主题
+# 应用各页面共用主题
 
-Fast、Plan 和单页开发使用同一条链路：设计源文件 → `design.md` 的 token → `app-theme.css` → 平台组件与自定义页面。页面代码负责布局、业务交互和局部装饰，不另建一套基础配色。
+Fast、Plan 和单页开发使用同一条链路：设计源文件 → `design.md` 的 token → `app-theme.css` → 导航、应用框架、原生表单、记录详情与自定义页面。页面代码负责布局、业务交互和局部装饰，基础配色与组件风格统一读取应用主题。
 
-## 平台变量是基础，项目主题按需扩展
+## 导航与应用框架
 
-平台变量清单是必须保留的基础契约，不是主题能力的上限。先根据用户需求设计，再复用已有语义或补充项目变量，不把风格压缩成主色、背景和圆角几项。`app-theme.css` 可以承载完整的项目主题变量，以及有明确消费对象的共享样式。
+设计应用时，同时确定导航、应用框架、提交与编辑表单、记录详情、自定义页面的视觉关系。导航负责说明应用身份、业务层级和当前位置；框架负责组织内容宽度、背景与滚动区域。它们与业务内容共用字体、形状、间距和状态语言，各区域按用途选择表面与强调程度。
+
+先按 [导航决策](navigation-decision.md) 确定菜单、层级、顺序、默认页面及顶部、侧边或 L 型布局，再将外观写入主题。三个设置各管一件事：`navigationType` / `layoutDirection` 表示入口组织和布局，`navTheme` 表示导航明暗模式，导航 token 表示实际颜色、边界、形状、文字与间距。业务布局保持已确认的选择；主题模板为该布局提供视觉样式。
+
+| 设计对象 | 写清的内容 | 与其他页面的关系 |
+| --- | --- | --- |
+| 导航和框架表面 | 导航背景、应用外衬、内容画布及交界处的边框、阴影 | 分清应用外衬、页面、卡片与表单的背景层次 |
+| 菜单状态 | 默认、悬停、选中的文字、图标、背景和标记；实际实现中的焦点、禁用与展开状态 | 选中态表达当前位置，按钮表达操作，分别保证可读性 |
+| 形状与边界 | 菜单项圆角、边框、选中标记、分组分隔及阴影 | 与表单控件、详情数据框和内容容器使用同一套形状规则 |
+| 文字与间距 | 菜单字体、字号、字重、行高、项高、内距和分组间距 | 与页面标题、字段标签、正文和数据密度协调 |
+| 布局与交互 | 导航占位或叠加、内容宽度、滚动、折叠及窄屏菜单 | 按 [连续性规则](page-continuity.md) 保持内容对齐与往返状态 |
+
+命名模板在 `tokens.application-global.appearance.navigation` 提供完整导航 token，并提供对应 `navTheme`。这组变量是导航外观的唯一取值来源，覆盖基础六色，以及模板定义的页头、Logo、分组、搜索、弹层、菜单尺寸、文字、工具按钮、顶部选中线和 L 型框架等角色。项目保留这组变量及其消费规则，将主色和已确认的项目差异合入同一主题；浅色导航可以呈现暖纸、柔绿、雾紫或精密线框，深色导航也按模板保留自己的材质、边界和选中方式。`light` / `dark` 用于选择平台导航模式，具体外观以主题 token 为准。
+
+`free-creative` 按业务独立设计上述关系，并在设计源中显式填写导航明暗与六个基础导航色：导航背景、菜单文字、悬停文字、选中文字、悬停背景和选中背景；其余导航变量按实际设计补齐。变量名以 [基础变量契约](../templates/design-themes/basic-tokens.json) 和当前模板为准，平台变量保留原名，扩展变量说明实际消费位置。项目用到的形状、文字与间距也写入 token，正文解释怎样使用。
+
+平台导航由应用主题及已有平台消费关系实现；自定义导航读取同一份导航 token，并在自身组件内实现形状、布局与交互。只有自定义组件实际引用、或经过核实的平台选择器使用的变量才会改变外观。自定义菜单的聚焦、折叠、拖拽与返回等交互按 `yida-nav-shell` 实现；导航隐藏、权限和页面范围沿用 PRD。
+
+菜单形状使用 `--pod-nav-menu-item-radius`；普通、悬停、选中边框分别使用 `--pod-nav-menu-item-border`、`--pod-nav-menu-item-hover-border`、`--pod-nav-menu-item-selected-border`。三项边框由 OpenYida 主题 CSS 的导航选择器消费，覆盖侧栏、L 型侧栏和顶部菜单。边框填写完整 CSS 值，例如 `none`、`1px solid #AAB7AE`、`3px double #A7744D`；各状态保持同一宽度，避免文字位置跳动。选中阴影继续使用 `--pod-nav-menu-item-selected-shadow`，可与边框组合。验收时查看菜单的实际圆角、线宽、线型和选中标记，分别核对侧栏与顶栏。
+
+Fast 在 `design.md` 的第 2.2 节说明最终导航与框架规则，token 写入 frontmatter；Plan 在 `visualStyle.tokens` 保存项目差异，由 CLI 生成同一设计与主题文件。导航 token 随应用主题一次生成、上传和校验，各页继续消费同一份主题。
+
+### 导航形状与密度的案例经验
+
+比较导航时，把圆角、三态边框、选中阴影、菜单高度、内距和间距作为一组设计。先让菜单轮廓和疏密有清楚的区别，再配合颜色与文字层级。下面四种做法已用于案例应用，并沉淀到对应主题的设计与 CSS；它们提供外观参考，顶部、侧边或 L 型布局仍由业务入口决定。
+
+| 风格 | 轮廓与选中方式 | 密度与框架 |
+| --- | --- | --- |
+| 波普印刷 | 方角、3px 粗墨线，黑底黄字搭配 5px 粉色硬阴影 | 顶部菜单 44px，间距 16px，68px 顶栏给菜单和阴影留空 |
+| 北欧云白 | 999px 胶囊，2px 透明边框预留位置，选中深绿底白字与轻阴影 | 菜单 52px，内距 12px 18px，间距 14px，柔绿侧栏保持舒展 |
+| 复古票据 | 方角、5px 棕色双线，浅纸底选中项配 4px 硬阴影 | 菜单 50px，内距 10px 14px，间距 14px，双线和纸张层次延续到内容 |
+| 终端像素 | 方角、1px 虚线，暗底亮字，左右各 5px 内阴影标记当前位置 | 菜单 36px、间距 4px，紧凑顶栏与侧栏延续日志节奏 |
+
+项目调整时，把具体取值写回设计源，正文说明选择理由和消费位置。品牌色继续使用项目输入；装饰阴影、纸张底色和边框色按各自角色配套。Fast 修改 `design.md`，Plan 修改 `visualStyle.tokens` 后重新生成；维护公共模板时，同时修改导航维护源、生成三文件和索引摘要。项目覆盖某个值后，以生成的项目取值表为准。
+
+验收先看访问态的数据管理页，再看自定义页、提交页和详情页：普通、悬停、选中状态的边框都应可辨；选中状态遇到悬停仍保持当前位置标记。粗边框采用 border-box，并检查内层行高、文字居中和点击区域。外阴影需有周围留白，内阴影保持文字可读；长菜单名、折叠菜单和窄屏也要检查。应用 `/admin` 是开发配置后台，业务使用者看到的导航在访问态验收。
+
+## 平台基础变量是应用主题基础框架
+
+宜搭平台基础变量是平台提供的应用主题基础变量框架，供原生导航、表单、详情页、表格和浮层消费。项目主题保留这些变量的名称与用途，并按用户需求扩展材质、布局、字体、动效和组件状态变量。`app-theme.css` 承载平台基础变量、项目扩展变量及有明确消费对象的共享样式。
 
 - **平台基础**：保留平台变量的名称、用途和必要桥接，给原生导航、表单、表格及浮层使用；项目可以按这些角色调整取值。
 - **项目扩展**：按实际设计补充渐变、纹理、字体层级、内容宽度、栅格间距、材质、阴影、动效和组件状态等变量。这些是可选例子，不是新增必填清单。使用项目或组件语义命名空间；`--oyd-*` 是现有约定，也可使用 `--magazine-*` 等明确前缀，不伪装成平台已支持的变量。
@@ -22,10 +61,12 @@ Fast、Plan 和单页开发使用同一条链路：设计源文件 → `design.m
 | --- | --- |
 | 应用主色及交互色阶 | Plan 的 `forUser.colorStrategy.primaryColor`；Fast 的品牌 token |
 | 页面底、卡片底、文字、填充、边界、全局字体和圆角 | 已有平台语义 token，原生页和自定义页共同消费 |
+| 导航、应用框架与菜单状态 | 完整导航 token 与框架变量，按 [导航与应用框架](#导航与应用框架) 记录消费位置 |
+| 原生表单控件、提交页背景及详情页只读字段数据框 | [原生表单变量、详情只读态与背景分层](native-form-styles.md)，沿用同一主题生成链路 |
 | 平台没有对应角色的色彩、字体、材质、尺寸、动效和组件状态 | 项目扩展 token，由主题 CSS 提供，使用者显式引用 |
 | 分栏、大标题位置、封面构图、单页纹理 | 页面设计与页面代码；需共享或随主题变化的参数引用扩展 token |
 
-例如主色为墨黑 `#1B1B1B`，并已确认奶油画布、暖白面板、橙红装饰标签时，Plan 在 `visualStyle.tokens` 写入以下项目差异；Fast 将同样的变量写入 `design.md.tokens` 对应分组。这个例子不是所有“杂志风”的默认配色，导航六色仍按当前导航方案成组设计。
+例如主色为墨黑 `#1B1B1B`，并已确认奶油画布、暖白面板、橙红装饰标签时，Plan 在 `visualStyle.tokens` 写入以下项目差异；Fast 将同样的变量写入 `design.md.tokens` 对应分组。这个例子只展示当前项目的内容配色，导航仍按完整应用设计配套。选中项阴影由 `--pod-nav-menu-item-selected-shadow` 独立控制。
 
 ```json
 {
@@ -103,7 +144,7 @@ antd 控件按 Canvas 技能接入 `CanvasThemeProvider`，由适配层读取当
 
 ## 验证主题是否真正一致
 
-1. **设计与文件**：逐项对照已确认的主色、页面底、面板、文字、字体及特色强调，确认它们出现在生成的主题 token 中，页面用的是同一角色。文件名叫 `app_theme.css` 或 `app-theme.css` 不影响契约，以本次输出路径为准。
+1. **设计与文件**：逐项对照已确认的导航、框架、主色、页面底、面板、文字、字体及特色强调，确认它们出现在生成的主题 token 中，页面用的是同一角色。导航明暗与模板或自由创意决策一致，导航状态、形状与密度保留本项目设计。文件名叫 `app_theme.css` 或 `app-theme.css` 不影响契约，以本次输出路径为准。
 2. **绑定**：`themeVerification.verified=true` 仅证明应用设置绑定了主题资源。`iframePropagation` 是配置字段，不是当前页面主题加载的检测结果；不能凭它为 `false` 就断言 Canvas 收不到变量，更不能据此改成固定色盘。
-3. **运行态**：应用同时包含原生页和自定义页时，分别检查一个原生列表/表单、一个自定义页及实际存在的抽屉/详情。核对主题资源、实际容器的计算变量、背景和主操作；iframe 单独检查其文档。变量缺失查资源加载与作用域，变量正确但外观不对查页面硬编码与样式覆盖。
+3. **运行态**：检查实际导航及其默认、悬停和选中状态，并对照应用框架、原生列表、提交/编辑表单、记录详情、自定义页及实际存在的抽屉。逐类检查实际存在的页面，核对主题资源、容器计算变量、背景、文字、形状、间距和主操作；iframe 单独检查其文档。变量缺失查资源加载与作用域，变量正确但外观不对查页面硬编码与样式覆盖。
 4. **交付**：原生页共享其组件支持的配色、字体、圆角等主题能力；杂志封面、分栏与特色版式只在有相应布局实现的页面出现。没有运行态证据时明确标记“主题已绑定，跨页面视觉待验证”，不能用编译成功、资源齐全或 fallback 看起来正确代替验收。

package/yida-skills/skills/yida-design/references/ask-human-interaction-contract.md

@@ -152,7 +152,7 @@ Fast / Plan 是面向用户的模式名称，仅在首轮澄清后的模式路
 
 首轮澄清结束后，编排按 [模式路由](design-mode.md) 处理尚未明确的执行方式，并按 [导航决策](navigation-decision.md) 由 AI 确定平台导航或自定义导航及布局。导航没有独立选择或确认轮，用户主动指定时沿用；Plan 将 AI 建议随整体方案展示。`intake.confirmed` 仅表示需求澄清完成，不表示方案获批。
 
-视觉方向与后续映射统一写入 brief 的 `visualSelection`；未选候选不进入有效范围，失效推导同步移除。
+视觉方向与后续映射统一写入 brief 的 `visualSelection`；Plan 没有明确完整视觉方向时，必须使用“应用设计风格”交互展示共用规则生成的三套候选。未选候选不进入有效范围，失效推导同步移除。
 
 ## 搭建计划展示
 

package/yida-skills/skills/yida-design/references/native-form-styles.md

@@ -0,0 +1,208 @@
+# 表单样式与提交页背景
+
+表单通过平台已有变量表达不同风格。按 [整体主题规则](application-theme-consistency.md#导航与应用框架) 将提交、编辑和记录详情与导航、应用框架、自定义页面一起设计，补齐控件、标签、分组、背景和状态。先沿用选中主题，再按填写场景确定具体值，同类表单保持一致。
+
+## 应用风格先于表单选型
+
+**表单支持可组合组件布局，并沿用应用视觉风格。** 顶部、左侧、主体、右侧和字段之间都可放置组件。Tab/切换负责内容切换，按钮组提供操作入口，图片或图形建立视觉焦点，标题与 `Divider`、分栏和状态区组织层级与节奏，字段负责数据采集。每个组件都要有明确作用。普通业务分组和章节分隔使用 `Divider`，横向字段组合使用 `ColumnContainer`。
+
+左侧栏、顶部区、主次分栏和字段间组件都是可用版式。表单支持组合 Tab、按钮、图片、状态区、`Divider`、`ColumnContainer` 和业务字段。为每张表单在 `design.md` 写清组件、区域位置、业务或视觉作用、列宽与窄屏重排，并按抽屉或 iframe 的实际宽度调整。
+
+先读取当前 `design.md` 中已确认的应用风格、字体、表面、线条、圆角、密度与状态规则，再设计提交、编辑和详情页。表单是应用风格的延续，不单独抽取另一套配色或风格；多样性来自不同应用的设计方向，以及同一应用内不同业务任务的合理布局差异，不是让每张表单随机换肤。
+
+| 应用方向示例 | 表单与详情的延续方式 |
+| --- | --- |
+| 杂志编辑风 | 延续标题字体、纸面底色、细线或强调侧线、章节层级和舒展留白；长说明单列，短字段可用主次分栏，详情保留相同阅读节奏 |
+| 精密商务风 | 延续克制圆角、细边界、稳定对齐和紧凑间距，适合成组双列和清晰章节 |
+| 柔和服务风 | 延续低对比表面、柔圆控件和宽松标签间距，优先易读单列或舒展双列 |
+| 高密度运营风 | 延续紧凑控件、明确网格与分组，按字段长度使用多列或横向标签，窄屏收拢 |
+
+这些是推导示例，不是固定行业映射或新增 preset。不能把杂志风等同于某个固定颜色，也不能让所有风格最后都变成相同白卡、相同圆角和相同间距。
+
+在现有 `design.md` 的组件规则及相关页面说明中写清：表单继承了哪些应用特征、主体宽度、列数/比例、标签位置、字段与组间距、分割线、背景层次、底部操作区和响应式，以及详情如何保持一致。无需新增文档或必填机器字段。
+
+## 实现职责与主题交付
+
+- **设计文件**：风格与页面布局写入 `design.md`；Fast 将 token 写入 `tokens.application-global`，Plan 通过 `visualStyle.tokens` 生成同一份 `design.md`。
+- **应用样式**：颜色、字体、控件、状态、背景、详情表面与底栏样式统一进入当前应用的 `app_theme.css` / `app-theme.css`，以实际生成路径为准，通过应用主题设置加载。已有变量优先；需要边框形式、伪元素等额外表达时，仅在核实平台 DOM 后向同一应用 CSS 添加有限作用域规则，并在设计源记录用途。装饰不遮挡输入、不承载必要信息，不用全局 `.next-*` 覆盖所有组件。
+- **表单结构**：列数、字段排列和标签位置使用表单属性、`ColumnContainer` 和 `Divider` 配置；不同控件遵守自身能力。应用 CSS 不替代字段结构，也不重排 DOM、伪造字段或改变提交行为。
+
+表单样式使用已验证的平台变量和组件。修改风格时更新设计源和同一份应用主题文件，所有表单复用该主题文件。
+
+## 控件和标签
+
+| 变量 | 平台消费位置 | 未配置时的消费回退 |
+| --- | --- | --- |
+| `--form-element-medium-corner` | 控件 `border-radius` | `8px` |
+| `--form-element-medium-height` | 单行控件 `height`，部分控件的 `line-height` | `32px` |
+| `--form-element-medium-font-size` | 控件 `font-size` | `14px` |
+| `--input-bg-color` | 输入表面 `background-color` | `#fff` |
+| `--input-border-width` | 输入边框宽度 | `1px` |
+| `--input-border-color` | 输入边框颜色 | `rgba(24, 28, 31, .12)` |
+| `--pod-form-label-color` | 字段标签 `color` | `var(--color-text1-10, rgba(24, 28, 31, .8))` |
+| `--form-top-label-margin-b` | 顶部标签 `margin-bottom` | `0` |
+
+表中的回退不是必须写死的设计值。模板将圆角连接到 `--corner-2`，填充连接到 `--pod-card-bg-color`，边框连接到 `--color-line1-2`，标签连接到 `--color-text1-10`；项目可以按语义单独调整。高度和使用同一变量的行高一起变化，不再增加一个平行行高变量。
+
+以下是不同方向的起点，按主题和真实业务选择，不随机逐字段切换，也不作为 CLI preset：
+
+| 方向 | 控件圆角 / 高度 / 字号 | 填充与边框 | 顶部标签间距 |
+| --- | --- | --- | --- |
+| 紧凑工具表单 | `4px` / `32px` / `14px` | 内容底色、清晰的 `1px` 细边界 | `4px` |
+| 舒展线框表单 | `8px` / `40px` / `14px` | 透明或内容底色、`1px` 细边界 | `8px` |
+| 柔和填充表单 | `12px` / `40px` / `14px` | 与内容表面可辨的弱填充、轻边界 | `8px` |
+| 暖纸登记表单 | `6px` / `40px` / `14px` | 暖白输入、暖灰边界、深色标签 | `6px` |
+
+多行文本、附件、成员选择和子表保留自身布局，不用全局 `input/textarea/.next-*` 规则强制同一高度。顶部标签间距不代表所有字段的行间距。
+
+默认、hover、focus 和只读详情应成套设计，不能只改默认边框后让聚焦跳回另一套风格。核实当前运行时对 `--input-hover-border-color`、`--input-focus-border-color`、`--input-hover-bg-color`、`--input-focus-bg-color` 等变量的消费与作用域后，写入应用主题；不能假定声明在根部就覆盖组件局部变量。焦点保持可辨，错误、警告、禁用保留独立语义。
+
+## 详情页只读字段数据框
+
+表单详情页使用只读字段数据框展示已提交的数据。修改详情页风格时，将以下 token 与表单控件、卡片和页面画布一起设计，并写入同一份应用主题。背景与卡片形成可辨层次，文字沿用正文色，圆角沿用控件或卡片的形状体系；字号、行高、最小高度、内距和字段间距共同决定信息密度。左侧指示线由指示色与内阴影共同表达，可按当前主题保留、弱化或关闭。
+
+| token | 控制的样式 | 推荐关系 |
+| --- | --- | --- |
+| `--pod-field-preview-bg-color` | 数据框 `background` | 从当前内容面或弱填充色推导，与 `--pod-card-bg-color` 保持层次 |
+| `--pod-field-preview-border-radius` | 数据框 `border-radius` | 与表单控件、卡片使用同一圆角体系 |
+| `--pod-field-preview-indicator-color` | 左侧指示线颜色 | 使用当前边界色或主题强调色 |
+| `--pod-field-preview-shadow` | 数据框 `box-shadow` 和左侧指示线 | 需要指示线时使用 `inset 2px 0 0 0 var(--pod-field-preview-indicator-color)`；平面风格可用 `none` |
+| `--pod-field-preview-text-color` | 数据值 `color` | 使用当前正文色并保证与数据框背景的对比度 |
+| `--form-element-medium-font-size` | 数据值 `font-size` | 与编辑态表单值保持同一字号层级 |
+| `--pod-field-preview-gap` | 数据框内部元素间距 | 按图标、文本、标签的组合密度确定 |
+| `--pod-field-preview-line-height` | 数据值 `line-height` | 与字号配套，保证单行和多行内容可读 |
+| `--pod-field-preview-min-height` | 数据框 `min-height` | 与编辑态单行控件高度协调 |
+| `--pod-field-preview-padding` | 数据框 `padding` | 与最小高度、行高共同形成垂直和水平留白 |
+
+独立详情页、数据管理详情、抽屉或 iframe 详情都使用这组应用主题 token。设计时在 `design.md` 记录最终值，通过主题生成命令写入 `app-theme.css`，再上传同一份主题文件；验收时分别检查普通文本、关联记录、日期、人员、长文本和空值，并核对 PC、窄屏和抽屉宽度下的计算样式。
+
+## 底部操作区与宽度对齐
+
+`--pod-page-footer-bg-color` 根据应用主题选择与画布或内容表面协调的实色、半透明或透明；不统一强制透明，也不默认白底。`--pod-sticky-footer-box-shadow` 根据材质和层次选取，可为 `none`。区分外层固定区域与内层按钮容器，避免重复背景、双重阴影和无设计依据的边线。
+
+设计表单主题时，这两个变量必须与控件变量一起显式写入设计源并生成到应用 CSS，不能只在正文写“跟随主题”后沿用模板默认值。Fast 写入 `design.md` 的 `tokens.application-global`；Plan 写入 `visualStyle.tokens` 并物化到 `design.md`。正文说明底栏采用哪个表面及是否需要阴影。
+
+| 变量 | 设计决策 | 示例含义 |
+| --- | --- | --- |
+| `--pod-page-footer-bg-color` | 选择与页面或内容面板协调的底色 | `var(--pod-card-bg-color)` 表示跟随面板；透明仅用于设计需要背景透出的情况 |
+| `--pod-sticky-footer-box-shadow` | 按主题选择平面、柔和悬浮或明确层次 | 平面纸张可用 `none`，浮层可用与主题协调的柔影；不统一套用默认黑色双层阴影 |
+
+主体和底栏使用同一内容宽度与水平对齐基准。不能仅为两者设置相同 `max-width` 就认为已对齐；同时检查包含块、百分比宽度、内边距、边框盒、左右 margin、滚动条和平台规则优先级。应用 CSS 的适配限定在已核实的页面/主题作用域，不把实验中的固定尺寸和高优先级覆盖作为所有应用默认值。
+
+当前灰度源码中，居中模式 `.vc-page-content-1180` 的正文与提交按钮栏共同消费 `--pod-page-content-max-width`；自动宽度使用 `--pod-page-auto-width-margin`。优先调整这两个已有变量，不另写两份 `width:calc(...)` 或实验固定宽度。`--pod-page-padding` 控制 PC 正文内距，`--pod-page-inner-group-spacing` 控制居中模式上下留白；移动端另用 `--pod-page-mobile-margin` / `--pod-page-mobile-padding`。宽度 token 不会自动切换页面的布局模式。
+
+底栏变量按实际渲染场景选择，**导航显隐与底栏类型是两个独立维度**。不能用 `isRenderNav=false`、URL 名称或是否在 iframe 中代替运行态判定。变量名保留平台实际大小写 `--pod-formView-stickyFooter-*`，不另造 `form-view-*` 别名。
+
+`factory.js` 根据 `__formRenderEnv__ === 'DATA_MANAGE'` 添加 `.is-data-manage-footer`；新版提交页且在 iframe 抽屉中另加 `.is-in-drawer-submit-footer`。两者可能同时出现，后者在提交页按钮容器样式中有显式适配。`.is-sticky-v2` 是容器内定位，不能套用固定栏的视口偏移和占位规则。
+
+| 场景 | 背景与阴影 | 其他消费项 |
+| --- | --- | --- |
+| 普通提交（有导航或无导航）/ 抽屉提交的内层按钮容器、详情按钮栏 | `--pod-page-footer-bg-color`、`--pod-sticky-footer-box-shadow` | `--pod-page-footer-border-radius`；该分支外层 `.stickyFooter` 在平台源码中保持透明且无阴影 |
+| 管理页表单视图及 `.is-data-manage-footer` | `--pod-formView-stickyFooter-bg-color`、`--pod-formView-stickyFooter-box-shadow` | `--pod-formView-stickyFooter-border`、`--pod-formView-stickyFooter-border-top`、`--pod-formView-stickyFooter`（圆角） |
+
+需要管理页和独立页一致时，在设计源分别配置对应变量，不能通过一条全局 `.stickyFooter` 覆盖抹平场景差异。两类容器有不同层级，阴影不必相同。
+
+应用包含数据管理内的表单视图时，显式确定 `--pod-formView-stickyFooter-bg-color`、`--pod-formView-stickyFooter-box-shadow`、`--pod-formView-stickyFooter-border`、`--pod-formView-stickyFooter-border-top` 及 `--pod-formView-stickyFooter`（圆角）。高度 `--pod-formView-stickyFooter-height` 同时影响外层、按钮行和占位，改变时检查全部三处。`--pod-formView-stickyFooter-bottom` 用于普通固定提交栏；管理页吸底还消费 `--pod-shell-padding`，不能统一强制 bottom 或 left 为零。`--pod-inDrawer-stickyFooter-*` 虽存在于公共定义中，本轮在该仓库的上述分支未发现直接消费，不能仅凭名称认定它能控制 iframe 提交栏。
+
+底部占位在背景连续的布局内处理，避免底部 margin 露出 body 底色；确需从 margin 改成 padding 时，根据实际固定栏高度保留空间，不盲目复制某个固定值。分别检查独立页面、实际 iframe/抽屉宽度与窄屏，左右边缘需符合设计，最后一个字段及错误提示可完整滚动到操作栏上方。
+
+## 提交页的背景分层
+
+`submission/{formUuid}?isRenderNav=false` 隐藏导航，不会取消应用主题，也不要求纯白背景。PC 抽屉里的 iframe 与独立提交页都需要检查；父页面的 CSS 变量不会自动继承进 iframe。
+
+| 层级 | 既有配置 | 作用范围 |
+| --- | --- | --- |
+| 应用外衬、无导航壳层 | `--pod-app-root-bg-color`、`--pod-app-root-bg-image` | 颜色与图片分开；图片值可为 `none`、渐变或真实 `url(...)` |
+| 页面画布、表单内容区 | `--pod-page-bg-color` | 只接受颜色；新版表单可通过 `--yida-form-content-bgcolor` 消费它 |
+| 卡片表面 | `--pod-card-bg-color` | 控制卡片及引用它的控件，不替代页面背景 |
+| 输入控件内部 | `--input-bg-color` | 独立于外层背景，保证填写内容可读 |
+
+模板通过 `body.pod-premium.page-type-submit .vc-shell-without-nav.pod-premium` 将外衬变量用于新版无导航提交页；平台默认壳层取导航背景，单独声明根背景图变量并不足以显示图片。该规则不修改有导航页面、旧主题或表单字段。渐变或背景图放在外层，内容表面保留可读底色。背景素材必须来自已确定的真实资源，不能让图像妨碍字段阅读；长表单、窄屏和滚动到底部时均应保持连续背景。默认居中靠上、cover、不重复，需要其他铺放方式时在已核实的作用范围调整。
+
+已有表单的 `Page.props.pageStyle`、`contentBgColor` 和 `contentBgColorMobile` 可能保留历史底色；不同运行版本的优先级也可能不同。先查看实际 body、壳层、`.vc-rootcontent` 和控件的计算样式，再通过应用主题或结构化页面属性调整。新表单的透明 `pageStyle` 只是一层默认值，不会自动改变已有表单；表单与详情页视觉统一由应用全局样式管理。
+
+模板显式将 `--yida-form-content-bgcolor` 接到 `--pod-page-bg-color`，避免 DeepContainer 的 inline 变量消费回退到白色。新版 AppThemePage 会过滤 `props.style` 中的自定义属性；因此不能把主题变量写进页面 style 代替应用主题。旧版 LegacyPage 则会在页面局部声明变量，根部设置不保证覆盖它。旧 `.vc-yida-shell-new` 还使用局部 `--vc-form-top-label-margin-b`，并非同名的 `--form-top-label-margin-b`；不要承诺一套 token 改遍所有历史布局。
+
+模板的 hover/focus 边框和 focus 底色已有源码消费者。富文本编辑器使用白色普通背景和固定蓝色焦点阴影时，先核实实际控件，再添加作用域明确的应用级适配，并在验收清单中检查默认、hover 和 focus 状态。
+
+## 写入现有主题源
+
+Fast 将以下变量合并到 `design.md` 的 `tokens.application-global`；Plan 合并到 `build-plan.json` 的 `visualStyle.tokens`，重新物化生成 `design.md` 和 CSS。原有品牌、导航、文字等 token 保留。以下只示范暖纸表单的项目差异，不是所有应用的默认主题：
+
+```json
+{
+  "--form-element-medium-corner": "6px",
+  "--form-element-medium-height": "40px",
+  "--form-element-medium-font-size": "14px",
+  "--input-bg-color": "#FFFCF6",
+  "--input-border-width": "1px",
+  "--input-border-color": "#D8CDBD",
+  "--pod-form-label-color": "#554B40",
+  "--form-top-label-margin-b": "6px",
+  "--pod-field-preview-bg-color": "#F7F1E7",
+  "--pod-field-preview-border-radius": "6px",
+  "--pod-field-preview-indicator-color": "#D8CDBD",
+  "--pod-field-preview-shadow": "inset 2px 0 0 0 var(--pod-field-preview-indicator-color)",
+  "--pod-field-preview-text-color": "#554B40",
+  "--pod-field-preview-gap": "4px",
+  "--pod-field-preview-line-height": "20px",
+  "--pod-field-preview-min-height": "32px",
+  "--pod-field-preview-padding": "0 8px",
+  "--pod-app-root-bg-color": "#F3EBDD",
+  "--pod-app-root-bg-image": "linear-gradient(135deg, #F3EBDD, #E8DDCB)",
+  "--pod-page-bg-color": "#FFFCF6",
+  "--pod-card-bg-color": "#FFFCF6",
+  "--pod-page-footer-bg-color": "var(--pod-card-bg-color)",
+  "--pod-sticky-footer-box-shadow": "none",
+  "--pod-page-footer-border-radius": "6px",
+  "--pod-formView-stickyFooter-bg-color": "var(--pod-page-bg-color)",
+  "--pod-formView-stickyFooter-box-shadow": "none",
+  "--pod-formView-stickyFooter-border": "none",
+  "--pod-formView-stickyFooter-border-top": "1px solid var(--input-border-color)",
+  "--pod-formView-stickyFooter": "0 0 6px 6px"
+}
+```
+
+Fast 更新使用 `openyida sample yida-design app-theme --design-file <design.md> --output <app-theme.css>`；Plan 使用物化结果中的 `outputs.theme`。两条路径都复用现有主题生成器，不新增表单专属主题文件、CLI 参数或一套 preset。已有主题增量更新时保留未修改的变量和定制 CSS。
+
+增量更新不会将新版模板的所有选择器自动合并到旧 CSS。已有主题缺少上述提交页背景规则时，先确认实际 DOM，再将模板中的这一小段规则补入原主题文件；不能省略 `--design-file` 重置整份主题。新建主题已包含该规则。
+
+通过 `openyida update-app <appType> --theme-file <app-theme.css>` 上传并绑定后，读回资源并检查实际页面；本地生成不代表线上生效。已有表单的字段更新不需要重新建表。
+
+## 验证
+
+### 新主题页面消费清单
+
+以下按 `vc-deep-yida` 中的实际消费分组；已有模板变量优先配置，不重复添加同名声明，也不把旧分支或注释里的变量算作新主题能力。
+
+| 页面 / 区域 | 已确认消费的 token | 检查范围 |
+| --- | --- | --- |
+| 提交 / 编辑原生表单 | `--pod-form-label-color`、`--yida-form-content-bgcolor`、控件自身的 `--form-element-medium-*` / `--input-*` | 新版 AppThemePage 不接收页面 style 中的变量；控件逐项核对，不能沿用 LegacyPage 密度映射的假设 |
+| 管理页标题及内容 | `--pod-data-manager-title-padding`、`--pod-page-data-manage-top-padding`、`--pod-page-padding` | 消费在管理页容器，Shell 也有覆盖；不是单张表单字段间距 |
+| 管理页表单视图底栏 | `--pod-formView-stickyFooter-*` | 核对 DATA_MANAGE、抽屉提交标记，以及 fixed / sticky-v2 模式 |
+| 详情页只读字段数据框 | `--pod-field-preview-bg-color`、`--pod-field-preview-border-radius`、`--pod-field-preview-indicator-color`、`--pod-field-preview-shadow`、`--pod-field-preview-text-color`、`--form-element-medium-font-size`、`--pod-field-preview-gap`、`--pod-field-preview-line-height`、`--pod-field-preview-min-height`、`--pod-field-preview-padding` | 核对数据框与卡片、编辑态控件的色彩、形状、排版和密度关系，并检查长文本与空值 |
+| 详情卡片 / 自定义详情 | `--pod-card-bg-color`、`--pod-card-border`、`--pod-card-border-radius`、`--pod-page-inner-group-spacing`、`--pod-page-auto-width-margin` | PC 详情仍有固定最小宽度，不把提交页断点视为详情已支持移动布局 |
+| 详情记录历史 | `--pod-card-padding`、`--pod-card-bg-color`、`--pod-card-border`、`--pod-card-border-radius` | 历史面板仍有固定 max-width，源码中注释掉的内容宽度 token 不算有效消费 |
+| 门户 / 展示页卡片 | `--pod-card-*`、`--pod-page-inner-group-spacing` | 门户会在特定场景局部重新声明卡片边框，需检查实际作用域 |
+| 移动表单 / 移动详情 | `--pod-form-label-color`、`--pod-page-mobile-margin`、`--pod-page-mobile-padding`；详情还用页面背景、组间距和外边距 | 移动端 Meet 控件与安全区有自己的消费路径，不把 PC StickyFooter 规则复制过去 |
+
+公共定义中的 `--pod-detail-*`、`--pod-field-preview-*` 继续保留，但完整只读详情还涉及访问态 owner；不能仅凭本仓库的卡片样式就宣布所有详情字段已覆盖。同样，`--form-element-table-padding`、`--form-icon-scale` 等在本次页面扫描中落在 legacy 路径，不为“补齐 token”而迁到全局新主题。
+
+### 场景验收
+
+- 查看控件包装层、输入文字和标签的计算样式，确认圆角、高度、字号、填充、边框和标签间距实际生效，不能只检查 `:root` 中是否出现变量。
+- 分别查看外层背景、表单内容底色和控件填充；外层渐变不能写入 `background-color`。遇到历史 inline 样式，查清来源后只改目标配置。
+- 核对长标签、多行文本、选择器、日期、附件、子表，以及焦点、错误和禁用状态；单行行高不能截断内容。
+- 检查设计源与生成的应用 CSS 均含显式的 `--pod-page-footer-bg-color`、`--pod-sticky-footer-box-shadow`；再检查底栏实际计算的背景和阴影，排除组件局部变量或旧 CSS 覆盖，不能只检查根变量存在。
+- 检查独立提交页、PC 抽屉 iframe、移动端及底部操作区；固定提交按钮不能遮挡最后一个字段。移动端按其实际组件能力验证，不声称 PC token 全部等效。
+- PC 分别检查有导航提交、无导航提交、数据管理表单视图、iframe 抽屉提交和详情；有导航时检查侧栏展开/折叠，不手写固定 left 补偿；管理页分别检查 fixed 与 sticky-v2。模板底部 padding 适配按实际固定底栏标记命中，不再依赖无导航 Shell。
+- 新版主题、旧版主题与已保存页面分别验证。没有运行态证据时，交付注明“主题已生成/绑定，视觉待验证”。
+
+### 本轮源码核对依据
+
+2026-09-19 拉取的 `origin/trunk-theme-gray`：`yc-common` 为 `5b1a7e0`，`yida-shell` 为 `ec03a98`，`vc-deep-yida` 为 `63d0d5977`。后续适配需重新核对分支，不将此快照视为永久契约。
+
+- `yc-common/styles/_pod_common.scss`：Pod 变量定义；模板已覆盖该文件的变量名，不因默认颜色不同就批量替换主题设计值。
+- `yida-shell/src/YidaShell/yida-app-theme.scss`：正文宽度、margin、padding 与无导航容器；`src/Basic/pc.scss`：旧 Shell 标签间距的局部变量。
+- `vc-deep-yida/src/vc-form-container/view.less`：两类底栏；`src/vc-page-yida/form/view.less`：提交页底部占位；`src/vc-page-yida/detail/view.less`：详情按钮栏。
+- `vc-deep-yida/src/components/deep-container/index.tsx`、`src/vc-page-yida/component/container/{appTheme,legacy}/page.jsx`：内容背景与变量来源；`src/components/deep-editor-field/main.scss`：富文本状态及硬编码边界。