Visual Audit Protocol

Audit existing templates for design quality issues. Reports findings in a structured format for human review. Does not auto-fix.

When to Use

Invoke this skill when:

• Asked to audit templates for visual quality
• Before a major UI PR (run alongside /review)
• After bulk template changes to catch regressions
• When a page "looks off" but the issue is not obvious

Audit Procedure

Step 1: Scope

Determine which templates to audit:

• Full audit: All templates in sova/dashboard/templates/ and sova/dashboard/static/
• Targeted audit: Specific templates (e.g., agents.html, queue.html)
• Diff audit: Only templates changed in the current branch (git diff --name-only main -- sova/dashboard/templates/ sova/dashboard/static/)

Step 2: Read References

Before auditing, read these files to understand the baseline:

1. docs/design-system.md: palette, typography, components
2. sova/dashboard/static/style.css: CSS variables, component classes
3. .claude/skills/dashboard-design/SKILL.md: quality rules and anti-slop bans

Step 3: Run Automated Checks

# Color violations: hardcoded hex/rgb/hsl outside Catppuccin palette
grep -rn --include='*.html' --include='*.js' --include='*.css' -E '(#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\(|hsla\()' sova/dashboard/templates/ sova/dashboard/static/ | grep -v '{#' | grep -v 'style.css' | grep -v '_head.html'

# Inline event handlers in templates (except onclick with stopPropagation in JS-rendered HTML)
grep -rn --include='*.html' -E 'onchange=|onsubmit=|onkeydown=|onload=' sova/dashboard/templates/

# Native title attribute instead of data-tooltip
grep -rn --include='*.html' --include='*.js' 'title="' sova/dashboard/templates/ sova/dashboard/static/app.js | grep -v '<title>' | grep -v 'data-tooltip'

# transition: all (should specify properties)
grep -rn --include='*.html' --include='*.css' --include='*.js' 'transition:\s*all\b' sova/dashboard/templates/ sova/dashboard/static/

# Arbitrary spacing values
grep -rn --include='*.html' -E '(p|m|gap)-\[' sova/dashboard/templates/

# Font sizes below minimum (use text-xs or a token; JS-rendered markup counts, so include *.js)
grep -rn --include='*.html' --include='*.css' --include='*.js' --exclude='*.min.js' -E 'text-\[(9|10|11)px\]|font-size:\s*(9|10|11)px' sova/dashboard/templates/ sova/dashboard/static/

# Raw fetch( instead of fetchAPI (fetchAPI owns the non-2xx error path).
# Expect hits: the fetch( inside fetchAPI itself, and pages that predate it. Report a hit in a file in
# scope; list a hit in an untouched page as pre-existing instead of counting it against the change.
grep -rn --include='*.html' --include='*.js' --exclude='*.min.js' -E '\bfetch\(' sova/dashboard/templates/ sova/dashboard/static/

# Raw setInterval( instead of visibilityAwarePoll (a raw timer keeps polling in a hidden tab).
# Expect hits: the setInterval( inside visibilityAwarePoll itself, a few timers in static/app.js that its
# own visibility handler manages (read the surrounding code), and pages that predate the helper. Apply the
# same in-scope versus pre-existing split.
grep -rn --include='*.html' --include='*.js' --exclude='*.min.js' 'setInterval(' sova/dashboard/templates/ sova/dashboard/static/

# Banned shadow classes (SOVA uses border-based depth)
grep -rn --include='*.html' -E 'shadow-(md|lg|xl|2xl)' sova/dashboard/templates/ | grep -v '{#'

# Overflow hidden/auto/scroll on containers (may clip tooltips/popovers)
grep -rn --include='*.html' --include='*.css' -E 'overflow-(hidden|auto|scroll)|overflow:\s*(hidden|auto|scroll)' sova/dashboard/templates/ sova/dashboard/static/ | grep -v 'overflow-x-auto'

# Missing escapeHtml on dynamic content in innerHTML
grep -rn --include='*.html' --include='*.js' 'innerHTML.*+.*\b(item\.|agent\.|data\.|pr\.)' sova/dashboard/templates/ sova/dashboard/static/ | grep -v 'escapeHtml'

# Cost values without parseFloat guard
grep -rn --include='*.html' --include='*.js' '\.toFixed(' sova/dashboard/templates/ sova/dashboard/static/ | grep -v 'parseFloat'

# ASCII characters used as icons (arrows, checks, dots)
grep -rn --include='*.html' -E "'&#x2[0-9a-fA-F]{3};|&rarr;|&larr;|&check;|\\\\u2" sova/dashboard/templates/

Step 3.5: Live Verification (mandatory for any audit ahead of approving a PR)

Static grep checks and code reading cannot catch browser-only bugs (layout timing, focus handling, JS runtime errors): a change can look correct on review and still be completely broken in the browser. Before signing off on a frontend/dashboard PR:

• Start the dashboard and load the affected page(s). Do not start or stop the user's own make dev instance: if it's already running, use it; otherwise start an isolated instance on an alternate port (e.g. uvicorn sova.dashboard.app:create_app --factory --port 8112).
• Exercise the actual golden path the PR touches (click through it, don't just look at it).
• If the PR claims "manually verified," verify independently anyway.

This step is required before the audit report can mark any finding as resolved-by-inspection, and before /review approves a UI PR based on this audit.

Step 4: Manual Inspection Checklist

For each template in scope, check:

A. Visual Hierarchy (most impactful)

B. Spacing Consistency

C. Color & Theme

D. Component Usage

E. Interaction Quality

F. AI-Tell Detection

G. Mechanical Pattern Checks (from the Step 3 greps)

Step 5: Report Format

Report findings as a structured list, grouped by severity:

## Visual Audit Report

**Scope**: [templates audited]
**Date**: [date]

### Critical (must fix before merge)
1. **[file:line]** [issue description] -- [fix suggestion]

### High (fix in this PR if touched, otherwise create issue)
1. **[file:line]** [issue description] -- [fix suggestion]

### Medium (fix when next touching this template)
1. **[file:line]** [issue description] -- [fix suggestion]

### Low (nice to have)
1. **[file:line]** [issue description] -- [fix suggestion]

### Summary
- Total findings: N
- Critical: N | High: N | Medium: N | Low: N
- Templates audited: N
- Templates clean: N
- Live-verified in browser: yes/no (see Step 3.5) -- if no, say why and flag the audit as incomplete

Do NOT auto-fix findings. Report them for human review. The user decides which to address.