visual-checklist

The IRIS check, made shippable. Every visual that ships from the GIR Studios team passes through Visual Studies. This script puts the same 9-criteria review in your terminal — auto-fills the tech facts, leaves the judgment cells for you, and writes a clean markdown report.

Run

python3 ~/.claude/skills/visual-checklist/scripts/check.py path/to/asset.png
# → asset.review.md alongside the file

# or to stdout
python3 ~/.claude/skills/visual-checklist/scripts/check.py path/to/asset.jpg --stdout

# JSON for downstream consumers
python3 ~/.claude/skills/visual-checklist/scripts/check.py path/to/asset.png --json

Works on PNG / JPG / WEBP / first frame of MP4/MOV (via ffmpeg if available).

The 9 criteria

1. GRAVITY — does it pull the eye on first glance? auto: edge-density score
2. FRAMING — is the subject placed intentionally? auto: rule-of-thirds proximity of brightest region
3. CONTRAST — clear hierarchy? eye knows where to land first? auto: luma stddev
4. TYPE — if there's text, is the font Cyber-Glass-aligned (FuturisticArmour-ish)? manual
5. PALETTE — does color serve the message? auto: 5 dominant colors + saturation mean
6. MOTION — for video: intentional or just movement? auto: skip if static frame
7. EDGE — clean crops, intentional negative space? auto: edge-pixel-touch detection
8. NOVELTY — different aligned with direction, not stuck in the box? manual
9. BRAND — would Gualo ship this? manual

Auto rows render with PASS / REVIEW based on heuristic thresholds. Manual rows render as REVIEW so you fill them.

Output (markdown)

# visual-checklist · asset.png · 2026-04-25T07:00

**format** PNG · **dim** 1920×1080 · **bit-depth** 8 · **size** 412 KB

| # | Criterion | Verdict | Auto-evidence |
|---|---|---|---|
| 1 | GRAVITY | PASS | edge-density 0.18 (target ≥ 0.05) |
| 2 | FRAMING | REVIEW | brightest region 0.34, 0.51 — near rule-of-thirds intersect |
| 3 | CONTRAST | PASS | luma stddev 62 (target ≥ 28) |
| 4 | TYPE | REVIEW | manual — has text? font aligned? |
| 5 | PALETTE | PASS | 5 dominants: #0a0a0c, #f0f0f8, #00ff88, #1a1a1e, #78787f · sat-mean 0.42 |
| 6 | MOTION | n/a | static image |
| 7 | EDGE | PASS | edge-pixel-touch ratio 0.02 (target < 0.10) |
| 8 | NOVELTY | REVIEW | manual — what's the move? |
| 9 | BRAND | REVIEW | manual — would Gualo ship this? |

## IRIS NOTES (fill in)

- Gravity grade:
- Framing grade:
- Brand alignment:
- Recommended next move:

Origin

@iris — GIR Studios Visual Studies Director. The 9-criteria checklist comes from the team's "what makes visuals magnetically addictive" study. v0.1 · 2026-04-25.