@xgent-ai/skills 0.6.0 → 0.7.0

package/vendor/phoenix-ui/bundle/blobs/7fcc966302139a5327e95ff4422112647975518b94a5c0796c4ed9f0c24343ab

@@ -0,0 +1,95 @@
+---
+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
+---
+
+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 `.cursor/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 `.cursor/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:** `.cursor/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/800abbc76533113fe7fc1bf5d1d7ef57b58961be7f297c693e847dfaeeaefbd2

@@ -0,0 +1,418 @@
+Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
+
+Use design-md's writing authority and source rules. Preserve an existing Markdown structure, YAML, unknown fields, comments and explicit tokens; partial context parsing does not authorize deleting or rewriting them. Existing accepted decisions and frozen targets require their own approved change scope. The canonical format below is a template for a newly authorized document or format migration, not a prerequisite for reading an incumbent DESIGN.md. A profile cannot supply missing colors or fonts.
+
+DESIGN.md follows the [official DESIGN.md format spec](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md): optional YAML frontmatter carrying machine-readable design tokens, followed by up to eight markdown sections in a fixed order. **Tokens are normative; prose provides context for how to apply them.** Sections may be omitted when not relevant, but those present stay in the specified order. Use the canonical headings below so the file remains portable across DESIGN.md-aware tools.
+
+## The frontmatter: token schema
+
+The YAML frontmatter is the machine-readable layer. It's what Stitch's linter validates and what the live panel renders tiles from. Keep it tight; every entry should correspond to a token the project actually uses.
+
+```yaml
+---
+name: <project title>
+description: <one-line tagline>
+colors:
+  primary: "#b8422e"
+  neutral-bg: "#faf7f2"
+  # ...one entry per extracted color; key = descriptive slug
+typography:
+  display:
+    fontFamily: "Cormorant Garamond, Georgia, serif"
+    fontSize: "clamp(2.5rem, 7vw, 4.5rem)"
+    fontWeight: 300
+    lineHeight: 1
+    letterSpacing: "normal"
+  body:
+    # ...
+rounded:
+  sm: "4px"
+  md: "8px"
+spacing:
+  sm: "8px"
+  md: "16px"
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.neutral-bg}"
+    rounded: "{rounded.sm}"
+    padding: "16px 48px"
+  button-primary-hover:
+    backgroundColor: "{colors.primary-deep}"
+---
+```
+
+Rules that matter:
+
+- **Token refs** use `{path.to.token}` (e.g. `{colors.primary}`, `{rounded.md}`). Components may reference primitives; primitives may not reference each other.
+- **Colors accept any valid CSS color string.** Hex is the recommended default for portability, but preserve an incumbent `rgb()`, `hsl()`, `oklch()`, wide-gamut, or mixed-color value when it is the project's normative source. Never split the source of truth without explicit reason.
+- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter: none of those fit. Carry them in the sidecar (Step 4b).
+- **Scale keys are open-ended.** Use whatever names the project already uses (`oxblood-deep`, `surface-container-low`). Don't rename to Material defaults.
+- **Variants are naming convention, not schema.** `button-primary` / `button-primary-hover` / `button-primary-active` as sibling keys.
+
+## The markdown body: eight sections (canonical order)
+
+1. `## Overview`
+2. `## Colors`
+3. `## Typography`
+4. `## Layout`
+5. `## Elevation & Depth`
+6. `## Shapes`
+7. `## Components`
+8. `## Do's and Don'ts`
+
+Omit irrelevant sections rather than filling them with invented rules. Put responsive layout in Layout, depth in Elevation & Depth, radius and form language in Shapes, and per-component behavior in Components. Unknown sections are preserved by the format, but new visual guidance should use the canonical structure whenever it fits.
+
+## When to run
+
+- New-work found a coherent incumbent visual system but no `DESIGN.md`.
+- The first implementation of a new world is complete and its provisional decisions need to be carbonized.
+- An existing `DESIGN.md` is stale (the design has drifted).
+- Before a large redesign, to capture the current state as a reference.
+
+If a `DESIGN.md` already exists, read it and follow the already authorized refresh, overwrite or merge scope. When that choice is unresolved, show the existing source and ask once about the intended change. Preserve explicit tokens and unknown fields through either path.
+
+## Two paths
+
+- **Scan mode** (default): the project has design tokens, components, or rendered output. Extract, then confirm descriptive language. Use when there's code to analyze.
+- **Seed mode**: the project is pre-implementation. Ensure PRODUCT.md exists, then reuse new-work's visual-world workshop and write its directional DESIGN.md seed. Re-run in scan mode once there's code.
+
+Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode; don't silently switch. `$phoenix-ui document --seed` requests new-work's world workshop, but it does not authorize replacing coherent code: when an incumbent system exists, offer scan mode or route an explicit identity-replacement request through new-work.
+
+## Scan mode (approach C: auto-extract, then confirm descriptive language)
+
+### Step 1: Find the design assets
+
+Search the codebase in priority order:
+
+1. **CSS custom properties**: grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
+2. **Tailwind config**: if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
+3. **CSS-in-JS theme files**: styled-components, emotion, vanilla-extract, stitches; look for `theme.ts`, `tokens.ts`, or equivalent.
+4. **Design token files**: `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
+5. **Component library**: scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
+6. **Global stylesheet**: the root CSS file usually has the base typography and color assignments.
+7. **Visible rendered output**: if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss.
+
+### Step 2: Auto-extract what can be auto-extracted
+
+Build a structured draft from the discovered tokens. For each token class:
+
+- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral; omit Secondary and Tertiary rather than inventing them.
+- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
+- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer; state it explicitly.
+- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
+- **Layout + spacing**: Extract grid, container, breakpoint, rhythm, and density behavior into Layout.
+- **Shapes**: Extract radius, corner, border, clipping, and recurring form behavior into Shapes.
+
+### Step 2b: Stage the frontmatter
+
+From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer: what the live panel and Stitch's linter consume.
+
+- **Colors**: one entry per extracted color. Key = descriptive slug (`oxblood-deep`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex; see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value.
+- **Typography**: one entry per role (`display`, `headline`, `title`, `body`, `label`). Typography is an object; include only the props that are real for the project (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`).
+- **Rounded / Spacing**: whatever scale steps the project actually uses, keyed by whatever scale name the project uses (`sm` / `md` / `lg`, or `surface-sm`, or numeric steps).
+- **Components**: one entry per variant (`button-primary`, `button-primary-hover`, `button-ghost`). Reference primitives via `{colors.X}`, `{rounded.Y}`. If a variant needs a property Stitch's 8-prop set doesn't cover (shadow, focus ring, backdrop-filter), carry the full snippet in the sidecar instead.
+
+Skip anything the project doesn't have. Empty scale keys or fabricated tokens pollute the spec.
+
+### Step 3: Ask the user for qualitative language
+
+Reuse qualitative decisions already present in the original request, accepted brief or existing DESIGN.md. Ask about the following only when a material decision is still missing, in structured rounds of no more than three questions each (or the harness's lower limit), waiting between rounds:
+
+- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
+- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, and any confirmed visual anti-reference.
+- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
+- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
+- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
+
+Carry a line from PRODUCT.md only when it is a durable brand commitment that actually constrains the visual system. Page strategy and surface concepts do not belong here.
+
+### Step 4: Write DESIGN.md
+
+The file opens with the YAML frontmatter staged in Step 2b (schema documented at the top of this reference), then the markdown body using the canonical structure below.
+
+```markdown
+---
+name: [Project Title]
+description: [one-line tagline]
+colors:
+  # ... staged frontmatter from Step 2b
+---
+
+# Design System: [Project Title]
+
+## Overview
+
+**Creative North Star: "[Named metaphor in quotes]"**
+
+[2-3 paragraph holistic description: personality, density, and aesthetic philosophy. Start from the North Star and work outward. State only confirmed visual rejections. End with a short **Key Characteristics:** bullet list.]
+
+## Colors
+
+[Describe the palette character in one sentence.]
+
+### Primary
+- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
+
+### Secondary (optional; omit if the project has only one accent)
+- **[Descriptive Name]** (#HEX): [Role.]
+
+### Tertiary (optional)
+- **[Descriptive Name]** (#HEX): [Role.]
+
+### Neutral
+- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
+- [...]
+
+### Named Rules (optional, powerful)
+**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine, e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
+
+## Typography
+
+**Display Font:** [Family] (with [fallback])
+**Body Font:** [Family] (with [fallback])
+**Label/Mono Font:** [Family, if distinct]
+
+**Character:** [1-2 sentence personality description of the pairing.]
+
+### Hierarchy
+- **Display** ([weight], [size/clamp], [line-height]): [Purpose; where it appears.]
+- **Headline** ([weight], [size], [line-height]): [Purpose.]
+- **Title** ([weight], [size], [line-height]): [Purpose.]
+- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
+- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
+
+### Named Rules (optional)
+**The [Rule Name] Rule.** [Short doctrine about type use.]
+
+## Layout
+
+[Describe the grid or spatial model, container behavior, density, responsive changes, and the spacing rhythm. Include exact values only when observed.]
+
+## Elevation & Depth
+
+[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
+
+### Shadow Vocabulary (if applicable)
+- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
+- [...]
+
+### Named Rules (optional)
+**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
+
+## Shapes
+
+[Describe the form language: corner/radius strategy, borders, clipping, and any recurring silhouette or geometry.]
+
+## Components
+
+For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
+
+### Buttons
+- **Shape:** [radius described, exact value in parens]
+- **Primary:** [color assignment + padding, in semantic + exact terms]
+- **Hover / Focus:** [transitions, treatments]
+- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
+
+### Chips (if used)
+- **Style:** [background, text color, border treatment]
+- **State:** [selected / unselected, filter / action variants]
+
+### Cards / Containers
+- **Corner Style:** [radius]
+- **Background:** [colors used]
+- **Shadow Strategy:** [reference Elevation section]
+- **Border:** [if any]
+- **Internal Padding:** [scale]
+
+### Inputs / Fields
+- **Style:** [stroke, background, radius]
+- **Focus:** [treatment, e.g. glow, border shift, etc.]
+- **Error / Disabled:** [if applicable]
+
+### Navigation
+- **Style, typography, default/hover/active states, mobile treatment.**
+
+### [Signature Component] (optional; if the project has a distinctive custom component worth documenting)
+[Description.]
+
+## Do's and Don'ts
+
+Concrete visual guardrails grounded in the incumbent implementation or the user's chosen world. Lead each with "Do" or "Don't" and include exact values only when established. Do not turn a task-specific concept or surface strategy into a system-wide prohibition.
+
+### Do:
+- **Do** [specific prescription with exact values / named rule].
+- **Do** [...]
+
+### Don't:
+- **Don't** [specific prohibition confirmed by the incumbent system or the user].
+- **Don't** [...]
+- **Don't** [...]
+```
+
+### Step 4b: Write .phoenix-ui/design.json sidecar (extensions only)
+
+The frontmatter owns token primitives (colors, typography, rounded, spacing, components). The sidecar at `.phoenix-ui/design.json` carries **what Stitch's schema can't hold**: tonal ramps per color, shadow/elevation tokens, motion tokens, breakpoints, full component HTML/CSS snippets (the panel renders these into a shadow DOM), and narrative (north star, rules, do's/don'ts). It extends the frontmatter, it doesn't duplicate it.
+
+Regenerate the sidecar whenever you regenerate root `DESIGN.md`. If the user only asks to refresh the sidecar (e.g., from the live panel's stale-hint), preserve `DESIGN.md` and write only `.phoenix-ui/design.json`.
+
+#### Schema
+
+```json
+{
+  "schemaVersion": 2,
+  "generatedAt": "ISO-8601 string",
+  "title": "Design System: [Project Title]",
+  "extensions": {
+    "colorMeta": {
+      "primary":        { "role": "primary",  "displayName": "Editorial Magenta", "canonical": "oklch(60% 0.25 350)", "tonalRamp": ["...", "...", "..."] },
+      "cool-paper": { "role": "neutral",  "displayName": "Cool Paper",    "canonical": "oklch(96% 0.005 230)", "tonalRamp": ["...", "...", "..."] }
+    },
+    "typographyMeta": {
+      "display": { "displayName": "Display", "purpose": "Hero headlines only." }
+    },
+    "shadows": [
+      { "name": "ambient-low", "value": "0 4px 24px rgba(0,0,0,0.12)", "purpose": "Diffuse hover glow under accent elements." }
+    ],
+    "motion": [
+      { "name": "ease-standard", "value": "cubic-bezier(0.4, 0, 0.2, 1)", "purpose": "Default easing for state transitions." }
+    ],
+    "breakpoints": [
+      { "name": "sm", "value": "640px" }
+    ]
+  },
+  "components": [
+    {
+      "name": "Primary Button",
+      "kind": "button | input | nav | chip | card | custom",
+      "refersTo": "button-primary",
+      "description": "One-line what and when.",
+      "html": "<button class=\"ds-btn-primary\">SAVE CHANGES</button>",
+      "css": ".ds-btn-primary { background: #191c1d; color: #fff; padding: 16px 48px; letter-spacing: 0.05em; text-transform: uppercase; font-weight: 500; border: none; border-radius: 0; transition: background 0.2s, transform 0.2s; } .ds-btn-primary:hover { background: oklch(60% 0.25 350); transform: translateY(-2px); }"
+    }
+  ],
+  "narrative": {
+    "northStar": "The Editorial Sanctuary",
+    "overview": "2-3 paragraphs of the philosophy, pulled from DESIGN.md Overview section.",
+    "keyCharacteristics": ["...", "..."],
+    "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }],
+    "dos":   ["Do use ..."],
+    "donts": ["Don't use ..."]
+  }
+}
+```
+
+**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter (tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints), keyed by the frontmatter token name (`colorMeta.<token-name>`, `typographyMeta.<token-name>`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them.
+
+#### Component translation rules
+
+The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly: no post-processing, no framework runtime.
+
+1. **Tailwind expansion.** If the source uses Tailwind (className="bg-primary text-white rounded-lg px-6 py-3"), expand every utility to literal CSS properties in the `css` string. Do **not** reference Tailwind classes; do **not** assume a Tailwind CSS bundle is loaded. Each component is self-contained.
+2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)`; they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time.
+3. **Icons.** Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or `<img src="...">`. A typical icon is 16-24px; copy the SVG path data directly.
+4. **States.** Include `:hover`, `:focus-visible`, and (if meaningful) `:active` rules inline. A static default-only snapshot makes the panel feel dead. Hover + focus rules in the CSS make it feel alive.
+5. **Reset bloat.** Extract only the component's *distinctive* CSS (background, color, padding, border-radius, typography, transition). Skip universal resets (`box-sizing: border-box`, `line-height: inherit`, `-webkit-font-smoothing`). The panel already has a neutral canvas; don't re-ship resets.
+6. **Scoped class names.** Prefix every class with `ds-` (e.g. `ds-btn-primary`, `ds-input-search`) so component CSS doesn't collide with other components' CSS in the same shadow DOM.
+
+#### What to include
+
+Aim for a tight set of **5-10 components** that best represent the visual system:
+
+- **Canonical primitives (always include if the project has them):** button (each variant as a separate component entry), input/text field, navigation, chip/tag, card.
+- **Signature components (include if distinctive):** the recurring custom patterns that actually define the implemented system.
+- **Skip the rest.** Utility components, form building blocks, wrapper layouts: not worth documenting unless visually distinctive.
+
+If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every `.phoenix-ui/design.json` has *something* to render, even on day zero.
+
+#### Tonal ramps
+
+For each color token, generate an 8-step `tonalRamp` array: dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH.
+
+#### Narrative mapping
+
+Pull directly from the DESIGN.md you just wrote:
+
+- `narrative.northStar` → the `**Creative North Star: "..."**` line from Overview
+- `narrative.overview` → the philosophy paragraphs from Overview
+- `narrative.keyCharacteristics` → the bulleted `**Key Characteristics:**` list
+- `narrative.rules` → every `**The [Name] Rule.** [body]` across all sections, tagged with `section`
+- `narrative.dos` / `narrative.donts` → the bullet lists from Do's and Don'ts verbatim
+
+Do not reword. The panel shows these as secondary collapsible context; the same voice that's in the Markdown carries through.
+
+### Step 5: Confirm and refine
+
+1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules).
+2. Mention that `.phoenix-ui/design.json` was also written alongside; the live panel will now render this project's actual button/input/nav primitives instead of generic approximations.
+3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
+
+Your own write is the freshest source; subsequent commands in this session don't need a reload.
+
+## Seed mode
+
+For projects with no visual system to extract yet. Produces a user-chosen visual-world scaffold, not a fabricated token spec.
+
+### Step 1: Route through new-work's workshop
+
+PRODUCT.md is the prerequisite. If it is missing, load [init.md](init.md) and complete its product interview first. Do not create a visual identity without durable product context.
+
+If PRODUCT.md exists, load [new-work.md](new-work.md) and resolve visual authority. Seed mode requires a concrete first surface: use the target the user named, or ask what they want to make first. Run new-work's **Create or replace the visual world** flow, then **Commit the world**, so the visual world and its first expression are chosen together. Stop after the directional DESIGN.md seed and surface brief; do not implement. A structured simulated user counts as the user and must get the same choice.
+
+If new-work already completed the workshop in this session, use its chosen direction directly. Do not ask again.
+
+### Step 2: Write seed DESIGN.md
+
+Use the canonical section order from Scan mode. Populate the selected workshop direction and leave unresolved implementation facts as honest placeholders. The seed commits a world and its invariants; it does not pretend implementation tokens already exist.
+
+Lead the file with:
+
+```markdown
+<!-- SEED: established with the user before implementation; re-run $phoenix-ui document once there's code to capture the actual tokens and components. -->
+```
+
+Per-section guidance in seed mode:
+
+- **Overview**: the chosen design thesis, layout behavior, material character, imagery stance, motion grammar, and reusable signature. Keep the selected first-surface expression in its surface brief; do not promote its composition into the global world.
+- **Colors**: the selected palette strategy and roles. Include values only when the user, an existing asset, or new-work's exploration established them; otherwise mark them `[to be resolved during implementation]`.
+- **Typography**: the selected type character and role relationship. Include font names only when established; otherwise mark the pairing `[to be resolved during implementation]`.
+- **Layout**: the selected spatial grammar and responsive behavior, without pretending exact measurements are settled.
+- **Elevation & Depth**: the selected material and depth behavior, stated as an invariant rather than inferred from a generic preset.
+- **Shapes**: the selected form and corner language.
+- **Components**: omit entirely; no components exist yet.
+- **Do's and Don'ts**: record the durable guardrails confirmed during the world choice, not task-local refusals.
+
+Seed mode writes a minimal frontmatter with `name` and `description` only; no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `.phoenix-ui/design.json` sidecar in seed mode for the same reason: nothing to render.
+
+### Step 3: Confirm
+
+1. Show the seed DESIGN.md. Call out that it is a seed (the marker is the literal commitment).
+2. Tell the user: "Re-run `$phoenix-ui document` once you have some code. That pass will extract real tokens and generate the sidecar."
+
+Your own write is the freshest source; no reload needed.
+
+## Style guidelines
+
+- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places; the frontmatter is normative.
+- **Carry only durable product constraints.** A binding logo, identity asset, accessibility need, or brand commitment from PRODUCT.md may constrain DESIGN.md. Surface strategy stays in its surface brief.
+- **Match the spec.** Use its eight canonical sections in order and omit any that are irrelevant. Put motion guidance with the world or component it affects rather than creating a token group the schema does not support.
+- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
+- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
+- **Exact values in parens**: hex codes, px/rem values, font weights; always the number in parens alongside the description.
+- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
+- **Be decisive where evidence is decisive.** Use hard language for actual invariants and softer language for provisional guidance.
+- **Use concrete audit tests only when they are grounded in the observed system or a confirmed user decision.** A one-sentence test beats a paragraph of principle.
+- **Reference PRODUCT.md selectively.** Product truth explains why the world fits; it does not supply page composition or a visual don't-list by default.
+- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
+
+## Pitfalls
+
+- Don't paste raw CSS class names. Translate to descriptive language.
+- Don't extract every token. Stop at what's actually reused; one-offs pollute the system.
+- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
+- Don't overwrite an existing DESIGN.md without asking.
+- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
+- Don't replace canonical sections with near-synonyms. Put layout and responsive behavior in `Layout`; put motion with the affected world or component.
+- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
+- Don't duplicate token values between frontmatter and prose. If a color is in `colors.primary` as hex, the prose can name it and describe its role but should not reassert a different hex. The frontmatter is normative.
+- Don't invent frontmatter token groups outside Stitch's schema (no `motion:`, `breakpoints:`, `shadows:` at the top level). Stitch's Zod schema only accepts `colors`, `typography`, `rounded`, `spacing`, `components`. Anything else belongs in the sidecar's `extensions`.

package/vendor/phoenix-ui/bundle/blobs/80301c933f175b9c9ce28e6d24216b8aa394379c3f3f0b8447e31d93b80a348c

@@ -0,0 +1,104 @@
+One-time live-mode project setup. Loaded from [live.md](live.md) only when `phoenix-ui live` reports `config_missing` / `config_invalid`, when `configDrift` needs handling, or when the config lacks `cspChecked`. Not part of the per-session hot path.
+
+## Write the config
+
+Create the file at the `path` the boot reported (default `.phoenix-ui/live/config.json`):
+
+```json
+{
+  "files": ["<path-or-glob>", "<path-or-glob>", ...],
+  "exclude": ["<optional-glob>", ...],
+  "insertBefore": "</body>",
+  "commentSyntax": "html",
+  "cspChecked": true
+}
+```
+
+`files` is the inject target: **the HTML files the browser actually loads**, not necessarily source (tracked vs generated does not matter here; wrap has its own generated-file guard). Entries are literal paths or globs. `exclude` (optional) skips files a `files` glob would otherwise include (email templates, demo fixtures). `cspChecked` records that the CSP step below has run; absent on first setup.
+
+**Hard-excluded paths (cannot be overridden):** `**/node_modules/**` and `**/.git/**`; injecting there would instrument third-party code.
+
+**Glob syntax:** `**` matches any number of segments (including zero), `*` matches within a segment, `?` matches one character. Paths are project-root-relative with forward slashes.
+
+| Framework | `files` | `insertBefore` | `commentSyntax` |
+|-----------|---------|----------------|-----------------|
+| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
+| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
+| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
+| Nuxt | `["app.vue"]` | `</body>` | `html` |
+| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
+| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
+| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
+| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
+| Multi-page (separate HTML per route) | `["public/**/*.html"]` glob over the served dir | `</body>` | `html` |
+
+Pick an anchor that exists in every file (`</body>` almost always works); `insertAfter` matches after a line instead. For multi-page sites prefer a glob so new pages are picked up automatically. For sites whose pages are rebuilt by a generator, the inject survives only until the next regeneration: re-run `phoenix-ui live` after each build (accept is unaffected; it writes true source via the fallback flow).
+
+**Framework adapters (auto-detected at inject time).** Every inject records what it wrote in `.phoenix-ui/live/inject-journal.json`; the next inject or remove heals artifacts a crash or wrong-directory stop left behind. SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably; `phoenix-ui live-inject` detects them and routes to a dedicated adapter (SvelteKit: dev-only root component from `+layout.svelte`; Nuxt: dev-only `.client.ts` plugin; TanStack Start: a generated dev-only `Phoenix UILiveRoot` component in `__root`). The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA takes the baseline Vite path.
+
+## Config drift
+
+On every boot the project is scanned for HTML files under common page roots (`public/`, `src/`, `app/`, `pages/`) that the resolved `files` list does not cover; they surface as `configDrift.orphans` with a hint. Tell the user once per session which files are uncovered and offer to add them or switch `files` to a glob. Never auto-update the config; the user decides. `configDrift` is `null` when there is no drift.
+
+## CSP detection (first-time only)
+
+Keep all allowances below development-only, including manual middleware and meta-tag edits. Do not change a deployed production site's CSP to load the localhost helper; see [live.md](live.md) for production inspection alternatives.
+
+If `config.cspChecked === true`, skip this whole section; the user was already asked once.
+
+```bash
+.agent/skills/phoenix-ui/scripts/phoenix-ui detect-csp
+```
+
+Output `{ shape, signals }`; the shape names the *patch mechanism*, so one template covers many frameworks:
+
+- **`null`**: no CSP; write the config with `cspChecked: true` and stop here.
+- **`append-arrays`**: CSP as structured directive arrays; auto-patchable (monorepo helpers with `additionalScriptSrc`/`additionalConnectSrc`, SvelteKit `kit.csp.directives`, Nuxt `nuxt-security`).
+- **`append-string`**: CSP as a literal value string; auto-patchable (inline `next.config.*` `headers()`, Nuxt `routeRules`).
+- **`middleware`** / **`meta-tag`**: detected but not auto-patched. Show the user the detected files, ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
+
+### Consent prompt (use this phrasing)
+
+> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
+>
+> ```diff
+> [file: <patchTarget>]
+> [exact diff, 2-5 lines]
+> ```
+>
+> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
+
+On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`.
+
+### append-arrays
+
+Declare near the top of the file that holds the CSP arrays, then append `...__phoenixUiLiveDev` to the script-src and connect-src arrays:
+
+```ts
+// Dev-only allowance so phoenix-ui live mode can load. Guarded by NODE_ENV.
+const __phoenixUiLiveDev =
+  process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
+```
+
+Per-framework: Next.js + monorepo helper: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` / `additionalConnectSrc`. SvelteKit: `svelte.config.js`, `kit.csp.directives['script-src']` and `['connect-src']`. Nuxt + nuxt-security: `nuxt.config.*`, `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`. Reference outputs: [nextjs-turborepo/expected-after-patch.ts](https://github.com/pbakaus/impeccable/blob/8dac6ae7e020c43ab10ce9b41939f6fd42627b96/tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts), [sveltekit-csp/expected-after-patch.js](https://github.com/pbakaus/impeccable/blob/8dac6ae7e020c43ab10ce9b41939f6fd42627b96/tests/framework-fixtures/sveltekit-csp/expected-after-patch.js). Idempotency: if `__phoenixUiLiveDev` already exists in the file, the patch is applied; just mark `cspChecked: true`.
+
+### append-string
+
+Two-point patch: declare a dev-only string, interpolate it into the CSP value at both directives (leading space so it concatenates cleanly; convert literals to template strings as part of the edit):
+
+```ts
+// Dev-only allowance so phoenix-ui live mode can load.
+const __phoenixUiLiveDev =
+  process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
+```
+
+- `script-src 'self' 'unsafe-inline'` becomes `` `script-src 'self' 'unsafe-inline'${__phoenixUiLiveDev}` ``
+- `connect-src 'self'` becomes `` `connect-src 'self'${__phoenixUiLiveDev}` ``
+
+Per-framework: Next.js inline `headers()` in `next.config.*`; Nuxt `routeRules['/**'].headers['Content-Security-Policy']` in `nuxt.config.*`. Reference outputs: [nextjs-inline-csp/expected-after-patch.js](https://github.com/pbakaus/impeccable/blob/8dac6ae7e020c43ab10ce9b41939f6fd42627b96/tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js), [nuxt-csp/expected-after-patch.ts](https://github.com/pbakaus/impeccable/blob/8dac6ae7e020c43ab10ce9b41939f6fd42627b96/tests/framework-fixtures/nuxt-csp/expected-after-patch.ts).
+
+## Troubleshooting
+
+If the user said "no" to the CSP patch and later reports live not working: their dev CSP blocks `http://localhost:8400`. Delete `cspChecked` from `.phoenix-ui/live/config.json` and re-run `phoenix-ui live`; setup asks again.
+
+After setup, re-run `phoenix-ui live`.