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: