analyzthis_design 1.20.1 → 2.0.1

package/dist/skills/deliberation-protocol/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: deliberation-protocol
+description: Adversarial deliberation protocol for all design personas. Personas ground objections in real task/PRD/UI context, run parallel critique rounds with low default satisfaction until consensus or Raj escalation. Use when personas hand off, deliberate, object, or review prior output.
+---
+
+# Deliberation Protocol (v1.19)
+
+Personas are **hard to satisfy by design**. They do not pass generic handoff documents — they **read, object, and ask contextual questions** about the real task, PRD, UI, and design system until evidence resolves objections or Raj arbitrates.
+
+Schema: `agents/deliberation-schema.json`
+
+---
+
+## Two modes
+
+| Mode | When | Output |
+|------|------|--------|
+| **Review** | Rounds 0..N-1, or when prior `persona_outputs` exist | Objections, questions, grounding — **not** a full rewrite |
+| **Produce** | Final round after consensus or Raj ruling | Full persona output schema + deliberation JSON |
+
+Default: `accepts_prior: false`, `satisfaction_with_prior` below threshold (0.4) until specific claims are addressed with evidence.
+
+---
+
+## Mandatory grounding
+
+Every **objection** must include `grounded_in` citing one of:
+
+- `task_map[N]` — primary user task from session
+- PRD excerpt from knowledge bank / vault
+- UI region (e.g. header, primary CTA, nav)
+- DS token or component path from repo
+
+**Forbidden:** generic handoff paragraphs ("Arjun scored X, therefore…") without contesting a **specific claim**.
+
+---
+
+## Deliberation JSON block (required)
+
+End every review-round response with:
+
+```json deliberation
+{
+  "grounding": [{"type": "task_map", "ref": "task_map[0]", "note": "Primary task is checkout, CTA buried"}],
+  "satisfaction_with_prior": 0.25,
+  "accepts_prior": false,
+  "objections": [{
+    "target_persona": "arjun",
+    "claim": "Friction is low because labels are clear",
+    "evidence_required": "Show task completion path in 3 steps from PRD",
+    "blocking": true,
+    "grounded_in": "task_map[0]: complete purchase in under 60s"
+  }],
+  "questions": ["Why is secondary nav above primary CTA given task_map[0]?"],
+  "revisions": ["Move primary CTA above fold, align with hierarchy rank #1"],
+  "verdict": "CONTEST"
+}
+```
+
+Verdict values: `CONTEST` | `ACCEPT` | `SHIP` | `REVISE` | `BLOCK`
+
+---
+
+## Parallel adversarial pairs
+
+From `agents/chain.json` → `deliberation_groups`:
+
+- **Critique:** Arjun → Meera∥Priya → Zara
+- **Ideation:** Meera → Noor∥Anuj → Arjun → Zara∥Priya
+- **Lite MoE:** Arjun → Meera
+
+Parallel personas critique **each other's output** on the same round — not independent essays.
+
+---
+
+## Raj escalation
+
+Activate Raj when:
+
+- 2+ unresolved **blocking** objections
+- Same claim repeats without new evidence (stalemate)
+- Round >= `escalate_to_raj_after_round` (default 2) with open objections
+
+**Order (v1.20):** Raj runs **after all deliberation groups complete** — e.g. Zara always runs before Raj in the critique chain.
+
+Raj reads all `persona_outputs` + `deliberation.round_log` and issues mandatory Stalemate Resolution.
+
+---
+
+## CLI / config
+
+```bash
+npx analyzthis_design run --task "..." --full --dry-run   # shows deliberation groups
+npx analyzthis_design run --task "..." --satisfaction 0.3  # harder to please
+npx analyzthis_design run --task "..." --max-rounds 2
+npx analyzthis_design run --task "..." --no-deliberate   # legacy sequential
+```
+
+Config (`~/.analyzthis_design/config.json`):
+
+```json
+{
+  "deliberation": {
+    "satisfaction_threshold": 0.4,
+    "max_rounds": 3,
+    "parallel_pairs": [["noor", "anuj"], ["meera", "priya"]],
+    "objection_token_cap": 600,
+    "prior_output_chars_first": 800,
+    "prior_output_chars_rebuttal": 400,
+    "prior_output_chars_produce": 1200,
+    "context_pack_chars_objection": 1500,
+    "context_pack_chars_produce": 3000,
+    "escalate_to_raj_after_round": 2
+  }
+}
+```
+
+**Low satisfaction ≠ unlimited tokens.** Objection rounds use **lite persona cards** (not full SKILL.md), **600-token output cap** (enforced on API + Devi/host), and **400-char prior-output snippets** on rebuttal rounds (parsed deliberation JSON summary preferred). Only synthesis and Raj produce rounds use full schemas.
+
+---
+
+## Session state
+
+After deliberation runs, `session-state.json` includes:
+
+- `deliberation.round_log` — per-persona parsed blocks per round
+- `deliberation.open_objections` — unresolved blocking items
+- `deliberation.consensus_reached` — boolean
+- `metrics.deliberation_rounds`, `objections_raised`, `objections_resolved`, `raj_escalations`
+
+Inspect: `npx analyzthis_design session show` | `npx analyzthis_design metrics`

package/dist/skills/design-critic/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: design-critic
+description: Run a structured multi-persona design critique with 4 specialist agents — Arjun (UX + Visual), Meera (Business), Priya (Feasibility), Zara (Delight). Includes an Information Hierarchy Gate that surfaces hierarchy failures regardless of composite score. Use when you want a rigorous, multi-dimensional review of a screen, flow, feature design, or UI mockup. Returns a Composite Score, verdict (SHIP/REVISE/BLOCK), and ranked action items.
+---
+
+# Design Critic
+
+Four specialist personas evaluate a design independently across UX, business, feasibility, and delight dimensions. Then synthesize into a composite verdict.
+
+---
+
+## Step -1: Load knowledge bank (highest priority)
+
+Before anything else, read the knowledge-bank skill from your host (sibling preferred): `~/.cursor/skills/knowledge-bank/SKILL.md`, `~/.claude/skills/knowledge-bank/SKILL.md`, `~/.grok/skills/knowledge-bank/SKILL.md`, `~/.agents/skills/knowledge-bank/SKILL.md`, or legacy `~/.claude/commands/knowledge-bank.md`.
+
+If the knowledge bank has content (i.e. it is not the "No knowledge bank connected yet" placeholder):
+- Treat every section in the knowledge bank as **ground truth** for this project
+- Brand guidelines, design decisions, product context, and research insights override your built-in defaults
+- Reference specific knowledge bank entries when scoring or critiquing — quote them directly when relevant
+
+If the knowledge bank is empty or missing, proceed without it.
+
+---
+
+## Step 0: Gather session context
+
+Before starting, ask the user for (or read from `_session-context` if available):
+
+```
+Product name:
+Primary user (role, session frequency, entity volume):
+North-star metric:
+Tech stack + design system:
+Is this a high-frequency working surface? [yes / no / mixed]
+First-time user surfaces in scope? [yes / no]
+Known research data (engagement rates, drop-off points, support tickets):
+```
+
+If any field is blank, treat it as "unknown — do not assume."
+
+---
+
+## Phase 1 — Arjun (UX lens)
+
+Read `~/.cursor/skills/arjun/SKILL.md` and activate Arjun.
+
+Arjun produces two output blocks: UX Critique (Honeycomb) and Visual Design Audit. Score the UX Honeycomb using the grade rubric in his SKILL.md, then run the Visual Design Audit in full — do not skip it even if Desirable scored B or above. Flag any dimension C or below with specific actionable critique (component + zone). His combined score = (UX score + Visual score) / 2. Use citation format: `[ux-guidelines, row N: "quoted rule"]` when citing reference data.
+
+---
+
+## Phase 2 — Meera (Business lens)
+
+Read `~/.cursor/skills/meera/SKILL.md` and activate Meera.
+
+**Adversarial review (v1.19):** Read `deliberation-protocol` from your host skills dir (sibling preferred), e.g. `~/.cursor/skills/deliberation-protocol/SKILL.md`, `~/.claude/skills/deliberation-protocol/SKILL.md`, `~/.grok/skills/deliberation-protocol/SKILL.md`, `~/.agents/skills/deliberation-protocol/SKILL.md`, or legacy `~/.claude/commands/deliberation-protocol.md`. Do NOT open with a generic handoff paragraph. Instead:
+- Read Arjun's output and **contest specific claims** with business evidence from task_map and knowledge bank
+- Default `accepts_prior: false` until hierarchy matches north-star metric
+- Meera runs **in parallel with Priya** in adversarial mode — each objects to the other's assumptions about adoption vs effort
+
+Produce the Business Impact output block after review rounds. Use citation format: `[products.csv, row N: "quoted value"]`.
+
+---
+
+## Phase 3 — Priya (Feasibility lens)
+
+Read `~/.cursor/skills/priya/SKILL.md` and activate Priya.
+
+**Adversarial review:** Challenge Meera's adoption assumptions and Arjun's UX fixes with **concrete implementation cost**. Cite real stack/components from knowledge bank. Parallel with Meera — object, do not summarize.
+
+Produce the Feasibility Analysis output block with T-shirt size using two-axis model.
+
+---
+
+## Phase 4 — Zara (Delight lens)
+
+Read `~/.cursor/skills/zara/SKILL.md` and activate Zara.
+
+**Adversarial review:** Given Priya's effort ceiling, **contest** whether delight budget exists. Object if delight would violate hierarchy or feasibility constraints.
+
+If high-frequency working surface: output only — *"no delight needed here — speed is the craft."*
+
+Otherwise produce the Delight Pass output block after deliberation rounds close.
+
+---
+
+## Phase 4.5 — Deliberation synthesis (before composite score)
+
+Read `deliberation-protocol` from your host skills dir (sibling preferred), e.g. `~/.cursor/skills/deliberation-protocol/SKILL.md`, `~/.claude/skills/deliberation-protocol/SKILL.md`, `~/.grok/skills/deliberation-protocol/SKILL.md`, `~/.agents/skills/deliberation-protocol/SKILL.md`, or legacy `~/.claude/commands/deliberation-protocol.md`.
+
+- Run objection rounds until `consensus_reached` or Raj escalates (2+ blocking objections, stalemate)
+- CLI: `npx analyzthis_design run --task "..." --full` enforces this in standalone runtime
+- Phase 5 composite score runs **only after** deliberation closes — not after pass-the-parcel handoffs
+
+---
+
+## Phase 5 — Composite score and verdict
+
+After all four personas have spoken:
+
+```
+## Composite Score
+Arjun (UX + Visual): [1–5]  ← combined score: (UX score + Visual score) / 2
+Meera (Business):    [1–5]
+Priya (Feasibility): [1–5]
+Zara (Delight):      [1–5]
+Total:               [sum /20]
+
+Verdict:
+  SHIP   = 16–20 (ready to build)
+  REVISE = 10–15 (specific changes required before build)
+  BLOCK  = <10   (fundamental problems; activate Raj)
+
+Top 3 actionable changes (ranked by impact):
+1. [change] — assigned to [Arjun/Meera/Priya/Zara]
+2. [change] — assigned to [...]
+3. [change] — assigned to [...]
+```
+
+---
+
+## Information Hierarchy Gate
+
+Run this check immediately after Phase 5, before the re-evaluation protocol or BLOCK escalation. Information hierarchy failures are treated like accessibility failures — they bypass the composite score math because a screen that leads with the wrong thing is broken regardless of how well everything else scores.
+
+Check both signals:
+1. **Arjun's Visual Hierarchy dimension** (from the Visual Design Audit) — did it score C or below?
+2. **Meera's Hierarchy check line** (from the Business Impact block) — did rank #1 on screen fail to match the north-star driver?
+
+```
+## Information Hierarchy Gate
+Arjun's Visual Hierarchy grade: [A–F]
+Meera's Hierarchy check: [matches / does not match]
+Gate status: [PASS / FAIL]
+```
+
+**If either signal fails:** the hierarchy issue is inserted into the Top 3 actionable changes automatically, even if it would not otherwise have ranked in the top 3 by score impact. State explicitly: *"Inserted by the Information Hierarchy Gate — this bypasses normal ranking because [Arjun / Meera] flagged a hierarchy failure."*
+
+**If both signals pass:** no gate action needed, proceed normally.
+
+---
+
+## Browser Verify Gate (post-phase)
+
+After the Information Hierarchy Gate and before declaring SHIP, if a running URL is available, run the same steps as `ux-story-gate` Phase 4.5: navigate → snapshot → click the primary task → screenshot at mobile + desktop. Record results in session state (`verify_results`). Do not declare SHIP if the primary interaction is broken. If browser tools are unavailable, mark `verify_results.primary_task: "not_run"` explicitly.
+
+---
+
+## Re-evaluation Protocol (after REVISE verdict)
+
+When the user applies changes and re-shares the updated design:
+
+1. Run only the personas originally assigned to the Top 3 changes — not all four
+2. Re-score only the Honeycomb dimensions that were flagged C or below
+3. Issue a delta verdict:
+
+```
+## Re-evaluation
+Changes applied: [list what the user addressed]
+Personas re-run: [Arjun / Meera / Priya / Zara — only those assigned]
+
+Updated scores:
+  [Persona]: [old score] → [new score] — [one-line reason]
+  [Persona]: [old score] → [new score] — [one-line reason]
+
+Total: [old /20] → [new /20]
+Updated verdict: SHIP / REVISE / BLOCK
+Information Hierarchy Gate: [PASS / FAIL — re-check if it was previously FAIL]
+```
+
+If new total ≥ 16 AND the Information Hierarchy Gate passes: verdict upgrades to SHIP — no further changes required.
+If new total remains <10, or the Information Hierarchy Gate still fails: activate Raj.
+
+---
+
+## BLOCK escalation
+
+If Composite Score < 10, or if two personas reach a structural objection neither will concede:
+
+Read `~/.cursor/skills/raj/SKILL.md` and activate Raj.
+Raj produces a revision directive using the mandatory Decision Format from his skill file.
+
+---
+
+## Relationship rules between personas
+
+- Arjun owns the visual foundation (Visual Design Audit) — he diagnoses and prescribes visual fixes himself, in full, on every pass
+- Zara adds exactly ONE delight moment on top of Arjun's visual foundation — she does not re-audit visual quality
+- Meera translates Arjun's friction points into retention and ARR language
+- Priya cost-checks every Zara delight addition — names cost (low/medium/high) explicitly
+- Raj only speaks during stalemate, BLOCK, or a persistent Information Hierarchy Gate failure — does not volunteer opinions
+- Information hierarchy is a cross-cutting priority, not a single persona's dimension — Arjun grades the visual execution of it, Meera checks it against the north-star metric, and the gate enforces that a failure on either signal cannot be outscored by strong performance elsewhere

package/dist/skills/design-director/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: design-director
+description: End-to-end design director — ideation, DesignSpec synthesis, spec gates (DS + hierarchy + visual), then guided implementation when build_approved. Use when you want personas to guide WHAT and HOW to design like a senior designer, not just critique.
+---
+
+# Design Director
+
+Orchestrates **brief → wireframe → DesignSpec → spec gates → implementation → verify**.
+
+Unlike `/persona-orchestrator` (critique-only) and unlike bare `/ux-ideator` (stops at wireframe), this skill owns the full **producer** path.
+
+---
+
+## When to use
+
+- "Design and build this screen"
+- "Guide the LLM on how to design our settings page"
+- "Turn this wireframe into an implementable spec"
+- After `/kavi` when starting a new feature
+
+**Prerequisites:** Run `/kavi` or `npx analyzthis_design collect` so tokens and components come from the repo.
+
+---
+
+## Phase 0 — Session + knowledge
+
+1. `npx analyzthis_design session show` — init if missing
+2. Read knowledge-bank skill (sibling or `~/.cursor/skills/knowledge-bank/SKILL.md`)
+3. Set `mode`:
+   - User said assess/propose/review only → `assess_only` (stop after spec)
+   - User said build/implement/ship/apply → `build_approved`
+
+Persist `mode` to session state.
+
+---
+
+## Phase 1 — Intake (ux-story-gate)
+
+Run Phases 0–1.5 from `skills/ux-story-gate/SKILL.md`:
+
+- PRD / task map
+- DS checklist + Figma node if available
+- MoE routing (for context only — this skill overrides chain selection)
+
+Do not skip the task map.
+
+---
+
+## Phase 2 — Ideation (wireframes)
+
+Run `skills/ux-ideator/SKILL.md` Phases 1–4 (Meera → Noor + Anuj → deliberation).
+
+**Mandatory:** full Concept A/B text wireframes (deep schema), not lite cards.
+
+Output: one **synthesized wireframe** with declared information hierarchy.
+
+---
+
+## Phase 3 — DesignSpec synthesis
+
+Read `skills/design-spec/SKILL.md`.
+
+Convert the synthesized wireframe into a complete **DesignSpec** JSON block:
+
+- Map every visible region → `layout.regions`
+- Map every interactive element → `components[]` with real import paths from the repo
+- Copy token values from knowledge bank / tailwind.config — set `tokens.source`
+- Fill all four `states`
+- Add `do` / `dont` from persona deliberation
+- Set `"status": "spec_review"`
+
+Persist:
+
+```bash
+npx analyzthis_design spec validate   # host extracts ```design-spec``` block and validates
+```
+
+Update session `design_spec` and `information_hierarchy.ranking` from the spec.
+
+---
+
+## Phase 4 — Spec gates + adversarial spec review (v1.19)
+
+Read `deliberation-protocol` from your host skills dir (sibling preferred), e.g. `~/.cursor/skills/deliberation-protocol/SKILL.md`, `~/.claude/skills/deliberation-protocol/SKILL.md`, `~/.grok/skills/deliberation-protocol/SKILL.md`, `~/.agents/skills/deliberation-protocol/SKILL.md`, or legacy `~/.claude/commands/deliberation-protocol.md`. After DesignSpec draft, run **adversarial review loops** before `spec_verdict`:
+
+| Persona | Contests |
+|---------|----------|
+| Arjun | Information hierarchy vs layout regions; visual/token choices |
+| Priya | Component import paths, effort, state machine traps |
+| Zara | Delight scope vs feasibility budget |
+
+Each persona: Review mode first — grounded objections citing `task_map`, real `import_path` values, DS tokens. Default `accepts_prior: false`. Raj on stalemate.
+
+CLI: personas debate during `npx analyzthis_design run --task "..." --full` with deliberation enabled.
+
+### 4a — DS gate
+
+Check `ds_checklist` from Phase 1. Spec must use token names, not invented hex. Fail → `"status": "revise"`, list fixes in `spec_verdict.notes`.
+
+### 4b — Hierarchy gate
+
+Rank #1 in `information_hierarchy` must match the component with `hierarchy_rank: 1` and the dominant layout region.
+
+### 4c — Arjun visual pass on the spec
+
+Read `skills/arjun/SKILL.md` — scoped **spec review only**:
+
+- Typography scale consistent?
+- Spacing rhythm (`tokens.spacing`) sufficient?
+- Color classes WCAG-safe per knowledge bank?
+
+Update `spec_verdict`. All three pass → set `"status": "ship"`.
+
+**If any gate fails:** stop. Do not implement. Return Top 3 spec fixes.
+
+---
+
+## Phase 5 — Implementation (build_approved + ship only)
+
+Skip entirely if `mode: assess_only` or `status !== "ship"`.
+
+**The DesignSpec is the contract.** The host LLM must:
+
+1. Read `session-state.json` → `design_spec`
+2. Implement **only** what the spec lists — same components, tokens, regions, states
+3. Use TypeScript + Tailwind + existing project components (match user stack)
+4. No new colors, no extra primary CTAs, no components not in `components[]`
+
+Handoff prompt to self:
+
+> Implement `{design_spec.screen_name}` exactly per session `design_spec`. Run Priya sanity check after first draft.
+
+Optional: run `skills/priya/SKILL.md` for effort confirmation before coding.
+
+---
+
+## Phase 6 — Post-build verify
+
+1. Run ux-story-gate Phase 4.5 (browser) if URL available
+2. Re-run **hierarchy gate** on the built UI (screenshot or DOM): is rank #1 still dominant?
+3. Arjun delta: visual audit on implemented screen vs spec — REVISE only flagged sections
+
+Record in `verify_results` and session `design_spec.spec_verdict`.
+
+---
+
+## Output summary block
+
+```
+## Design Director — Run Summary
+Mode:              [assess_only | build_approved]
+Wireframe:         [synthesized concept — one line]
+Spec status:       [draft | spec_review | ship | revise]
+DS gate:           [pass | fail]
+Hierarchy gate:    [pass | fail]
+Arjun spec pass:   [pass | fail]
+Implementation:    [done | skipped — reason]
+Verify:            [pass | fail | not_run]
+Next step:         [implement | fix spec | fix UI per delta list]
+```
+
+---
+
+## Relationship to other skills
+
+| Skill | Role |
+|---|---|
+| `/ux-ideator` | Wireframes + deliberation (Phases 1–2 of this skill) |
+| `/design-spec` | Spec format + validation rules |
+| `/persona-orchestrator` | Critique existing UI — use **after** build for SHIP/REVISE |
+| `/design-critic` | Multi-persona review — not the producer path |
+
+---
+
+## CLI helpers
+
+```bash
+npx analyzthis_design spec template
+npx analyzthis_design spec show
+npx analyzthis_design spec validate --file design-spec.json
+```

package/dist/skills/design-personas/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: design-personas
+description: Load the session context template for design persona workflows. Use this to set up context before running design-critic or ux-ideator. All 7 personas (Arjun, Meera, Priya, Zara, Noor, Anuj, Raj) read this context at runtime to ground their critiques in project-specific data.
+disable-model-invocation: true
+---
+
+# Design Personas — Session Context
+
+This skill provides the session context template used by all 7 design personas. Fill this in before starting a `design-critic` or `ux-ideator` session. Fields left blank are treated as "unknown — do not assume."
+
+---
+
+## How to use
+
+1. Copy the template below into your chat
+2. Fill in what you know — leave blank what you don't
+3. Run `/design-critic` or `/ux-ideator`
+
+---
+
+## Session Context Template
+
+```
+## Product
+Product name:
+Industry / vertical:
+Product type: [B2B SaaS / marketplace / consumer app / internal tool / other]
+Stage: [early / growth / mature]
+
+## Primary user
+Who they are:
+Session frequency: [daily / weekly / monthly / occasional]
+Entity volume: [e.g. "50 campaigns", "200 orders", "10 clients"]
+Key pain points:
+
+## Business context (Meera reads this)
+Primary north-star metric: [e.g. retention, ARR, DAU, conversion rate]
+Customer segments: [e.g. enterprise / mid-market / SMB]
+Competitive context: [key competitors, parity gaps, differentiation opportunities]
+Pricing model: [subscription / usage-based / freemium / other]
+
+## User research (Arjun reads this)
+Available research: [session recordings / interviews / surveys / support tickets / analytics]
+Key engagement data: [e.g. "feature X has <5% click rate", "users drop off at step 3"]
+Known friction points:
+Empty / error states that exist:
+
+## Expert-user profile (Anuj reads this)
+Who the expert user is:
+High-frequency actions (>10×/session):
+Actions that currently require multiple clicks but shouldn't:
+Bulk operations needed:
+
+## Tech stack (Priya reads this)
+Frontend: [e.g. React, Vue, Next.js]
+Backend: [e.g. REST API, GraphQL]
+Known infrastructure constraints:
+Third-party dependencies relevant to this feature:
+Design system / component library:
+Components already available for this feature:
+
+## Design system (Noor + Anuj + Priya read this)
+Component library:
+Known gaps (components not in library):
+Token system: [CSS vars / design tokens / Tailwind / other]
+
+## PRD context (Raj reads this)
+Primary persona priority: [who does the PRD explicitly prioritize?]
+Stated success criteria:
+Known constraints ("must not" statements):
+Prior design decisions already made:
+
+## Surface classification (Zara reads this)
+Is this a high-frequency working surface? [yes / no / mixed]
+First-time-user surfaces in scope:
+Once-ever moments in scope (onboarding, first success, etc.):
+Available animation/motion capabilities:
+
+## Recent product decisions (all personas read this)
+1.
+2.
+3.
+
+## What is NOT in scope
+-
+```
+
+---
+
+## Persona reference map
+
+| Persona | Role | Active in |
+|---------|------|-----------|
+| Arjun | UX Agent — UX Honeycomb | `design-critic` Ph5, `ux-ideator` Ph2 |
+| Meera | Business Agent — retention, ARR, GTM | `design-critic` Ph5, `ux-ideator` Ph1 |
+| Priya | Feasibility Agent — engineering effort | `design-critic` Ph5, `ux-ideator` Ph6 |
+| Zara | Delight Agent — Peak-End, one moment | `design-critic` Ph5, `ux-ideator` Ph5.5 |
+| Noor | IA Architect — Concept A, minimalist | `ux-ideator` Ph2, Ph3, Ph4 |
+| Anuj | Power-User Advocate — Concept B, dense | `ux-ideator` Ph2, Ph3, Ph4 |
+| Raj | Arbitrator — stalemate only | `ux-ideator` Ph4, Ph5 fallback |

package/dist/skills/design-reference/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: design-reference
+description: Shared design reference data used by all 7 design personas. Contains color palettes, UI styles, typography pairings, UX guidelines, product-type patterns, landing page layouts, chart types, icon library, mobile interface rules, React performance patterns, and stack-specific guidance. Personas read specific files from this directory when making design decisions.
+disable-model-invocation: true
+---
+
+# Design Reference Data
+
+Shared knowledge base for all 7 design personas. Each CSV covers a specific design domain. Personas read only the files relevant to their current task — see the mapping below.
+
+---
+
+## File index
+
+| File | What it contains | Who reads it |
+|---|---|---|
+| `ux-guidelines.csv` | Platform-specific UX rules — scroll behavior, nav, feedback, accessibility (WCAG) | Arjun, Noor, Anuj |
+| `ui-reasoning.csv` | UI pattern decisions by product category — recommended style, color mood, effects, anti-patterns | Arjun, Noor, Meera |
+| `app-interface.csv` | Mobile-specific rules — icon labels, touch targets, gestures (iOS/Android/React Native) | Arjun, Anuj |
+| `styles.csv` | 85 UI styles — keywords, best-for, do-not-use-for, light/dark, performance, accessibility, Tailwind compatibility | Zara, Noor |
+| `colors.csv` | 161 WCAG-tested color palettes — primary/secondary/accent/background tokens by product type | Zara, Meera, Noor |
+| `typography.csv` | 74 font pairings — heading + body fonts, mood keywords, best-for, CSS import, Tailwind config | Zara |
+| `google-fonts.csv` | Full Google Fonts catalog — use only when picking a specific font pairing | Zara (conditional) |
+| `products.csv` | 162 product type → style mappings — recommended style, landing pattern, dashboard style, color focus | Meera, Raj |
+| `landing.csv` | Landing page layout patterns — section order, CTA placement, color strategy, conversion optimization | Meera, Zara |
+| `charts.csv` | 25 chart types — when to use, when not to use, accessibility grade, library recommendation | Arjun, Zara |
+| `icons.csv` | Phosphor icon catalog — name, keywords, import code, usage context, style | Noor, Zara |
+| `react-performance.csv` | React rendering patterns — memoization, lazy loading, virtualization, bundle splitting | Priya |
+| `stacks/nextjs.csv` | Next.js-specific patterns and component guidance | Priya |
+| `stacks/react.csv` | React-specific patterns | Priya |
+| `stacks/shadcn.csv` | ShadCN component availability and usage | Priya, Noor, Anuj |
+| `stacks/[other].csv` | angular, astro, flutter, html-tailwind, jetpack-compose, laravel, nuxt-ui, nuxtjs, react-native, svelte, swiftui, threejs, vue | Priya (match to session context stack) |
+
+---
+
+## How personas use this data
+
+Each persona's SKILL.md specifies which files to read and when. Personas do NOT read all files at once — they read the minimum set needed for the current evaluation.
+
+**Reading rule:** Read the CSV, extract the rows relevant to the product type / stack / style in the session context, and use that data to ground your output in specific, named values rather than abstract advice.
+
+## Citation format (mandatory for all personas)
+
+Every time you cite a value from a reference file, use this format inline:
+
+```
+[filename, row N: "exact quoted value from the relevant column"]
+```
+
+**Examples:**
+- `[ux-guidelines.csv, row 22: "Minimum 44×44px touch targets — Severity: High"]`
+- `[ui-reasoning.csv, row 6: "Financial Dashboard — must_have: real-time-updates, must_have: high-contrast"]`
+- `[styles.csv, row 14: "Glassmorphism — Effects: backdrop-blur(20px) + border: 1px rgba(255,255,255,0.2)"]`
+- `[stacks/shadcn.csv, row 8: "DataTable — supports column visibility toggle and row selection"]`
+
+**Never cite abstractly.** "Add a 44px touch target" is wrong. `[ux-guidelines.csv, row 22: "Minimum 44×44px — Severity: High"]` is correct. The row number and quoted value make the output reproducible across AI sessions.
+
+---
+
+## Reference paths (after install)
+
+All files live at: `~/.cursor/skills/design-reference/`
+
+```
+~/.cursor/skills/design-reference/
+├── ux-guidelines.csv
+├── ui-reasoning.csv
+├── app-interface.csv
+├── styles.csv
+├── colors.csv
+├── typography.csv
+├── google-fonts.csv
+├── products.csv
+├── landing.csv
+├── charts.csv
+├── icons.csv
+├── react-performance.csv
+└── stacks/
+    ├── nextjs.csv
+    ├── react.csv
+    ├── shadcn.csv
+    └── ... (16 stacks total)
+```