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, sourcing and self-hosting icons, and ordering style layers correctly. For font/glyph setup, see maplibre-fonts-glyphs.

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 sprite for a custom or self-hosted style (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
• Route shields render as bare numbers or missing badges
• 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: