Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/originalankur/maptoposter/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Theme files define the color palette and visual style for map posters. They are JSON files stored in the themes/ directory and must end with a .json extension.

​
Schema Definition

​
File Location

themes/{theme_name}.json
Example: themes/terracotta.json, themes/noir.json

​
Required Fields

All theme files must include the following fields:
​
name
string
required
Display name of the theme (e.g., “Terracotta”, “Neon Cyberpunk”)
​
description
string
required
Short description of the theme’s aesthetic and color palette
​
bg
string
required
Background color in hex format (e.g., “#F5EDE4”)Used for the poster background and empty space around the map.
​
text
string
required
Text color in hex format (e.g., “#8B4513”)Used for city name, country name, coordinates, and attribution text.
​
gradient_color
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.
​
water
string
required
Water feature color in hex format (e.g., “#A8C4C4”)Used for rivers, lakes, bays, straits, and other water bodies.
​
parks
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:
​
road_motorway
string
required
Motorway and highway color in hex formatApplied to:
  • motorway
  • motorway_link
Typically the boldest/brightest road color.
​
road_primary
string
required
Primary road color in hex formatApplied to:
  • trunk
  • trunk_link
  • primary
  • primary_link
Major roads connecting cities and regions.
​
road_secondary
string
required
Secondary road color in hex formatApplied to:
  • secondary
  • secondary_link
Important roads within cities.
​
road_tertiary
string
required
Tertiary road color in hex formatApplied to:
  • tertiary
  • tertiary_link
Local connector roads.
​
road_residential
string
required
Residential street color in hex formatApplied to:
  • residential
  • living_street
  • unclassified
Neighborhood streets and local roads.
​
road_default
string
required
Default road color in hex formatFallback color for any road types not covered by the above categories.

​
Complete Example

{
  "name": "Terracotta",
  "description": "Mediterranean warmth - burnt orange and clay tones on cream",
  "bg": "#F5EDE4",
  "text": "#8B4513",
  "gradient_color": "#F5EDE4",
  "water": "#A8C4C4",
  "parks": "#E8E0D0",
  "road_motorway": "#A0522D",
  "road_primary": "#B8653A",
  "road_secondary": "#C9846A",
  "road_tertiary": "#D9A08A",
  "road_residential": "#E5C4B0",
  "road_default": "#D9A08A"
}

​
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: 
from create_map_poster import load_theme

theme = load_theme("noir")
print(theme["name"])  # "Noir"
print(theme["bg"])    # "#1C1C1C"

​
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
All themes follow this exact schema structure.

Build docs developers (and LLMs) love

Get started for freeTalk to us