Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

maplibre-cartography

Cartographic principles for MapLibre GL JS — label and symbol legibility on imagery vs. vector basemaps, figure-ground for point icons, styling vector roads over aerial imagery, visual hierarchy, layer ordering for data injection, and accessibility. Use when styling a map, choosing text or symbol colors, making markers or roads readable on satellite/aerial imagery, or ordering layers correctly.

maplibre · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add maplibre/maplibre-agent-skills --skill maplibre-cartography

About this skill


name: maplibre-cartography description: Cartographic principles for MapLibre GL JS — label and symbol legibility on imagery vs. vector basemaps, figure-ground for point icons, styling vector roads over aerial imagery, visual hierarchy, layer ordering for data injection, and accessibility. Use when styling a map, choosing text or symbol colors, making markers or roads readable on satellite/aerial imagery, or ordering layers correctly. metadata: status: verified

MapLibre Cartography

MapLibre renders exactly what you describe in your style. This skill covers how to describe it well: choosing label colors for readability on any basemap, building a coherent visual hierarchy, and ordering style layers correctly. For font/glyph setup, see maplibre-fonts-glyphs; for sprites, icon sourcing, and route shields, see maplibre-sprites-icons.

When to Use This Skill

  • Reviewing a style against cartographic best practices before it ships
  • Choosing label text-color and text-halo-color, or point symbol/icon colors, for a new or migrated style — including cases where they read fine on a flat vector basemap but disappear or camouflage once the basemap is imagery
  • Setting up or debugging sprite, icons, or route shields — see maplibre-sprites-icons; for glyphs, see maplibre-fonts-glyphs
  • Injecting your own data layers into an existing basemap without covering labels
  • Restyling roads from a light-basemap vector palette so they sit in (not on top of) imagery
  • Auditing a style for contrast accessibility

Basemap Type Determines Label Colors

MapLibre places labels dynamically, so you cannot mask the background behind each label as you would on a static map. Instead, choose a text-halo-color that separates the label from every background it might land on, and a text-color that reads against the halo. On a single uniform basemap tone (flat light or dark vector), the halo can match that tone instead of contrasting it — the text itself does the contrasting against the basemap. Imagery has no single tone to match, so there the halo must contrast every possible background instead:

Basemap typeBackgroundRecommended text colorRecommended halo
Light vector (streets, OpenFreeMap positron)Pale/whiteDark (#333 or similar)Light semi-transparent (rgba(255,255,255,0.8))
Dark vector (dark-matter, navigation night)DarkWhite or near-white (#ffffff)Dark semi-transparent (rgba(0,0,0,0.75))
Satellite or aerial imagery (NAIP, Sentinel-2)Unpredictable — bright crops, dark forests, urban rooftopsWhite (#ffffff)Dark semi-transparent (rgba(0,0,0,0.75))

The most common mistake is a white halo with no transparency: unless the background is pure white, it disrupts the spatial connection between the label and the feature it labels — add transparency. The second is reusing a light-vector palette over imagery, where it fails on dark terrain, forests, and water. On imagery, always use white text and a dark semi-transparent halo ("text-color": "#ffffff", "text-halo-color": "rgba(0,0,0,0.75)", "text-halo-width": 1.2).

For tinted labels (parks, water, POIs), use a light tint of the semantic color (#c8f5cc parks, #a8d8ff water) rather than the dark saturated version: tints read against dark halos while keeping semantic meaning, where full-saturation colors contrast poorly at small sizes.

Halo width

Wider halos increase legibility but add visual weight. Typical values:

Contexttext-halo-width
Body labels (city, town, village)0.8–1.5
Country / continent (large text)1.5–2.0
Small POI or peak labels0.8–1.2
Water / park labels with colored text1.0–1.5

text-halo-width is in pixels relative to the text. The halo must not bleed into adjacent labels: keep it tight at small text sizes and add transparency.

Point Symbols and Icons on Imagery

Markers face the same figure-ground problem as labels, but with different tools. A colored icon on aerial imagery competes with an unpredictable, busy, desaturated photographic background.

  • You cannot separate a symbol from a background that owns its hue. A green icon over green parkland, a brown icon over bare soil: both camouflage. Most aerial imagery is low-saturation, so the axis the background is weakest on is chroma. A saturated fill (amber, terracotta) separates while still reading as a natural, earthy color. Shifting hue alone, toward a different earth tone, does not help if that hue is also in the scene.
  • Carve the symbol out with icon-halo-color/icon-halo-width, exactly as you would halo a label — this only affects SDF sprite images (addImage(..., { sdf: true }) or a sprite built as SDF); a full-color raster icon has no halo paint property, so any edge treatment on it has to be baked into the artwork itself. A thin light halo reads against dark canopy and water; a darker edge holds against bright soil and rooftops. Keep it thin — a fat ring reads as a sticker — except for the one class of symbol meant to dominate the map (an emergency marker, the single most important thematic feature), where a heavier ring is the point.
  • Flat fills read as stickers on a photo. Give la
Read the complete source ↗