Opendesign Design

Design Skill · Pixso 组件系统

🎨 设计师第一次使用？ → 先读 references/designer-guide.md，里面有角色决策树、规范速览卡和推荐交互方式。核心建议：逐楼层生成，不要一次性生成整页——逐楼层还原度远高于整页一次性生成。

💡 本文件为 AI 执行入口，仅包含生成设计稿所需的指令与约束。完整使用说明、目录结构、协议信息请查看 README.md；请勿全量加载所有子文件，按工作流按需读取即可。

🔴 生成任何设计稿前，必读以下硬约束文档：

1. global/hard-constraints.md — 变量映射硬约束 + 组件组合规则（合并版）：PC / MB 双断点下，字号 / 行高 / 间距 / 栅格 / 图标尺寸的合法取值白名单，以及按钮对齐 / 排列 / 间距、组件栅格挂靠、卡片间距、禁止组合黑名单及自动校验清单。所有几何数值必须严格选自该白名单，禁止四舍五入、推断或造数。

以上约束最高优先级，与下文 #图标处理规范（核心约束） 并列，缺一不可。

数据资源

栅格、响应式断点、设计变量等数据来自 atomgit 上游仓库。使用时通过 WebFetch 实时拉取最新版本，不要 bundle 到本地：

本 skill 内 bundled 的索引文件（设计稿生产专用，无上游真源）：

• references/pixso-mcp-adapter/component-keys.md — 536 个 UI 组件变体的 componentKey 索引
• references/pixso-mcp-adapter/icon-keys.md — 187 个图标的 componentKey 索引

组件索引

每个组件的详细设计规范见 components/{name}.md，涵盖适用场景、变体说明、布局规格、颜色/字体 Token 映射、识别特征。

图标处理规范（核心约束）

⚠️ 本节规则优先级最高，所有生成步骤必须遵守。

图标存储机制

OpenEuler 设计系统中，图标以 svgSha 外部引用方式存储在 Pixso 服务器上（非内嵌 SVG 路径）。这意味着：

• 图标 SVG 数据不存在于 DSL 中，无法通过工具直接提取路径
• code_to_design 内嵌的任何 SVG 均为通用占位符，不属于设计系统图标
• create_instance 生成的组件实例自带正确图标，由 Pixso 在渲染时从服务器解析

图标库资源

OpenEuler 拥有独立图标库 Pixso 文件 kbqInwBrCTGnM0MsPJDgvA，包含 187 个线性图标（24×24px）。完整索引见 references/pixso-mcp-adapter/icon-keys.md。

图标使用规则

SVG 来源优先级（所有场景统一）：① references/assets/ 已有文件（Read 内联）→ ② 手写符合线性风格的 SVG 路径 → ③ CSS（兜底，需注释）

SVG 内嵌方式：直接将 <svg> 标签写入 HTML，不使用 <img src>。图标颜色跟随设计系统 Token，默认使用 currentColor 继承父元素色值。

create_instance 仍可用于需要 live Symbol 绑定或 Token 联动的特殊场景，但不再作为图标的强制路径。

执行工作流

⚠️ 核心原则：逐楼层生成，不要一次性生成整页。 一次性处理整页所有组件规范会导致上下文溢出、细节丢失。逐楼层生成时，AI 每次只需处理 1~2 个组件规范，还原度显著更高。

第零步：读取硬约束文档 + 拉取上游Token（强制起手式）

读取 global/hard-constraints.md
   — 锁定当前目标设备（MB 或 PC）
   — 明确该设备下字号 / 行高 / 间距 / 栅格 / 图标尺寸的合法取值集合
   — 明确按钮对齐 / 排列优先级 / 间距规则
   — 明确组件栅格挂靠要求、卡片间距规则
   — 明确禁止组合黑名单（Banner 嵌套、多尺寸 Banner 并排、按钮位置等）

WebFetch 拉取 openEuler 主题 Token（必须执行！）
   → https://raw.atomgit.com/openeuler/opendesign-token/raw/master/packages/opendesign-token/tokens/openeuler-token.json
   — 将 JSON 中的颜色/字号/间距变量翻译为 :root CSS 变量
   — ⚠️ 禁止凭训练数据"猜测"颜色值！尤其是 --o-color-fill1（页面背景=浅灰，不是纯白）
   — 拉取失败时：使用 references/designer-guide.md 中的 Token 语义速查表作为降级数据源

后续所有步骤的几何数值必须落在硬约束的白名单内，组件排布必须符合组合规则。无法对应到约束的需求 → 停下询问用户，禁止造数或静默放行。

第一步：规划页面楼层结构

根据用户需求，将页面拆解为楼层序列。所有落地页遵循固定结构（见 hard-constraints.md §8）：

导航楼层（必选）→ [Banner 楼层]（可选）→ 楼层 1 → 楼层 2 → … → 页脚楼层（必选）

向用户输出楼层规划，等待确认后才能继续：

我理解本次页面由以下楼层组成，请确认或调整：
  1. 导航楼层（ONavigation）
  2. Banner 楼层（OBanner，XL/L/M/无）
  3. 功能介绍楼层（OCard × N 栅格）
  4. 数据统计楼层（自定义数字 + 描述）
  5. 页脚楼层（ONavigation Footer）

请确认每个楼层的类型和内容，确认后我将逐楼层读取规范并生成。

楼层模板速查见 #楼层模板索引。用户确认后，进入逐楼层循环。

第二步：读取设计规范（全局，仅执行一次）

使用 get_variable_sets 获取当前文件所有变量集合
使用 get_variables(variableSetId) 读取具体变量值（颜色/字号/间距等）
使用 get_local_styles 获取本地样式（填充色/描边/文字样式）

如需对照上游 Token 真源（语义化变量名、栅格断点），通过 WebFetch 拉取 #数据资源 中的三个 atomgit URL。

逐楼层循环（第三步 ~ 第六步，每个楼层执行一轮）

🔄 对第一步规划中的每个楼层，依次执行第三步到第六步。每次只处理一个楼层，完成验证后再进入下一个楼层。

第三步：确认本楼层涉及的组件

仅列出当前楼层用到的组件，不是整页所有组件：

当前楼层：[楼层名称]
涉及组件：
  - OCard（封面卡片，vertical）
  - OButton（solid + outline）
  - OTag（分类标签）

确认后我将读取对应规范。

用户确认后，逐一读取每个组件的 components/{name}.md，全部读取完毕才能进入下一步。

第四步：读取本楼层组件规范与资源

1. 读取本楼层涉及的每个 components/{name}.md
2. 如有楼层模板（floors/{type}.md），读取模板获取完整规格
3. 检查图标资源：
   ls references/assets/<组件名>/
   有文件 → Read 每个文件，全部内联到 HTML 对应位置
   无文件 → 手写线性风格 SVG 路径，注释注明「assets 中无资源」
4. 独立图标：查 references/pixso-mcp-adapter/icon-keys.md 按中文名匹配

第五步：生成本楼层

选择生成模式（全页统一，首次确定后后续楼层沿用）：

模式 A：code_to_design(htmlStr) — 当前楼层的 HTML 片段，包含精确位置与像素级样式

模式 B：生成当前楼层的独立 HTML 片段（含内联 CSS），后续在第七步组装为完整页面

第六步：验证本楼层

逐项核对本楼层的硬约束自检清单：
□ 字号是否来自该设备列的字号集合？字号与行高是否成对？
□ 间距是否来自该设备列的间距集合？
□ 卡片间距是否为 PC 32px / MB 12px？
□ 按钮是否左对齐、solid 唯一、间距 24px？
□ 所有组件是否挂靠栅格容器？
□ 【HTML栅格】楼层内容容器 width + max-width 是否为 1488px（PC）/ 312px（MB）？（禁止 1200px / 1140px / 960px）
□ 【HTML栅格】楼层内容容器是否使用 margin-left: 216px + margin-right: 216px（PC）/ margin-left: 24px + margin-right: 24px（MB）？（禁止 `margin: 0 auto` + `padding: 0 216px` 组合）
□ 【HTML栅格】楼层内容容器 padding 是否为 0？（禁止用 padding 控制楼层边距，padding 仅用于组件内部间距）
□ 【HTML栅格】验证：margin-left + width + margin-right = 画布宽度（PC: 216+1488+216=1920 / MB: 24+312+24=360）
□ 【HTML颜色】`:root` 中的颜色值是否来自上游Token（openeuler-token.json），而非凭训练数据猜测？（尤其检查 `--o-color-fill1` 是否误写为纯白 `#FFFFFF`）
□ 【HTML颜色】`body` 的 `background-color` 是否使用 `var(--o-color-fill1)`？（禁止 `#FFFFFF` / `white`）

模式 A：get_node_dsl(itemId) + get_image(itemId) 验证
模式 B：在浏览器中打开 HTML 片段验证

验证不通过 → 修正后重验，通过后才进入下一个楼层。

第七步：组装所有楼层为完整页面

所有楼层验证通过后，按楼层顺序组装为完整页面：

导航楼层 → Banner 楼层 → 楼层 1 → 楼层 2 → … → 页脚楼层

楼层间距统一使用间距 10（PC 72px / MB 32px）

模式 A：将所有楼层 HTML 拼接为完整页面，通过 code_to_design 输出

模式 B：将所有楼层 HTML 片段组装为完整 HTML 文件，包含统一的 <head> / CSS Reset / Token 引入

第八步：最终验证

□ 页面结构是否符合：导航 → [Banner] → 楼层(s) → 页脚？
□ 楼层间距是否统一为间距 10（PC 72px / MB 32px）？
□ 全页组件组合是否无黑名单违规？
□ 整体视觉一致性检查

通用生成约束（所有楼层共用）

🚨 以下约束无论哪种模式、哪个楼层均强制生效，违反即违规：

• 必须逐一读取当前楼层涉及组件的规范文档 components/{name}.md
• 合法的参数来源只有三个：① 对应组件规范文档 ② 硬约束白名单（第零步） ③ 上游 Token 真源
• 三者之外的任何取值均属自定义内容，一律禁止，包括但不限于：近似色值、估算间距、推断圆角、猜测默认变体
• 如果规范文档中找不到所需参数 → 停下，询问用户，禁止自行填充
• 图标：直接内嵌 <svg> 路径，禁止色块占位符或 <img src> 引用
• SVG 颜色：currentColor 继承父元素色值，或对应 Token CSS 变量

楼层模板索引

每个楼层模板是一个自包含的生成单元——AI 读了这个文件就能精确生成该楼层，无需再拼凑多个组件规范。模板包含：布局结构、精确尺寸/间距/字号值（直接取自硬约束白名单）、PC 和 MB 双端规格。

节点 ID 获取方式

• 从 Pixso 画布 URL 提取：?item-id=1:2 → itemId 为 1:2
• 使用 mcp__pixso-desktop__get_all_components 或 mcp__pixso-desktop__get_local_styles 返回结果中查找对应 key/id

注意事项

• 当你准备使用某一个组件来生成设计稿时，你应该读取 opendesign-components 的 skill，来看他对应的组件开发 skill 中说明的传参是否足以支持你的想法
• 所有 itemId 格式为 "数字:数字"，例如 "123:456"
• 若未指定 itemId，工具默认操作当前 Pixso 画布中已选中的节点
• 导出图片时使用 get_export_image 并配置 exportSettings（PNG/SVG/PDF 等）
• 组件文档中所有色值、字号、间距必须匹配上游 Token 的变量名，禁止使用硬编码值
• 编写组件文档时，参见 global/component-doc-spec.md 中的 Token 匹性要求和格式规范

异常与降级策略

componentKey 速查

• 完整 536 个 UI 组件变体：references/pixso-mcp-adapter/component-keys.md
• 完整 187 个图标 componentKey：references/pixso-mcp-adapter/icon-keys.md

常用高频变体（Light 模式默认变体，已验证）：

📎 人工参考附录

• 更新日志：CHANGELOG.md
• 项目说明与目录结构：README.md
• 组件文档编写规范：global/component-doc-spec.md