---
name: visual-checklist
description: Review any image or video frame against the @iris visual-studies checklist — 9 gravity / framing / motion / palette / type / brand criteria. Auto-fills tech facts (format, dimensions, dominant palette, brightness/contrast histogram, edge density) and emits a structured markdown report with PASS / REVIEW / FAIL per category. Built by @iris (GIR Studios Visual Studies Director) — the "would Gualo ship this?" check, scriptable. Drop in a path, get a one-page review you can paste back to the creator.
---


# 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

```bash
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.