Themes & Colors

Themes change the look of your pixel map. Colors, fill patterns, overlays. You write a small JSON file, upload it, and the map picks it up.

You don't need to fill in everything. Set what you care about, the rest falls back to HappyMaps defaults. A theme can be two lines long or fifty. Both work.

For a one-off color tweak you don't need a file at all. Flip on Advanced mode in the Configuration panel and edit inline, see Slicing and Advanced mode. This page covers the full version: themes you save, share, and reuse.

A small example

This is Sunset. Five palette slots, a dark canvas, and a checkerboard fill. Save it as a .json file, upload it in Studio, change a hex code, and you have your own look.

{
  "id": "sunset",
  "name": "Sunset",
  "schemaVersion": 1,
  "fillStyle": "duo-checkerboard",
  "palette": [
    {"primary": "#ff7a1a", "secondary": "#e85f00", "name": "Ember"},
    {"primary": "#ffd071", "name": "Peach"},
    {"primary": "#ff4d88", "name": "Flamingo"},
    {"primary": "#b44dff", "name": "Dusk"},
    {"primary": "#4d6dff", "name": "Twilight"}
  ],
  "panelBorder": "#2a1f16",
  "panelText": "#2a1f16",
  "infoBoxBorder": "#2a1f16",
  "infoBoxText": "#2a1f16",
  "canvasText": "#f4ede1",
  "canvasBackground": "#12080a",
  "infoBoxBackground": "#f4ede1",
  "overlays": {
    "cross": "#f4ede1",
    "plus": "#f4ede1",
    "circle": "#f4ede1",
    "tripleCircle": "#f4ede1"
  }
}

A machine-readable copy lives at /themes/example.json.

What you can change

Colors

A theme has two places to set colors.

On the theme itself, for things that apply once: canvas background, panel borders, info box text.
In the palette, for per-object fills. Each palette entry is a color slot you can assign to an object.

Palette slots have a primary color and optionally a secondary and tertiary. Skip the last two and HappyMaps derives them from primary, so duo and trio patterns still look sensible.

Fill styles

fillStyle sets the default pattern used when an object fills its panels.

solid, one color
duo-checkerboard, duo-row, duo-col, two colors
trio-checkerboard, trio-row, trio-col, three colors

Overlays

overlays controls the color of the optional shapes you can draw on top of objects: cross, plus, circle, triple circle. Each one is a hex color.

Built a theme you like? Send it my way at wouter@happymaps.co. No promises, but the good ones might end up in the built-in library for everyone to use :).

How colors resolve

Every color has a fallback chain. HappyMaps checks these in order, first one wins:

The object's own override
The palette slot assigned to that object
The theme's top-level value
The HappyMaps baseline theme
#ffffff

That's why a theme with one or two colors still produces a full-looking map. Everything else cascades.

Full reference

For when you want every field.

Top-level fields

Field	Type	Required	Notes
id	string	yes	Lowercase letters, numbers, dashes. 2 to 40 characters. Can't collide with a built-in theme.
name	string	yes	1 to 60 characters.
schemaVersion	integer	yes	Currently `1`.
fillStyle	enum	no	One of the seven fill styles above.
palette	array	no	Array of palette slots.
panelBorder	hex	no	Border around each panel.
infoBoxBorder	hex	no	Border around per-object info boxes.
panelText	hex	no	Text inside panels.
infoBoxText	hex	no	Text inside info boxes.
canvasText	hex	no	Project info and chrome. Theme-level only.
canvasBackground	hex	no	Canvas fill outside objects.
infoBoxBackground	hex	no	Background behind info-box text.
overlays	object	no	Keys: cross, plus, circle, tripleCircle. Each a hex color.

All colors are #RRGGBB hex. Extra keys are ignored, so newer files won't break older builds.

Palette slot

Each entry in palette is an object with:

primary, the main color
secondary, used by duo-* and trio-*. Auto-derived from primary if missing.
tertiary, used by trio-*. Auto-derived from primary if missing.
name, optional label shown in the slot picker.

Validation rules

id, name, and schemaVersion are required.
All color fields must be #RRGGBB hex.
fillStyle, if present, must be one of the seven values above.
Payload capped at 32 KB.