@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/.claude/skills/visual-review/SKILL.md

@@ -0,0 +1,503 @@
+---
+tier: lite
+name: visual-review
+description: "Visual UX review \u2014 screenshot a rendered page and evaluate against design tokens, usability standard, and Creative Director / Designer luminaries. Requires Playwright MCP."
+problem: "Rendered pages ship with visual regressions. Design tokens drift from usability standards."
+value: "Visual UX review \u2014 screenshot a rendered page and evaluate against design tokens plus usability."
+inputs: [Page URL and viewport]
+outputs: [Screenshot at each viewport, Findings per usability rule, Token alignment report]
+user_invocable: true
+disable_model_invocation: false
+composes_baseline: anthropic-frontend-design
+requires:
+  cli: [npx]
+  mcp: [playwright]
+---
+
+# Visual Review
+
+Screenshot a rendered page and evaluate it against the project's design
+system, usability standard, and luminary principles. This gives the
+Designer and Creative Director "eyes" on what was actually built.
+
+> **Baseline composition:** Bassclef's review composes on top of Anthropic's `frontend-design` skill defaults. Adopters firing plain Claude produce output evaluated against the baseline's typography + color + motion + spatial-composition guidance; this skill extends the evaluation with luminary-specific lenses (Tufte for data density, Ive for hierarchy, Rams for restraint, Cooper + Norman for affordances) plus bassclef's design-token + usability-standard discipline.
+
+## Prerequisites
+
+### Infrastructure check (run before first use)
+
+Check if Playwright MCP is available by looking for the
+`mcp__playwright__browser_navigate` tool. If it's NOT available:
+
+1. **Tell the user** — don't silently degrade:
+   > Visual review requires Playwright MCP but it's not available in this session.
+   > To install it, add the Playwright MCP server to your Claude Code config:
+   >
+   > ```json
+   > // In .claude/settings.json or ~/.claude/settings.json
+   > {
+   >   "mcpServers": {
+   >     "playwright": {
+   >       "command": "npx",
+   >       "args": ["@anthropic-ai/mcp-server-playwright"]
+   >     }
+   >   }
+   > }
+   > ```
+   >
+   > Then restart the session. Want me to add this to your settings now?
+
+2. **If the user says yes**, use the `/update-config` skill to add the
+   Playwright MCP server configuration, then tell them to restart.
+
+3. **If the user declines or this is an unattended session**, fall back
+   to manual verification mode: inspect code for tap targets, font sizes,
+   contrast values. Note "manual — no Playwright" in the report. This is
+   degraded mode, not a skip — a report is still required.
+
+### Stale browser recovery
+
+If Playwright MCP errors with "Target page, context or browser has been
+closed" or "Browser is already in use", a stale chrome process from a
+previous session is holding the lock. Fix:
+
+```bash
+pkill -f "mcp-chrome" 2>/dev/null; sleep 1
+```
+
+Then retry the navigation. This is common after long sessions, crashed
+agents, or overnight runs where the browser outlived the session.
+
+### Other prerequisites
+
+- A page must be running (local dev server, staging URL, etc.)
+- If the page requires auth, sign in first via Playwright before running this skill
+
+## Procedure
+
+### Step 1: Navigate and Screenshot (desktop + mobile)
+
+Screenshot at **both** viewports. A desktop-only review misses broken
+mobile layouts (sidebar eating half the screen, tables overflowing,
+tap targets too close together).
+
+```
+Desktop (1280px):
+1. Resize to 1280x800 via mcp__playwright__browser_resize
+2. Navigate to the target URL via mcp__playwright__browser_navigate
+3. Wait for the page to load
+4. Take a full-page screenshot via mcp__playwright__browser_take_screenshot
+5. Capture the accessibility snapshot via mcp__playwright__browser_snapshot
+
+Mobile (375px):
+6. Resize to 375x812 via mcp__playwright__browser_resize
+7. Take a full-page screenshot
+8. Capture the accessibility snapshot
+9. Check: does the sidebar collapse? Do tables reflow? Are tap targets ≥44px?
+```
+
+If the mobile viewport shows a broken layout (sidebar visible at full width,
+content pushed off-screen, horizontal scroll required), flag it as a
+**FAIL** — not a minor issue. Mobile is not optional.
+
+If the user didn't provide a URL, ask for one. Do not guess.
+
+### Step 2: Structural Analysis (from accessibility snapshot)
+
+Using the accessibility snapshot, evaluate:
+
+- **Heading hierarchy**: Are headings properly nested (h1 > h2 > h3)?
+- **Landmark regions**: Are banner, main, nav, contentinfo present?
+- **Interactive elements**: Do all buttons/links have accessible labels?
+- **Form structure**: Are form fields labeled? Are required fields marked?
+
+### Step 3: Usability Standard Check (from screenshot + snapshot)
+
+Evaluate against the 8-point usability standard (`.claude/rules/usability.md`):
+
+| Check | Method | Pass/Fail |
+|---|---|---|
+| 1. Role check | Is operator jargon visible? Database enums exposed? | |
+| 2. Scanning distance | Label-to-value gaps > 150px? | |
+| 3. Typography hierarchy | Key numbers 14px+ bold? Labels smaller + muted? Text < 11px? | |
+| 4. Jargon & copy | Raw enum values? Non-externalized labels? | |
+| 5. Attribution | Actions attributed to people, not just counts? | |
+| 6. Accessibility | Tap targets 44px+? Contrast 4.5:1+? Translucent text BGs? | |
+| 7. Consistency | Same badge/status treatment everywhere? | |
+| 8. Visual verification | Does what you SEE match what the code says? | |
+
+For checks that need measurement, use `mcp__playwright__browser_evaluate` to
+inspect computed styles:
+
+```js
+// Example: check tap target sizes
+document.querySelectorAll('button, a, [role="button"]').forEach(el => {
+  const rect = el.getBoundingClientRect();
+  if (rect.width < 44 || rect.height < 44) {
+    console.log(`Small target: ${el.textContent?.trim()} (${rect.width}x${rect.height})`);
+  }
+});
+```
+
+```js
+// Example: check text sizes
+document.querySelectorAll('*').forEach(el => {
+  const size = parseFloat(getComputedStyle(el).fontSize);
+  if (el.textContent?.trim() && size < 11) {
+    console.log(`Small text: "${el.textContent.trim().slice(0,30)}" at ${size}px`);
+  }
+});
+```
+
+### Step 4: Designer Evaluation (luminary lens)
+
+Evaluate what you SEE through these lenses:
+
+**Norman (usability)**:
+- Is the right action obvious? Can you tell what to do without thinking?
+- Are affordances clear? Do clickable things look clickable?
+- Is error prevention in place? Can the user make mistakes easily?
+
+**Cooper (goal-directed)**:
+- Does the page serve the user's primary goal directly?
+- Is there unnecessary friction between the user and their goal?
+
+**Krug (don't make me think)**:
+- Can you navigate without reading instructions?
+- Are choices obvious and unambiguous?
+
+### Step 5: Creative Director Evaluation (luminary lens)
+
+Evaluate the visual design through these lenses:
+
+**Lupton (typography)**:
+- Is there a clear typographic hierarchy (headline > subhead > body > caption)?
+- Is type used to tell a visual story, or is it all the same weight/size?
+- Do font choices support the brand's personality?
+
+**Albers (color)**:
+- Are colors working in context (not just in isolation)?
+- Is there a clear color hierarchy (primary action, secondary, muted)?
+- Are color relationships intentional or accidental?
+
+**Rams (good design)**:
+- Is the design honest? Does it promise only what it delivers?
+- Is it as little design as possible — less but better?
+- Could anything be removed without losing function?
+
+**Ive (craft)**:
+- Is there obsessive attention to detail (radii, shadows, weight, spacing)?
+- Does the digital surface feel considered, or thrown together?
+- Is there material honesty — do elements feel like what they are?
+
+**Kuznetsov (motion)** — if transitions/animations are present:
+- Do animations guide attention or just decorate?
+- Do state transitions convey meaning (loading, success, error)?
+- Is motion hierarchy clear (primary action animates, background stays still)?
+
+**Apple HIG (restraint)**:
+- Is there progressive disclosure, or is everything shown at once?
+- Is there visual clutter that could be removed?
+- Does the design show restraint and clarity?
+
+**Tufte (data display)** — if data is present:
+- Is the data-ink ratio high (minimal chartjunk)?
+- Are numbers formatted for scanning (aligned, consistent decimals)?
+- Is the most important data the most visually prominent?
+
+### Step 5.5: Prototype Drift Check (production UI only)
+
+When reviewing a production UI surface (not a prototype itself), diff
+the rendered production against the approved prototype referenced by
+the iteration goal or canvas. See
+`.claude/rules/prototype-production-coupling.md` §4.
+
+1. Locate the approved prototype for this surface — check the active
+   iteration goal's References block, or canvas under `docs/canvases/`,
+   for a `docs/prototypes/` path.
+2. If no prototype exists and the surface is user-visible: flag as a
+   finding ("prototype-production coupling rule §2 violation — no
+   prototype on file for this surface").
+3. If a prototype exists, render both and compare structurally:
+   - Layout: same regions, same hierarchy
+   - Affordances: same interaction targets, same visual weights
+   - Token fidelity: same color/spacing/type vocabulary
+4. Acceptable variances (call out with rationale):
+   - Responsive adaptation for viewport
+   - Real-data density shifts (more rows, truncation)
+   - Performance-driven simplifications (removed animations)
+5. Unacceptable (block merge as finding):
+   - Layout restructure
+   - Affordance changes (button → link, etc.)
+   - Hierarchy inversions
+   - Token substitutions not documented in an ADR
+
+Output: "Prototype drift: [none | minor (listed) | blocking (listed)]"
+
+### Step 6: Output Findings
+
+Write a structured report:
+
+```markdown
+## Visual Review: [page name / URL]
+
+**Screenshot**: [reference to saved file]
+**Date**: [today]
+**Reviewer**: Designer + Creative Director (automated)
+
+### Structural (accessibility snapshot)
+- [findings]
+
+### Usability Standard (8-point check)
+| Check | Result | Notes |
+|---|---|---|
+| 1. Role check | PASS/FAIL | |
+| ... | | |
+
+### Designer Findings
+- **Norman**: [findings]
+- **Cooper**: [findings]
+- **Krug**: [findings]
+
+### Creative Director Findings
+- **Lupton**: [findings]
+- **Albers**: [findings]
+- **Apple HIG**: [findings]
+- **Tufte**: [findings, if applicable]
+
+### Summary
+- **Critical** (must fix before merge): [list]
+- **Important** (should fix this iteration): [list]
+- **Minor** (log for future): [list]
+- **Positive** (what's working well): [list]
+
+### Verdict: PASS / PASS WITH NOTES / FAIL
+```
+
+## Luminary Separation — Creator vs. Evaluator
+
+When an iteration goal names a primary luminary, that luminary guided
+construction. Visual review must use **complementary luminaries** as
+evaluators — never grade your own homework.
+
+### Complement pairs
+
+| Primary (guided construction) | Evaluator (validates in visual review) | Tension |
+|---|---|---|
+| Norman (affordance) | Krug (simplicity) + Apple HIG (restraint) | "Is it obvious?" vs. "Is it too much?" |
+| Cooper (goals) | Norman (affordance) + Weinschenk (cognition) | "Right goal?" vs. "Right controls?" |
+| Krug (simplicity) | Cooper (goals) + Norman (affordance) | "Simple enough?" vs. "Complete enough?" |
+| Lupton (typography) | Tufte (data clarity) + Rams (honesty) | "Does it narrate?" vs. "Is it true?" |
+| Albers (color) | Heller (appropriateness) + Ive (craft) | "Does it work?" vs. "Does it feel right?" |
+| Tufte (data) | Lupton (hierarchy) + Rams (less but better) | "Shows the data?" vs. "Tells the story?" |
+| Prater (entity-derived) | Norman (affordance) + Morville (findability) | "Matches the model?" vs. "Users find it?" |
+| Morville (findability) | Prater (entity-derived) + Krug (simplicity) | "Can they find it?" vs. "Do they understand it?" |
+| Apple HIG (restraint) | Lupton (expression) + Walter (delight) | "Restrained enough?" vs. "Too sterile?" |
+| Rams (honesty) | Ive (craft) + Apple HIG (restraint) | "Honest?" vs. "Refined?" |
+| Material (systematic) | Apple HIG (restraint) + Tufte (data clarity) | "Systematic?" vs. "Necessary?" |
+| Tidwell (patterns) | Norman (affordance) + Cooper (goals) | "Proven pattern?" vs. "Right pattern for this goal?" |
+
+### How to apply
+
+1. Read the iteration goal's `primary_luminary:` field
+2. Look up the complement pair above
+3. In Step 4 (Designer Evaluation), weight the evaluator luminaries
+4. In Step 5 (Creative Director Evaluation), use the CD complement
+5. If no primary luminary is set, use all luminaries equally (default)
+
+The complement creates productive tension: the evaluator asks the questions
+the primary luminary wouldn't ask about their own approach.
+
+## Prototype Variant Evaluation
+
+When called during `/riff-prototypes`, visual review evaluates each
+variant and produces a **structured comparison** to inform the operator's
+selection. This replaces pure preference with evidence.
+
+### Procedure for prototype evaluation
+
+For each variant (2-3):
+1. Run the full visual review (Steps 1-5)
+2. Score each usability check (0-2: fail / partial / pass)
+3. Note which luminary principles are strongest and weakest
+4. Capture the variant's distinctive quality in one sentence
+
+Then produce a comparison:
+
+```markdown
+## Prototype Comparison
+
+| Criterion | Variant A (Norman) | Variant B (Lupton) | Variant C (Prater) |
+|---|---|---|---|
+| Usability score | 14/16 | 11/16 | 13/16 |
+| Strongest principle | Affordance clarity | Visual narrative | Domain coherence |
+| Weakest area | Visual storytelling | Tap target sizes | Discoverability |
+| Distinctive quality | "Every action is obvious" | "The page tells a story" | "Navigation mirrors the domain" |
+
+### Recommendation
+Based on the iteration goal's risk and value signals:
+- If retiring UX risk → [variant] scores highest on usability
+- If proving lovability → [variant] has strongest emotional quality
+- If proving viability → [variant] best serves the primary user goal
+
+**Recommended winner**: [variant] — [one sentence why]
+**Elements to carry from others**: [specific things worth keeping]
+```
+
+The operator makes the final call. The recommendation is evidence, not a decision.
+
+### What happens after selection
+
+1. Selected variant's luminary becomes `primary_luminary:` in iteration goal
+2. Complement pair is set for all subsequent visual reviews in this iteration
+3. `/ux-migration` runs next — gap analysis from prototype to production
+4. Construction builds the real thing, guided by the selected luminary
+5. Every UI commit during Construction triggers visual review with the complement evaluators
+
+## When to run this skill (MUST gate for UI changes)
+
+This skill is a **MUST gate** — not a suggestion — for these triggers:
+
+| Trigger | Gate level | Who invokes |
+|---|---|---|
+| Builder completes a UI change | **MUST** — blocks commit | Builder via /verify |
+| Prototype sprint variant evaluation | **MUST** — blocks selection | Designer |
+| Transition spot-check | **SHOULD** — logged if skipped | Creative Director |
+| Human requests it | **MUST** — explicit invocation | Anyone |
+
+**Evidence requirement**: Visual review produces a report file at
+`docs/visual-reviews/YYYY-MM-DD-{page-name}.md`. The pre-commit hook
+checks for this when UI files are staged. No report = warning.
+
+If Playwright MCP is unavailable, the agent MUST:
+1. State that Playwright MCP is not available
+2. Perform manual verification (tap targets, contrast, typography from code)
+3. Note "manual — no screenshot" in the report
+4. This is degraded mode, not a skip
+
+## Headless / CI Mode
+
+Visual review can run in headless environments (Docker, CI, staging) for
+automated pipeline verification. This extends the local-only default.
+
+### Environment detection
+
+At skill start, detect the environment:
+
+```bash
+# CI environment
+[ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ] || [ -n "$GITLAB_CI" ]
+
+# Docker / headless
+[ ! -d /tmp/.X11-unix ] && [ -z "$DISPLAY" ] && [ -z "$WAYLAND_DISPLAY" ]
+```
+
+### Headless Playwright configuration
+
+Playwright MCP runs headless by default — no display server needed. The
+screenshots are identical to headed mode. No special configuration required
+for headless operation.
+
+If running in Docker, ensure the container has:
+```dockerfile
+# Playwright dependencies
+RUN npx playwright install --with-deps chromium
+```
+
+### Targeting staging URLs
+
+Visual review can target any URL, not just localhost:
+
+```
+/visual-review https://staging.example.com/deals
+```
+
+When targeting staging:
+- Auth may differ — use staging credentials or service account
+- Data may differ — note in report: "Reviewed against staging data"
+- Network latency affects load times — increase wait timeouts
+- Never target production for automated reviews (read-only risk is low,
+  but the principle matters)
+
+### CI integration (GitHub Actions)
+
+Run visual review as a non-blocking PR check:
+
+```yaml
+# .github/workflows/visual-review.yml
+name: Visual Review
+on: [pull_request]
+
+jobs:
+  visual-review:
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.labels.*.name, 'ui-change')
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: npm ci && npx playwright install --with-deps chromium
+
+      - name: Start dev server
+        run: npm run dev &
+        env:
+          PORT: 3000
+
+      - name: Wait for server
+        run: npx wait-on http://localhost:3000 --timeout 30000
+
+      - name: Run visual review
+        run: npx claude -p "/visual-review http://localhost:3000"
+        continue-on-error: true  # non-blocking initially
+
+      - name: Upload screenshots
+        uses: actions/upload-artifact@v4
+        with:
+          name: visual-review-screenshots
+          path: docs/visual-reviews/
+          if-no-files-found: warn
+```
+
+### PR artifact screenshots
+
+Screenshots are saved as PR artifacts for human review. The report
+references them:
+
+```markdown
+### Screenshots
+- Desktop (1280px): [artifact: visual-review-screenshots/desktop.png]
+- Mobile (375px): [artifact: visual-review-screenshots/mobile.png]
+```
+
+In CI, these are downloadable from the Actions run. In local review,
+they're at `docs/visual-reviews/`.
+
+### Blocking vs. non-blocking
+
+| Phase | Gate level | Recommended |
+|-------|-----------|------------|
+| Initial adoption | Non-blocking (continue-on-error) | Learn what it catches without blocking PRs |
+| After 2 weeks | Blocking for FAIL verdicts | FAIL = broken layout, not style nits |
+| Mature | Blocking for FAIL + PASS WITH NOTES | Full gate enforcement |
+
+Start non-blocking. Promote to blocking after the team trusts the verdicts.
+
+### Environment requirements summary
+
+| Environment | Display | Server | Auth | Notes |
+|-------------|---------|--------|------|-------|
+| Local dev | Headed or headless | localhost:3000 | Dev credentials | Default mode |
+| Docker | Headless | localhost:PORT | Dev credentials | Install playwright deps |
+| CI (GitHub Actions) | Headless | localhost:PORT | Dev credentials | Upload artifacts |
+| Staging | Headless | staging URL | Staging credentials | Note in report |
+| Production | Not recommended | — | — | Use staging instead |
+
+## What this skill does NOT do
+
+- Interactive flow testing (clicking through multi-step flows) — see /visual-qa
+- Design token generation — that's the Creative Director's job
+- Implementation fixes — flag issues, don't fix them
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.