Overview
Theme files define the color palette and visual style for map posters. They are JSON files stored in thethemes/ directory and must end with a .json extension.
Schema Definition
File Location
themes/terracotta.json, themes/noir.json
Required Fields
All theme files must include the following fields:string
required
Display name of the theme (e.g., “Terracotta”, “Neon Cyberpunk”)
string
required
Short description of the theme’s aesthetic and color palette
string
required
Background color in hex format (e.g., “#F5EDE4”)Used for the poster background and empty space around the map.
string
required
Text color in hex format (e.g., “#8B4513”)Used for city name, country name, coordinates, and attribution text.
string
required
Color for gradient fade effects in hex formatApplied at top and bottom of the map to create smooth transitions. Typically matches the background color.
string
required
Water feature color in hex format (e.g., “#A8C4C4”)Used for rivers, lakes, bays, straits, and other water bodies.
string
required
Parks and green spaces color in hex format (e.g., “#E8E0D0”)Used for parks, grass areas, and other leisure/green spaces.
Road Hierarchy Colors
Themes use a hierarchical color system for different road types, from major highways to small residential streets:string
required
Motorway and highway color in hex formatApplied to:
- motorway
- motorway_link
string
required
Primary road color in hex formatApplied to:
- trunk
- trunk_link
- primary
- primary_link
string
required
Secondary road color in hex formatApplied to:
- secondary
- secondary_link
string
required
Tertiary road color in hex formatApplied to:
- tertiary
- tertiary_link
string
required
Residential street color in hex formatApplied to:
- residential
- living_street
- unclassified
string
required
Default road color in hex formatFallback color for any road types not covered by the above categories.
Complete Example
Design Guidelines
Color Relationships
Background & Text
Ensure sufficient contrast between
bg and text for readability. The text appears at the bottom of the poster with city name, country, and coordinates.Road Hierarchy
Use a gradual color progression from
road_motorway (boldest) to road_residential (subtlest) to create visual hierarchy and depth.Water & Parks
These should be distinguishable from both the background and roads while complementing the overall color scheme.
Gradients
The
gradient_color typically matches bg to create seamless fade effects at the top and bottom of the map.Theme Styles
Common theme approaches:- Monochromatic: Single hue with varying lightness (e.g., Blueprint, Midnight Blue)
- Analogous: Adjacent colors on the color wheel (e.g., Terracotta, Warm Beige)
- Complementary: Opposite colors for high contrast (e.g., Neon Cyberpunk)
- Natural: Earth tones and organic colors (e.g., Forest, Autumn)
- Technical: High contrast, geometric feel (e.g., Blueprint, Noir)
Validation
Color Format
All color fields must use 6-digit hex format with hash symbol:- Valid:
"#FF0000","#1A2B3C" - Invalid:
"FF0000","#FFF","red"
Required Fields
If any required field is missing, the theme will fail to load and fall back to the default terracotta theme.Loading Themes
Themes can be loaded in multiple ways:Built-in Themes
MapToPoster includes 17 built-in themes:- autumn
- blueprint
- contrast_zones
- copper_patina
- emerald
- forest
- gradient_roads
- japanese_ink
- midnight_blue
- monochrome_blue
- neon_cyberpunk
- noir
- ocean
- pastel_dream
- sunset
- terracotta (default)
- warm_beige