phoenix-ui

Phoenix UI provides local design tools for frontend work. Follow the project's product truth, accepted direction, and design rules; use the command references to create complete, accessible interfaces with a clear visual direction.

Install this runtime through @xgent-ai/skills on npm. Source copies from skills.sh do not include an engine installation. The engine does not update or download during context, detection, or hooks. Explicit engine install restores the version pinned by the installed package.

Core principles:

• Go all out. No hedging, no shortcuts. The deliverable must be complete (except assets the user must provide).
• Dream big and bold. Distinct, beautiful, outstanding and highly inspiring work.
• Keep Phoenix design self-QA to one batched inspection and at most one confirmation after fixing the findings. This ceiling applies to the design pass. Independent review-ui/apply-ui-review cycles and work the user has authorized follow their own completion conditions. Finish-reviewer and component-review evidence do not close an independent UI acceptance cycle.

Setup

1. Run <skill-base-dir>/scripts/phoenix-ui context once per session, where <skill-base-dir> contains this SKILL.md; keep cwd at the user's project. It resolves every <skill-base-dir>/scripts/phoenix-ui <verb> command in this skill and its references. This release supports macOS and Linux. The thin launcher requires Node >=18 and validates the fixed manifest, binary digest and Phoenix engine version before running. Users do not need Rust. Pass a named source file or route as --target <path>. It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance; follow its directives. For design facts, also read <skill-base-dir>/scripts/phoenix-ui context --target <primary-target> --json: product, design, surfaceBrief, provenance, parseCoverage and conflicts retain their original sources. Read the original when coverage is partial. An explicitly enabled profile provides advice; product truth, accepted directions and frozen targets retain authority. Missing context or a disabled profile supplies no template defaults. If JSON mode is unavailable, read the originals directly and disclose that the profile and brief mapping were not loaded; do not install or upgrade as a side effect.
2. Load the request's playbook: its Commands-table reference for an explicit/implied sub-command, or reference/new-work.md for a new surface or replacement visual world. Inspect target and incumbent visual truth before editing. When the app cannot run, start with committed visual-regression goldens or screenshot fixtures; verify target and freshness against current tokens, CSS, components, or assets, resolve conflicts, and compare theme/variant captures.
3. After resolving analysis and direction, read reference/craft-floor.md immediately before any UI edit, including small refinements. It carries the quality floor, the absolute bans, and the reflexes no detector catches. Do not load it for planning-only work.

Launcher unavailable: On refusal or failure, send a separate message before the next tool call: “Context loading did not run; I’ll read the existing project context directly.” Then read existing PRODUCT.md and DESIGN.md without inventing missing context, follow applicable steps 2–3, and continue through permitted tools. This applies to planning and editing; launcher failure alone does not block either.

How to design

• The brief wins. Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning. Redirecting a clear brief toward your taste is failure.
• Refinement preserves; redesign replaces. Refinement keeps the incumbent identity, behavior, copy, and everything outside scope. Ask before replacing factual copy or adding claims. Redesign keeps product truth, content, function, native affordances, and constraints; choose a replacement world within the authorized scope. Changes to an existing DESIGN.md follow design-md's writing authority and the user's accepted decisions. Record approval for changes to frozen targets before replacing them.
• Visual authority is evidence, not a filename. Missing DESIGN.md alone does not make a project greenfield; new-work decides whether to preserve, expand, or replace the incumbent world.

Modes

The mode names what the visitor's success looks like on this surface.

• Persuade: the visitor decides and acts; design is the product. Landing pages, marketing, campaigns, pricing. Earn attention and action. Ship real imagery when the brief needs it; follow the committed world, not category habit.
• Operate: the visitor completes a task. App UI, dashboards, editors, admin, settings, tools. Scanability, consistency, native expectations, and the real usage scene outrank expression. Brand lives in precise details.
• Read: the visitor understands something. Docs, articles, guides, help, changelogs. Structure for comprehension, then make the reading experience worth staying in.
• Experience: the visitor is inside the work itself. Portfolios, galleries, showcases. Let the artifact lead from the first viewport; the interface recedes.

Choose the mode from the requested surface, not the product, and persist it only in that surface brief. A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade. See new-work.md for new surfaces and operate.md for deeper Operate/Read guidance.

Commands

Command	Category	Description	Reference
craft [feature]	Build	Deprecated alias for an ordinary new-work request	reference/craft.md
shape [feature]	Build	Plan UX/UI before writing code	reference/shape.md
init	Build	Capture durable product context in PRODUCT.md	reference/init.md
document	Build	Generate DESIGN.md from existing project code	reference/document.md
extract [target]	Build	Pull reusable tokens and components into design system	reference/extract.md
critique [target]	Evaluate	UX design review with heuristic scoring	reference/critique.md
audit [target]	Evaluate	Technical quality checks (a11y, perf, responsive)	reference/audit.md · native: reference/audit.native.md
polish [target]	Refine	Final quality pass before shipping	reference/polish.md
bolder [target]	Refine	Amplify safe or bland designs	reference/bolder.md
quieter [target]	Refine	Tone down aggressive or overstimulating designs	reference/quieter.md
distill [target]	Refine	Strip to essence, remove complexity	reference/distill.md
harden [target]	Refine	Production-ready: errors, i18n, edge cases	reference/harden.md
onboard [target]	Refine	Design first-run flows, empty states, activation	reference/onboard.md
animate [target]	Enhance	Add purposeful animations and motion	reference/animate.md
colorize [target]	Enhance	Add strategic color to monochromatic UIs	reference/colorize.md
typeset [target]	Enhance	Improve typography hierarchy and fonts	reference/typeset.md
layout [target]	Enhance	Fix spacing, rhythm, and visual hierarchy	reference/layout.md
delight [target]	Enhance	Add personality and memorable touches	reference/delight.md
overdrive [target]	Enhance	Push past conventional limits	reference/overdrive.md
clarify [target]	Fix	Improve UX copy, labels, and error messages	reference/clarify.md
adapt [target]	Fix	Adapt for different devices and screen sizes	reference/adapt.md · native: reference/adapt.native.md
optimize [target]	Fix	Diagnose and fix UI performance	reference/optimize.md
live	Iterate	Visual variant mode: pick elements in the browser, iterate on alternatives	reference/live.md
generate [n] [action] [element]	Iterate	Variants, versions, or alternatives of a named element to choose from in the live browser; no manual picking	reference/generate.md

Routing:

• Continue an accepted direction for this target: reuse the original brief returned by context. A matching accepted hash restores the direction across sessions without another interview or concept roll. A stale, missing or ambiguous mapping requires resolving the original source and acceptance decision; do not select by mtime or silently accept changed bytes. If the user requests a different direction, record that change scope and use design-reference for the new choice.
• Visual references/direction: use design-reference. Interaction-pattern choice: use ui-pattern-research. Create/update DESIGN.md: use design-md's source and writing rules. Phoenix shape consumes the accepted interaction choice and develops the remaining surface decisions.
• Independent UI acceptance: route to review-ui; an existing UI report routes repairs to apply-ui-review. If the required skill is unavailable, report that prerequisite rather than claim Phoenix's design review completed that acceptance.
• No argument: read routing.md and present its context-aware menu; never auto-run a command.
• Explicit or clearly implied request to run a command: load its reference (native variant on native platforms) and follow it. Ask once if two commands fit.
• Workflow or command-selection question: read Workflow questions.
• Otherwise: treat the request as general design work. Missing PRODUCT.md routes a new surface or replacement world through init, then new-work; a narrow refinement of existing code proceeds on the incumbent implementation as phoenix-ui context directs, offering init afterward rather than blocking on it.
• teach aliases init. craft is a deprecated alias for ordinary new-work and adds nothing. shape owns task discovery, then enters new-work only for visual-world and surface-concept decisions.

After an authorized context or brief write, refresh context --target <primary-target> --json before using the changed facts. Init loads the native platform reference itself when the platform it recorded is ios, android, or adaptive.

Pin / Unpin: <skill-base-dir>/scripts/phoenix-ui pin <pin|unpin> <command> creates or removes a standalone $<command> shortcut. Report the script's result concisely; relay stderr verbatim on error.

Hooks: $phoenix-ui hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> manages the design detector hook for this project (auto-runs the detector after UI file edits and surfaces findings). Load reference/hooks.md when the user invokes it with any argument.

Doctor: $phoenix-ui doctor reports and repairs drift between this project's Phoenix UI artifacts (PRODUCT.md, DESIGN.md and its sidecar, config, surface briefs, the hook) and what this version reads. Load reference/doctor.md when the user invokes it, or when they ask what is out of date, stale, or needs refreshing. A CONTEXT_STALE directive in Setup's output is the cheap subset of the same report; act on it there per its own instructions rather than running doctor unasked.

Never repair drift as a side effect of a design task. A CONTEXT_STALE finding is reported, not acted on, unless the user asks. The one exception is a finding marked auto, which the next write to that file performs anyway.