qualia-framework 5.9.1 → 6.2.7

package/skills/qualia-vibe/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: qualia-vibe
+description: "Fast aesthetic pivot — swap the design vibe (tokens: color, typography, motion, depth) without touching component structure or layout. Default mode proposes ONE direction (per rules/one-opinion.md). Sub-modes: --variants for A/B/C menu (only when user explicitly asked), --extract URL to reverse-engineer DESIGN.md from a reference site, --sync to back-sync code → DESIGN.md when tokens drifted in code. Triggers: 'different vibe', 'change the look', 'swap the aesthetic', 'try something bolder', 'redesign the look', 'match this site', 'sync the design file'."
+disable-model-invocation: false
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# /qualia-vibe — Fast Aesthetic Pivot
+
+Swap the **vibe** without redoing the **app**. Tokens only: color, typography, depth, motion, brand accents. Component structure, routing, data flow, and layout grid stay exactly where they were. This is the difference between `/qualia-vibe` (~3 min) and `/qualia-polish --redesign` (~30 min).
+
+## When to use
+
+- Client said "I want a different vibe" / "make it look bolder" / "this feels too startup-y" → `/qualia-vibe`
+- You want to test if a different aesthetic is right BEFORE committing the redesign → `/qualia-vibe`
+- You want to match a reference site's design system → `/qualia-vibe --extract https://example.com`
+- Someone changed CSS vars or Tailwind config directly and DESIGN.md is out of sync → `/qualia-vibe --sync`
+- You want to enumerate options (rare — see `rules/one-opinion.md`) → `/qualia-vibe --variants 3`
+
+## When NOT to use
+
+- The complaint is "this component is broken" or "the spacing is wrong" → `/qualia-polish` (component or section scope).
+- The site has no DESIGN.md yet → run `/qualia-new` first; vibe is a PIVOT, not a cold start.
+- You want a structural redesign (layout, navigation, information architecture) → `/qualia-polish --redesign` (~30 min ground-up).
+
+## Layout-preservation contract
+
+`/qualia-vibe` ONLY changes:
+
+- Color tokens (CSS vars / Tailwind palette / brand accents).
+- Typography (font-family, scale, weights, italic accents).
+- Depth tokens (shadow elevations, border treatments).
+- Motion tokens (easing, duration, signature interactions).
+- The "Aesthetic direction" line in DESIGN.md §1.
+
+It does NOT touch:
+
+- Component structure (`return (…)` JSX is preserved).
+- Routing, data fetching, business logic.
+- Layout grid (responsive breakpoints, container widths).
+- Information architecture or copy.
+
+If the user actually wants structural change, route to `/qualia-polish --redesign`.
+
+## Modes
+
+### Default — propose one pivot, apply it
+
+Per `rules/one-opinion.md`. Read PRODUCT.md register + anti-references + scene sentence. Propose ONE concrete direction with one-paragraph justification. Ask one yes/no: "Ship this, or pivot?" If user pivots, ask what they didn't like, propose ONE alternative. Never widen.
+
+### `--variants N`
+
+The opt-in menu. Generate N concrete direction briefs (each 4 lines: direction / color / typography / motion). Use `AskUserQuestion` to let the user pick. Default N=3, max 5.
+
+### `--extract <URL or image path>`
+
+Reverse-engineer a DESIGN.md draft from a reference. Captures a screenshot at 1440 (via `scripts/playwright-capture.mjs`), runs an extract-mode vision prompt (NOT score-mode), outputs structured tokens matching DESIGN.md sections 1-7. User reviews + edits the draft before applying.
+
+### `--sync`
+
+Back-sync. Reads the codebase's actual CSS vars, Tailwind config, and font imports. Diffs against DESIGN.md. Outputs (a) tokens in code not in DESIGN.md ("undocumented"), (b) tokens in DESIGN.md not in code ("orphaned"), (c) tokens that drifted in value. With `--sync --write`, patches DESIGN.md to match code.
+
+## Process
+
+### 0. Pre-flight gates
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner vibe 2>/dev/null
+
+# DESIGN.md must exist
+test -f .planning/DESIGN.md || {
+  echo "DESIGN.md not found. Run /qualia-new (or /qualia-polish --redesign for a ground-up redesign) first."
+  exit 1
+}
+
+# PRODUCT.md should exist (for register + anti-references context)
+test -f .planning/PRODUCT.md || echo "Warning: PRODUCT.md missing — vibe proposals will be less anchored. Consider /qualia-new first."
+```
+
+### 1. Parse the mode
+
+- `--extract <url-or-path>` → go to Extract flow.
+- `--sync` (with optional `--write`) → go to Sync flow.
+- `--variants [N]` → go to Variants flow.
+- Direction explicitly named on command line (e.g. `/qualia-vibe brutalist`) → skip proposal, jump to Apply.
+- Otherwise → Default (propose one).
+
+### 2. Default flow (propose one)
+
+Read substrate:
+- `.planning/PRODUCT.md` (register, anti-references, scene sentence)
+- `.planning/DESIGN.md` (current direction, current token set)
+- `qualia-design/design-laws.md` (banned patterns)
+- `qualia-design/design-brand.md` OR `qualia-design/design-product.md` (matching register)
+
+Propose ONE direction. Output format:
+
+```
+Current: {DESIGN.md §1 direction line}
+Proposed: {ONE new direction, concrete — e.g. "editorial broadsheet, ivory ground, deep navy ink, italic Cormorant accents"}
+Why: {1-2 sentences citing PRODUCT.md register, anti-refs, scene sentence}
+Token deltas: {3-7 bullet token changes the pivot implies}
+Cost: ~3 min to apply, layout preserved.
+```
+
+Use `AskUserQuestion` with two options: `Ship this pivot` / `Different direction`.
+
+If "Different direction": ask one follow-up — "What about the proposal didn't fit?" — then propose ONE new direction with the rejection incorporated. Never enumerate alternatives.
+
+### 3. Apply
+
+Once user approves a direction:
+
+1. Update DESIGN.md §1 (Aesthetic direction).
+2. Update DESIGN.md §2 (Color — OKLCH token set).
+3. Update DESIGN.md §3 (Typography — font-family, scale).
+4. Update DESIGN.md §6 (Depth — shadow elevations).
+5. Update DESIGN.md §7 (Motion — easing, duration).
+6. Apply the same token changes to code:
+   - CSS vars in `app/globals.css` or `src/styles/globals.css` (whichever exists)
+   - `tailwind.config.{ts,js,mjs}` colors / fonts / spacing extensions
+   - Font imports (`@import url(...)` in CSS, or `<link>` in `app/layout.tsx`, or `next/font/google` calls)
+7. Run `node ~/.claude/bin/slop-detect.mjs` on changed files. Block on critical findings (no banned fonts in the new vibe).
+8. Capture one screenshot at desktop (1440) for visual diff:
+   ```bash
+   node ~/.claude/skills/qualia-polish/scripts/playwright-capture.mjs \
+     --url ${URL:-http://localhost:3000} \
+     --out .planning/vibe-after.png \
+     --width 1440
+   ```
+9. Commit:
+   ```bash
+   git -c user.name="Qualia Vibe" -c user.email="vibe@qualia.solutions" \
+     commit -m "vibe(pivot): {old direction} → {new direction}"
+   ```
+
+If the commit fails (no dev server, no slop-detect, network error), surface the exact failure — do NOT silently swallow.
+
+### 4. Variants flow
+
+```bash
+node ~/.claude/skills/qualia-vibe/scripts/tokens.mjs propose-variants \
+  --product .planning/PRODUCT.md \
+  --design  .planning/DESIGN.md \
+  --count   ${N:-3}
+```
+
+Output N briefs side-by-side. `AskUserQuestion` with N options (one per variant) plus "None of these — propose something else". User picks one → continue to Apply (step 3).
+
+### 5. Extract flow
+
+```bash
+node ~/.claude/skills/qualia-vibe/scripts/extract.mjs \
+  --source ${URL_OR_IMAGE} \
+  --out    .planning/DESIGN-extracted.md
+```
+
+The script:
+1. If source is a URL, capture screenshot via `playwright-capture.mjs`.
+2. Sends screenshot + extract-mode prompt to visual-evaluator agent.
+3. Visual evaluator returns a JSON token bundle (color OKLCH, font families, scale, depth, motion).
+4. Script renders the bundle into a DESIGN.md draft.
+
+Present the draft. Diff against current DESIGN.md. User can: `Apply as new vibe`, `Save draft only`, or `Cancel`. If apply → Apply flow (step 3) using the extracted tokens.
+
+### 6. Sync flow
+
+```bash
+node ~/.claude/skills/qualia-vibe/scripts/tokens.mjs sync \
+  --design .planning/DESIGN.md \
+  ${WRITE:+--write}
+```
+
+The script:
+1. Greps CSS for `:root { --token: value; }` declarations.
+2. Reads `tailwind.config.*` for colors / fonts / spacing extensions.
+3. Parses font imports.
+4. Diffs against DESIGN.md token sections.
+5. Prints three sections: `Undocumented (in code, not in DESIGN.md)`, `Orphaned (in DESIGN.md, not in code)`, `Drifted (different values)`.
+6. If `--write`, patches DESIGN.md to match code; commits with `vibe(sync): align DESIGN.md to code`.
+
+## Output contracts
+
+Vibe always writes ONE of these as its final line:
+
+- `DONE — vibe pivot: {old direction} → {new direction} ({sha})`
+- `DONE — vibe extract: draft saved to {path}`
+- `DONE — vibe sync: {N} drift findings ({sha if --write})`
+- `CANCELLED — user declined all proposed pivots`
+- `BLOCKED — {reason}` (DESIGN.md missing, slop-detect critical, etc.)
+
+## Rules
+
+1. **One opinion by default.** Per `rules/one-opinion.md`. Menus require explicit `--variants`.
+2. **Layout never changes.** If the proposal would require touching JSX structure, route to `/qualia-polish --redesign` and stop.
+3. **DESIGN.md and code stay in sync.** Every apply writes BOTH. Sync mode exists to recover from drift, not to normalize it.
+4. **slop-detect is the brake.** A pivot that introduces a banned font / gradient / hex-in-jsx is rejected. The new vibe must pass the same gates as the old one.
+5. **One screenshot, not three.** Vibe is fast by design. The full 3-viewport check belongs in `/qualia-polish --loop` after the vibe lands.
+6. **Commit identity is local.** Vibe sets git user inline so it works on fresh clones without global config.
+
+## Anti-patterns
+
+- ❌ Presenting "Here are 5 directions: pick one" when the user said "change the vibe". → Use `rules/one-opinion.md`: propose ONE.
+- ❌ Touching `return (…)` JSX. → If the pivot needs structural change, stop and route to `--redesign`.
+- ❌ Skipping slop-detect because "the user is in a hurry". → The vibe pivot is exactly when banned fonts/gradients sneak in.
+- ❌ Auto-running `--sync --write` without surfacing the diff first. → Always show drift before patching DESIGN.md.
+- ❌ Treating `--extract` output as ground truth. → It's a DRAFT. User must approve before apply.
+
+## Examples
+
+```
+/qualia-vibe                           # propose one pivot, apply on approval
+/qualia-vibe brutalist                 # explicit pivot to named direction
+/qualia-vibe --variants 3              # generate 3 options (use sparingly)
+/qualia-vibe --extract https://stripe.com
+/qualia-vibe --extract ./refs/inspo.png
+/qualia-vibe --sync                    # show drift between code and DESIGN.md
+/qualia-vibe --sync --write            # patch DESIGN.md to match code, commit
+```

package/skills/qualia-vibe/scripts/extract.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * extract.mjs — reverse-engineer a DESIGN.md draft from a URL or screenshot.
+ *
+ * Pipeline:
+ *   1. If source is a URL → capture screenshot at 1440 via playwright-capture.mjs.
+ *      If source is a local image path → use it directly.
+ *   2. Emit a JSON scaffold the LLM uses to generate the extracted token bundle.
+ *   3. The skill (qualia-vibe) reads the scaffold, runs the vision evaluator in
+ *      extract mode, gets the bundle back, renders it as a DESIGN.md draft.
+ *
+ * This script does NOT call any LLM directly — it stages the inputs and emits
+ * a deterministic JSON contract. The /qualia-vibe skill orchestrates the LLM
+ * call.
+ *
+ * Usage:
+ *   extract.mjs --source <URL or image path> [--out <path>]
+ *
+ * Exit codes:
+ *   0  success — JSON scaffold emitted to stdout, screenshot path included
+ *   1  capture failed (network, no playwright, bad URL)
+ *   2  invocation error
+ */
+
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { argv, exit, env } from "node:process";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+function flag(name, fallback) {
+  const i = argv.indexOf(name);
+  if (i < 0) return fallback;
+  return argv[i + 1] || fallback;
+}
+
+const source = flag("--source");
+const outDraft = flag("--out", ".planning/DESIGN-extracted.md");
+
+if (!source) {
+  console.error("--source required (URL or local image path)");
+  exit(2);
+}
+
+// ─── Stage 1: locate or capture screenshot ────────────────────────────
+
+let screenshotPath;
+
+const isUrl = /^https?:\/\//i.test(source);
+if (isUrl) {
+  const stamp = Date.now().toString(36);
+  const outDir = join(tmpdir(), `qualia-vibe-extract-${stamp}`);
+  mkdirSync(outDir, { recursive: true });
+  screenshotPath = join(outDir, "ref-1440.png");
+
+  // Resolve playwright-capture.mjs — search the same order as loop.mjs.
+  const candidates = [
+    env.QUALIA_CAPTURE_SCRIPT,
+    `${env.HOME}/.claude/skills/qualia-polish/scripts/playwright-capture.mjs`,
+    resolve(dirname(new URL(import.meta.url).pathname), "..", "..", "qualia-polish", "scripts", "playwright-capture.mjs"),
+  ].filter(Boolean);
+  const captureScript = candidates.find((p) => existsSync(p));
+  if (!captureScript) {
+    console.error("playwright-capture.mjs not found. Install the framework or set QUALIA_CAPTURE_SCRIPT.");
+    exit(1);
+  }
+
+  const r = spawnSync("node", [
+    captureScript,
+    "--url", source,
+    "--out", screenshotPath,
+    "--width", "1440",
+  ], { encoding: "utf8" });
+
+  if (r.status !== 0 || !existsSync(screenshotPath)) {
+    console.error(`screenshot capture failed (exit=${r.status})`);
+    if (r.stderr) console.error(r.stderr);
+    exit(1);
+  }
+} else {
+  screenshotPath = resolve(source);
+  if (!existsSync(screenshotPath)) {
+    console.error(`image not found: ${screenshotPath}`);
+    exit(2);
+  }
+  try { statSync(screenshotPath).isFile(); } catch {
+    console.error(`source must be a file: ${screenshotPath}`);
+    exit(2);
+  }
+}
+
+// ─── Stage 2: emit extraction scaffold ────────────────────────────────
+
+const scaffold = {
+  mode: "extract",
+  source: source,
+  screenshot: screenshotPath,
+  output_draft: outDraft,
+  instruction:
+    "Examine the screenshot and EXTRACT the visible design tokens. Do NOT score, judge, or critique — describe what is actually present. Output the bundle matching the schema below. If a value is not visible (e.g. motion in a static screenshot), set it to null.",
+  schema: {
+    aesthetic_direction: "1 sentence — name the aesthetic in concrete terms",
+    color: {
+      strategy: "Restrained | Committed | Full palette | Drenched",
+      ground: "OKLCH or hex of the dominant background",
+      ink: "OKLCH or hex of the dominant text color",
+      accent: "OKLCH or hex of the single brand accent (if present)",
+      notes: "1 sentence on color logic visible (e.g. 'single saturated accent, otherwise neutrals')",
+    },
+    typography: {
+      primary_family: "best guess at the headline font family",
+      secondary_family: "best guess at body / sans counterpart, or null",
+      scale_observation: "tight | airy | dramatic | flat — one word",
+      weight_range: "e.g. '400/600' or 'mono single weight'",
+      italic_usage: "common | rare | never",
+    },
+    spatial: {
+      grid_observation: "8px | 12-col | bespoke | dense | airy — one phrase",
+      max_width_observation: "narrow | medium | wide | full",
+    },
+    depth: {
+      shadow_intensity: "none | subtle | bold",
+      borders: "hairline | medium | heavy | none",
+    },
+    motion: {
+      visible: "true | false | unknown (static)",
+      character: "snap | glide | spring | none",
+    },
+    register_guess: "Brand | Product | hybrid",
+    confidence: "low | medium | high",
+  },
+  rules: [
+    "Banned fonts: Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk, Montserrat, Poppins, Lato, Open Sans. If you see one of these, name it AND flag it so the user can decide whether to ban or accept.",
+    "Banned patterns: purple-blue gradient, gradient text, bounce/elastic easing. Flag the same way.",
+    "Confidence < high → user must review before /qualia-vibe applies.",
+  ],
+  next_step: `After producing the bundle, write a DESIGN.md draft to ${outDraft} using the bundle to populate sections 1 (Direction), 2 (Color), 3 (Typography), 4 (Spacing), 6 (Depth), 7 (Motion). Leave sections that depend on PRODUCT.md or anti-references empty — the user will fill them.`,
+};
+
+console.log(JSON.stringify(scaffold, null, 2));
+exit(0);