Choose, build and repair a palette
Choosing
Match the request, in this order of preference:
- The user named a palette or a game. Use it.
palette op="preset"for a bundled one,op="load"for a file they have, orreference op="sample_palette"to pull one out of a screenshot they gave you. - 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.
- The sprite is joining an existing project.
sprite_infoan existing asset and match it exactly. Consistency beats a nicer palette. - 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.
Building ramps
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.
Repairing a sprawled palette
Symptom: validate reports off-palette colours, or the sprite has ninety
near-identical browns.
-
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.
-
Decide the target palette. Either the existing one, minus the near-duplicates, or a fresh one.
-
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.
-
Re-check.
palette op="analyze"again, thenlook 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.
Contrast
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.
Related
rules://01-palette-and-color, rules://02-shading-and-light,
rules://20-color-for-pixel-art, rules://21-limited-and-platform-palettes.


