visual-audit

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, dashboard.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
grep -rn --include='*.html' --include='*.css' -E 'text-\[(9|10|11)px\]|font-size:\s*(9|10|11)px' 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/