Choose, build and repair a palette

Match the request, in this order of preference:

1. The user named a palette or a game. Use it. palette op="preset" for a bundled one, op="load" for a file they have, or reference op="sample_palette" to pull one out of a screenshot they gave you.
2. The user described an era. "8-bit" → PICO-8. "Game Boy" → gameboy. "NES" → build 12–16 colours by hand as 3–4 hues × 4 values.
3. The sprite is joining an existing project. sprite_info an existing asset and match it exactly. Consistency beats a nicer palette.
4. Nothing said. PICO-8. It is 16 colours, forgiving, and reads well.

palette op="preset" with no valid preset lists what is bundled and says that anything else can be loaded from a file.

A ramp is one material's run of colours. Build them hue-shifted:

palette op="ramp" base="#c04030" steps=5 spread=0.55

Shadows come out cooler, highlights warmer — the thing that separates pixel art from a brightness slider. Three to five steps per material is plenty; more is decisions you will not use.

Reuse steps across materials. Sharing the darkest colour between skin and leather ties the sprite together and costs nothing.

Symptom: validate reports off-palette colours, or the sprite has ninety near-identical browns.

1. Diagnose:

   palette op="analyze"

   This reports off-palette colours in the art, near-duplicate palette entries (ΔE < 3 — the same colour to a viewer), unused slots and the lowest-contrast pair.

2. Decide the target palette. Either the existing one, minus the near-duplicates, or a fresh one.

3. Snap the art onto it:

   recolor op="snap" layer="…"

   Perceptual (CIELAB) nearest, applied per distinct colour in one pass. The result reports exactly which colour became which and how many pixels moved, so you can see whether a merge was wrong before the user does.

4. Re-check. palette op="analyze" again, then look op="preview". Merging two colours that were doing different jobs is the risk here; look for a form that has gone flat.

Or start over from the art: palette op="extract" replaces the palette with one quantized from the sprite's own colours (RGB sprites only, maxColors default 16) — useful when the sprite came from a reference image imported at full colour and never had a curated palette to snap onto.

Value contrast carries readability, not hue contrast. Check by running recolor op="desaturate" on a copy — if the shapes stop reading in greyscale, the palette's values are too close, and no amount of hue will fix it.

rules://01-palette-and-color, rules://02-shading-and-light, rules://20-color-for-pixel-art, rules://21-limited-and-platform-palettes.