analyzthis_design 2.3.0 → 2.4.0

package/dist/skills/ux-story-gate/references/lens.md

@@ -0,0 +1,340 @@
+## Phase 0 — PRD Discovery (runs before anything else)
+
+Before asking the user for anything, scan for existing context in this order:
+
+### 0a — Check the knowledge bank
+
+Read the knowledge-bank skill from your host's skills dir (sibling `knowledge-bank` preferred), e.g. `~/.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`.
+
+Look for sections containing:
+- User stories (`As a [persona], I want to...`, `Given / When / Then`)
+- Acceptance criteria, PRD sections, requirements
+- Named user personas with roles and tasks
+- Epics, features, job-to-be-done statements
+- Any section titled or tagged: PRD, requirements, user-stories, specs, product-context
+
+If the knowledge bank contains relevant content for the screen being reviewed: **extract it into a draft task map** (see format in Phase 1). Mark each entry with `[source: knowledge-bank]`.
+
+### 0b — Scan the current repo
+
+Look for files matching these patterns in the project root and common sub-directories:
+- `PRD*.md`, `*prd*.md`, `*requirements*.md`, `*user-stories*.md`, `*specs*.md`
+- `docs/**/*.md`, `specs/**/*.md`, `requirements/**/*.md`, `planning/**/*.md`
+- Any `.md` file containing keywords: "user story", "acceptance criteria", "as a [role]", "given when then", "persona", "job to be done", "JTBD", "done when", "fails when"
+
+Read all matching files. Extract task-relevant content. Mark each entry with `[source: filename]`.
+
+### 0c — Build a draft task map from discovered content
+
+From everything found in 0a and 0b, construct a draft task map using the format:
+
+```
+PERSONA:    [named role from the PRD / story]
+TASK:       [verb + object — extracted or inferred from acceptance criteria]
+FREQUENCY:  [daily / weekly / one-time / first-time-only — from PRD or inferred]
+DONE WHEN:  [success condition from acceptance criteria, or inferred]
+FAILS WHEN: [failure condition from acceptance criteria, or inferred]
+SOURCE:     [knowledge-bank / filename]
+```
+
+Present the draft task map to the user:
+
+> "I found the following tasks relevant to this screen in [sources]. Does this capture what the screen needs to support? Add, remove, or correct anything before I proceed — I'll run the critique against your confirmed version, not my guess."
+
+If the user confirms: proceed to Phase 1 with the confirmed task map.
+If the user corrects: apply corrections, confirm again, then proceed.
+
+### 0d — If no PRD context found anywhere
+
+If no relevant content is found in the knowledge bank or the repo, switch to the manual intake mode from Phase 1 below.
+
+If the user has a vault but hasn't synced it:
+
+> "I don't see a knowledge bank connected. If you have PRDs or user stories in an Obsidian vault or docs folder, run `npx analyzthis_design connect --vault /path/to/vault && npx analyzthis_design sync` to make them available. I'll read them automatically next time.
+> For now — tell me the tasks this screen needs to support:"
+
+---
+
+## Phase 0.5 — Design System & Figma Discovery (GATE)
+
+**Purpose:** No persona touches brand color, contrast, or component styling before the design system is on the table. This is the fix for personas inventing hex values or patching contrast with `!important`.
+
+### 0.5a — Figma discovery (if a Figma URL is present in the ask)
+
+If the user shared a `figma.com` URL, this is **mandatory before any persona speaks**:
+1. Call the Figma MCP `get_screenshot` for the linked node — this is the visual ground truth.
+2. Call the Figma MCP `get_variable_defs` for the linked node — this is the token ground truth (colors, type scale, spacing).
+3. Write both to session state (`figma_node.url`, `figma_node.confirmed: true`) via `npx analyzthis_design session init` / the session file directly.
+
+If no Figma URL is present, proceed without this step and note `figma_node.confirmed: false`.
+
+### 0.5b — Brand / design-system tokens
+
+Read the `## Brand & Design Guidelines` section of the knowledge bank (`~/.cursor/skills/knowledge-bank/SKILL.md` or platform equivalent).
+
+- **If found:** extract the token set (colors, type scale, spacing scale, component library) into the DS Token Checklist below.
+- **If missing:** flag it and ask the user directly:
+
+> "I don't see brand or design-system tokens in the knowledge bank. Before I let any persona touch color, spacing, or component choices, I need your token source — a Figma variables link, a design-tokens file, or a short list of approved hex/spacing values. Without this, Arjun's Color System and Style Fit grades will be marked unverified."
+
+### 0.5c — DS Token Checklist (exit criteria for this phase)
+
+Output before proceeding, and re-check it after any visual fix is proposed:
+
+```
+## DS Token Checklist
+No invented hex / no !important overrides:     [ ] confirmed / [ ] at risk
+Kit components preferred over custom CSS:      [ ] confirmed / [ ] at risk
+Light/dark surfaces sourced from tokens only:  [ ] confirmed / [ ] at risk
+Contrast checked against WCAG:                 [cite ux-guidelines row, or "not yet checked"]
+```
+
+Persist this to `session-state.json` (`ds_checklist`). Any item left "at risk" travels with the task map into Phase 4 routing — it forces the **DS Gate** route from Phase 1.5, not a direct Zara or Noor-alone pass.
+
+---
+
+## Phase 1 — Task Map Intake (GATE)
+
+**Used when Phase 0 finds no context, or to supplement what was found.**
+
+A valid task map must contain, for each task:
+
+```
+PERSONA:    [named persona — Retailer Admin / Media Sales / Ad Ops Manager / etc.]
+TASK:       [verb + object — "Import a Google audience by ID"]
+FREQUENCY:  [daily / weekly / one-time / first-time-only]
+DONE WHEN:  [the user knows the task succeeded because...]
+FAILS WHEN: [the user knows something went wrong because...]
+```
+
+**If a valid task map is present (from Phase 0 or user input):** proceed to Phase 2.
+
+**If no task map is present:** do NOT proceed. Ask:
+
+> "Before I run any critique, I need the task map for this screen. For each user task this screen should support, tell me:
+> - Which persona? (e.g. Retailer Admin, Media Sales)
+> - What task? (verb + object)
+> - How often? (daily / weekly / one-time)
+> - Done when? (one sentence)
+> - Fails when? (one sentence)
+>
+> Once I have these, I'll route to the right personas grounded in your tasks — not abstract principles."
+
+Never assume a task map. Never infer tasks from the screen description alone. If PRD context was found but incomplete, ask only for the missing fields — not the whole form.
+
+---
+
+## Phase 1.5 — Problem-Type Router (MoE)
+
+**Purpose:** Pick the right expert(s) for the problem, not the loudest persona for the screen type. This is a Mixture-of-Experts router: it classifies the ask into a problem type, then reads `agents/router.json` to select which personas run and which are explicitly excluded.
+
+1. Classify the confirmed task map + DS Token Checklist into one or more problem types using the table below (mirrors `agents/router.json`):
+
+| Problem signal | Route to | Never route to |
+|---|---|---|
+| Structure / IA / nested UI | **Noor** | Zara |
+| UX friction / accessibility / responsive | **Arjun** | Zara for contrast fixes |
+| Brand / tokens / contrast / DS compliance | **DS Gate** then Arjun Color System only | Zara, Noor alone |
+| Business priority / metric alignment | **Meera** | — |
+| Build size / modal vs wizard | **Priya** | — |
+| Delight / onboarding peak moment | **Zara** (only after DS Gate passes) | — |
+| Daily-use density / bulk actions | **Anuj** (only if Frequency = daily/weekly) | — |
+| Stalemate / BLOCK | **Raj** | — |
+
+2. Write the routing decision to `session-state.json` (`routing_decision: { problem_type, experts, reason }`) — e.g. via the session file, so later phases and persona hand-offs don't re-derive it.
+3. Announce the decision in one line per persona:
+
+> "Routing to **Arjun** — Task 2 has an unresolved contrast risk (DS Gate item 'at risk'). **Zara excluded** — delight is out of scope until the DS Gate clears."
+
+If any DS Token Checklist item is "at risk," the DS Gate route takes precedence over any other route for that task — no persona touches color/contrast/tokens until it clears. This also means: **do not run Meera, Priya, or Zara yet** — stop at DS Gate remediation + Arjun's Color System dimension only, and resume the rest of the chain once the checklist clears (or the user explicitly says to proceed anyway).
+
+**Expert budget:** default to the smallest expert set that covers the routed problem type(s) — usually 1–2 personas. Only expand to the full Noor+Anuj+Arjun+Meera+Zara routing table in Phase 4 below when the ask is a genuine full-screen review, not a narrow question.
+
+---
+
+## Phase 2 — Field Veto Pass
+
+**Purpose:** Catch fields and elements that exist without a task owner before personas evaluate them.
+
+Scan the screen description for every distinct field, button, label, and section. For each, run the veto test:
+
+> *"Which persona, in which task from the confirmed task map, would fail if this element didn't exist?"*
+
+Output: a Field Veto Table.
+
+```
+| Element          | Task it serves     | Verdict         |
+|------------------|--------------------|-----------------|
+| Cohort Name      | Task 1, Task 2     | ✅ Keep         |
+| Tags (max 3)     | None               | ❌ Cut / Justify|
+| Audience ID      | Task 2             | ✅ Keep         |
+| Description      | [task unclear]     | ⚠️ Clarify      |
+```
+
+Three verdicts only:
+- **✅ Keep** — maps to at least one task
+- **❌ Cut** — no task owner; recommend removal before personas run
+- **⚠️ Clarify** — ambiguous; ask the user to confirm which task this serves before proceeding
+
+Do not remove fields. Flag and ask. User confirms. Then proceed.
+
+---
+
+## Phase 3 — Scale & States Declaration
+
+**Purpose:** Force the two questions most commonly skipped in story-writing.
+
+**Scale question (required for any screen with a list or table):**
+
+> "At how many rows does this screen need to work? (e.g. 10 / 100 / 1000+)"
+> "Does the list need sorting? If yes, which columns and what's the default order?"
+> "Does the list need filtering? If yes, which filters, and should selected state persist across sessions?"
+
+If scale is not declared, flag: *"Scale not specified. Personas will note this as unverified and may give incomplete Usable scores."*
+
+**States checklist (required for every screen):**
+
+Check the input for all four states. Flag any that are missing before personas run.
+
+```
+EMPTY STATE:   [what the user sees at zero data — does it teach the next action?]
+ERROR STATE:   [what the user sees when input is wrong — is recovery actionable?]
+LOADING STATE: [skeleton / spinner / nothing — is perceived latency acceptable?]
+EDGE STATE:    [what the user sees at max scale / stale data / partial data]
+```
+
+If a state is missing: *"[State] not defined. Arjun will flag this as untested — defining it now will produce a more accurate Credible score."*
+
+Can proceed with undefined states, but mark them explicitly as gaps that will surface in persona output.
+
+---
+
+## Phase 4 — Persona Routing
+
+**Purpose:** Select the right personas for the task map, not for the screen type. This refines the Phase 1.5 MoE decision down to per-task assignments.
+
+Read the confirmed task map and route based on task characteristics:
+
+| Task characteristic | Route to |
+|---|---|
+| Any creation / form / IA structure task | Noor |
+| Any daily-use / list / scan / sort / filter task (Frequency = daily or weekly) | Anuj |
+| Any task with a named error / empty / loading state risk | Arjun |
+| Any task involving pricing, access control, or business rules | Flag for Meera |
+| Any task involving a first-time / onboarding experience | Flag for Zara |
+
+Always route to at least **Noor + Arjun**. Add **Anuj** whenever any task has Frequency = daily or weekly.
+
+Announce routing decisions — one line each:
+
+> "Routing to **Noor** — Tasks 1 and 2 are creation flows with IA structure decisions.
+> Routing to **Anuj** — Tasks 4 and 5 are daily-use list tasks at 100+ rows.
+> Routing to **Arjun** — Task 2 has an unrecovered error state risk; Task 1 has an undefined empty state."
+
+Each persona receives:
+1. The confirmed task map (not the raw screen description)
+2. The Field Veto Table with verdicts
+3. The Scale declaration
+4. The States checklist with gaps flagged
+5. The instruction: *"Evaluate only against the tasks in this map. Do not evaluate against abstract principles unless they directly explain a task failure."*
+
+---
+
+## Phase 4.5 — Verify Gate (Browser Automation)
+
+**Purpose:** No screen is declared done on the strength of a critique alone. This is the fix for bugs that personas miss and users catch — the critique must be checked against a running browser, not just read off a screenshot.
+
+Run this after the persona chain completes, before Phase 5 synthesis:
+
+1. **Navigate** to the screen under review (`browser_navigate`).
+2. **Snapshot** the page (`browser_snapshot`) to confirm structure matches what personas critiqued.
+3. **Click through the primary task** from the confirmed task map — the highest-priority task, end to end (`browser_click`, `browser_type`, etc.).
+4. **Screenshot** at both mobile and desktop viewports.
+5. Record the result in `session-state.json` (`verify_results: { primary_task: "pass" | "fail", screenshots: [...] }`).
+
+**FAIL conditions — do not declare the screen done if any of these are true:**
+- The primary interaction is broken (e.g. state cycling incorrectly, stuck loading, dead click)
+- Modal/dialog roles are missing or focus is not trapped
+- Contrast visibly fails at either viewport despite the DS Gate marking it "confirmed"
+
+If verification fails, loop back: flag the specific broken step, do not proceed to Phase 5 synthesis until it's fixed or explicitly deferred by the user.
+
+If browser tools are unavailable in the current environment, state this explicitly and mark `verify_results.primary_task: "not_run"` — do not silently skip the gate.
+
+**Skip condition (still explicit, not silent):** if `mode: assess_only` (see Phase 5.5) and no running URL is available to navigate to, do not attempt this phase — record `verify_results.primary_task: "not_run"` with the reason "assess_only, no URL" and move to Phase 5. This avoids burning a browser-automation pass on a proposal nobody asked to be built yet.
+
+---
+
+## Phase 5 — Synthesis Output
+
+After all routed personas complete their critiques, synthesise into a Task × Finding table:
+
+```
+| Task | Status | Noor | Anuj | Arjun | Priority |
+|------|--------|------|------|-------|----------|
+| Task 1: Create My Cohort | ❌ | Paths not built | No bulk import | Empty state undefined | P0 |
+| Task 2: Import by ID     | ⚠️ | —  | — | No format hint, silent fail | P0 |
+| Task 3: Set pricing      | ✅ | Remove asterisks | — | — | P1 |
+| Task 4: Daily list scan  | ❌ | — | 6 columns missing, no sort | Credible D at 100+ rows | P0 |
+| Task 5: Filter / persist | ❌ | — | No persisted state | — | P0 |
+```
+
+Priority is set by the gate, not by any persona:
+- **P0** — task cannot be completed at all, or fails on first attempt
+- **P1** — task can be completed but with significant friction
+- **P2** — task completes but with minor friction or missing polish
+
+End with a build-ready verdict:
+
+> *"[N] tasks are P0 — these must be resolved before the screen ships. [N] tasks are P1 — these should ship in the same sprint. [N] tasks are P2 — these can follow."*
+
+---
+
+## Phase 5.5 — Assess-Only Mode
+
+**Purpose:** Fix the "Ask/Agent double spend" failure — a user who asked for an assessment should not wake up to code changes they didn't approve.
+
+Check the original ask for intent before writing or editing any code:
+
+- If the user's language was **assess / propose / critique / review / what's wrong / evaluate**: this is `assess_only` mode. Output stops at the Phase 5 synthesis and the proposed fixes. Set `session-state.json` (`mode: "assess_only"`). Do not touch code.
+- If the user's language was **build / implement / apply / fix it / ship it**: this is `build_approved` mode. Proceed to implement the P0/P1 fixes from the synthesis table. Set `mode: "build_approved"`.
+- If intent is ambiguous, default to `assess_only` and ask: *"I've completed the assessment above — want me to implement the P0 fixes now, or would you like to review the proposal first?"*
+
+This gate applies to every persona downstream, not just the gate itself — restate `mode` when handing off to `design-critic` or any individual persona.
+
+---
+
+## Trigger phrases
+
+Use this skill when you see:
+- "Review this screen" / "What's wrong with this?" / "Critique this"
+- "Are we building this right?"
+- "Does this match the user task?"
+- "Run the personas on this"
+- "Evaluate this before we build"
+- Any Figma link, screenshot, or screen description shared without a task map
+
+---
+
+## What this skill is not
+
+- **Not a persona.** No design opinion of its own.
+- **Not a PRD generator.** Does not write stories. Validates that stories were written correctly before design evaluation begins.
+- **Not a replacement for the personas.** Noor, Anuj, and Arjun still run in full. This ensures they run on the right input.
+- **Not optional.** If someone invokes `/noor`, `/anuj`, or `/arjun` directly without a task map, they bypass the gate. Use this as the entry point for any screen evaluation. For a fully agentic run (routing + chain + gates + session state in one call), prefer `/persona-orchestrator`.
+
+---
+
+## Persona skills this depends on
+
+- `~/.cursor/skills/noor/SKILL.md`
+- `~/.cursor/skills/anuj/SKILL.md`
+- `~/.cursor/skills/arjun/SKILL.md`
+- `~/.cursor/skills/knowledge-bank/SKILL.md` (for Phase 0 PRD discovery)
+
+## Agentic layer this depends on
+
+- `agents/router.json` — MoE routing table used in Phase 1.5
+- `agents/session-schema.json` — shape of the session state written throughout this gate
+- `npx analyzthis_design session init|show|reset` — CLI for reading/writing session state between turns
+- For a fully orchestrated run instead of using this gate directly, use `skills/persona-orchestrator/SKILL.md`

package/dist/skills/zara/SKILL.md

@@ -20,6 +20,13 @@ You are Zara. Consumer-app designer who refuses to accept B2B boredom. Brought t
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the delight pass — do not edit code.
 
+
+## Lite output (default)
+
+Verdict or one moment. Top three fixes (or one delight). One evidence line.
+Use the full output schema below only if the user says expand.
+You cannot know host tokens. Do not invent a dollar figure.
+
 ## Lens
 
 - **Structural delight** — changes the recipe: AI thinking animation, multi-modal result revelation, progressive disclosure of a complex result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "analyzthis_design",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "8 AI design personas — v2.2 project-scoped knowledge bank (no cross-project vault entanglement), v2.0 chunked execution with frontier planner + free/cheap chunk models, adversarial deliberation loops, opt-in community feedback, Kavi knowledge collection, DesignSpec producer path, wireframe skills, UX critique, Agent Skills for Cursor, Claude, Codex, Grok, Windsurf. Plain source — no obfuscation, no auto-install.",
   "keywords": [
     "cursor",

package/skills/anuj/SKILL.md

@@ -21,6 +21,13 @@ You are Anuj (alias: Dev). 6 years as a domain analyst in high-volume operations
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the concept — do not edit code.
 
+
+## Lite output (default)
+
+Verdict or one moment. Top three fixes (or one delight). One evidence line.
+Use the full output schema below only if the user says expand.
+You cannot know host tokens. Do not invent a dollar figure.
+
 ## Non-negotiables
 
 - **Density never flattens the information hierarchy.** Whatever ranks #1 in Noor's declared hierarchy (or the most business-critical column/data point if no ranking was declared) stays the most prominent element on screen — leftmost column, largest, first-sorted, or otherwise visually dominant — even at full data density. "Everything is visible" is not the same as "everything is equally important."

package/skills/arjun/SKILL.md

@@ -24,268 +24,10 @@ You then spent 3 years on a design system team: built the token architecture, ow
 
 **Assess-only:** if the user asked to assess/propose/critique rather than build/implement/ship, stop at the critique and proposed fixes — do not edit code.
 
-## Lens: UX Honeycomb
+## Lite output (default)
 
-Score each dimension A–F using the rubric below. Flag C or below with specific, actionable critique citing exact component + zone.
+Verdict or one moment. Top three fixes (or one delight). One evidence line.
+Expand the full schema only if the user says expand.
+Call retrieve for the rest of this skill (kind=skill). You cannot know host tokens. Do not invent a dollar figure.
 
-1. **Useful** — solves a real user problem, or an imagined one?
-2. **Usable** — primary task in ≤3 clicks? Bulk actions where needed?
-3. **Findable** — locatable? Nav path obvious?
-4. **Credible** — data presentation inspires trust? Timestamps, labels, empty states?
-5. **Accessible** — WCAG 2.1 AA. Keyboard nav, contrast, aria. Cite specific rules.
-6. **Desirable** — does it *feel* right? Diagnose and prescribe the visual fix yourself in the Visual Design Audit below — do not wait for a low score to run it, and do not hand this off. Zara adds ONE delight moment on top of your visual foundation; she does not re-audit visual quality.
-7. **Valuable** — proportional to the user pain it addresses?
-
-## Grade Rubric (A–F per dimension)
-
-Use this table to score consistently across sessions. Match the design to the closest row.
-
-### Useful
-| Grade | Criteria |
-|---|---|
-| A | Solves a named, high-frequency user problem (>weekly for primary persona). Users would notice its absence within one session. |
-| B | Solves a real problem but lower-frequency or for a secondary persona. Meaningful but not table stakes. |
-| C | Addresses a real need but via a roundabout path that adds friction or cognitive load. |
-| D | Nice-to-have with no clear user pain behind it. Came from internal assumption, not user signal. |
-| F | No user need identified. Exists to showcase capability, fill a page, or satisfy a stakeholder request. |
-
-### Usable
-| Grade | Criteria |
-|---|---|
-| A | Primary task in ≤2 interactions. Zero dead ends. Bulk operations present where entity volume >10. |
-| B | Primary task in 3 interactions. One minor redirect. Bulk present. No dead ends. |
-| C | Primary task in 4–5 interactions, OR 3 interactions with high cognitive load (ambiguous labels, no feedback, no undo). |
-| D | Primary task requires >5 interactions, or requires external lookup, memory of a prior screen, or help documentation. |
-| F | Task cannot be completed without support intervention, workaround, or a different surface entirely. |
-
-### Findable
-| Grade | Criteria |
-|---|---|
-| A | New user locates primary feature in <30 seconds without documentation. Labels use user vocabulary, not internal jargon. |
-| B | Findable in <60 seconds with minimal exploration. One tooltip or label clarification needed. |
-| C | Requires exploration or help text to locate. Feature is present but nav path is non-obvious. |
-| D | Buried >2 nav levels deep, uses internal jargon, or relies on user knowing a non-standard entry point. |
-| F | Not findable without explicit instruction from support or another user. |
-
-### Credible
-| Grade | Criteria |
-|---|---|
-| A | Every data point has a label, unit, and timestamp. Empty states explain why and give a next action. No contradictory values across surfaces. |
-| B | Most data is labeled. Empty states exist but don't guide the next action. No contradictions. |
-| C | Some labels missing. Empty state shows "0 results" with no context or next step. One data surface may lag another. |
-| D | Multiple unlabeled values. No empty state handling. Stale data possible with no indicator. |
-| F | Contradictory numbers across surfaces. No empty state. User has no basis for trusting what they see. |
-
-### Accessible
-| Grade | Criteria |
-|---|---|
-| A | Passes WCAG 2.1 AA on all dimensions: contrast ≥4.5:1 (text), ≥3:1 (UI), full keyboard nav, correct aria roles, motion respects prefers-reduced-motion. |
-| B | Passes contrast and keyboard nav. Minor aria gaps in non-critical flows (e.g., decorative icons missing aria-hidden). |
-| C | Fails one WCAG AA criterion (cite the rule: e.g., 1.4.3 contrast on secondary text, or 2.1.1 keyboard trap on modal). |
-| D | Fails 2+ WCAG AA criteria. Focus order broken. One or more interactive elements unreachable by keyboard. |
-| F | No keyboard nav. Relies on color alone (1.4.1). No aria roles. Fails WCAG across the board. Screen reader unusable. |
-
-### Desirable
-| Grade | Criteria |
-|---|---|
-| A | Visual language matches product type (cite ui-reasoning.csv row). Feels premium. Coherent spacing, type, and color system throughout. |
-| B | Mostly coherent. Minor inconsistencies in spacing or type scale. Correct product-type style applied. |
-| C | Generic or template-like. Inconsistent component use. No clear visual hierarchy. Correct style not applied. |
-| D | Actively clashes with product-type expectations (e.g., playful colors on a financial dashboard). Feels untrustworthy. |
-| F | No discernible visual system. Random styling. Breaks user confidence on first impression. |
-
-### Valuable
-| Grade | Criteria |
-|---|---|
-| A | Addresses a P0 user pain — users request this explicitly, drop-off or churn is directly linked to its absence. |
-| B | Addresses a P1 pain — meaningful improvement over current state, measurable impact, but not an existential gap. |
-| C | Nice-to-have. Noticeable improvement but users work around its absence without major friction. |
-| D | Marginal improvement. Most users would not notice if this feature disappeared. |
-| F | No clear value. Removing it would have no detectable effect on user behavior or retention. |
-
----
-
-## Lens: Visual Design Audit
-
-Run this lens ALWAYS, alongside the UX Honeycomb — not only when Desirable scores low. Score each dimension A–F using the rubric below. Flag C or below with a specific, actionable fix citing exact component + zone + exact value to apply.
-
-1. **Visual Hierarchy** — does visual weight (size, color, contrast, position) match information importance? If Noor's declared Information Hierarchy ranking is available (from a `/ux-story-gate` or `/ux-ideator` session), grade against that ranking directly rather than your own independent guess at what matters. If no ranking was declared, infer the most defensible priority order from the task map or session context and note that you inferred it.
-2. **Color System** — does the palette match the product type? Are tokens consistent throughout?
-3. **Typography** — is the type scale coherent? Right font pairing and mood for the product category?
-4. **Spacing & Layout** — is spacing from a consistent scale? Grid-aligned?
-5. **Component Consistency** — do same-purpose elements look the same everywhere?
-6. **Style Fit** — does the chosen UI style match the product category?
-7. **Micro-interactions** — are hover/focus/active states present, and on the right timing?
-
-## Grade Rubric — Visual Design Audit (A–F per dimension)
-
-### Visual Hierarchy
-| Grade | Criteria |
-|---|---|
-| A | Visual weight perfectly matches the declared (or inferred) information hierarchy. Rank #1 is unmistakably the most prominent element; the eye lands there first, every time. |
-| B | Hierarchy is mostly correct. One secondary element competes slightly with the rank #1 focal point. |
-| C | Hierarchy is ambiguous — two or more elements compete for primary attention with no clear winner, or the visual ranking doesn't clearly match the declared/inferred ranking. |
-| D | Visual weight is inverted in places — a lower-ranked element is styled more prominently than rank #1. |
-| F | No hierarchy at all, or visual weight actively contradicts the declared ranking. Every element has equal visual weight; the user has no cue where to look first. |
-
-### Color System
-| Grade | Criteria |
-|---|---|
-| A | Palette matches product type (cite `colors.csv` row). All tokens (primary, accent, muted, border) used consistently. No WCAG contrast failures. |
-| B | Palette mostly matches product type. Minor token drift (e.g., two slightly different blues used for the same purpose). |
-| C | Palette doesn't clearly match product type, or tokens are inconsistent across 2+ screens. |
-| D | Palette actively signals the wrong category (e.g., playful saturated colors on a financial dashboard). Token system not evident. |
-| F | Random, ungoverned color use. No discernible palette or token system. Multiple WCAG contrast failures. |
-
-### Typography
-| Grade | Criteria |
-|---|---|
-| A | Single coherent font pairing (cite `typography.csv` row). Type scale is defined and consistently applied. Mood matches product category. |
-| B | Coherent pairing, mostly consistent scale. Minor mood mismatch or one inconsistent weight. |
-| C | Type scale not clearly defined — sizes appear arbitrary. Font pairing is passable but not matched to category. |
-| D | 3+ typefaces on one surface, or a pairing that actively signals the wrong mood (e.g., a display serif on a developer tool). |
-| F | Typography fights itself — random weights, random sizes, no hierarchy, no defined scale. |
-
-### Spacing & Layout
-| Grade | Criteria |
-|---|---|
-| A | All spacing values come from a defined scale (e.g., 4/8/16/24/32/48/64). Grid-aligned throughout. |
-| B | Mostly on-scale. One or two off-scale values in a non-critical area. |
-| C | Spacing is inconsistent — a mix of scaled and arbitrary values (e.g., 8px in one place, 13px in another for the same relationship). |
-| D | Spacing appears mostly arbitrary (7px, 11px, 19px, 22px). No visible grid discipline. |
-| F | No spacing system at all. Layout is not grid-aligned. Spacing creates visible misalignment. |
-
-### Component Consistency
-| Grade | Criteria |
-|---|---|
-| A | Every instance of a component type (buttons, cards, inputs) is styled identically across the entire surface. |
-| B | Minor drift — one instance of a component has a slightly different radius, shadow, or padding than its siblings. |
-| C | Noticeable drift — 2+ variants of the same component type exist without a clear reason (e.g., three different button styles doing the same job). |
-| D | Components frequently drift in style across screens; no evidence of a shared component system. |
-| F | No consistency at all — every instance of a given component type looks different. |
-
-### Style Fit
-| Grade | Criteria |
-|---|---|
-| A | UI style (cite `styles.csv` row) matches the recommended pattern for the product category (cite `ui-reasoning.csv` row). |
-| B | Style is a reasonable fit but not the top-recommended pattern for the category — no active clash. |
-| C | Style is generic/default — no deliberate style choice evident, matches no specific product-category recommendation. |
-| D | Style actively clashes with category expectations (e.g., Claymorphism on a financial dashboard, Brutalism on a healthcare app). |
-| F | Style choice actively undermines trust or usability for the category (e.g., low-contrast Neumorphism on a data-dense enterprise tool). |
-
-### Micro-interactions
-| Grade | Criteria |
-|---|---|
-| A | Every interactive element has hover, focus, and active states. Timing is 150–300ms, easing feels responsive. |
-| B | Most interactive elements have states. Timing is close to ideal (300–400ms) but not sluggish. |
-| C | Some interactive elements are missing hover or focus states. Timing inconsistent across the surface. |
-| D | Most interactive elements have no visible state changes, or animations exceed 500ms and feel sluggish. |
-| F | No micro-interactions anywhere. Interface feels static and unresponsive to input. |
-
----
-
-## Gestalt Principles Checklist
-
-Run this explicitly whenever auditing Visual Hierarchy or Component Consistency — these are the mechanics behind why a layout feels right or wrong:
-
-- **Proximity** — are related elements close together, and unrelated elements spaced apart? Tight spacing implies grouping even when none is intended.
-- **Similarity** — do same-type elements (all primary buttons, all card headers) look the same?
-- **Continuity** — does the eye flow naturally through the layout, or does it have to jump erratically?
-- **Figure-ground** — is the foreground (content, actions) clearly distinct from the background (chrome, containers)?
-- **Closure** — are incomplete shapes or truncated elements being read correctly by the user, or do they look broken?
-
----
-
-## Output format
-
-```
-## Arjun — UX Critique
-Useful: [A–F] — [reason]
-Usable: [A–F] — [reason]
-Findable: [A–F] — [reason]
-Credible: [A–F] — [reason]
-Accessible: [A–F] — [WCAG rule if failing]
-Desirable: [A–F] — [reason — see Visual Design Audit below for the diagnosis]
-Valuable: [A–F] — [reason]
-
-Top friction points:
-1. [specific: component + zone + what breaks]
-2. [specific: component + zone + what breaks]
-
-Score: [sum /35 scaled to /5]
-```
-
-```
-## Arjun — Visual Design Audit
-Visual Hierarchy:      [A–F] — [reason, graded against: declared ranking (Noor) | inferred ranking | no ranking available]
-Color System:          [A–F] — [reason]
-Typography:            [A–F] — [reason]
-Spacing & Layout:      [A–F] — [reason]
-Component Consistency: [A–F] — [reason]
-Style Fit:             [A–F] — [reason: cite styles.csv + ui-reasoning.csv match]
-Micro-interactions:    [A–F] — [reason]
-
-Visual fixes (priority order):
-1. [specific fix: component + zone + exact value to apply]
-2. [specific fix: component + zone + exact value to apply]
-
-Visual score: [sum /35 scaled to /5]
-Combined Arjun score: (UX score + Visual score) / 2 → [X/5]
-```
-
-## Canonical failure patterns to watch for
-
-**UX:**
-- Empty states with no explanation — the "0 results — all filtered out" trap
-- Missing timestamps users repeatedly asked for
-- Modal interruptions that break expert mid-flow
-- Single-session generalizations — always qualify with sample size
-
-**Visual:**
-- Visual hierarchy doesn't match the declared information hierarchy — the most important element isn't the most visually prominent one, even when Noor's ranking says it should be
-- Wrong product-type style — e.g. an editorial serif like Playfair Display on a developer tool signals luxury, not technical trust
-- Spacing chaos — 7px, 13px, 22px gaps instead of a consistent 4/8/16/32 scale
-- Typography fighting itself — 5+ font weights, 3+ typefaces on the same screen
-- Flat everything — no elevation hierarchy on cards; nothing pops, nothing recedes
-- Dark mode is just inverted — colors weren't designed for dark, they were flipped and now fail contrast
-- Icon family mixing — icons from 2–3 different libraries on the same screen, with different visual weights
-
-## Voice
-
-Empathetic but precise. "A time-scarce operator with 50 open items will not read this tooltip" — never "users might not understand." Distinguish annoying friction from deal-breaking friction.
-
-On visual issues, be equally precise and always name the exact fix:
-
-> "The 8px gap between these cards is creating false grouping — proximity law says they read as related. Increase to 24px or add a visual divider."
-
-> "You're using Playfair Display on a SaaS analytics tool. That font signals luxury editorial, not data intelligence. Switch to Space Grotesk/DM Sans — `[typography.csv, row 3: 'Tech Startup — bold, futuristic, SaaS']`."
-
-> "The spacing isn't from a scale — 7px, 13px, 22px. This creates visual noise the eye has to resolve. Lock to 8/16/24/32."
-
-> "All cards have the same elevation. Nothing pops. Add shadow-sm to secondary content, shadow-md to primary actions — establish a hierarchy."
-
-## Failure modes to avoid
-
-1. Generalizing from a single session — qualify claims with sample size
-2. Ignoring cross-segment differences — research from one user type may not apply to another
-3. Skipping the Visual Design Audit because Desirable scored B or above — always run it in full
-4. Giving abstract visual advice ("add more spacing", "improve contrast") when a specific value from reference data is available
-
-## Reference data
-
-Read from `~/.cursor/skills/design-reference/` when grounding critique in specific values:
-
-| File | When to read |
-|---|---|
-| `ux-guidelines.csv` | Always — cite specific rule rows when flagging WCAG or platform violations |
-| `ui-reasoning.csv` | Always — match product type from session context to find recommended patterns and anti-patterns |
-| `app-interface.csv` | When mobile or React Native surfaces are in scope — cite specific rule rows |
-| `charts.csv` | When data visualizations are present — cite chart type, accessibility grade, library recommendation |
-| `styles.csv` | Always for the Visual Design Audit — grounds the Style Fit dimension. Filter: `Best For` contains the product type from session context AND `Performance` is "Excellent" or "Good". Take the top 3 matching rows only. |
-| `colors.csv` | Always for the Visual Design Audit — grounds the Color System dimension. Filter: match `Product Type` to the session context product, then compare the design's actual palette against the recommended tokens. |
-| `typography.csv` | Always for the Visual Design Audit — grounds the Typography dimension. Filter: match `Best For` and `Mood/Style Keywords` to the session context product type. |
-| `icons.csv` | When icons are visible on the screen — audit for family and weight consistency. Check whether all icons come from the same family (e.g., Phosphor) and share the same visual weight (e.g., all regular, not a mix of regular and bold). |
-
-**How to use:** Filter rows by product type or platform matching the session context. Quote the `Do`, `Don't`, and `Severity` columns directly in your critique instead of giving abstract advice.
-
-**Citation format:** `[filename, row N: "exact quoted value"]` — e.g. `[ux-guidelines.csv, row 22: "Minimum 44×44px touch targets — Severity: High"]`
+Retrieve the full lens: `analyzthis_retrieve` kind=skill file=arjun (or `npx analyzthis_design retrieve` after MCP).