Mapbox Style Patterns

---

name: mapbox-style-patterns description: Common style patterns, layer configurations, and recipes for typical mapping scenarios including restaurant finders, real estate, data visualization, navigation, delivery/logistics, and more. Use when implementing specific map use cases or looking for proven style patterns.

---

Mapbox Style Patterns Skill

This skill provides battle-tested style patterns and layer configurations for common mapping scenarios.

Pattern Library

Pattern 1: Restaurant/POI Finder

Use case: Consumer app showing restaurants, cafes, bars, or other points of interest

Visual requirements:

POIs must be immediately visible

Street context for navigation

Neutral background (photos/content overlay)

Mobile-optimized

Recommended layers:

{
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {
        "background-color": "#f5f5f5"
      }
    },
    {
      "id": "water",
      "type": "fill",
      "source": "mapbox-streets",
      "source-layer": "water",
      "paint": {
        "fill-color": "#d4e4f7",
        "fill-opacity": 0.6
      }
    },
    {
      "id": "landuse-parks",
      "type": "fill",
      "source": "mapbox-streets",
      "source-layer": "landuse",
      "filter": ["==", "class", "park"],
      "paint": {
        "fill-color": "#e8f5e8",
        "fill-opacity": 0.5
      }
    },
    {
      "id": "roads-minor",
      "type": "line",
      "source": "mapbox-streets",
      "source-layer": "road",
      "filter": ["in", "class", "street", "street_limited"],
      "paint": {
        "line-color": "#e0e0e0",
        "line-width": {
          "base": 1.5,
          "stops": [
            [12, 0.5],
            [15, 2],
            [18, 6]
          ]
        }
      }
    },
    {
      "id": "roads-major",
      "type": "line",
      "source": "mapbox-streets",
      "source-layer": "road",
      "filter": ["in", "class", "primary", "secondary", "tertiary"],
      "paint": {
        "line-color": "#ffffff",
        "line-width": {
          "base": 1.5,
          "stops": [
            [10, 1],
            [15, 4],
            [18, 12]
          ]
        }
      }
    },
    {
      "id": "restaurant-markers",
      "type": "symbol",
      "source": "restaurants",
      "layout": {
        "icon-image": "restaurant-15",
        "icon-size": 1.5,
        "icon-allow-overlap": false,
        "text-field": ["get", "name"],
        "text-offset": [0, 1.5],
        "text-size": 12,
        "text-allow-overlap": false
      },
      "paint": {
        "icon-color": "#FF6B35",
        "text-color": "#333333",
        "text-halo-color": "#ffffff",
        "text-halo-width": 2
      }
    }
  ]
}

Key features:

Desaturated base map (doesn't compete with photos)

High-contrast markers (#FF6B35 orange stands out)

Clear road network (white on light gray)

Parks visible but subtle

Text halos for readability

Pattern Selection Guide

Decision Tree

Question 1: What is the primary content?

User-generated markers/pins -> POI Finder Pattern

Property data/boundaries -> Real Estate Pattern

Statistical/analytical data -> Data Visualization Pattern

Routes/directions -> Navigation Pattern

Real-time tracking/delivery zones -> Delivery/Logistics Pattern (customer markers should include a pulse animation via second circle layer + requestAnimationFrame + setPaintProperty; see references/delivery-logistics.md)

Question 2: What is the viewing environment?

Daytime/office -> Light theme

Night/dark environment -> Dark Mode Pattern

Variable -> Provide theme toggle

Question 3: What is the user's primary action?

Browse/explore -> Focus on POIs, rich detail

Navigate -> Focus on roads, route visibility

Track delivery/logistics -> Real-time updates, zones, status

Analyze data -> Minimize base map, maximize data

Select location -> Clear boundaries, context

Question 4: What is the platform?

Mobile -> Simplified, larger touch targets, less detail

Desktop -> Can include more detail and complexity

Both -> Design mobile-first, enhance for desktop

Layer Optimization Patterns

Performance Pattern: Simplified by Zoom

{
  "id": "roads",
  "type": "line",
  "source": "mapbox-streets",
  "source-layer": "road",
  "filter": [
    "step",
    ["zoom"],
    ["in", "class", "motorway", "trunk"],
    8,
    ["in", "class", "motorway", "trunk", "primary"],
    12,
    ["in", "class", "motorway", "trunk", "primary", "secondary"],
    14,
    true
  ],
  "paint": {
    "line-width": {
      "base": 1.5,
      "stops": [
        [4, 0.5],
        [10, 1],
        [15, 4],
        [18, 12]
      ]
    }
  }
}

Reference Files

Additional patterns and configurations are available in the references/ directory. Load the relevant file when a specific pattern is needed.

| File | Contents | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | references/real-estate.md | Pattern 2: Real Estate Map -- property boundaries, price color-coding, amenity markers | | references/data-viz-base.md | Pattern 3: Data Visualization Base Map -- minimal grayscale base for choropleth/heatmap overlays | | references/navigation.md | Pattern 4: Navigation/Routing Map -- route display, user location, turn arrows | | references/dark-mode.md | Pattern 5: Dark Mode / Night Theme -- near-black background, reduced brightness | | references/delivery-logistics.md | Pattern 6: Delivery/Logistics Map -- real-time tracking, zones, driver markers, ETA badges | | references/expressions-clustering.md | Data-driven expression patterns + clustering for dense POIs | | references/common-modifications.md | 3D Buildings, Terrain/Hillshade, Custom Markers |

Loading instructions: Read the reference file that matches the user's use case. For example, if implementing a delivery tracking map, load references/delivery-logistics.md.

Testing Patterns

Visual Regression Checklist

[ ] Test at zoom levels: 4, 8, 12, 16, 20

[ ] Verify on mobile (375px width)

[ ] Verify on desktop (1920px width)

[ ] Test with dense data

[ ] Test with sparse data

[ ] Check label collision

[ ] Verify color contrast (WCAG)

[ ] Test loading performance

When to Use This Skill

Invoke this skill when:

Starting a new map style for a specific use case

Looking for layer configuration examples

Implementing common mapping patterns

Optimizing existing styles

Need proven recipes for typical scenarios

Debugging style issues

Learning Mapbox style best practices