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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add maplibre/maplibre-agent-skills --skill maplibre-cartography技能说明
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-colorandtext-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; forglyphs, 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 type | Background | Recommended text color | Recommended halo |
|---|---|---|---|
| Light vector (streets, OpenFreeMap positron) | Pale/white | Dark (#333 or similar) | Light semi-transparent (rgba(255,255,255,0.8)) |
| Dark vector (dark-matter, navigation night) | Dark | White 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 rooftops | White (#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:
| Context | text-halo-width |
|---|---|
| Body labels (city, town, village) | 0.8–1.5 |
| Country / continent (large text) | 1.5–2.0 |
| Small POI or peak labels | 0.8–1.2 |
| Water / park labels with colored text | 1.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