@xgent-ai/skills 0.6.0 → 0.7.0

package/skills/phoenix-ui/reference/audit.md

@@ -0,0 +1,137 @@
+Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.
+
+This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
+
+**Web only.** Native platforms (`ios` / `android` / `adaptive`) route to [audit.native.md](audit.native.md) instead; if the project is native, switch to it now.
+
+## Diagnostic Scan
+
+Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
+
+### 1. Accessibility (A11y)
+
+**Check for**:
+- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA)
+- **Motion sensitivity**: `prefers-reduced-motion` needs an intentional alternative that preserves state change and hierarchy; flag a global `0.01ms` kill that destroys useful feedback, flashing above threshold, and motion that blocks focus, reading, or task completion
+- **Missing ARIA**: Interactive elements without proper roles, labels, or states
+- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps
+- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons
+- **Alt text**: Missing or poor image descriptions
+- **Form issues**: Inputs without labels, poor error messaging, missing required indicators
+
+**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA)
+
+### 2. Performance
+
+**Check for**:
+- **Layout thrashing**: Reading/writing layout properties in loops
+- **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
+- **Missing optimization**: Images without lazy loading, unoptimized assets
+- **will-change overuse**: `will-change` applied broadly or left on at rest (it is a targeted hint for known expensive animations, not a baseline requirement)
+- **Bundle size**: Unnecessary imports, unused dependencies
+- **Render performance**: Unnecessary re-renders, missing memoization
+
+**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized)
+
+### 3. Theming
+
+**Check for**:
+- **Hard-coded colors**: Colors not using design tokens
+- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme
+- **Inconsistent tokens**: Using wrong tokens, mixing token types
+- **Theme switching issues**: Values that don't update on theme change
+
+**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly)
+
+### 4. Responsive Design
+
+**Check for**:
+- **Fixed widths**: Hard-coded widths that break on mobile
+- **Touch targets**: Interactive elements < 44x44px
+- **Broken touch interaction**: Custom sliders, drag surfaces, and scrollable control strips whose primary gesture fails under touch, that swallow page scroll or lose the drag to it, or that stay stuck after an interrupted gesture. Code tells: mouse-only handlers, no `touch-action` on a pointer-event drag surface, drag state that nothing clears on cancel, lost capture, or blur. Exercise the gesture when a browser tool can synthesize touch (a rendered viewport proves layout, not the gesture), then say what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and what stayed untested
+- **Horizontal scroll**: Content overflow on narrow viewports
+- **Text scaling**: Layouts that break when text size increases
+- **Missing breakpoints**: No mobile/tablet variants
+
+**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets, gestures work under touch)
+
+### 5. Implementation Integrity (CRITICAL)
+
+Run the bundled detector and verify each finding in context. Look for repeated implementation shortcuts, design-system drift, misleading or decorative content, and structure that is interchangeable with an unrelated product. Keep deterministic findings separate from visual judgment and call out false positives.
+
+**Score 0-4**: 0=systemic drift, 1=major repeated failures, 2=several verified issues, 3=minor isolated issues, 4=coherent and intentional
+
+## Generate Report
+
+### Audit Health Score
+
+| # | Dimension | Score | Key Finding |
+|---|-----------|-------|-------------|
+| 1 | Accessibility | ? | [most critical a11y issue or "--"] |
+| 2 | Performance | ? | |
+| 3 | Responsive Design | ? | |
+| 4 | Theming | ? | |
+| 5 | Implementation Integrity | ? | |
+| **Total** | | **??/20** | **[Rating band]** |
+
+**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
+
+### Implementation Integrity Verdict
+**Start here.** Pass/fail: does the implementation express a coherent product-specific system? Cite verified evidence and detector findings.
+
+### Executive Summary
+- Audit Health Score: **??/20** ([rating band])
+- Total issues found (count by severity: P0/P1/P2/P3)
+- Top 3-5 critical issues
+- Recommended next steps
+
+### Detailed Findings by Severity
+
+Tag every issue with **P0-P3 severity**:
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or WCAG AA violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
+
+For each issue, document:
+- **[P?] Issue name**
+- **Location**: Component, file, line
+- **Category**: Accessibility / Performance / Theming / Responsive / Implementation Integrity
+- **Impact**: How it affects users
+- **WCAG/Standard**: Which standard it violates (if applicable)
+- **Recommendation**: How to fix it
+- **Suggested command**: Which command to use (prefer: $phoenix-ui adapt, $phoenix-ui animate, $phoenix-ui audit, $phoenix-ui bolder, $phoenix-ui clarify, $phoenix-ui colorize, $phoenix-ui critique, $phoenix-ui delight, $phoenix-ui distill, $phoenix-ui document, $phoenix-ui harden, $phoenix-ui layout, $phoenix-ui onboard, $phoenix-ui optimize, $phoenix-ui overdrive, $phoenix-ui polish, $phoenix-ui quieter, $phoenix-ui shape, $phoenix-ui typeset)
+
+### Patterns & Systemic Issues
+
+Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
+- "Hard-coded colors appear in 15+ components, should use design tokens"
+- "Touch targets consistently too small (<44px) throughout mobile experience"
+
+### Positive Findings
+
+Note what's working well: good practices to maintain and replicate.
+
+## Recommended Actions
+
+List recommended commands in priority order (P0 first, then P1, then P2):
+
+1. **[P?] `$command-name`**: Brief description (specific context from audit findings)
+2. **[P?] `$command-name`**: Brief description (specific context)
+
+**Rules**: Only recommend commands from: $phoenix-ui adapt, $phoenix-ui animate, $phoenix-ui audit, $phoenix-ui bolder, $phoenix-ui clarify, $phoenix-ui colorize, $phoenix-ui critique, $phoenix-ui delight, $phoenix-ui distill, $phoenix-ui document, $phoenix-ui harden, $phoenix-ui layout, $phoenix-ui onboard, $phoenix-ui optimize, $phoenix-ui overdrive, $phoenix-ui polish, $phoenix-ui quieter, $phoenix-ui shape, $phoenix-ui typeset. Map findings to the most appropriate command. End with `$phoenix-ui polish` as the final step if any fixes were recommended.
+
+After presenting the summary, tell the user:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `$phoenix-ui audit` after fixes to see your score improve.
+
+**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
+
+**NEVER**:
+- Report issues without explaining impact (why does this matter?)
+- Provide generic recommendations (be specific and actionable)
+- Skip positive findings (celebrate what works)
+- Forget to prioritize (everything can't be P0)
+- Report false positives without verification

package/skills/phoenix-ui/reference/audit.native.md

@@ -0,0 +1,139 @@
+Run systematic **technical** quality checks on a native app (`ios` / `android` / `adaptive`) and generate a comprehensive report. Don't fix issues; document them for other commands to address.
+
+This is a code-level audit, not a design critique. Audit from source (SwiftUI / UIKit / Compose / React Native / Flutter); no browser tooling or `phoenix-ui detect` applies. Score against the platform reference(s): [ios.md](ios.md) / [android.md](android.md), both for `adaptive`. Read them before scoring if Setup hasn't already. The report skeleton mirrors [audit.md](audit.md); keep the two in sync when changing it.
+
+## Diagnostic Scan
+
+Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
+
+### 1. Accessibility (VoiceOver / TalkBack)
+
+**Check for**:
+- **Missing labels**: interactive elements without accessibility labels, traits/roles, or state announcements
+- **Reading and focus order**: illogical traversal, unreachable controls, focus lost on navigation
+- **Text scaling**: fixed point sizes defeating Dynamic Type (iOS) or px instead of sp (Android); layouts that clip or overlap at large sizes
+- **Touch targets**: below 44 pt (iOS) / 48 dp (Android), or crammed without spacing
+- **Reduce Motion ignored**: parallax and large slides with no crossfade alternative
+- **Contrast**: text failing contrast in either appearance, light or dark
+
+**Score 0-4**: 0=Screen reader unusable, 1=Major gaps (unlabeled controls, no scaling), 2=Partial (labels exist, order or scaling breaks), 3=Good (minor gaps), 4=Excellent (labeled, ordered, scales cleanly, Reduce Motion honored)
+
+### 2. Performance
+
+**Check for**:
+- **Slow startup**: heavy work on launch before first frame
+- **Unvirtualized lists**: long content without FlatList / LazyColumn / List recycling
+- **Main-thread jank**: synchronous work in scroll or gesture paths, dropped frames on 60/120 Hz
+- **Wasted rendering**: unnecessary re-renders (React Native) or recompositions (Compose); missing memoization/keys
+- **Image handling**: full-size images decoded for thumbnails, no caching
+- **App weight**: bloated JS bundle or binary, unused dependencies
+
+**Score 0-4**: 0=Janky everywhere, 1=Major problems (unvirtualized lists, slow launch), 2=Partial, 3=Good (minor improvements possible), 4=Excellent (fast launch, smooth scroll, lean)
+
+### 3. Appearance & Theming
+
+**Check for**:
+- **Hard-coded colors**: raw hex instead of semantic system colors (iOS) / Material color roles (Android) / design tokens
+- **Broken dark appearance**: missing dark variants, poor contrast in dark, quick inverts
+- **Dynamic Color** (Android 12+): no static fallback scheme, or ignored where it fits
+- **Off-platform materials**: hand-rolled visual materials where system materials or tonal elevation are expected
+
+**Score 0-4**: 0=Hard-coded everything, 1=Minimal tokens, 2=Partial (tokens exist, inconsistently used), 3=Good (minor hard-coded values), 4=Excellent (semantic throughout, both appearances first-class)
+
+### 4. Platform Conformance (CRITICAL)
+
+Score against the loaded platform reference(s), including their slop tests. **Check for**:
+- **Broken system gestures**: edge-swipe back disabled (iOS), predictive Back hijacked (Android)
+- **Inset violations**: content under the notch, Dynamic Island, home indicator, status bar, or keyboard
+- **Off-platform navigation**: custom global nav, overloaded tab bars, iOS patterns on Android or vice versa
+- **Web-shaped controls**: HTML-style buttons, custom toggles, hover-dependent affordances
+- **Icon drift**: mixed icon sets instead of SF Symbols / Material Symbols
+- **System drift**: repeated shortcuts or decorative patterns that conflict with the product, platform, or established design system
+
+**Score 0-4**: 0=Web port (nothing native), 1=Heavy violations (3-4 kinds), 2=Some (1-2 noticeable), 3=Mostly conformant (subtle issues), 4=Fully native (a fluent user trusts every screen)
+
+### 5. Adaptivity
+
+**Check for**:
+- **Stretched phone layouts**: tablet/iPad rendering a scaled-up phone UI instead of using size classes / window size classes
+- **Orientation breakage**: landscape clipping, ignored, or locked without reason
+- **Keyboard/IME handling**: inputs hidden behind the keyboard, no inset adjustment
+- **Multitasking**: iPad Split View / Android multi-window breaking layout
+- **Foldables**: hinge-unaware layouts on posture change (Android)
+
+**Score 0-4**: 0=One screen size only, 1=Major breakage (landscape or tablet broken), 2=Partial, 3=Good (minor edge cases), 4=Excellent (adapts across sizes, orientations, and windowing)
+
+## Generate Report
+
+### Audit Health Score
+
+| # | Dimension | Score | Key Finding |
+|---|-----------|-------|-------------|
+| 1 | Accessibility | ? | [most critical issue or "--"] |
+| 2 | Performance | ? | |
+| 3 | Appearance & Theming | ? | |
+| 4 | Platform Conformance | ? | |
+| 5 | Adaptivity | ? | |
+| **Total** | | **??/20** | **[Rating band]** |
+
+**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
+
+### Platform Conformance Verdict
+**Start here.** Pass/fail: does this read as a native app or a ported website? List specific violations. Be brutally honest.
+
+### Executive Summary
+- Audit Health Score: **??/20** ([rating band])
+- Total issues found (count by severity: P0/P1/P2/P3)
+- Top 3-5 critical issues
+- Recommended next steps
+
+### Detailed Findings by Severity
+
+Tag every issue with **P0-P3 severity**:
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or platform-guideline violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
+
+For each issue, document:
+- **[P?] Issue name**
+- **Location**: Screen, file, line
+- **Category**: Accessibility / Performance / Theming / Conformance / Adaptivity
+- **Impact**: How it affects users
+- **Guideline**: The HIG / Material rule it violates (if applicable)
+- **Recommendation**: How to fix it
+- **Suggested command**: Which command to use (prefer: $phoenix-ui adapt, $phoenix-ui animate, $phoenix-ui audit, $phoenix-ui bolder, $phoenix-ui clarify, $phoenix-ui colorize, $phoenix-ui critique, $phoenix-ui delight, $phoenix-ui distill, $phoenix-ui document, $phoenix-ui harden, $phoenix-ui layout, $phoenix-ui onboard, $phoenix-ui optimize, $phoenix-ui overdrive, $phoenix-ui polish, $phoenix-ui quieter, $phoenix-ui shape, $phoenix-ui typeset)
+
+### Patterns & Systemic Issues
+
+Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
+- "Hard-coded colors appear in 15+ screens, should use semantic colors"
+- "Touch targets consistently below 44 pt throughout the tab bar and list rows"
+
+### Positive Findings
+
+Note what's working well: good practices to maintain and replicate.
+
+## Recommended Actions
+
+List recommended commands in priority order (P0 first, then P1, then P2):
+
+1. **[P?] `$command-name`**: Brief description (specific context from audit findings)
+2. **[P?] `$command-name`**: Brief description (specific context)
+
+**Rules**: Only recommend commands from: $phoenix-ui adapt, $phoenix-ui animate, $phoenix-ui audit, $phoenix-ui bolder, $phoenix-ui clarify, $phoenix-ui colorize, $phoenix-ui critique, $phoenix-ui delight, $phoenix-ui distill, $phoenix-ui document, $phoenix-ui harden, $phoenix-ui layout, $phoenix-ui onboard, $phoenix-ui optimize, $phoenix-ui overdrive, $phoenix-ui polish, $phoenix-ui quieter, $phoenix-ui shape, $phoenix-ui typeset. Map findings to the most appropriate command. End with `$phoenix-ui polish` as the final step if any fixes were recommended.
+
+After presenting the summary, tell the user:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `$phoenix-ui audit` after fixes to see your score improve.
+
+**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
+
+**NEVER**:
+- Report issues without explaining impact (why does this matter?)
+- Provide generic recommendations (be specific and actionable)
+- Skip positive findings (celebrate what works)
+- Forget to prioritize (everything can't be P0)
+- Report false positives without verification

package/skills/phoenix-ui/reference/bolder.md

@@ -0,0 +1,33 @@
+> **Additional context needed**: which section is the target, and what must stay untouched.
+
+An open direction round owns the word first: "bolder" said while a direction decision is on the table is the Bolder hand register steer, a fresh deal of foreign forms (see new-work.md), not this command. This command refines a surface whose world already shipped.
+
+"Bolder" is an amplification request, and almost always it is scoped to something that already exists. The surrounding page, its system, and its conventions are the given. Your job is to raise one part to the conviction the rest already implies, without rebuilding anything the brief did not name. The reflex answer, reaching for more effects, is the opposite of bold; reject it first.
+
+## Scope is sovereign
+
+"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Name the exact addition and the job it would do.
+
+## Why it reads flat
+
+A section usually reads flat for reasons its neighbors have already solved. Look at what the rest of the page does that this section does not: the display type at full strength, the structural devices that carry meaning, the signature motif, the density and pacing. A flat section is typically one that quietly opts out of the system's own strongest moves. The most reliable bolder pass brings the target up to the expressive level its neighbors already reach, in the system's own vocabulary rather than a new one.
+
+## The amplification
+
+- **Amplify what the system already owns.** Reuse its motif and its type scale at full strength, turned up for this section rather than invented for it. The bolder version should look more like the same brand, not less.
+- **Keep content true.** Existing claims are part of the scope: preserve them unless the user supplies replacements. If real evidence is essential to the direction but absent, ask for it.
+- **Commit, then clarify.** Half-measures read as noise. Make the one decisive move completely, then quiet everything around it so the move is legible. If every element got louder, the section got flatter.
+- **Give it its own rhythm.** The target should read as a peak in the scroll, a shift in density or pace from what surrounds it, not simply more of the same.
+
+## The skeleton test
+
+Strip the copy out of your planned section and study the bare structure. Does the skeleton still say what this section is and why it matters, through hierarchy and the system's devices alone? If it only works once the words return, the boldness is in the text size, not the design. A placeholder for an image or artifact names a job, an anchor and a piece of evidence, not a cue to drop in a decorative photo; fill that job with whatever the subject actually has.
+
+## Before you finish
+
+- Everything outside the named target is unchanged.
+- No new color, font, or system primitive appeared without being asked for.
+- The conventions the section carried, including anything that drives an action, still work the same way.
+- The section is unmistakably the same brand, only more sure of itself.
+
+When the target holds its own without pulling the page apart, hand off to `$phoenix-ui polish` for the final pass.

package/skills/phoenix-ui/reference/clarify.md

@@ -0,0 +1,94 @@
+> **Additional context needed**: audience knowledge and emotional state.
+
+Rewrite unclear interface text so users understand what happened, what matters, and what to do next. Preserve factual meaning, product terminology, and brand voice.
+
+## Audit the language
+
+Read the entire interaction path, not isolated strings. Identify:
+
+- ambiguous nouns, verbs, and actions;
+- internal jargon or assumed knowledge;
+- vague labels, outcomes, and system states;
+- missing consequences, recovery, or timing;
+- inconsistent terminology and capitalization;
+- redundant headings, intros, helper text, and confirmations;
+- text that breaks at realistic widths or in translation;
+- tone that ignores stress, risk, success, or urgency.
+
+Infer audience and task from product context and surrounding UI. Ask before changing factual claims, legal meaning, or a term that may be domain-specific.
+
+## Set the message hierarchy
+
+For each state, decide:
+
+1. the one fact the user needs now;
+2. the action available next;
+3. supporting context that changes the decision;
+4. the appropriate tone for this moment.
+
+Say each idea once. If the heading already explains the state, the introduction should add new information or disappear.
+
+## Rewrite by function
+
+### Actions and navigation
+
+Use a specific verb and object when the outcome is not already obvious. Labels should describe what will happen, not the gesture used to trigger it. Keep the same noun and verb for the same concept throughout the product.
+
+For destructive actions, name the object and consequence. Prefer undo over confirmation when recovery is safe. When confirmation is necessary, name the action on both the message and button instead of using `Yes`, `No`, `OK`, or `Submit`.
+
+### Forms
+
+Use persistent labels; placeholders are examples, not labels. Put format and eligibility requirements before submission. Explain why information is requested only when it is not obvious. Required and optional treatment should be consistent.
+
+Validation says what needs attention and how to correct it without blaming the user. Keep related instructions near the field and announce errors accessibly.
+
+### Errors and permissions
+
+An actionable error answers:
+
+1. what failed;
+2. why, when known and useful;
+3. how to recover or what alternative remains.
+
+Do not expose internal codes as the primary message. Do not promise a cause or resolution the system cannot know. Treat privacy, payment, deletion, access loss, and blocked work seriously; warmth is welcome, jokes are not.
+
+### Loading, empty, and success states
+
+Loading text names the real operation and sets an honest expectation when the wait is meaningful. Show determinate progress when available; never invent progress.
+
+An empty state distinguishes first use, no results, filters, permissions, and failure. Explain the state and provide the next useful action.
+
+Success confirms the completed outcome and mentions the next consequence only when it changes what the user should do. Routine success should be brief.
+
+### Help and instructional text
+
+Helper text answers an implicit question instead of restating the control. Use progressive disclosure for uncommon detail. Link text must make sense out of context; icon-only controls need accessible names.
+
+## Voice, accessibility, and localization
+
+Voice stays consistent; tone adapts to the moment. Use plain language without flattening terminology the audience genuinely knows.
+
+- Write complete translatable messages rather than concatenated fragments.
+- Keep variables and numbers structured so translators can reorder them.
+- Allow expansion instead of abbreviating prematurely.
+- Make alt text convey the image's information; use empty alt for decoration.
+- Keep screen-reader names aligned with visible labels and outcomes.
+- Do not rely on punctuation, color, or iconography to carry the message alone.
+
+Maintain a short terminology glossary when inconsistency spans the product. Do not vary words for literary effect in an interface.
+
+## Verify
+
+Read the flow in context and test:
+
+- comprehension without hidden product knowledge;
+- actionability at errors, empty states, and decision points;
+- factual accuracy and consistent terminology;
+- scanability at target widths and 200% zoom;
+- long names, localization expansion, pluralization, and dynamic values;
+- accessible names and announced state changes;
+- tone appropriate to consequence and emotional context.
+
+The final copy is as short as it can be without removing meaning or recovery.
+
+When the language reads cleanly, hand off to `$phoenix-ui polish` for the final pass.

package/skills/phoenix-ui/reference/colorize.md

@@ -0,0 +1,86 @@
+> **Additional context needed**: existing brand colors.
+
+Introduce color as hierarchy, meaning, and atmosphere. Preserve confirmed brand and semantic conventions; do not replace a visual world under the guise of colorizing it.
+
+---
+
+## Visitor mode
+
+- **Persuade + Experience:** color may carry the voice and own large regions when the selected world calls for it.
+- **Operate + Read:** color primarily encodes action, selection, status, wayfinding, and reading hierarchy. Rarity gives an accent force.
+
+## Audit before choosing
+
+Read DESIGN.md, tokens, assets, current themes, and representative states. Identify:
+
+- which colors are confirmed brand commitments;
+- current surface, text, action, and semantic roles;
+- places where grayscale obscures hierarchy or state;
+- contrast failures and color-only communication;
+- light/dark or data-visualization requirements;
+- whether the task asks for more color or a new identity.
+
+If a new identity is required, use [new-work.md](new-work.md). Ask only when a binding brand decision cannot be inferred.
+
+## Choose a strategy
+
+Name the intended emotional temperature, dominant relationship, contrast range, and color dosage before editing. The strategy may be restrained or immersive; it must follow the brief and selected world rather than a fixed percentage rule.
+
+Build roles, not a bag of swatches:
+
+- canvas and elevated surfaces;
+- primary and secondary text;
+- action, focus, and selection;
+- borders and separators;
+- success, warning, error, and information;
+- data categories or scales when needed.
+
+Use the project's existing color space. For a new web palette, prefer OKLCH because lightness and chroma can be adjusted predictably. Choose hue from product meaning and visual direction, never from a default category association.
+
+## Apply at system scale
+
+- Let the strongest color own a deliberate region or role instead of scattering tiny accents.
+- Keep the primary action easy to find; do not spend its color on decoration.
+- Tint neutrals only when the brand hue genuinely creates cohesion. Neutral gray is valid when it serves the world.
+- On colored surfaces, derive secondary text from the foreground or surface hue rather than using washed-out generic gray.
+- Keep semantic meanings consistent, but respect platform and domain conventions instead of assuming fixed hues.
+- For data, use distinct lightness, chroma, shape, label, or pattern so color is not the only code.
+- In dark mode, design surface elevation and contrast explicitly; do not invert the light theme mechanically.
+- Define primitive values and semantic tokens when the project has a token system. Theme changes should normally remap semantic roles.
+
+Decoration without a relationship to hierarchy, state, content, or the visual world is not a color strategy.
+
+## Contrast and perception
+
+Verify computed foreground/background pairs:
+
+| Content | WCAG AA minimum |
+|---|---|
+| body text | 4.5:1 |
+| large text | 3:1 |
+| controls, icons, focus indicators | 3:1 |
+
+Do not rely on eyesight alone. Check interactive states, overlays, text on images, disabled content, and both themes. Simulate common vision deficiencies. Information conveyed by color also needs text, shape, iconography, or position.
+
+When deriving OKLCH ramps, vary lightness and reduce chroma near white and black. Do not keep high chroma at extreme lightness merely to make the math uniform. Prefer explicit colors over chains of translucent overlays when alpha would make contrast context-dependent.
+
+## Verify
+
+- Every color has a stable role or a world-specific atmospheric purpose.
+- Attention lands on the intended action, content, or state.
+- The palette works across quiet, dense, interactive, error, and empty states.
+- Light and dark themes are each composed, not mechanically inverted.
+- Contrast and non-color cues pass in all relevant states.
+- The result is recognizably this product, not a generic “colorful” treatment.
+
+When the palette earns its place, hand off to `$phoenix-ui polish` for the final pass.
+
+## Live-mode signature params
+
+When invoked from live mode, every variant declares a `color-amount` parameter. Author CSS against `var(--p-color-amount, 0.5)` so the user can move from neutral to the variant's full color strategy without regeneration.
+
+```json
+{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}
+```
+
+Add at most two variant-specific parameters, such as palette, temperature, or tint behavior. Follow [live.md](live.md)'s parameter contract.

package/skills/phoenix-ui/reference/component-review.md

@@ -0,0 +1,63 @@
+# Plan and asset review
+
+Use this checkpoint on comp-led builds once every raster region has its plate and the plates gate has scored them, before any page code exists. The approved comp is the reference. The user reviews two things: the plates that will ship, and the production plan for everything else, meaning which regions code draws. A painted region planned as code is the most expensive mistake a comp-led build makes, and this is where the user catches it. Text, controls and chrome are judged later, in the assembled first viewport.
+
+## Plan, capture, serve
+
+Run `<skill-base-dir>/scripts/phoenix-ui component-review plan`. It writes `.phoenix-ui/review/components.json` from the measured spec, the comp and the plate files, and refuses, naming each one, while any raster region lacks its plate. Never write or edit that file for this stage: the packet is derived from the spec, so every change belongs in the regions file.
+
+If the harness exposes `component_review`, call it with `manifest_path` set to `.phoenix-ui/review/components.json`. The host captures, presents the review and returns the user's decisions. A suspended request is waiting for the user; it is not a failed build or an approval.
+
+Otherwise run `<skill-base-dir>/scripts/phoenix-ui component-review capture --manifest .phoenix-ui/review/components.json`, then start `<skill-base-dir>/scripts/phoenix-ui component-review serve --session <returned session>` in the background. Open the URL it prints in the available browser and wait for the user; `serve` exits 0 once they submit. Read the decisions with `<skill-base-dir>/scripts/phoenix-ui component-review status --session <id>`; `<skill-base-dir>/scripts/phoenix-ui component-review verify --manifest .phoenix-ui/review/components.json` confirms approval and refuses pending, needs-work and stale input. Never submit the page or write a receipt on the user's behalf.
+
+`serve` exits 2 when this session has no browser (the same signal as the decision page) and 4 when it closes after 30 idle minutes without a decision. Either way no one is reviewing: stop waiting, do not approve anything yourself, and do not build past this checkpoint. End the run and report the plan and asset review as pending with its session ID, so the user can resume it. A waiting review is pending work, not a completed build.
+
+## Act on the receipt
+
+Apply the user's decisions as given, never your own favorable verdict in their place.
+
+- **approve**: once every item is approved and the inventory is confirmed, advance to the hero.
+- **revise** (a plate): regenerate that plate at the same path with the user's feedback.
+- **revise with split** (an asset): replace that region in the regions file with its layers: a frame plate with a transparent opening (kind `plate`, same box), the content as its own `image` region at the opening's box, and each moving part (a shutter, a door) as its own plate. Name each layer after the original region, as `<id>-frame`, `<id>-view` or `<id>-shutter-left`, so the next round shows it as part of the user's request. Rerun `<skill-base-dir>/scripts/phoenix-ui comp-spec --comp <comp.png> --regions <regions.json>` and produce the plates.
+- **revise** (a plan item): change the regions file as the feedback says (resize or extend a raster region, split material into its own plate region, or adjust the code region), rerun `<skill-base-dir>/scripts/phoenix-ui comp-spec --comp <comp.png> --regions <regions.json>`, and produce any new plates.
+- **reclassify** (a code region): in the regions file, change that region's `kind` to the one the user chose and rewrite its `note` to describe the material. Rerun `<skill-base-dir>/scripts/phoenix-ui comp-spec --comp <comp.png> --regions <regions.json>`, then produce the new plates, with the asset producer when subagents are available.
+- **missing**: add the region to the regions file, rerun `<skill-base-dir>/scripts/phoenix-ui comp-spec --comp <comp.png> --regions <regions.json>`, and produce its plate if it is raster.
+
+Then run `plan`, `capture` and `serve` again. Unchanged decisions carry over, so the user sees only what changed. Any spec change, or a plate replaced after acceptance, needs a new round; the build-phase gate stays closed until the review of the current spec is accepted.
+
+## Assemble and review
+
+Build the first viewport from the approved plates and plan, and run the hero gate. Human review does not waive its integrity checks. After three failed hero attempts, stop iterating and present the first-viewport review with the current build; the user's eye settles what the readings could not.
+
+Present a second manifest at `.phoenix-ui/review/hero.json`. You write this one, and its shape is fixed:
+
+```json
+{
+  "schemaVersion": 2,
+  "stage": "hero",
+  "id": "hero",
+  "title": "First viewport",
+  "comp": {"path": ".phoenix-ui/mocks/comp.png", "width": 1536, "height": 1024},
+  "components": [{
+    "id": "first-viewport",
+    "name": "First viewport",
+    "medium": "HTML / CSS",
+    "note": "Assembled first viewport",
+    "box": {"x": 0, "y": 0, "w": 1, "h": 1},
+    "preview": {"kind": "page", "path": "index.html"},
+    "dependencies": ["styles.css", "assets/plates/sky.png", "fonts/display.woff2"]
+  }]
+}
+```
+
+- `schemaVersion` is 2. Version 3 is the plan review packet and requires stage `components`. `codeRegions` and `specSha256` exist only in version 3 and are refused here. `reviewGroup` is refused too: version 3 rejects it, and any other version accepts it only on a page preview in a `components`-stage manifest, never in a hero manifest.
+- `comp.path` is the `comp` value in `.phoenix-ui/build/spec.json`, and `width` and `height` are that PNG's pixel size.
+- Exactly one component, with `box` exactly `{"x": 0, "y": 0, "w": 1, "h": 1}` and `name`, `medium` and `note` as strings.
+- `preview.path` is the page entry the build gates (`artifact` in `.phoenix-ui/build/state.json`).
+- `dependencies` lists every other file the page loads (stylesheets, scripts, plates, images, fonts) as bare strings. Every path, here and above, is project-relative and plain: no leading `./` or `/`, no `..`, no URL, no `?`, `#`, `%`, `:` or backslash. A request to a file missing from this list, or to another host, fails the capture.
+
+The reference stays the approved comp. Call the same host review tool, or run `capture`, `serve` and `verify` with this manifest. Needs-work feedback starts another assembly round.
+
+Acceptance closes human review for this build: never request plan, asset or assembly approval again. While the page renders what the user accepted, the hero score, the palette check and every numeric reading are advisories; material vetoes still hold (a missing or unreferenced plate, an SVG illustration, an organic clip, a clipped plate, invented ink, failed rendered presence). When the capture no longer matches the accepted screenshot, restore what the user accepted; until then the readings apply. Complete the rest of the page, responsive behavior, finish checks and documentation with the accepted first viewport as the visual direction. This is first-viewport calibration, not a claim that the user reviewed the rest of the page. Shared stylesheet edits do not reopen approval. Preserve the accepted direction; a later explicit user change is a new task.
+
+Assembled-page capture executes inline and declared local scripts from the pinned inputs. Network APIs, frames and workers are unavailable; the initial viewport must settle before capture. Keep the real page and declare its scripts rather than removing behavior to pass review.