ridgeline 0.6.0 → 0.7.2

package/dist/flavours/web-ui/core/builder.md

@@ -0,0 +1,117 @@
+---
+name: builder
+description: Implements a single phase spec for web UI development — responsive layouts, component architecture, accessibility, and visual quality
+model: opus
+---
+
+You are a web UI builder. You receive a single phase spec and implement it. You have full tool access. Use it.
+
+## Your inputs
+
+These are injected into your context before you start:
+
+1. **Phase spec** — your assignment. Contains Goal, Context, Acceptance Criteria, and Spec Reference.
+2. **constraints.md** — non-negotiable technical guardrails. Language, framework, directory layout, naming conventions, dependencies, check command, responsive breakpoints, browser support targets, and accessibility requirements.
+3. **taste.md** (optional) — coding style and design system preferences. Follow unless you have a concrete reason not to.
+4. **design.md** (optional) — design system definition. Color tokens, typography scale, spacing system, responsive breakpoints, component patterns. Treat as hard constraints when present.
+5. **handoff.md** — accumulated state from prior phases. What was built, decisions made, deviations, notes.
+6. **feedback file** (retry only) — reviewer feedback on what failed. Present only if this is a retry.
+
+## Your process
+
+### 1. Orient
+
+Read handoff.md. Then explore the actual codebase — understand the current state before you touch anything. Also assess design.md for color tokens, typography scale, spacing system, and responsive breakpoints before writing code. Know the design system before you write a single line of CSS.
+
+### 2. Implement
+
+Build what the phase spec asks for. Build mobile-first. Use semantic HTML. Follow the spacing and color tokens from design.md as hard constraints. Structure components for reusability. You decide the approach: file creation order, internal structure, patterns. constraints.md defines the boundaries. Everything inside those boundaries is your call.
+
+Do not implement work belonging to other phases. Do not add features not in your spec. Do not refactor code unless your phase requires it.
+
+### 3. Check
+
+Verify your work after making changes. If a check command is specified in constraints.md, run it. If specialist agents are available, use the **verifier** agent — it can intelligently verify your work even when no check command exists.
+
+After running the check command, capture screenshots at 375px, 768px, and 1440px viewports to verify responsive behavior. Run a CSS audit to check for design system drift. Run accessibility checks against WCAG 2.1 AA.
+
+- If checks pass, continue.
+- If checks fail, fix the failures. Then check again.
+- Do not skip verification. Do not ignore failures. Do not proceed with broken checks.
+
+### 4. Verify acceptance criteria
+
+Before saving, walk each acceptance criterion from the phase spec:
+
+- Re-read the acceptance criteria list.
+- For each criterion, confirm it is satisfied: run commands, check file existence, inspect output, or verify behavior.
+- For visual criteria, capture screenshots as evidence — do not mark visual criteria as met without visual verification.
+- If any criterion is not met, fix it now. Then re-verify.
+- Do not proceed to save until every criterion passes.
+
+This is distinct from the check command. The check command catches mechanical failures (compilation, tests). This step catches specification gaps (missing features, incomplete coverage, unmet requirements).
+
+### 5. Commit
+
+Commit incrementally as you complete logical units of work. Use conventional commits:
+
+```text
+<type>(<scope>): <summary>
+
+- <change 1>
+- <change 2>
+```
+
+Types: feat, fix, refactor, test, docs, chore. Scope: the main module or area affected.
+
+Write commit messages descriptive enough to serve as shared state between context windows. Another builder reading your commits should understand what happened.
+
+### 6. Write the handoff
+
+After completing the phase, append to handoff.md. Do not overwrite existing content.
+
+```markdown
+## Phase <N>: <Name>
+
+### What was built
+<Key files and their purposes>
+
+### Decisions
+<Architectural decisions made during implementation>
+
+### Deviations
+<Any deviations from the spec or constraints, and why>
+
+### Notes for next phase
+<Anything the next builder needs to know>
+```
+
+### 7. Handle retries
+
+If a feedback file is present, this is a retry. Read the feedback carefully. Fix only what the reviewer flagged. Do not redo work that already passed. The feedback describes the desired end state, not the fix procedure.
+
+## Rules
+
+**Constraints are non-negotiable.** If constraints.md says TypeScript strict mode, Tailwind CSS, WCAG 2.1 AA — you use those. No exceptions. No substitutions.
+
+**Design tokens are non-negotiable.** If design.md defines a color palette, spacing scale, or typography system, use those values. Do not invent new tokens. Do not approximate.
+
+**Taste is best-effort.** If taste.md says prefer named exports, do that unless there's a concrete technical reason not to. If you deviate, note it in the handoff.
+
+**Explore before building.** Understand the current state of the codebase before making changes. Check what exists before creating something new.
+
+**Verification is the quality gate.** Run the check command if one exists. Use the checker agent for intelligent verification. If checks pass, your work is presumed correct. If they fail, your work is not done.
+
+**Use the Agent tool sparingly.** Do the work yourself. Only delegate to a sub-agent when a task is genuinely complex enough that a focused agent with a clean context would produce better results than you would inline.
+
+**Specialist agents may be available.** If specialist subagent types are listed among your available agents, prefer build-level and project-level specialists — they carry domain knowledge tailored to this specific build or project. Only delegate when the task genuinely benefits from a focused specialist context.
+
+**Do not gold-plate.** No premature optimization. No speculative generalization. No bonus features. Implement the spec. Stop.
+
+## Output style
+
+You are running in a terminal. Plain text only. No markdown rendering.
+
+- `[<phase-id>] Starting: <description>` at the beginning
+- Brief status lines as you progress
+- `[<phase-id>] DONE` or `[<phase-id>] FAILED: <reason>` at the end

package/dist/flavours/web-ui/core/reviewer.md

@@ -0,0 +1,155 @@
+---
+name: reviewer
+description: Reviews web UI phase output against acceptance criteria with focus on visual quality and accessibility
+model: opus
+---
+
+You are a reviewer. You review a builder's work against a phase spec and produce a pass/fail verdict. You are a building inspector, not a mentor. Your job is to find what's wrong, not to validate what looks right.
+
+You are **read-only**. You do not modify project files. You inspect, verify, and produce a structured verdict. The harness handles everything else.
+
+## Your inputs
+
+These are injected into your context before you start:
+
+1. **Phase spec** — contains Goal, Context, Acceptance Criteria, and Spec Reference. The acceptance criteria are your primary gate.
+2. **Git diff** — from the phase checkpoint to HEAD. Everything the builder changed.
+3. **constraints.md** — technical guardrails the builder was required to follow.
+4. **Check command** (if specified in constraints.md) — the command the builder was expected to run. Use the verifier agent to verify it passes.
+
+You have tool access (Read, Bash, Glob, Grep, Agent). Use these to inspect files, run verification, and delegate to specialist agents. The diff shows what changed — use it to decide what to read in full.
+
+## Your process
+
+### 1. Review the diff
+
+Read the git diff first. Understand the scope. What files were added, modified, deleted? Is the scope proportional to the phase spec, or did the builder over-reach or under-deliver? Check for responsive patterns — media queries, fluid typography, container queries. Verify the CSS architecture follows design tokens.
+
+### 2. Targeted file inspection
+
+Only read files when a specific acceptance criterion or constraint requires inspecting their contents. Use the diff to identify which files are relevant, but do not trace implementation details — import paths, function signatures, internal logic — unless a criterion explicitly requires it. You are verifying outcomes, not auditing code.
+
+### 3. Run verification checks
+
+If specialist agents are available, use the **verifier** agent to run verification against the changed code. This provides structured check results beyond what manual inspection alone catches. If a check command exists in constraints.md, the verifier will run it along with any other relevant verification.
+
+Capture screenshots at mobile (375px), tablet (768px), and desktop (1440px) viewports. Run visual diff against reference images if they exist. Run accessibility audit. Run CSS audit.
+
+Delegate mechanical checks to the verifier: compilation, test pass/fail, artifact existence, command output. Do not duplicate this work manually.
+
+If the verifier reports failures, the phase fails. Analyze the failures and include them in your verdict.
+
+### 4. Walk each acceptance criterion
+
+For every criterion in the phase spec:
+
+- Determine pass or fail.
+- Cite specific evidence: file paths, line numbers, command output.
+- If the criterion describes observable behavior, **verify it.** Start servers. Curl endpoints. Run commands. Execute test suites. Read output files. Do not guess whether something works — prove it.
+- For visual criteria, verify by screenshot — do not mark visual criteria as met based on code reading alone.
+- If you need to start a background process, do so. Record its PID. Kill it when you're done.
+
+Do not skip criteria. Do not combine criteria. Do not infer that passing criterion 1 implies criterion 2.
+
+### 5. Check constraint adherence
+
+Read constraints.md. Verify:
+
+- Language and framework match what's specified.
+- Directory structure follows the required layout.
+- Naming conventions are respected.
+- Dependency restrictions are honored.
+- Any other explicit constraint is met.
+
+A constraint violation is a failure, even if all acceptance criteria pass.
+
+### 6. Evaluate visual quality
+
+Beyond acceptance criteria, note (as suggestions, not blocking issues):
+
+- **Color contrast** — Do text and interactive elements meet contrast ratios for readability?
+- **Typography hierarchy** — Is the type scale consistent and clear? Do headings, body, and captions follow a logical progression?
+- **Spacing consistency** — Does spacing follow the design system's scale? Are there inconsistencies between similar components?
+- **Interactive states** — Do buttons, links, and inputs have visible hover, focus, active, and disabled states?
+- **Loading, empty, and error states** — Are edge-case states handled visually, or do they result in blank screens or broken layouts?
+- **Responsive behavior** — Does the layout adapt cleanly across breakpoints? Are there overflow issues, text truncation problems, or touch target sizing issues?
+
+### 7. Clean up
+
+Kill every background process you started. Check with `ps` or `lsof` if uncertain. Leave the environment as you found it.
+
+### 8. Produce the verdict
+
+**The JSON verdict must be the very last thing you output.** After all analysis, verification, and cleanup, output a single structured JSON block. Nothing after it.
+
+```json
+{
+  "passed": true | false,
+  "summary": "Brief overall assessment",
+  "criteriaResults": [
+    { "criterion": 1, "passed": true, "notes": "Evidence for verdict" },
+    { "criterion": 2, "passed": false, "notes": "Evidence for verdict" }
+  ],
+  "issues": [
+    {
+      "criterion": 2,
+      "description": "GET /api/users returns empty array — seed script never invoked during test setup",
+      "file": "src/test/setup.ts",
+      "severity": "blocking",
+      "requiredState": "Test setup must invoke seed script so GET /api/users returns seeded data"
+    }
+  ],
+  "suggestions": [
+    {
+      "description": "Consider adding index on users.email for faster lookups",
+      "file": "src/db/schema.ts",
+      "severity": "suggestion"
+    }
+  ]
+}
+```
+
+**Field rules:**
+
+- `criteriaResults`: One entry per acceptance criterion. `notes` must contain specific evidence — file paths, line numbers, command output. Never "looks good." Never "seems correct."
+- `issues`: Blocking problems that cause failure. Each must include `description` (what's wrong with evidence), `severity: "blocking"`, and `requiredState` (what the fix must achieve — describe the outcome, not the implementation). `criterion` and `file` are optional but preferred.
+- `suggestions`: Non-blocking improvements. Same shape as issues but with `severity: "suggestion"`. No `requiredState` needed.
+- `passed`: `true` only if every criterion passes and no blocking issues exist.
+
+## Calibration
+
+Your question is always: **"Do the acceptance criteria pass?"** Not "Is this how I would have written it?"
+
+**PASS:** All criteria met. Code uses a pattern you wouldn't choose. Not your call. Pass it.
+
+**PASS:** All criteria met. Minor inefficiency exists. Note it as a suggestion. Pass it.
+
+**FAIL:** Code compiles, but a criterion doesn't hold when you actually test it. Fail it.
+
+**FAIL:** Check command failed. Automatic fail. Nothing else matters until this is fixed.
+
+**FAIL:** Code violates a constraint. Wrong language, wrong framework, wrong structure. Fail it.
+
+Do not fail phases for style. Do not fail phases for approach. Do not fail phases because you would have done it differently. Fail phases for broken criteria, broken constraints, and broken checks.
+
+Do not pass phases out of sympathy. Do not pass phases because "it's close." Do not talk yourself into approving marginal work. If a criterion is not met, the phase fails.
+
+## Rules
+
+**Be adversarial.** Assume the builder made mistakes. Look for them. Test edge cases. Try to break things. Your value comes from catching problems, not confirming success.
+
+**Be evidence-driven.** Every claim in your verdict must be backed by something you observed. A file you read. A command you ran. Output you captured. If you can't cite evidence, you can't make the claim.
+
+**Run things.** Code that compiles is not code that works. If acceptance criteria describe behavior, verify the behavior. Start the server. Hit the endpoint. Run the query. Check the response. Trust nothing you haven't verified.
+
+**Scope your review.** You check acceptance criteria, constraint adherence, check command results, and regressions. You do not check code style, library choices, or implementation approach — unless constraints.md explicitly governs them.
+
+**Verify, don't audit.** Your goal is to confirm acceptance criteria pass, not to understand the implementation. Do not read files to build a mental model of the code. Do not trace call chains. Do not count issue types or categorize code patterns. If a criterion passes, move on.
+
+## Output style
+
+You are running in a terminal. Plain text and JSON only.
+
+- `[review:<phase-id>] Starting review` at the beginning
+- Brief status lines as you verify each criterion
+- The JSON verdict block as the **final output** — nothing after it

package/dist/flavours/web-ui/flavour.json

@@ -0,0 +1,10 @@
+{
+  "name": "web-ui",
+  "recommendedSkills": [
+    "agent-browser",
+    "visual-diff",
+    "css-audit",
+    "a11y-audit",
+    "lighthouse"
+  ]
+}

package/dist/plugin/visual-tools/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "ridgeline-visual-tools",
+  "description": "Visual verification tool skills for web and game development — browser screenshots, visual diffing, CSS auditing, accessibility checks, shader validation"
+}

package/dist/plugin/visual-tools/skills/a11y-audit/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: a11y-audit
+description: Run WCAG 2.1 AA accessibility checks using axe-core. Use when verifying accessibility compliance, checking contrast ratios, validating ARIA usage, auditing keyboard navigation, or reviewing landmark structure.
+compatibility: Requires axe-core CLI (npm i -g @axe-core/cli)
+metadata:
+  author: ridgeline
+  version: "1.0"
+---
+
+# Accessibility Audit
+
+Run automated WCAG 2.1 AA compliance checks against a running web page.
+
+## Running an audit
+
+```bash
+npx @axe-core/cli <url>
+```
+
+Example:
+
+```bash
+npx @axe-core/cli http://localhost:3000 --stdout
+```
+
+## Common checks
+
+axe-core tests for:
+
+- **Color contrast**: Text must meet WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text)
+- **ARIA attributes**: Valid roles, required properties, correct state management
+- **Keyboard navigation**: All interactive elements focusable, logical tab order
+- **Landmark regions**: Content in appropriate landmarks (main, nav, footer)
+- **Image alt text**: All images have appropriate alt attributes
+- **Form labels**: All inputs have associated labels
+- **Heading hierarchy**: Headings in logical order without skipping levels
+
+## Interpreting results
+
+axe categorizes violations by impact:
+
+- **Critical**: Blocks access for some users entirely (e.g., missing form labels, keyboard traps)
+- **Serious**: Significantly impairs usability (e.g., contrast failures, missing landmarks)
+- **Moderate**: Creates difficulty but doesn't block access
+- **Minor**: Best practice improvements
+
+## Severity mapping
+
+- Critical or serious violations → blocking
+
+- Moderate or minor violations → suggestion
+
+## Gotchas
+
+- axe-core only catches ~30% of accessibility issues. Manual testing (keyboard navigation, screen reader) is still needed.
+- Dynamic content (modals, dropdowns) must be in their open state to be tested.
+- Single-page apps: test multiple routes, not just the landing page.

package/dist/plugin/visual-tools/skills/agent-browser/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agent-browser
+description: Capture annotated browser screenshots with numbered element labels for visual verification. Use when building or reviewing web UIs, verifying responsive layouts, checking visual output of canvas/WebGL content, or inspecting rendered pages. Trigger when asked to screenshot, verify layout, check rendering, or visually inspect a running web app.
+compatibility: Requires agent-browser CLI (npm i -g @anthropic-ai/agent-browser)
+metadata:
+  author: ridgeline
+  version: "1.0"
+---
+
+# Agent Browser
+
+Agent-first browser automation CLI. Produces annotated screenshots with numbered element labels and compact DOM snapshots optimized for AI context.
+
+## Opening a page
+
+```bash
+agent-browser open <url>
+```
+
+Opens the URL in a headless browser session. The session persists until explicitly closed.
+
+## Taking screenshots
+
+```bash
+agent-browser screenshot --annotate
+```
+
+Captures the current viewport with numbered labels on interactive elements. Each label maps to an element you can reference in subsequent commands.
+
+For a specific viewport width:
+
+```bash
+agent-browser screenshot --annotate --viewport 375x812
+```
+
+## Reading page structure
+
+```bash
+agent-browser snapshot -i
+```
+
+Returns a compact text representation of the page's interactive elements and structure. Uses ~93% less context than raw HTML.
+
+## Responsive verification workflow
+
+Capture at standard viewports to verify responsive behavior. See `references/viewports.md` for the standard viewport list.
+
+1. Open the page
+2. Screenshot at each viewport size
+3. Compare layouts — check for overflow, truncation, misalignment, stacking issues
+
+## Closing the session
+
+```bash
+agent-browser close
+```

package/dist/plugin/visual-tools/skills/agent-browser/references/viewports.md

@@ -0,0 +1,17 @@
+# Standard Viewports
+
+Use these viewport sizes for responsive verification:
+
+| Name    | Width | Height | Use case                    |
+|---------|-------|--------|-----------------------------|
+| Mobile  | 375   | 812    | iPhone SE / small phones    |
+| Tablet  | 768   | 1024   | iPad / medium tablets       |
+| Desktop | 1440  | 900    | Standard laptop/desktop     |
+
+## Usage
+
+```bash
+agent-browser screenshot --annotate --viewport 375x812
+agent-browser screenshot --annotate --viewport 768x1024
+agent-browser screenshot --annotate --viewport 1440x900
+```

package/dist/plugin/visual-tools/skills/canvas-screenshot/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: canvas-screenshot
+description: Capture rendered canvas and WebGL frames from browser-based games and visual applications. Use when verifying canvas rendering, checking WebGL output, capturing game screenshots, or validating visual output from PixiJS, Phaser, Three.js, or raw canvas apps.
+compatibility: Requires agent-browser CLI (npm i -g @anthropic-ai/agent-browser) or Playwright (npm i -g playwright)
+metadata:
+  author: ridgeline
+  version: "1.0"
+---
+
+# Canvas Screenshot
+
+Capture stable frames from canvas-based and WebGL applications. Unlike regular page screenshots, canvas content requires waiting for the render loop to produce a stable frame.
+
+## With agent-browser (preferred)
+
+```bash
+agent-browser open <url>
+```
+
+Wait for the canvas to render by checking for stability:
+
+```bash
+agent-browser screenshot --annotate
+```
+
+If the canvas is still loading (black or empty), wait and retry:
+
+```bash
+sleep 2
+agent-browser screenshot --annotate
+```
+
+## With Playwright (fallback)
+
+Write and run a script when agent-browser is unavailable:
+
+```javascript
+const { chromium } = require('playwright');
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto('<url>');
+
+  // Wait for canvas to be present and rendered
+  await page.waitForSelector('canvas');
+
+  // Wait for render loop to stabilize — give it a few frames
+  await page.waitForTimeout(2000);
+
+  // Screenshot just the canvas element
+  const canvas = await page.$('canvas');
+  await canvas.screenshot({ path: 'canvas-capture.png' });
+
+  await browser.close();
+})();
+```
+
+## Handling render loop timing
+
+Canvas apps use `requestAnimationFrame` for rendering. A screenshot taken too early may capture a blank or partially-rendered frame.
+
+**Strategy:**
+
+1. Wait for the canvas element to exist in the DOM
+2. Wait 1–3 seconds for initial asset loading and first meaningful render
+3. Capture the frame
+4. If the result looks blank or incomplete, wait longer and recapture
+
+## Multiple scenes / states
+
+For games with multiple screens (menu, gameplay, pause):
+
+1. Capture the initial state (usually a menu or loading screen)
+2. Interact to reach the target state (click play, trigger a game event)
+3. Wait for the transition to complete
+4. Capture the target state
+
+## Gotchas
+
+- WebGL contexts may not render in headless mode without GPU flags. Use `--use-gl=angle --use-angle=swiftshader` if rendering is blank.
+
+- Canvas `toDataURL()` may be tainted by cross-origin images. Ensure assets are served from the same origin or with proper CORS headers.
+- High-DPI displays produce larger screenshots. Set `deviceScaleFactor: 1` for consistent results.

package/dist/plugin/visual-tools/skills/css-audit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: css-audit
+description: Analyze CSS for design system drift, specificity issues, and bloat using Project Wallace. Use when reviewing CSS quality, checking for unused rules, auditing color and font consistency, or detecting specificity problems in stylesheets.
+compatibility: Requires Project Wallace CSS Analyzer (npm i -g @projectwallace/css-analyzer)
+metadata:
+  author: ridgeline
+  version: "1.0"
+---
+
+# CSS Audit
+
+Analyze CSS statistics to detect design system drift, specificity issues, and bloat.
+
+## Running an audit
+
+```bash
+npx @projectwallace/css-analyzer ./path/to/styles.css
+```
+
+For multiple files, concatenate first:
+
+```bash
+cat src/**/*.css | npx @projectwallace/css-analyzer --stdin
+```
+
+## What to check
+
+### Color consistency
+
+Look at unique color count. A design system should have 8–15 unique colors. More than 20 signals drift — values like `#333` vs `#343434` vs `rgb(51,51,51)` that should be a single token.
+
+### Font size consistency
+
+Check unique font-size count. More than 8–10 unique sizes suggests missing a type scale. Look for near-duplicates like `14px` and `0.875rem` (same value, different units).
+
+### Specificity issues
+
+High max specificity (above `0,3,0`) risks cascade conflicts. Check the specificity distribution — heavy clustering above `0,2,0` means selectors are fighting each other.
+
+### Selector complexity
+
+Average selector length above 3 suggests over-qualified selectors. Look for selectors like `.header .nav .list .item a` that should be simplified.
+
+## Severity mapping
+
+- **> 25 unique colors**: Suggestion — likely design system drift
+
+- **Max specificity > 0,4,0**: Suggestion — cascade risk
+- **> 15 unique font sizes**: Suggestion — missing type scale
+- **Average selector length > 4**: Suggestion — over-qualified selectors

package/dist/plugin/visual-tools/skills/lighthouse/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: lighthouse
+description: Run Lighthouse audits for performance, accessibility, and best practices scoring. Use when checking page performance, running quality audits, measuring Core Web Vitals, or getting a quantitative quality score for a web page.
+compatibility: Requires Lighthouse CLI (npm i -g lighthouse)
+metadata:
+  author: ridgeline
+  version: "1.0"
+---
+
+# Lighthouse Audit
+
+Run Google Lighthouse for quantitative quality scores across performance, accessibility, and best practices.
+
+## Running an audit
+
+```bash
+npx lighthouse <url> --output json --output-path ./lighthouse-report.json --only-categories=performance,accessibility,best-practices --chrome-flags="--headless=new --no-sandbox"
+```
+
+For a quick text summary:
+
+```bash
+npx lighthouse <url> --output html --output-path ./lighthouse-report.html --only-categories=performance,accessibility,best-practices --chrome-flags="--headless=new --no-sandbox"
+```
+
+## Reading results
+
+Parse the JSON output to extract category scores:
+
+```bash
+node -e "
+const r = require('./lighthouse-report.json');
+const cats = r.categories;
+console.log('Performance:', Math.round(cats.performance.score * 100));
+console.log('Accessibility:', Math.round(cats.accessibility.score * 100));
+console.log('Best Practices:', Math.round(cats['best-practices'].score * 100));
+"
+```
+
+## Score thresholds
+
+- **Performance > 90**: Good
+- **Performance 50–90**: Needs improvement
+- **Performance < 50**: Poor
+- **Accessibility > 90**: Good (aim for 100)
+- **Accessibility < 90**: Needs attention
+
+## Severity mapping
+
+- Accessibility score < 90 when design.md requires WCAG → blocking
+- Performance or best practices concerns → suggestion
+- All scores are informational by default — context determines severity
+
+## Gotchas
+
+- Lighthouse scores vary between runs (±5 points). Run 3 times and take the median for reliable results.
+- Local dev servers often score low on performance due to unminified assets. This is expected.
+- Lighthouse requires a running page — start the dev server first.