# Visual Audit

> Use when performing structured visual design critique of an interface. Covers hierarchy, contrast, spacing, typography, color, and component consistency with actionable fix recommendations. Do not use for design token architecture (use design-system-architecture) or animation specifications (use motion-design).

- **Type:** Skill
- **Install:** `agentstack add skill-dtsong-my-claude-setup-visual-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dtsong](https://agentstack.voostack.com/s/dtsong)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dtsong](https://github.com/dtsong)
- **Source:** https://github.com/dtsong/my-claude-setup/tree/main/skills/council/artisan/visual-audit

## Install

```sh
agentstack add skill-dtsong-my-claude-setup-visual-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Visual Audit

## Purpose

Perform a structured visual design critique of an interface, producing specific actionable feedback on hierarchy, contrast, spacing, typography, color, and overall coherence.

## Scope Constraints

Reads screenshots, mockups, or live implementation for visual analysis. Does not modify source code or design files. Does not generate new designs or components.

## Inputs

- Screenshots, mockups, or live implementation of the interface
- Design system or style guide (if it exists)
- Target context (marketing page, app dashboard, settings screen, etc.)
- Accessibility requirements (WCAG AA, AAA, or custom)

## Input Sanitization

No user-provided values are used in commands or file paths. All inputs are treated as read-only analysis targets.

## Procedure

### Progress Checklist
- [ ] Step 1: Squint test
- [ ] Step 2: Hierarchy audit
- [ ] Step 3: Typography audit
- [ ] Step 4: Color and contrast audit
- [ ] Step 5: Spacing and alignment audit
- [ ] Step 6: Component consistency audit

### Step 1: Squint Test

View the interface at arm's length (or blur it mentally). Identify:
- What's the loudest element? Is it the right one?
- Can you identify the primary action within 3 seconds?
- Is there a clear visual reading order?
- Are there any areas of visual "soup" (too much competing for attention)?

### Step 2: Hierarchy Audit

Check the information hierarchy:
- **Heading levels:** Are there clear H1 → H2 → H3 distinctions via size and weight?
- **Primary vs secondary actions:** Is the primary action visually dominant (filled button) vs secondary (ghost/outline)?
- **Content grouping:** Are related items visually grouped (proximity) and distinct groups separated (spacing)?
- **Emphasis distribution:** Is anything fighting for attention that shouldn't be?

### Step 3: Typography Audit

Check the type system:
- **Scale consistency:** Are font sizes from a defined scale (not arbitrary)?
- **Line height:** Is body text at 1.4-1.6x line height for readability?
- **Measure:** Are line lengths between 45-75 characters for body text?
- **Weight usage:** Is font weight used semantically (bold for emphasis, not decoration)?
- **Font pairing:** Are typefaces intentionally paired (one serif + one sans, or a single family)?

### Step 4: Color and Contrast Audit

Check color usage:
- **Contrast ratios:** All text meets WCAG AA (4.5:1 normal text, 3:1 large text)
- **Color meaning:** Color is not the sole indicator of status (add icons, text, patterns)
- **Palette coherence:** Colors come from a defined palette, not ad-hoc hex values
- **Dark mode:** If supported, contrast ratios are verified in dark mode too
- **Saturation balance:** No oversaturated elements that vibrate or strain eyes

### Step 5: Spacing and Alignment Audit

Check spatial consistency:
- **Grid adherence:** Elements align to a defined grid (4px, 8px base)
- **Consistent spacing:** Same-level items use the same spacing value
- **Breathing room:** Content doesn't feel cramped; whitespace is used intentionally
- **Alignment lines:** Elements that should align actually align (check left edges, baselines)

### Step 6: Component Consistency Audit

Check for visual consistency:
- **Button styles:** All buttons of the same type look the same
- **Card patterns:** Cards share border radius, shadow, padding
- **Icon style:** Icons are from one set (outlined, filled, or mixed intentionally)
- **Form elements:** Inputs, selects, and textareas share a visual language

> **Compaction resilience**: If context was lost during a long session, re-read the Inputs section to reconstruct what interface is being audited, check the Progress Checklist for completed steps, then resume from the earliest incomplete step.

## Output Format

```markdown
# Visual Audit Report

## Overall Assessment
**Score:** [1-10]
**Summary:** [2-3 sentences on the interface's visual effectiveness]

## Squint Test Results
- **Primary focus:** [What draws the eye first — is this correct?]
- **Reading order:** [Clear / Unclear / Competing elements]
- **Visual noise:** [Low / Medium / High]

## Findings

### [CRITICAL] [Category] — [Finding]
**Current:** [What's happening now]
**Issue:** [Why it's a problem — cite specific principle]
**Fix:** [Specific change — exact values where possible]

### [IMPROVEMENT] [Category] — [Finding]
**Current:** [What's happening now]
**Suggestion:** [Specific improvement with rationale]

## Contrast Report
| Element | Foreground | Background | Ratio | Pass AA |
|---------|-----------|------------|-------|---------|
| Body text | #333 | #fff | 12.6:1 | Yes |
| Muted text | #999 | #fff | 2.8:1 | NO |

## Quick Wins
1. [Change that would have the biggest visual impact for the least effort]
2. [Second quick win]
3. [Third quick win]
```

## Handoff

- Hand off to design-system-architecture if audit reveals inconsistent or missing design tokens across the interface.
- Hand off to motion-design if audit identifies state transitions or feedback interactions lacking animation specs.

## Quality Checks

- [ ] Every finding includes a specific fix, not just a problem description
- [ ] Contrast ratios are calculated with actual color values
- [ ] Typography findings reference a type scale or specific sizes
- [ ] Spacing findings reference a grid system or specific values
- [ ] At least 3 quick wins are identified with effort-to-impact prioritization
- [ ] Dark mode contrast is checked if dark mode is supported

## Evolution Notes

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dtsong](https://github.com/dtsong)
- **Source:** [dtsong/my-claude-setup](https://github.com/dtsong/my-claude-setup)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dtsong-my-claude-setup-visual-audit
- Seller: https://agentstack.voostack.com/s/dtsong
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.