pixel-art-studio

# Pixel Art Studio

Programmatic pixel art creation with palette discipline, dithering, animation, and automated quality control. Designed for **production-quality output**, not "look-pixelated filter on a photo."

## When to use this skill

| User says | What to do |
|---|---|
| "make a pixel art X" / "create a sprite" | [Static sprite workflow](#workflow-1-single-frame-sprite) |
| "animate this", "walk cycle", "idle animation" | [Animation workflow](#workflow-2-animation) |
| "convert this image to pixel art", "pixelate this" | [Preprocessing workflow](#workflow-3-image-to-pixel-art) |
| "generate sprite sheet" | [Sprite sheet workflow](#workflow-4-sprite-sheet) |
| "review this pixel art / score it" | [Quality review workflow](#workflow-5-quality-review) |
| "show palette options" / "use Endesga 64" | [Palette browsing](#palette-management) |

If user provides only a vague description ("a cat sprite"), pick the **standard sprite workflow** with **32×32 + Endesga 32 palette** as the safe default, then offer to iterate.

---

## Prerequisites

```bash
pip install Pillow numpy
# Optional but recommended for advanced quality checks:
pip install scikit-image scipy
```

`Pillow` is **mandatory**; `numpy` is mandatory; the rest are optional (the scripts will degrade gracefully).

---

## Core principle: design discipline > pixel quantity

A 16×16 sprite with deliberate cluster choices reads better than a 64×64 with random pixel noise. **Always start from the smallest grid that conveys the subject**, expand only when needed for detail.

The four pillars of quality (encoded in `scripts/quality_check.py`):

1. **Per-pixel hygiene** — no orphan single pixels, no parallel doublies, no banded ramps
2. **Cluster coherence** — pixel groups read as recognizable shapes, not noise
3. **Palette discipline** — limited (≤32 typically), with hue rotation across luminance ramp
4. **Silhouette readability** — render-as-solid-shape and verify subject is recognizable

When in doubt, run `quality_check.py` after generation and fix issues until score ≥ 80/100.

---

## Workflow 1: Single-frame sprite

### Step 1 — Pick canvas size

| Subject complexity | Canvas | Examples |
|---|---|---|
| Icon / glyph | 8×8 | heart, key, arrow, smiley |
| Simple sprite | 16×16 | NES character, item, tile |
| **Standard sprite** ⭐ | **32×32** | indie character, animal, prop |
| Detailed character | 48×48 - 64×64 | hi-bit hero, boss, building |
| Mobile RPG humanoid (CN/KR) | 48×72 | 8-direction walking character |
| Hero / portrait | 96×96 - 128×128 | promotional art, big boss |

When user is vague: **32×32**.

### Step 2 — Pick palette

Three modes:
- **Bundled palette** (recommended): Use `scripts/palette.py --list` to enumerate. Default for vague subjects: **Endesga 32**.
- **Style-anchored palette**: subject-specific recommendations in `references/02-palette-theory.md`
- **Custom palette**: 4-16 hex colors curated by hand. Validate with palette ramp checker.

Common style → palette mapping:
| User intent | Palette |
|---|---|
| Generic, modern indie | `endesga-32` or `endesga-64` |
| 8-bit retro / Famicom feel | `nes` or `pico-8` |
| Mono / GameBoy DMG | `gameboy-dmg` |
| Soft pastel / cute | `sweetie-16` |
| Atmospheric / cinematic | `apollo` or `slso8` |
| Industrial / cool | `steam-lords` |
| Chinese xianxia / palace | `gugong-red-wall` or `qinghua` |
| Korean traditional | `obangsaek` (5-color) |
| Dark fantasy (Stoneshard-style) | `stoneshard-inspired` |

### Step 3 — Design layer-by-layer

**Always think in this order, not free-form:**

1. **Silhouette** (darkest color, just outline) — does shape read at intended size?
2. **Base fill** — primary 1-2 colors covering largest areas
3. **Cell shading** — pick **3-4 discrete shades**, place them per a single light direction (default: top-left)
4. **Hue shift** — shadows shift **cooler+desaturated** (toward blue-violet); highlights **warmer+saturated** (toward yellow-orange). Hue rotation across ramp ≥ 30°
5. **Selective AA** — only on staircase patterns longer than 1×1, using intermediate-color halftone strip
6. **Details** — eyes, patterns, small features. Each pixel must belong to a cluster ≥ 2-3 pixels (no orphans)

**NEVER do pillow shading**: dark border + light center regardless of light source. Auto-detected as anti-pattern in `quality_check.py`.

### Step 4 — Generate JSON

Use the [Sparse Coordinate JSON format](references/08-json-schema.md). Minimal example:

```json
{
  "width": 16,
  "height": 16,
  "background": "transparent",
  "pixel_size": 16,
  "palette_ref": "endesga-32",
  "pixels": [
    {"x": 7, "y": 4, "color": "#a8ca58"},
    ...
  ]
}
```

For **animation**, use the multi-frame extended schema (`frames` array — see Workflow 2).

### Step 5 — Render PNG

```bash
python ${CLAUDE_PLUGIN_ROOT}/skills/creative/pixel-art-studio/scripts/render.py \
  sprite.json -o sprite.png
```

### Step 6 — Quality check

```bash
python ${CLAUDE_PLUGIN_ROOT}/skills/creative/pixel-art-studio/scripts/quality_check.py sprite.png
```

Output is JSON. **Score ≥ 80** = ship. Score 60-80 = fix issues listed. Score < 60 = redesign.

### Step 7 — Display + iterate

Read the PNG with the Read tool to show user. Offer fixes for any quality issues flagged.

---

## Workflow 2: Animation

### Frame counts (production-validated)

Pick from this table — do NOT improvise frame counts.

| Animation | Min | **Standard** ⭐ | Premium | FPS |
|---|---|---|---|---|
| Idle (breathing) | 2 | **4** | 6-8 | 6 |
| Walk | 4 (Celeste) | **6** (Shovel Knight) | 8-12 | 8 |
| Run | 6 | **8** | 10 | 10 |
| Attack | 3 | **5** | 6-8 | 10-12 |
| Death | 4 | **6-8** | 10+ | 8-10 |
| Hit reaction | 1 | **2-3** | — | 10 |

Cultural variations:
- **Western indie**: 8-12 fps standard
- **Chinese mobile RPG**: 4-frame walk @ 200ms (5 fps) is documented standard
- **Korean dot mobile**: 6 frames @ 8-12 fps; chibi 4-frame walk
- **Russian indie**: typically follows Western, sometimes "Punch Club rule" (draw 1×, r