mapbox-style-patterns

by mapbox

Battle-tested Mapbox style patterns and layer configurations for six common mapping scenarios. Includes ready-to-use JSON layer configurations for restaurant finders, real estate, data visualization, navigation, dark mode, and delivery/logistics maps Provides decision tree for selecting the right pattern based on content type, environment, user action, and platform Covers performance optimization techniques including zoom-based filtering, data-driven styling, and clustering for dense POIs... npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-style-patterns Download ZIPGitHub68

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