Yida Theme
Designyida-themeYida Theme is an Agent Skill for design published in the openyida/openyida repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
宜搭应用主题色与全局主题变量配置技能。用于应用级换肤、主题 token 设计、style#yida-global-theme 注入、Divider/布局/看板/数据管理等跨模块主题一致性处理。
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/openyida/openyida/blob/HEAD/yida-skills/skills/yida-theme/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/yida-theme, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
宜搭应用主题色与全局主题变量
适用场景
当用户提到以下诉求时使用本技能:
- 应用主题色、品牌色、换肤、整体视觉风格、全局颜色策略
--color-brand1-*、--color-brand-*、--color-groupstyle#yida-global-theme、主题 CSS 注入、普通应用缺少主题变量- Divider 分割线、布局容器、看板、数据管理、门户、移动端主题不一致
- 讨论是否使用
useCustomStyle、enableCustomThemeStyle - 需要在 Tianshu / yc-utils / yida-shell / yida-app / yida-next 中设计主题配置链路
如果只是创建字段结构,不涉及颜色策略,回到 yida-create-form-page。如果只是自定义页面视觉方向,先用 yida-page-uiux 定方向;涉及应用级主题 token 或注入时再读本技能。
严格禁止
- 不要只为了“好看”在 Schema 或 JSX 中随机硬编码品牌色。
- 不要把主题色能力理解成表单专用。shell、应用布局、工作台、数据管理、门户、看板、基础组件都会消费主题变量。
- 不要改写未知的主题字段名。短期配置可叫
useCustomStyle,长期推荐enableCustomThemeStyle/customThemeStyle。 - 不要把黑色、深灰、灰黑中性色作为普通应用的默认主题色;只有用户明确要求暗色模式、高对比、奢侈品牌或极简黑色视觉时才选择。
核心原则
- 应用级主题优先。用户说“整个应用/全局/系统整体/左侧导航/菜单/顶部壳层一起换色”时,按应用主题处理,不只改某个页面或表单。
- 页面级主题次之。用户只说“这个页面/首页/看板美化或换色”时,优先在页面内控制,不污染应用全局。
- 表单与流程表单只消费主题。Divider、ColumnContainer、PageSection 等组件应跟随应用主题变量;普通分组不要单独硬编码色值。
- 注入位置越早越好。长期应由 Tianshu 在 layout head 注入
style#yida-global-theme;运行时脚本注入只能作为短期兜底。 - 保持
style#yida-global-theme的 id 和:root { ... }结构。yc-data-manage等代码会读取这个 style 节点解析变量。 - 普通应用主题色优先选有明确品牌识别度的蓝、青、绿、紫、橙等色相;黑灰只适合作为文字、分割线、背景层或明确暗色场景的辅助色。
--theme 预置值与自定义主题边界
openyida create-app --theme <key> / openyida update-app --theme <key> 只能填写平台预置主题 key,不能填 AI 自己设计的任意主题名或色值。
允许值:
| key | 颜色倾向 |
|---|---|
deepBlue | 深蓝 |
podBlue | 蓝色 |
royalBlue | 皇家蓝 |
lightBlue | 浅蓝 |
teal | 青色 |
podGreen | 绿色 |
deepPurple | 深紫 |
purple | 紫色 |
podOrange | 橙色 |
yellow | 黄色 |
magenta | 玫红 |
red | 红色 |
greyBlue | 灰蓝 |
coffee | 咖啡 |
black | 黑色 |
如果设计的是“活力橙”“深玫红”“高级暗黑金”“自定义蓝紫渐变”等非预置视觉,处理方式是:
- 不要把自定义名字传给
--theme。应用colour仍使用最接近的预置 key 作为 fallback,例如通用展示应用用podBlue。 - 每个自定义页面都要注入主题变量:在 Canvas / 普通自定义页中注入或输出
style#yida-global-theme,至少包含--color-brand1-6、--color-brand1-9、--color-brand1-2、--color-brand-1~--color-brand-4、--color-group。 - 页面级 sample 默认独立主题:官方 sample 展示应用、模板画廊、演示页必须在每个页面里带自己的页面级主题 token;否则宿主应用如果是
black,所有页面会被全局黑灰变量染黑。 - 应用级自定义主题才写全局 token:只有用户明确要整个应用统一自定义品牌色时,才规划
enableCustomThemeStyle/customThemeStyle.tokens或 Tianshu head 注入;否则保持页面级注入,避免污染其他页面。
主题变量语义
这些变量是设计语义,不要求每次都直接写入字段 JSON;它们用于指导颜色选择和避免乱用硬编码色值。
| 变量 | 语义 | 典型影响 |
|---|---|---|
--color-brand1-1 | hover / 高亮辅助色 | hover、outline、辅助强调、部分 shell 渐变 |
--color-brand1-2 | 浅背景 / 导航浅色 | Divider light 背景、工作台浅背景、顶部 Banner、轻量容器底色 |
--color-brand1-3 | 背景层 / 空间浅色 | 空间主题背景层、弱背景渐变 |
--color-brand1-6 | 主品牌色 | Divider 主色、主按钮、激活文字、重点边框 |
--color-brand1-9 | 深选中态 | pressed/active 深色、深色强调文字、深色选中背景 |
--color-brand1-10 | 禁用 / 弱化主题色 | disabled、半透明主题色、弱化背景 |
--color-brand-1 ~ --color-brand-4 | 移动端/旧版 token 桥接 | 移动表单、数据管理、旧组件主题色 |
--color-group | 多色序列 | 图表、多色标签、分组色板 |
常用设计判断:
- 主操作、激活状态、Divider 主线条:优先跟随
--color-brand1-6。 - 浅色分组底、轻提示背景、Divider light 背景:优先跟随
--color-brand1-2。 - 深色 active/pressed/选中:优先跟随
--color-brand1-9。 - 图表、多色标签、业务状态色板:优先使用
--color-group或平台图表色板。
推荐配置结构
长期建议把“是否启用自定义主题”和“具体 token”拆开:
{
"enableCustomThemeStyle": "true",
"customThemeStyle": {
"source": "openyida",
"themeKey": "deepBlue",
"version": 1,
"tokens": {
"--color-brand1-1": "rgba(116, 135, 236, 1)",
"--color-brand1-2": "rgba(232, 235, 252, 1)",
"--color-brand1-3": "rgba(57, 84, 228, 0.2)",
"--color-brand1-6": "rgba(57, 84, 228, 1)",
"--color-brand1-9": "rgba(42, 61, 159, 1)",
"--color-brand1-10": "rgba(57, 84, 228, 0.3)",
"--color-brand-1": "rgba(57, 84, 228, 0.3)",
"--color-brand-2": "rgba(116, 135, 236, 1)",
"--color-brand-3": "rgba(57, 84, 228, 1)",
"--color-brand-4": "rgba(42, 61, 159, 1)",
"--color-group": "rgba(57, 84, 228, 1),rgba(0, 122, 255, 1),rgba(138, 92, 253, 1),rgba(30, 41, 128, 1),rgba(255, 107, 53, 1),rgba(0, 200, 255, 1)"
}
}
}
字段说明:
| 字段 | 作用 |
|---|---|
enableCustomThemeStyle | 是否启用自定义主题 style 注入 |
customThemeStyle.themeKey | 预置主题 key,如 deepBlue、podBlue、coffee |
customThemeStyle.tokens | 最终注入到 style#yida-global-theme 的 token map |
customThemeStyle.source | 来源追踪,如 openyida、ai-agent、manual,不控制能力 |
customThemeStyle.version | token 结构版本,便于兼容升级 |
渲染优先级建议:
enableCustomThemeStyle=true且customThemeStyle.tokens非空:直接注入 tokens。- 有
customThemeStyle.themeKey但没有 tokens:从统一主题矩阵按 themeKey 取 tokens。 - 有
themeConfig.themeColor:用generateTheme(themeColor)兜底。 - 只有
colour:按旧逻辑加载${colour}.min.css,并可从主题矩阵生成 CSS var。 - 都没有:使用平台默认主题。
colour/theme 与自定义 token 的关系
只注入自定义 CSS token 但不改 colour / theme 会形成混合状态:
- 会生效:使用 CSS var 的组件,如 Divider、部分 shell active/hover、数据管理操作色、移动端若干组件。
- 不完全生效:
${colour}.min.css、图标颜色、应用设置展示、导航预览、应用卡片、旧 CSS class 或 Sass 编译变量。 - 风险:配置显示仍是旧主题,但运行态视觉是新主题;应用复制、导出、导入或模板化时,如果没有持久化
customThemeStyle,主题可能丢失。
处理建议:
- 如果自定义主题对应已有平台主题,同步
colour为最接近的主题 key,让配置展示、图标、预览更一致。 - 如果是任意品牌色,保留
colour作为 legacy fallback,同时写入customThemeStyle.tokens作为运行态真实主题。 - UI 上应显示“当前启用自定义主题”,避免用户看到
colour=orange但页面实际是另一套颜色。
主题注入方案
长期方案:Tianshu head 注入
推荐由 Tianshu 在页面 layout head 阶段注入:
<style id="yida-global-theme">
:root {
--color-brand1-6: rgba(57, 84, 228, 1);
--color-brand1-9: rgba(42, 61, 159, 1);
--color-brand1-2: rgba(232, 235, 252, 1);
--color-group: rgba(57, 84, 228, 1),rgba(0, 122, 255, 1),rgba(138, 92, 253, 1),rgba(30, 41, 128, 1),rgba(255, 107, 53, 1),rgba(0, 200, 255, 1);
}
</style>
Tianshu 改动建议:
AppConfigType增加ENABLE_CUSTOM_THEME_STYLE和CUSTOM_THEME_STYLE。AppRegisterVO/AppRegisterVoAdapter暴露这两个配置。CommonContextBuilder/BaseAction放入模板上下文。layout/inst/formSubmit.vm、formEdit.vm、taskDetail.vm、pageView.vm、instStart.vm等 head 中尽量靠前注入。screen/inst/*.vm的window.pageConfig/window.g_config透出同名字段,便于前端兜底。
短期方案:运行时注入
普通应用尚未在 head 注入时,可以用运行时脚本兜底:
function injectYidaGlobalTheme(tokens) {
function inject(doc) {
if (!doc || !doc.head) return;
var style = doc.getElementById('yida-global-theme');
if (!style) {
style = doc.createElement('style');
style.id = 'yida-global-theme';
doc.head.insertBefore(style, doc.head.firstChild);
}
style.textContent = ':root {' + Object.keys(tokens).map(function (key) {
return key + ': ' + tokens[key] + ';';
}).join('') + '}';
}
inject(window.document);
try {
if (window.top && window.top !== window) {
inject(window.top.document);
}
} catch (e) {
// cross-origin top cannot be written
}
}
短期方案边界:
- 它晚于页面 head 加载,可能有首屏闪动。
- 跨域
window.top不能写,只能静默跳过。 - 如果更早的 CSS/JS 已解析过
style#yida-global-theme,运行时注入可能偏晚。
OpenYida 使用建议
- 创建完整应用时,如果用户提出品牌色或主题诉求,先判断主题作用域是
app还是page。 - 创建表单或流程表单时,普通分组用
Divider并保持主题模式;不要在每个 Divider 上写随机自定义色。 - 生成自定义页面时,页面局部主题可以使用页面 CSS token;只有要影响 shell、表单、数据管理、门户等全局区域时,才走应用级主题配置。
- 碰到普通应用缺少 Divider 主题变量时,OpenYida 可以注入运行时
style#yida-global-theme兜底,但这不替代长期 Tianshu head 注入。 - 需要跨模块统一主题时,应输出一份
customThemeStyle.tokens,并说明是否同步colour。 - 修改已有应用主题时,不要只相信更新接口回包。必须回读
getAppIncludingAecpInfo,确认colour与config.COLOUR都变为目标主题;页面运行态再刷新检查style#yida-global-theme。 updateAppName类轻量接口可能返回成功但忽略colour/icon/navTheme/layoutDirection。涉及主题、图标、导航或布局时,应先回读当前应用详情,再用updateApp携带现有壳层字段保存;其中接口实际接收字段是mode,即使错误文案写的是appMode。- 官方 sample 展示应用如果只是承载样例库,应用全局主题优先用通用蓝色(如
podBlue)作为中性底座;每个 sample 页面再用页面级固定主题形成差异化,避免宿主黑灰主题污染所有样例。
官方 sample 主题验收纪律
处理官方 Samples 展示应用或模板画廊时,把“应用主题”和“页面主题”分开验收:
- 应用壳层需要蓝色或中性底座时,使用平台预置值,例如
openyida update-app <appType> --theme podBlue。不要把“活力橙”“深玫红”“暗黑金”等自定义名字传给--theme。 - 每个 sample 页面必须自带页面级
style#yida-global-theme或等价 scoped tokens,确保页面刷新后不会被宿主应用的black/ 灰黑变量污染。 - 页面级自定义主题要覆盖导航、按钮、标签、图表色板和浅背景,不只改 hero 或几张卡片。
- 修改应用主题后必须回读应用详情,确认
colour与config.COLOUR都是目标预置 key;修改页面主题后用 schema / runtimeCode grep 确认style#yida-global-theme已随页面发布。
验证清单
- 普通表单、流程表单、详情页、提交页都能读取主题变量。
- shell 导航、工作台、数据管理、门户组件颜色不串色。
style#yida-global-themeid 保持不变,yc-data-manage可解析。- 应用编辑态仍可进入,字段配置项没有被 AIOA / Pod Premium 误隐藏。
- 自定义 token 与
colour不一致时,配置 UI 有明确提示或 fallback。 - 已有应用换主题后,详情接口回读
colour/config.COLOUR/icon/iconUrl/navTheme/layoutDirection,不要只看 CLI success。