---
name: reference-style
description: 查看项目视觉参考，区分可见特征与制作假设，归纳有依据的风格规则，并通过 SmartUI 项目 MCP 工具维护风格与组件文档。用于参考分析、风格提取及复现偏差校准。
---

# 从参考中提取可执行的项目规则

用 SmartUI 项目 MCP 工具保存参考依据与风格，而不是只在聊天中留下结论。调用参数见[项目工具说明](../../docs/project-tools.md)。编写项目绘制程序时读[程序约定](../../docs/drawing-programs.md)；实际 PhotoCraft 制作与修改使用 [photocraft-drawing Skill](../photocraft-drawing/SKILL.md)。

已有资产的页面排版使用 [page-composition Skill](../page-composition/SKILL.md)。反馈先定位到组件外观或状态、资产导出、页面布局、文字或运行时适配；布局变化不触发基础组件重绘。

## 看图与记录依据

`project_root` 是业务工程根目录的绝对路径。`<data_root>` 是保存参考、当前风格和制作资料的工程相对目录。普通项目使用 `smart-ui`，Unity 项目使用创建时指定的 `Assets` 子目录，默认 `Assets/SmartUI`。资料目录纳入 Git，本机 `.smartui/` 整体忽略。登记的参考原图保存在 `<data_root>/references/`，工程内引用使用相对路径。

已有项目先 `project_context`，查看已有规则、组件规格和预览，避免重复建立矛盾规范。新项目先 `project_create`。用 `project_add_reference` 登记只读原图，用 `project_inspect_reference` 查看整图、关键区域和需要的色块。坐标相对完整参考，按预览测量时传 coordinate_size。

必须实际查看返回图片后归纳。按参考中适用的维度分析用色与对比、轮廓比例、描边、明暗和高光阴影、材质纹理、内容关系及尺寸伸缩规则；无需给所有参考套相同栏目。图层数量、材质和程序结构服务于当前需求。

优先提炼决定目标尺寸下观感的少量特征，说明哪些需要匹配参考、哪些按当前业务要求调整。用实际样片检验分析，不额外增加一轮纯文字审查；样片暴露遗漏时回头修正规则，不能只检查产物是否符合自己写出的规则。

规则引用 reference_id 与具体区域或特征，区分可见观察、制作假设和待测参数。截图不能唯一反推原始笔刷、图层顺序、真实材质和光源数量。没有证据时不补造纹理、磨损或光照理论。

取色返回原始通道统计，不做 ICC 转换或背景合成。避开文字、遮挡与抗锯齿混色，截图表观色不直接等于原始素材色。必要时用多个清楚色块比较，说明依据及不确定性。

## 归纳颜色用途和状态差异

从参考说明颜色用在哪些区域、承载什么信息，以及色相、明暗或饱和度的关系怎样影响辨识。举例时区分组件底面、内容和重点操作，指出在实际背景中哪处需要更醒目。60/30/10、邻近色、补色和动效都是可按需求选择的方法。根据页面目标判断强调方式，避免套固定面积比例或假定动态元素总应优先。

按当前需求列出组件需要的状态和主题，说明各状态如何区分、哪些轮廓、边厚、留白或内容位置需要共用。把有依据的颜色用途和状态差异交给共用参数，让组件规格引用所需主题和状态。若参考只显示部分状态，把补充画法记为待验证方案，并将视觉区别和运行时交互分别验收。

## 区分基础 UI 与 ICON 的风格要求

基础 UI 与 ICON（图标）共享适用的参考依据，但分别描述制作要求。基础 UI 记录几何、边厚、伸缩和状态；ICON 记录内容语义、造型、描边、配色、明暗和细节密度，以及目标显示尺寸、使用背景、透明背景需求和留白。不要将面板的圆角、九宫格或拉伸规则直接套到 ICON，也不要因参考含有 ICON 就要求为它编写 PhotoCraft 绘制程序。

ICON 图像采用独立的宿主生图或图像编辑流程。SmartUI 不内置生图后端；登记真实产物后，可查看当前图像并建立固定坐标的静态 UI 组合。检查时同时查看单图和实际尺寸的组合，关注辨识度、视觉重心及与文字、容器的关系。布局调整复用当前图像。需要改图时，用同一资产 ID 登记确认采用的图像。占位可以验证布局，不能代替完整美术效果验收。工具字段与限制见[独立图像资产与静态组合预览](../../docs/project-tools.md#独立图像资产与静态组合预览)，实际操作见[ICON 资产 Skill](../icon-assets/SKILL.md)。

## 建立文字角色与固定字号

从整页参考识别标题、操作、正文、辅助说明和关键数值的用途，区分持续阅读、快速扫读和短时演出。实际查看代表区域，记录字体与字重、相对大小、行高、字距、文字本色、描边及投影各自的颜色和透明度、效果尺寸，以及适用背景。截图字形高度不是原始字号，不能直接套社区案例中的数值。

先归纳项目需要的少量固定字号，再定义完整角色样式；不同角色可共用档位，行高分别校准。用 `project_update_typography` 保存独立规范，参数见[项目文字规范](../../docs/project-tools.md#项目文字规范)。参考依据包含参考 ID、区域、坐标尺寸、观察和设计决定。证据不足时注明设计假设，不填成用户已确认。

角色至少说明用途和适用条件，填色、描边和投影分别选择，合法无效果用 `null`。字体引用工程内持久文件，缺字或文件变化应明确修正源头。先用正式页面工具制作小型文字样片，检查真实文案、复杂汉字、数字和长标签在实际背景中的效果；包含其他语言时按真实译文复查。目标设备和运行态可读性另行验证，浏览器截图不能替代。具体方法及社区依据见[文字设计规范](../../docs/typography-plan.md)。

文字规范保存在 `<data_root>/typography.json`，工具生成 `<data_root>/docs/typography.md`。更新后用上下文中的 `typography_usage` 和 `page_status` 定位受影响页面，显式重建并复查。文字规范变化不要求重画无关组件。

## 维护项目文档与校准

用 `project_update_style` 保存 description、rules、parameters 和 reference_ids，证据可用 `{reference_id, note}`。说明规则适用于基础 UI、ICON 还是两者，参数按实际用途组织，不强加固定色板、圆角或高光字段。需要通过 PhotoCraft 制作的组件用 `project_define_component` 保存完整规格，其中 program_id 引用已保存的程序；定义规格不表示已经生成资产。ICON 占位和独立生成图像不登记为待绘制组件。

每次写入用最新 revision，冲突时重新读取核对。`<data_root>/docs/style.md` 和 `<data_root>/docs/components.md` 由 MCP 根据项目资料生成，通过工具更新原始资料。

先校准覆盖主要画法的少量代表组件，再推广到整组。需要检查图文和容器关系时，只组合一个典型区域，沿用后续制作的程序与资产；不为组件校准提前补齐完整页面、场景、全部图标或未来状态。具体范围及结束条件见[参考匹配与按需修正流程](../../docs/style-reproduction-validation.md)。

用 `project_create_visual_check` 并排查看需要比较的当前组件产物，按目标显示尺寸设置等比倍率和背景。常规检查显式传 `grayscale=false`，只看彩色图；需要诊断明暗时使用默认开启的灰度图，放大、多背景及多尺寸也按问题需要使用。已有同条件检查用 `project_get_visual_check` 读取，不重复生成。

代表组件或发现偏差的组件用 `project_compare_component` 对照当前产物与参考区域。选可比区域并显式设置需要的等比倍率。查看拼图后，用 `project_record_feedback` 分别记录可见现象和建议改动，按依据关联节点 key 或规则 ID；已有对照用 `project_get_comparison` 读取。先汇总目标尺寸下可见、影响大的同源偏差，再集中修改规格、程序或共用规则，不逐项重绘或规定固定修正轮数。

修改后以同一参考区域和可比条件查看参考和当前产物，检查目标偏差与受影响状态，再用 `project_update_feedback` 逐项复查。主要偏差已处理且无相关退步时结束；没有明确改法、修正无收益或达到约定预算时说明未解决项，不把停止修正记为通过。规则、参数或程序变化时核对受影响组件，按需重绘并重新检查实际预览。

交付规则依据、对照及待验证项。确认反馈依据对应当前组件产物。用户风格确认需要用户明确给出。