mapbox-cartography

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

Typography Best Practices

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

Map Context Considerations

Know Your Audience:

• General public: Simplify, use familiar patterns (Google/Apple style)
• Technical users: Include more detail, technical layers, data precision
• Domain experts: Show specialized data, use domain-specific symbology

Use Case Optimization:

• Navigation: Emphasize roads, clear hierarchy, route visibility
• Data visualization: Muted base map, let data stand out
• Storytelling: Guide viewer attention, establish mood with colors
• Location selection: Show POIs clearly, provide context
• Analysis: Include relevant layers, maintain clarity at different zooms

Platform Considerations:

• Mobile: Larger touch targets (44x44px minimum), simpler designs, readable at arm's length
• Desktop: Can include more detail, hover interactions, complex overlays
• Print: Higher contrast, larger text, consider CMYK color space
• Outdoor/Bright: Higher contrast, avoid subtle grays

Style Layer Best Practices

Layer Ordering (bottom to top):

1. Background (solid color or pattern)
2. Landuse (parks, residential, commercial)
3. Water bodies (oceans, lakes, rivers)
4. Terrain/hillshade (if using elevation)
5. Buildings (3D or 2D footprints)
6. Roads (highways → local streets)
7. Borders (country, state lines)
8. Labels (place names, street names)
9. POI symbols
10. User-generated content (routes, markers)

Zoom Level Strategy

Zoom 0-4 (World to Continent):

• Major country boundaries
• Ocean and sea labels
• Capital cities only

Zoom 5-8 (Country to State):

• State/province boundaries
• Major cities
• Major highways
• Large water bodies

Zoom 9-11 (Metro Area):

• City boundaries
• Neighborhoods
• All highways and major roads
• Parks and landmarks

Zoom 12-15 (Neighborhood):

• All streets
• Building footprints
• POIs (restaurants, shops)
• Street names

Zoom 16-22 (Street Level):

• All detail
• House numbers
• Parking lots
• Fine-grained POIs

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"

}

```

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"

}

```

Scenario: Restaurant Finder App

Requirements:

• Restaurants must be highly visible
• Street context for navigation
• Muted background (food photos overlay)

Recommendations:

• Use bold, warm colors for restaurant markers (red, orange)
• Gray out background (low saturation)
• Keep street labels clear but not dominant
• High contrast for selected restaurant
• Mobile-optimized touch targets

Scenario: Real Estate Map

Requirements:

• Property boundaries clearly visible
• Neighborhood context
• Price differentiation

Recommendations:

• Use color scale for price ranges (green=affordable, red=expensive)
• Show parks and amenities prominently
• Include school zones if relevant
• Label neighborhoods clearly
• Show transit access

Scenario: Data Visualization Overlay

Requirements:

• Data layer is primary focus
• Base map provides context only
• Multiple data points may cluster

Recommendations:

• Monochromatic, low-contrast base map
• Use data-ink ratio principle (minimize non-data elements)
• Base map grayscale or single muted hue
• Remove unnecessary labels
• Consider using light base for dark data, vice versa

Scenario: Navigation/Routing

Requirements:

• Route must be unmissable
• Turn-by-turn clarity
• Current location always visible

Recommendations:

• Route in high-contrast color (blue or purple)
• Animate route line or use dashed pattern
• Large, clear turn indicators
• Dim unrelated features
• User location: pulsing blue dot
• Next turn: prominent arrow/icon

Style Performance:

• Minimize layer count (combine similar layers)
• Use expressions instead of multiple layers for variants
• Simplify complex geometries at lower zooms
• Use sprite sheets for repeated icons
• Leverage tileset simplification

Loading Speed:

• Preload critical zoom levels
• Use style optimization tools
• Minimize external resource calls
• Compress images in sprite sheets

Checklist:

• [ ] View at all relevant zoom levels
• [ ] Test in different lighting conditions
• [ ] Check on actual devices (mobile, desktop)
• [ ] Verify color accessibility (colorblind.org)
• [ ] Review with target users
• [ ] Test with real data density
• [ ] Check label collision/overlap
• [ ] Verify performance on slower devices

1. Too many colors: Stick to 5-7 main colors maximum
2. Insufficient contrast: Text must be readable
3. Overcrowding: Not everything needs a label
4. Ignoring zoom levels: Show appropriate detail for scale
5. Poor label hierarchy: Organize by importance
6. Inconsistent styling: Maintain visual consistency
7. Neglecting performance: Complex styles slow rendering
8. Forgetting mobile: Test on actual devices

Invoke this skill when:

• Designing a new map style
• Choosing colors for map elements
• Making decisions about visual hierarchy
• Optimizing for specific use cases
• Troubleshooting visibility issues
• Ensuring accessibility
• Creating themed maps (dark mode, vintage, etc.)