Mapbox Cartography
Apply cartographic color, hierarchy, and typography rules when styling Mapbox maps for apps and customer-facing geospatial UIs.
Overview
Mapbox Cartography is an agent skill most often used in Build (also Launch distribution polish) that applies cartographic design principles for effective Mapbox map styles.
Install
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-cartographyWhat is this skill?
- Teaches visual hierarchy for POIs, routes, roads, and background terrain
- Covers analogous, complementary, and monochromatic color harmony for basemaps
- Maps color psychology defaults such as blue water and green parks
- Grounded in Mapbox style design and cartographic best practices
- Use when choosing colors, type, or style structure—not when wiring raw tile endpoints alone
- Four-tier visual hierarchy model from POIs through background terrain
Adoption & trust: 1k installs on skills.sh; 64 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Mapbox map looks cluttered or unreadable because layer contrast, color choices, and label hierarchy were guessed instead of designed.
Who is it for?
Indie builders styling custom Mapbox basemaps for navigation, logistics, or property apps before shipping to users.
Skip if: Backend-only geospatial ETL with no map UI, or teams that only need raw Mapbox API wiring without visual design decisions.
When should I use this skill?
Use when designing map styles, choosing colors, or making cartographic decisions with Mapbox.
What do I get? / Deliverables
You get concrete hierarchy and color guidance so Mapbox styles emphasize what users must see first and mute background geography.
- Documented hierarchy and color recommendations for a Mapbox style
- Cartographic rationale for contrast, typography, and landcover colors
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Map style decisions are made while implementing the map frontend—the canonical Build shelf—even though polish also matters at launch. Cartography for Mapbox styles is visual and interaction design on the map layer, which sits in frontend build work.
Where it fits
Pick a restrained palette for a clickable prototype map so stakeholders judge flows without neon clutter.
Establish POI and route contrast before locking Mapbox style JSON in the app repo.
Tune label weights and muted backgrounds for launch screenshots and embeddable marketing maps.
How it compares
Cartographic design doctrine for Mapbox—not a tile server DevOps skill or a general GIS analysis package.
Common Questions / FAQ
Who is mapbox-cartography for?
Solo builders and designers implementing Mapbox-powered maps who want agent-backed cartographic judgment on colors, type, and hierarchy.
When should I use mapbox-cartography?
Use it in Build while defining Mapbox styles; reuse at Launch when polishing customer-facing map branding and contrast for marketing screenshots or embedded maps.
Is mapbox-cartography safe to install?
It is design guidance with no inherent shell access—review the Security Audits panel on this page like any third-party skill before trusting agent suggestions in production repos.
SKILL.md
READMESKILL.md - Mapbox Cartography
# Mapbox Cartography Skill This skill provides expert cartographic knowledge to help you design effective, beautiful, and functional maps using Mapbox. ## Core Cartographic Principles ### Visual Hierarchy Maps must guide the viewer's attention to what matters most: - **Most important**: POIs, user location, route highlights - **Secondary**: Major roads, city labels, landmarks - **Tertiary**: Minor streets, administrative boundaries - **Background**: Water, land use, terrain **Implementation:** - Use size, color intensity, and contrast to establish hierarchy - Primary features: high contrast, larger symbols, bold colors - Background features: low contrast, muted colors, smaller text ### Color Theory for Maps **Color Harmony:** - **Analogous colors**: Use colors next to each other on color wheel (blue-green-teal) for cohesive designs - **Complementary colors**: Use opposite colors (blue/orange, red/green) for high contrast emphasis - **Monochromatic**: Single hue with varying saturation/brightness for elegant, minimal designs **Color Psychology:** - **Blue**: Water, trust, calm, professional (default for water bodies) - **Green**: Parks, nature, growth, eco-friendly (vegetation, parks) - **Red/Orange**: Urgent, important, dining (alerts, restaurants) - **Yellow**: Caution, highlight, attention (warnings, selected items) - **Gray**: Neutral, background, roads (infrastructure) **Accessibility:** - Ensure 4.5:1 contrast ratio for text (WCAG AA) - Don't rely solely on color to convey information - Test designs with colorblind simulators - Avoid red/green combinations for critical distinctions **Color Palette Templates:** Light Theme (Day/Professional): ```json { "background": "#f5f5f5", "water": "#a0c8f0", "parks": "#d4e7c5", "roads": "#ffffff", "buildings": "#e0e0e0", "text": "#333333" } ``` Dark Theme (Night Mode): ```json { "background": "#1a1a1a", "water": "#0d47a1", "parks": "#2e7d32", "roads": "#3a3a3a", "buildings": "#2d2d2d", "text": "#ffffff" } ``` > **Road color rule for dark themes:** Roads must use neutral dark gray (`#3a3a3a`), visibly distinct from the background but not colored. Never style roads with amber, blue, or other hues — reserve color for app data layers (routes, markers). Colored base roads and colored data layers will compete visually. Local roads that blend into the background (`#1e1e1e` on `#1a1a1a`) create a "floating labels" problem where street names appear with no visible road beneath them. High Contrast (Accessibility): ```json { "background": "#000000", "water": "#0066ff", "parks": "#00ff00", "roads": "#ffffff", "buildings": "#808080", "text": "#ffffff" } ``` Vintage/Retro: ```json { "background": "#f4e8d0", "water": "#b8d4d4", "parks": "#c8d4a4", "roads": "#d4c4a8", "buildings": "#e4d4c4", "text": "#4a3828" } ``` ### Typography at Map Scale **Font Selection:** - **Sans-serif** (Roboto, Open Sans): Modern, clean, high legibility at small sizes - use for labels - **Serif** (Noto Serif): Traditional, formal - use sparingly for titles or historic maps - **Monospace**: Technical data, coordinates **Text Sizing:** ``` Place labels (cities, POIs): 11-14px Street labels: 9-11px Feature labels (parks): 10-12px Map title: 16-20px Attribution: 8-9px ``` **Label Placement:** - Point labels: Center or slightly offset (avoid overlap with symbol) - Line labels: Follow line curve, repeat for long features - Area labels: Center in polygon, sized appropriately - Prioritize: Major features get labels first, minor features labeled if space allows ### Zoom Level Strategy **Zoom 0-4** (World to Continent): - Major country boundaries - Ocean an