@xgent-ai/skills 0.6.0 → 0.7.0

package/vendor/phoenix-ui/bundle/blobs/f67a499846c8f42498f069afbd1700946c9d6dc8ce60f1be3a197c91273144f0

@@ -0,0 +1,113 @@
+# $phoenix-ui hooks
+
+Manage the **design detector hook** for the current project.
+
+The hook runs the phoenix-ui design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code, Codex, and GitHub Copilot use a post-tool-use hook and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless quiet mode is on (`hook.quiet` in config). Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write. Grok Build fires the same PostToolUse scan to mark touched files, then surfaces findings on Stop `additionalContext`. Do not expect a Grok per-edit reminder: Grok discards that stdout.
+
+The detector rules run in two tiers. The per-edit hook surfaces only the immediate tier: mechanical, unambiguous problems worth interrupting an edit for, such as broken images, overflowing or clipped content, contrast and legibility failures, gradient text, glow shadows, and design-system drift. Everything else (copy cadence, palette and typography taste, layout rhythm) is deferred to a deep pass on the `Stop` hook event, which runs the full rule set over every UI file touched in the session and surfaces the remaining findings once, deduplicated against what the per-edit pass already reported. A session with nothing left to report stops silently. Set `hook.perEditRules` to `"all"` in `.phoenix-ui/config.json` to restore the full rule set on every edit. The Stop deep pass is wired for Claude Code, Codex, and Grok Build, which dispatch a native `Stop` hook event. Cursor does not get one (its stop hook is not consistently dispatched; the pre-write gate covers it), and GitHub Copilot's stop-style events do not feed context back to the model, so they keep the full detector per edit. Grok also fires an observe-only Stop with `reason: "shutdown"` after `end_turn`; skip that one, scan only `end_turn`.
+
+Every hook is a mechanical pass. The reflexes no scanner catches live in [craft-floor.md](craft-floor.md), which the skill loads before it edits UI, so they apply whether or not a hook is wired. A session with no automatic hook gets one `MANUAL_DETECTOR_REQUIRED` directive from `phoenix-ui context` asking for a single detector run at the end.
+
+This command toggles the hook **per project** by editing `.phoenix-ui/config.json` (the unified Phoenix UI config; hook runtime settings live under its `hook` key, and shared detector ignores live under `detector`). Per-developer overrides, including the install consent decision (`hook.consent`) the CLI records, live in the gitignored `.phoenix-ui/config.local.json`. Set `hook.enabled: false` to turn the hook off, `hook.quiet: true` to silence the clean/pending acks, or `hook.auditLog` to a file path for an NDJSON log. The legacy `PHOENIX_UI_HOOK_DISABLED`, `PHOENIX_UI_HOOK_QUIET`, and `PHOENIX_UI_HOOK_LOG` env vars are still honored and override these config values when set.
+
+Declare server-side template extensions under **`detector.extensions`** when the project uses Blade, Twig, ERB, or Handlebars files; the hook skips them otherwise because they sit outside the built-in extension list. One entry per extension, `{ "ext": ".blade.php", "engine": "html" }`. `engine` picks the analyzer (`html` for markup templates, `text` for JS/TS/CSS-like files) and defaults to `html`. Match against the end of the filename, so double extensions like `.blade.php` and `.html.erb` work. Config only adds extensions; the built-in list always applies.
+
+Manual `npx phoenix-ui detect` scans use the same project filter config by default: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. `hook.enabled` only controls automatic hook execution, not manual CLI scans. Use `npx phoenix-ui detect --no-config ...` for a raw detector run that ignores project config/context. Use `npx phoenix-ui ignores ...` for direct CLI CRUD on the same detector ignores.
+
+Supported harnesses: Claude Code (`.claude/settings.local.json` in the project, which is gitignored so the hook stays machine-local; a hook you move into the shared `settings.json` is honored in place too), Codex (`.codex/hooks.json` in the project), Cursor (`.cursor/hooks.json` in the project), Grok Build (`.grok/hooks/phoenix-ui.json` in the project; requires `/hooks-trust` or `--trust`), and GitHub Copilot (`.github/hooks/phoenix-ui.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read). For the Copilot CLI, repo-level hooks fire once `.github/hooks/phoenix-ui.json` is committed to the repository's default branch.
+
+On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
+
+Gemini installs session and completion hooks in `.gemini/settings.json`, merged into the settings already there (comments are tolerated; a commented file is backed up to `settings.json.bak` before the rewrite, and a file that is not valid JSON is left alone). It does not install a per-edit detector hook. The `BeforeTool` hook only rewrites shell commands that run `build-phase`, and only on macOS and Linux; on Windows (where Gemini runs hooks through PowerShell) no session id reaches the shell, so a comp build is not tied to the session and the completion reminder stays silent.
+
+## Routing
+
+The first argument is the action. Defaults to `status`.
+
+| Action | What it does |
+|---|---|
+| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
+| `on` | Set `enabled: true` in `.phoenix-ui/config.json`, record local hook consent as accepted, and install/repair provider hook manifests when the skill is installed. |
+| `off` | Set `enabled: false` in `.phoenix-ui/config.json`. |
+| `ignore-rule <id>` | Append `<id>` to `detector.ignoreRules`; for `overused-font`, requires `--all-values`. Suppresses the rule across the whole project. |
+| `ignore-file <glob>` | Append `<glob>` to `detector.ignoreFiles`. Suppresses **every** rule for matching files. |
+| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.phoenix-ui/config.json`. |
+| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.phoenix-ui/config.local.json`. |
+| `ignore-value <id> "*" --file <glob> [--file <glob>...]` | Turn one rule off in matching files only, leaving it active everywhere else. Repeat `--file`, or use `--file=<glob>` / `--files=<glob>`. A bare `"*"` with no `--file` is refused: use `ignore-rule <id>` if you really mean project-wide. |
+| `reset` | Delete the project config, dedup cache, and Cursor pending queue, and remove the hook's entries from every provider manifest `on` installs, the committed Copilot file included (a team-shared `settings.json` that `on` never writes is never touched). |
+
+## Flow
+
+1. Resolve the action from the user's argument. If no action was given, default to `status`.
+2. Invoke the admin script and pass the user's output through verbatim:
+
+   ```bash
+   .agents/skills/phoenix-ui/scripts/phoenix-ui hooks <action> [args...]
+   ```
+
+3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `$phoenix-ui hooks on`."
+4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write on a UI file."
+5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.phoenix-ui/config.json`; add `--local` only when the user explicitly asks for a private exception.
+6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
+
+## Triage findings
+
+The hook itself never writes ignore config; every exception goes through `phoenix-ui hooks`. Triage each finding into one of three outcomes:
+
+- **Real design problem**: fix it. Never add an ignore to skip a fix or to push a blocked write through.
+- **Confident false positive or sanctioned exception**: persist the narrowest ignore yourself and disclose it in your reply. The bar is evidence you can name: an intentional demo or fixture, documentation of bad design, literal or domain-appropriate motion (a ball that bounces), or a choice the user already confirmed. Put that evidence in `--reason` as `"<who decided: evidence>"`; write "user confirmed" only when the user actually did.
+- **Unsure**: leave the finding standing and ask the user in one line. Ask once; a one-line question costs less than the hook re-firing on every later edit.
+
+Self-serve stops at `ignore-value`. `ignore-file` and `ignore-rule` silence too much to add on your own judgment; ask the user first.
+
+Prefer the narrowest exception:
+
+- If the finding line shows an `ignore-value <rule> <value>` pair, pass it to `phoenix-ui hooks ignore-value` with your `--reason`. This writes shared `.phoenix-ui/config.json` by default.
+- For value-specific findings such as `overused-font` and `bounce-easing`, use `ignore-value` for the specific value. Do not use `ignore-rule overused-font` for a specific font.
+- If the finding has no value-specific command, such as `side-tab`, scope that one rule to the file: `ignore-value <id> "*" --file <path>`. Run `npx phoenix-ui detect <path>` first to see what actually fires there.
+- Reach for `ignore-file <path>` only when the whole file is out of scope for design review: a fixture, a generated artifact, a deliberate slop demo. It silences every rule for that file permanently, including rules that have not been written yet. A real UI surface with one noisy rule wants the file-scoped value ignore above.
+- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
+- Prefer config ignores (the commands above) by default; they keep suppressions in one reviewable place. Reach for an inline comment only when the waiver must travel with a single file that leaves the repo (a generated/exported standalone document, an emailed HTML file). The supported marker is `phoenix-ui-disable <rule>` (whole file) or `phoenix-ui-disable-line` / `phoenix-ui-disable-next-line` (one line), in any comment syntax, with an optional reason after `:` or `--`. The detector honors it by default; `--no-inline-ignores` or `--no-config` bypasses it.
+
+Example value-specific exception:
+
+```bash
+.agents/skills/phoenix-ui/scripts/phoenix-ui hooks ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
+```
+
+Example self-served exception, with the evidence named:
+
+```bash
+.agents/skills/phoenix-ui/scripts/phoenix-ui hooks ignore-value bounce-easing bounce-ball --shared --reason "Agent: literal ball-bounce animation, bounce easing is the subject"
+```
+
+Example whole-rule font exception:
+
+```bash
+.agents/skills/phoenix-ui/scripts/phoenix-ui hooks ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
+```
+
+Example one-rule-in-one-file exception, for a file that is still worth reviewing
+for everything else:
+
+```bash
+.agents/skills/phoenix-ui/scripts/phoenix-ui hooks ignore-value design-system-font-size "*" --file "src/overlay/widget.js" --reason "Injected widget builds its own type scale; DESIGN.md's ramp describes the site"
+```
+
+Example whole-file exception, for a file that is out of scope entirely:
+
+```bash
+.agents/skills/phoenix-ui/scripts/phoenix-ui hooks ignore-file "src/legacy/Card.tsx"
+```
+
+## Constraints
+
+- Never modify `.phoenix-ui/config.json` or `.phoenix-ui/config.local.json` by hand from this command. Always go through `phoenix-ui hooks` so writes stay validated and the file shape stays consistent. One exception: `detector.extensions` has no admin action, so when the user asks to cover a template stack, edit that one field in `.phoenix-ui/config.json` directly and leave the rest of the file untouched.
+- Do not edit the launcher or the binary behind `phoenix-ui hook` and `phoenix-ui hook-before-edit` from this flow. Those are skill plumbing.
+- Cursor can block a proposed write when the detector finds a real issue. Claude Code, Codex, and GitHub Copilot do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
+- The hook is bundled with the Phoenix UI skill and installed through project-local manifests: `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, `.github/hooks/phoenix-ui.json`, and `.gemini/settings.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/phoenix-ui.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly.
+
+## Failure modes
+
+- If `.phoenix-ui/config.json` or `.phoenix-ui/config.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `phoenix-ui hooks status` will show malformed files as ignored.
+- If the user asks to "disable the hook" globally, lead with `$phoenix-ui hooks off` (persistent for this project; writes `hook.enabled: false` to config). The legacy `PHOENIX_UI_HOOK_DISABLED=1` env var also works as a one-shot override that follows the shell.

package/vendor/phoenix-ui/bundle/blobs/f6859300f1a76ba57c8a7374ccb6c414efa0d4c5bbb4ba5a089cabdec688820c

@@ -0,0 +1,97 @@
+---
+name: phoenix-ui
+description: 用于前端设计、重设计、局部优化与 live 交互；不用于后端任务、仅维护设计规范或独立 UI 验收。结合项目上下文提供设计命令和本地检测，npm 安装后使用。
+version: 0.1.0
+license: Apache 2.0
+metadata:
+  version: 0.1.0
+  source: skills/phoenix-ui/src
+  source_sha256: c5c32748444236a0fe97df5b010904e610a7b919b29ea108b5645167ffd2c301
+allowed-tools:
+  - Bash(.pi/skills/phoenix-ui/scripts/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 `.pi/skills/phoenix-ui/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 `.pi/skills/phoenix-ui/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](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](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](reference/new-work.md) for new surfaces and [operate.md](reference/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](reference/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
+| `init` | Build | Capture durable product context in PRODUCT.md | [reference/init.md](reference/init.md) |
+| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
+| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) · native: [reference/audit.native.md](reference/audit.native.md) |
+| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
+| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
+| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
+| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) · native: [reference/adapt.native.md](reference/adapt.native.md) |
+| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, iterate on alternatives | [reference/live.md](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](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](reference/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](reference/routing.md#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:** `.pi/skills/phoenix-ui/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](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](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.

package/vendor/phoenix-ui/bundle/blobs/f6cec907cf998a070724c4c457cd7217bec65a0fbf50fd1b9f823489f607166c

@@ -0,0 +1,46 @@
+# Visualize: Direction Comps & Asset Production
+
+Load this from [new-work.md](new-work.md) on a comp-led build, when image generation is available (a harness-native tool or the API fallback `phoenix-ui context` reports). A code-led contract skips this file by design, not by drift; do not load it then. PRODUCT.md and DESIGN.md are preconditions. The MODE RULES block concept-seed printed for this surface (COMPS) governs these comps together with this file and wins where they conflict; with no roll this session, read the mode's file named in new-work.md. New-work has already resolved the visual world; this file must not reopen it. A surface-scope structure round that already put three visualized cards before the user (new-work.md, established world) has discharged this round: the locked card's comp is the approved comp, so record the approval and continue at After approval; generate nothing new.
+
+A probe tests composition, narrative, hierarchy, density, focal moment, signature use, and image requirements. It is not a second identity workshop. Keep DESIGN.md's palette, typography direction, material language, component character, imagery stance, and motion grammar fixed.
+
+## Generate three compositional options
+
+The comp round runs inside the build's phase state: `phoenix-ui build-phase start --direction <seed key> --kind <...>` has already run (the roll's output names the command) and its `comps` phase is open before the first comp is generated; a comp rendered before that sits outside the state, and a session resumed from that point has no phases to follow. `phoenix-ui generate-image` refuses to write under `.phoenix-ui/mocks/` until start has run; a harness-native image tool is bound by the same order.
+
+Render three distinct high-fidelity north-star comps of the requested surface, saved under `.phoenix-ui/mocks/` so they survive the session. Comp at the surface's own viewport: portrait at device size for a native app or mobile-first surface, desktop landscape otherwise; a phone screen comped landscape misstates the composition before anything is built against it. Comps are the build thread's own work, never delegated: the thread that writes the prompts holds the direction's full context and has seen every comp when the build starts. Open every image by its workspace-relative path; sandboxed viewers reject absolute paths, and everything under the project root has a relative one. Base the comps on real content and the surface concepts already developed with the user. On an established world, anchor every comp on the real identity: capture a screenshot of a representative existing page and pass it as a reference image (the harness image tool's input image, or `phoenix-ui generate-image --ref`); the prompt leads with the new surface's structure while the reference carries palette, type, and component character, because DESIGN.md words alone drift where a pixel reference does not. Name what the reference contributes and what it must not: chrome, palette, type, and component character carry over; the reference page's own content does not, and a banner, hero, or card lifted verbatim is the reference leaking, not fidelity. Three is the number: one comp invites rubber-stamping; the spread between three surfaces the composition worth building. The chosen card's decision comp is the first of the three: it already renders this direction at full fidelity under this discipline, so generate two more that vary what the first held fixed, from the direction in words rather than with the first comp as an input image (a reference image anchors the layout, and three comps collapse into one composition). How comps two and three vary from the first is the mode's call, in its COMPS rules. A variant that simplifies the first into a tidier version of itself adds no choice to the round. Send all three to the approval point together. Only a round arriving with no decision comp (a degraded roll, an identity-mode page, a direction pinned without the decision round) renders all three here.
+
+- A comp is a designed surface, not a picture of the subject. Lead the prompt with the surface's own structure: the regions this design has, named in order with their scale relationships; a page with no navigation says so instead of inventing one, and an unconventional surface states its unconventional skeleton. A prompt that leads with atmosphere gets a vignette back: the model paints the fish market instead of the fish market's website. How far the world reaches into the page, and what it may carry, is the mode's call, in its COMPS rules. Render the page itself edge to edge: no browser window, address bar, device or desk around it, so prompt it as the page, never as a screenshot of a browser. Self-check every render: if it could hang as a poster, or reads as a photograph with some text on it, it is not a comp; regenerate with the dealt composition's regions named and its parts working in place.
+- The inverse is also a failure: a surface with none of its subject in it. The subject appears as the content the regions hold; the world dresses the frame and never displaces what the frame shows. The deletion usually rides in on the prompt's exclusion list, so exclusions bind invented claims, and a medium ban belongs to the committed imagery stance, never to caution. Before accepting a render, point at the subject; a render that depicts everything about the world and nothing of the subject fails however faithful its atmosphere. Regenerate with the subject's content named region by region.
+- Judge a comp as the shipped screen: the visitor's job must be readable from the image alone. Name the surface's mode from the render with no caption; a render whose mode cannot be read back is art direction without a surface. Regenerate with the visitor's job as the prompt's spine.
+- Commitment is depth, not performance spread across regions. The world enters through one dominant move plus the material, type, and spacing that support it; the remaining regions hold still in that material so the move can be read. A region that simply does its job in the world's grammar carries the direction further than a region performing the concept. The check cuts competition, never content: a quieted region keeps its information and stops performing, and the page still carries its content (a way to navigate, the offer, its supporting copy, an action, a glimpse of what follows) at real reading size (body text near 16px on a 1440px-wide page). That is a list of content, not a layout: where each piece sits is the composition's call. A second element competing with the named focal moment at the same scale means the comp is shouting; with no named focal moment, several regions performing the concept at once is the same shout. Regenerate keeping the strongest move and quieting the rest. Busy is louder, not bolder.
+- When the user shortlisted multiple concepts, spread the three across them.
+- When one direction is committed, vary the structural uncertainty an image can resolve: topology, sequence, density, hierarchy, focal composition, or interaction framing.
+- Show enough beyond the opening moment to prove the concept can govern the whole surface.
+- Do not generate a palette artifact, ask new atmosphere questions, introduce a different type voice, or invent a new motif. If the committed world cannot support the concept, return to the concept shortlist rather than changing the world.
+
+Each comp is a direction test, not a screenshot specification. Core UI text, responsive behavior, accessibility, semantics, and interaction states remain implementation responsibilities.
+
+## One approval point
+
+Show the three together on the decision page (`phoenix-ui serve-question`, one option per comp with the comp as its hero), or in the harness only when it renders images inline; a text-only surface does not count as display. Ask what should carry forward, what feels false to the world, and whether the selected concept should be approved, combined, revised, or rejected. Then stop and wait. A structured simulated user counts as attended and receives the same question.
+
+Do not begin code until the user approves a direction or explicitly delegates the choice. If they delegate, choose using the task brief, PRODUCT.md, and DESIGN.md, and state the evidence. Approval refines the task concept; it does not modify DESIGN.md.
+
+This approval point has no substitute and no skip condition. When the structured question tool errors, fall back to the decision page; only after both fail may you treat the choice as delegated, and a delegated pick is recorded exactly as an approval is and disclosed in your first reply, not your last. The finish reviewer treats comp-round comps with no recorded approval as a material finding; decision comps under `.phoenix-ui/mocks/decision/` are the direction round's hand, not comp-round output, and imply no approval on their own.
+
+After approval, record the choice where tools can find it: the approved comp's path goes in the surface brief, and its prompt sidecar (the image's full file name plus `.json`: `a.png` gets `a.png.json`) gains `"approved": true` (every comp generated through `phoenix-ui generate-image` has one; create it if a native tool didn't). The sidecar travels with the mocks folder, so the approval survives sessions and machines that never see the brief, and it is what `phoenix-ui build-phase advance` reads to close the comps phase. Summarize the composition and the parts of the comp that must not be literalized, return to new-work.md, record the direction contract from the approved concept, and build.
+
+## After approval: the comp becomes a spec
+
+The approved comp is a north star for translation into semantic, responsive, accessible code, never a license to recompose: keeping the palette and mood while redrawing the topology is a second art direction. Do not rasterize core UI text or controls. Do not substitute a different visual driver after approval without asking.
+
+What the comp shows is measured, not remembered. new-work.md section 6 runs the build as phases (`phoenix-ui build-phase`): the spec phase turns the comp into region boxes with sampled palettes (`phoenix-ui comp-spec`), and the medium of every region follows from what the pixels are, never from what feels buildable: a figure, a product object, machinery, any illustration with perspective, shading, or drawing skill in it, and any texture by name (woven cloth, paper grain, fabric, leather, brushed metal) is a `plate` / `image` / `texture` region and ships as a raster; text, controls, chrome, diagrams with countable elements, flat shape systems, and anything that must move, scale, or respond are semantic. Writing "CSS" for a sculpted panel's finish, or a many-vertex `clip-path` for a torn edge, is the quiet deletion of the approved design; the detector's organic-clip-path and buried-raster rules and the hero gate's region scores catch it. Dropping an image-native region is a scope decision the user makes at the approval point, never a silent flattening after it. Generated imagery is a material, not a claim: evidence rules bind assertions, specs, testimonials, and photographs presented as real, never render fidelity.
+
+## Plates and provenance
+
+Every raster region's plate is produced in the plates phase, before any page code, by the shipped asset producer or in the current thread (use `phoenix-ui comp-spec --crop <id>` and save `phoenix-ui comp-spec --plate-prompt <id>` to a prompt file; pass the crop and prompt to the harness image tool, or use `phoenix-ui generate-image --ref <crop.png> --prompt-file <prompt.txt> --out <plate.png> --size <WxH> --quality high`). For isolated cutouts, add `--background transparent` to both the plate-prompt and API generation commands; use native PNG alpha and preserve white paint and clear gaps. Use `--background opaque` for full-frame imagery. Create output directories first and inspect alpha on light and dark grounds. Generation context is part of the asset: after generating any image with any tool, run `.trae-cn/skills/phoenix-ui/scripts/phoenix-ui embed-prompt <image> --prompt "<prompt>"` with the exact string the tool received (`phoenix-ui generate-image` does this itself), so the intent lives inside the file; `--read` recovers it, `--scan <dir>` lists rasters still missing one. The embedded prompt plus the region's row in the spec is the raster's **provenance**, and every raster the artifact references carries it; a sourced, stock, or pre-existing raster embeds its origin instead. A raster created or replaced later, in a fix batch or a reviewer's rebuild, is produced the same way; a raster a fix abandons is deleted in the same batch.
+
+Convert images with a converter `phoenix-ui context` reported at boot (the IMAGE_TOOLS line); probe only when it reported none, at most once per session, never per image.
+
+Return to [new-work.md](new-work.md) for the direction contract, the phased build, and the finishing pass.