phoenix-ui

Phoenix UI 为前端工作提供本地设计工具。遵循项目的产品事实、已接受的方向和设计规则；使用命令参考，创建完整、易于访问且视觉方向明确的界面。

通过 npm 上的 @xgent-ai/skills 安装此运行时。从 skills.sh 获取的源代码副本不包含引擎安装。引擎不会在上下文加载、检测或钩子运行期间更新或下载。显式运行 engine install 可恢复已安装软件包锁定的版本。

核心原则：

• 全力以赴。不含糊，不走捷径。交付内容必须完整（用户必须提供的素材除外）。
• 大胆畅想。打造独特、美观、出众且极具启发性的作品。
• 将 Phoenix 设计自检控制在一次批量检查内，并且最多在修复问题后确认一次。此上限适用于设计阶段。独立的 review-ui/apply-ui-review 周期以及用户授权的工作，遵循各自的完成条件。finish-reviewer 和组件审查证据不能结束独立的 UI 验收周期。

设置

1. 每个会话运行一次 <skill-base-dir>/scripts/phoenix-ui context；<skill-base-dir> 是包含此 SKILL.md 的目录；将当前工作目录（cwd）保留在用户的项目目录中。此命令会解析此技能及其参考文档中的所有 <skill-base-dir>/scripts/phoenix-ui <verb> 命令。此版本支持 macOS 和 Linux。轻量启动器要求 Node >=18，并会在运行前验证固定清单、二进制文件摘要和 Phoenix 引擎版本。用户无需安装 Rust。通过 --target <path> 指定源文件或路由。它会加载 PRODUCT.md、DESIGN.md、匹配的界面简介和原生平台指南；请遵循其中的指示。 如需了解设计事实，还要读取 <skill-base-dir>/scripts/phoenix-ui context --target <primary-target> --json：product、design、surfaceBrief、provenance、parseCoverage 和 conflicts 保留其原始来源。若覆盖不完整，请读取原始文件。显式启用的配置文件仅提供建议；产品事实、已接受的方向和冻结目标仍具有最高优先级。缺少上下文或未启用配置文件时，不提供模板默认值。如果无法使用 JSON 模式，请直接读取原始文件，并说明未加载配置文件及简介映射；不要因此安装或升级。
2. 加载请求对应的操作指南：对于明确或隐含的子命令，读取其 Commands 表格中的参考文档；对于新界面或替换视觉风格，读取 reference/new-work.md。编辑前检查目标界面和现有视觉事实。如果应用无法运行，先检查已提交的视觉回归基准图或截图夹具；根据当前令牌、CSS、组件或素材验证目标及其时效性，解决冲突，并比较不同主题/变体的截图。
3. 分析和方向确定后，在任何 UI 编辑前（包括小幅调整），立即读取 reference/craft-floor.md。其中包含质量底线、绝对禁止事项，以及任何检测器都无法捕捉的常规检查要点。仅做规划时不要加载此文件。

**启动器不可用：**如果启动器拒绝运行或失败，请在下一次工具调用之前发送一条单独消息：“上下文加载未运行；我会直接读取现有项目上下文。”然后读取现有的 PRODUCT.md 和 DESIGN.md，不要臆造缺失的上下文；遵循适用的步骤 2–3，并继续使用获准的工具。规划和编辑均适用此要求；仅启动器故障不会阻止任何一项工作。

如何设计

• 以设计简报为准。 即使与高饱和图案警示冲突，也要遵循指定的美学风格、时代、材质、字体和配色。把明确的设计简报引向你偏好的方向，就是失败。
• 优化保留原貌；重新设计则另起炉灶。 优化要保留现有的身份、行为、文案，以及范围之外的一切。替换事实性文案或添加声明前，先征求同意。重新设计要保留产品事实、内容、功能、原生交互方式和约束；在授权范围内选择新的视觉方向。对现有 DESIGN.md 的修改，须遵循 design-md 的写作权限和用户已接受的决定。替换已冻结的目标前，先记录批准。
• 视觉依据在于证据，而非文件名。 缺少 DESIGN.md 本身并不意味着项目是从零开始；由 new-work 决定是保留、扩展还是替换现有的视觉方向。

模式

模式描述了访客在此界面上的成功标准。

• 说服： 访客做出决定并采取行动；设计就是产品。适用于落地页、营销、活动和定价。吸引关注并促成行动。若设计简报需要真实图像，就提供真实图像；遵循既定的视觉方向，而非行业惯例。
• 操作： 访客完成一项任务。适用于应用 UI、仪表板、编辑器、管理、设置和工具。易于浏览、保持一致、符合原生预期并贴合真实使用场景，比表现力更重要。品牌体现在精准的细节中。
• 阅读： 访客理解某些内容。适用于文档、文章、指南、帮助内容和更新日志。先围绕理解来组织结构，再让阅读体验值得继续。
• 体验： 访客置身于作品本身。适用于作品集、画廊和展示页面。从首屏开始就让作品成为主角；界面应退居幕后。

根据所请求的界面选择模式，而不是根据产品选择；并且仅在该界面的设计简报中记录模式。工具的落地页仍属于“说服”；时装屋的文档仍属于“阅读”；文档索引属于“阅读”，而非“说服”。新界面请参阅 new-work.md；更深入的“操作”／“阅读”指导请参阅 operate.md。

命令

命令	类别	描述	参考
craft [feature]	构建	已弃用的别名，用于普通的新工作请求	reference/craft.md
shape [feature]	构建	编写代码前规划 UX/UI	reference/shape.md
init	构建	在 PRODUCT.md 中记录持久的产品背景信息	reference/init.md
document	构建	根据现有项目代码生成 DESIGN.md	reference/document.md
extract [target]	构建	将可复用的设计令牌和组件提取到设计系统中	reference/extract.md
critique [target]	评估	使用启发式评分进行 UX 设计评审	reference/critique.md
audit [target]	评估	技术质量检查（a11y、性能、响应式）	reference/audit.md · 原生：reference/audit.native.md
polish [target]	优化	发布前的最终质量检查	reference/polish.md
bolder [target]	优化	强化安全或平淡的设计	reference/bolder.md
quieter [target]	优化	弱化过于激进或过度刺激的设计	reference/quieter.md
distill [target]	优化	提炼核心，去除复杂性	reference/distill.md
harden [target]	优化	做好生产就绪准备：错误、i18n、边界情况	reference/harden.md
onboard [target]	优化	设计首次使用流程、空状态和激活体验	reference/onboard.md
animate [target]	增强	添加有明确目的的动画和动态效果	reference/animate.md
colorize [target]	增强	为单色 UI 添加经过策略性设计的色彩	reference/colorize.md
typeset [target]	增强	改进排版层级和字体	reference/typeset.md
layout [target]	增强	修复间距、节奏和视觉层级	reference/layout.md
delight [target]	增强	增添个性与令人印象深刻的细节	reference/delight.md
overdrive [target]	增强	突破常规限制	reference/overdrive.md
clarify [target]	修复	改进 UX 文案、标签和错误消息	reference/clarify.md
adapt [target]	修复	适配不同设备和屏幕尺寸	reference/adapt.md · 原生：reference/adapt.native.md
optimize [target]	修复	诊断并修复 UI 性能问题	reference/optimize.md
live	迭代	视觉变体模式：在浏览器中选择元素，并迭代尝试不同方案	reference/live.md
generate [n] [action] [element]	迭代	为指定元素生成变体、版本或备选方案，供你在实时浏览器中选择；无需手动挑选	reference/generate.md

路由：

• **为此目标延续已接受的方向：**复用 context 返回的原始 brief。匹配的已接受哈希可在不同会话间恢复该方向，无需再次访谈或抽取概念。映射过期、缺失或存在歧义时，必须解析原始来源和接受决策；不得按修改时间选择，也不得默默接受已更改的字节。如果用户要求更换方向，请记录变更范围，并使用 design-reference 选择新方向。
• **视觉参考／方向：**使用 design-reference。**交互模式选择：**使用 ui-pattern-research。**创建／更新 DESIGN.md：**遵循 design-md 的来源和写作规则。Phoenix shape 使用已接受的交互选择，并确定其余界面决策。
• **独立的 UI 验收：**转至 review-ui；已有 UI 报告时，转至 apply-ui-review 进行修复。如果所需技能不可用，请说明此前置条件，而不要声称 Phoenix 的设计审查已完成该验收。
• **没有参数：**读取 routing.md 并呈现符合上下文的菜单；绝不自动运行命令。
• **明确或明显暗示要运行命令：**加载该命令的参考文档（在原生平台上使用原生变体）并遵循其中说明。若有两个命令都适用，只询问一次。
• **关于工作流或命令选择的问题：**读取 Workflow questions。
• **其他情况：**将请求视为一般设计工作。缺少 PRODUCT.md 时，通过 init 处理新界面或替代世界，然后进入 new-work；对现有代码进行小范围优化时，按照 phoenix-ui context 的指示基于当前实现继续，并在之后提供 init 选项，而不是因此阻塞工作。
• teach 是 init 的别名。craft 是普通 new-work 的弃用别名，不增加任何功能。shape 负责发现任务，然后仅在视觉世界和界面概念决策方面进入 new-work。

授权写入 context 或 brief 后，在使用已更改的信息前，先刷新 context --target <primary-target> --json。如果 Init 记录的平台是 ios、android 或 adaptive，它会自行加载原生平台参考文档。

固定／取消固定：<skill-base-dir>/scripts/phoenix-ui pin <pin|unpin> <command> 可创建或移除独立的 $<command> 快捷方式。简要报告脚本结果；出错时原样转达 stderr。

Hooks：$phoenix-ui hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> 用于管理此项目的设计检测器 hook（UI 文件编辑后自动运行检测器并显示发现结果）。用户带参数调用时，加载 reference/hooks.md。

Doctor：$phoenix-ui doctor 会报告并修复此项目的 Phoenix UI 产物（PRODUCT.md、DESIGN.md 及其 sidecar、配置、界面 brief、hook）与当前版本读取内容之间的偏差。用户调用它时，或询问哪些内容已过期、陈旧或需要刷新时，加载 reference/doctor.md。Setup 输出中的 CONTEXT_STALE 指令是同一报告的精简子集；应按照其自身说明处理，而不要未经请求就运行 doctor。

**绝不要在设计任务中顺带修复偏差。**应报告 CONTEXT_STALE 发现结果，但除非用户提出要求，否则不采取操作。唯一例外是标记为 auto 的发现；下次写入该文件时会自动处理。