mapbox-style-patterns
π―Skillfrom mapbox/mapbox-agent-skills
|Provides curated Mapbox style patterns and layer configurations for implementing common mapping use cases like restaurant finders, real estate, and data visualization.
Part of
mapbox/mapbox-agent-skills(9 items)
Installation
npx add-skill mapbox/mapbox-agent-skillsnpx add-skill mapbox/mapbox-agent-skills --skill mapbox-web-performance-patternsnpx add-skill mapbox/mapbox-agent-skills --listnpx add-skill mapbox/mapbox-agent-skills -a cursornpx add-skill mapbox/mapbox-agent-skills -a vscode+ 2 more commands
Skill Details
Common style patterns, layer configurations, and recipes for typical mapping scenarios including restaurant finders, real estate, data visualization, navigation, and more. Use when implementing specific map use cases or looking for proven style patterns.
Overview
# 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:
```json
{
"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 2: Real Estate Map
Use case: Property search, neighborhood exploration, real estate listings
Visual requirements:
- Property boundaries clear
- Neighborhood context visible
- Amenities highlighted (schools, parks, transit)
- Price/property data display
Recommended layers:
```json
{
"layers": [
{
"id": "background",
"type": "background",
"paint": {
"background-color": "#fafafa"
}
},
{
"id": "parks-green-spaces",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "landuse",
"filter": ["in", "class", "park", "pitch", "playground"],
"paint": {
"fill-color": "#7cb342",
"fill-opacity": 0.3
}
},
{
"id": "water",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "water",
"paint": {
"fill-color": "#42a5f5",
"fill-opacity": 0.4
}
},
{
"id": "roads",
"type": "line",
"source": "mapbox-streets",
"source-layer": "road",
"paint": {
"line-color": "#e0e0e0",
"line-width": {
"base": 1.2,
"stops": [
[10, 0.5],
[15, 2],
[18, 6]
]
}
}
},
{
"id": "property-boundaries",
"type": "line",
"source": "properties",
"paint": {
"line-color": "#7e57c2",
"line-width": 2,
"line-opacity": 0.8
}
},
{
"id": "property-fills",
"type": "fill",
"source": "properties",
"paint": {
"fill-color": [
"interpolate",
["linear"],
["get", "price"],
200000,
"#4caf50",
500000,
"#ffc107",
1000000,
"#f44336"
],
"fill-opacity": 0.3
}
},
{
"id": "school-icons",
"type": "symbol",
"source": "composite",
"source-layer": "poi_label",
"filter": ["==", "class", "school"],
"layout": {
"icon-image": "school-15",
"icon-size": 1.2
},
"paint": {
"icon-opacity": 0.8
}
},
{
"id": "transit-stops",
"type": "circle",
"source": "transit",
"paint": {
"circle-radius": 6,
"circle-color": "#2196f3",
"circle-stroke-color": "#ffffff",
"circle-stroke-width": 2
}
}
]
}
```
Key features:
- Properties color-coded by price (greenβyellowβred)
- Parks prominently visible (important for home buyers)
- Schools and transit clearly marked
- Property boundaries visible
- Clean, professional aesthetic
Pattern 3: Data Visualization Base Map
Use case: Choropleth maps, heatmaps, data overlays, analytics dashboards
Visual requirements:
- Minimal base map (data is the focus)
- Context without distraction
- Works with various data overlay colors
- High contrast optional for dark data
Recommended layers:
```json
{
"layers": [
{
"id": "background",
"type": "background",
"paint": {
"background-color": "#f0f0f0"
}
},
{
"id": "water",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "water",
"paint": {
"fill-color": "#d8d8d8",
"fill-opacity": 0.5
}
},
{
"id": "admin-boundaries",
"type": "line",
"source": "mapbox-streets",
"source-layer": "admin",
"filter": ["in", "admin_level", 0, 1, 2],
"paint": {
"line-color": "#999999",
"line-width": {
"base": 1,
"stops": [
[0, 0.5],
[10, 1],
[15, 2]
]
},
"line-dasharray": [3, 2]
}
},
{
"id": "roads-major-simplified",
"type": "line",
"source": "mapbox-streets",
"source-layer": "road",
"filter": ["in", "class", "motorway", "primary"],
"minzoom": 6,
"paint": {
"line-color": "#cccccc",
"line-width": {
"base": 1.2,
"stops": [
[6, 0.5],
[10, 1],
[15, 2]
]
},
"line-opacity": 0.5
}
},
{
"id": "place-labels-major",
"type": "symbol",
"source": "mapbox-streets",
"source-layer": "place_label",
"filter": ["in", "type", "city", "capital"],
"layout": {
"text-field": ["get", "name"],
"text-size": {
"base": 1,
"stops": [
[4, 10],
[10, 14]
]
},
"text-font": ["Open Sans Semibold"]
},
"paint": {
"text-color": "#666666",
"text-halo-color": "#ffffff",
"text-halo-width": 2
}
}
]
}
```
Key features:
- Grayscale palette (doesn't interfere with data colors)
- Minimal detail (roads, borders only)
- Major cities labeled for orientation
- Low opacity throughout
- Perfect for overlay data
Pattern 4: Navigation/Routing Map
Use case: Turn-by-turn directions, route planning, delivery apps
Visual requirements:
- Route highly visible
- Current location always clear
- Turn points obvious
- Street names readable
- Performance optimized
Recommended layers:
```json
{
"layers": [
{
"id": "background",
"type": "background",
"paint": {
"background-color": "#ffffff"
}
},
{
"id": "water",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "water",
"paint": {
"fill-color": "#a8d8ea"
}
},
{
"id": "landuse",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "landuse",
"paint": {
"fill-color": [
"match",
["get", "class"],
"park",
"#d4edda",
"hospital",
"#f8d7da",
"school",
"#fff3cd",
"#e9ecef"
],
"fill-opacity": 0.5
}
},
{
"id": "roads-background",
"type": "line",
"source": "mapbox-streets",
"source-layer": "road",
"paint": {
"line-color": "#333333",
"line-width": {
"base": 1.5,
"stops": [
[10, 2],
[15, 8],
[18, 20]
]
},
"line-opacity": 0.3
}
},
{
"id": "roads-foreground",
"type": "line",
"source": "mapbox-streets",
"source-layer": "road",
"paint": {
"line-color": "#ffffff",
"line-width": {
"base": 1.5,
"stops": [
[10, 1],
[15, 6],
[18, 16]
]
}
}
},
{
"id": "route-casing",
"type": "line",
"source": "route",
"paint": {
"line-color": "#0d47a1",
"line-width": {
"base": 1.5,
"stops": [
[10, 8],
[15, 16],
[18, 32]
]
},
"line-opacity": 0.4
}
},
{
"id": "route-line",
"type": "line",
"source": "route",
"paint": {
"line-color": "#2196f3",
"line-width": {
"base": 1.5,
"stops": [
[10, 6],
[15, 12],
[18, 24]
]
}
}
},
{
"id": "user-location",
"type": "circle",
"source": "user-location",
"paint": {
"circle-radius": 8,
"circle-color": "#2196f3",
"circle-stroke-color": "#ffffff",
"circle-stroke-width": 3
}
},
{
"id": "user-location-pulse",
"type": "circle",
"source": "user-location",
"paint": {
"circle-radius": {
"base": 1,
"stops": [
[0, 16],
[1, 24]
]
},
"circle-color": "#2196f3",
"circle-opacity": {
"base": 1,
"stops": [
[0, 0.4],
[1, 0]
]
}
}
},
{
"id": "turn-arrows",
"type": "symbol",
"source": "route-maneuvers",
"layout": {
"icon-image": ["get", "arrow-type"],
"icon-size": 1.5,
"icon-rotation-alignment": "map",
"icon-rotate": ["get", "bearing"]
}
}
]
}
```
Key features:
- Thick, high-contrast route (blue on white)
- Pulsing user location indicator
- Turn arrows at maneuver points
- Simplified background (focus on route)
- Color-coded land use for context
Pattern 5: Dark Mode / Night Theme
Use case: Reduced eye strain, night use, modern aesthetic, battery saving (OLED)
Visual requirements:
- Dark background
- Reduced brightness
- Maintained contrast
- Readable text
- Comfortable viewing
Recommended layers:
```json
{
"layers": [
{
"id": "background",
"type": "background",
"paint": {
"background-color": "#0a0a0a"
}
},
{
"id": "water",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "water",
"paint": {
"fill-color": "#1a237e",
"fill-opacity": 0.5
}
},
{
"id": "parks",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "landuse",
"filter": ["==", "class", "park"],
"paint": {
"fill-color": "#1b5e20",
"fill-opacity": 0.4
}
},
{
"id": "buildings",
"type": "fill",
"source": "mapbox-streets",
"source-layer": "building",
"paint": {
"fill-color": "#1a1a1a",
"fill-opacity": 0.8,
"fill-outline-color": "#2a2a2a"
}
},
{
"id": "roads-minor",
"type": "line",
"source": "mapbox-streets",
"source-layer": "road",
"filter": ["in", "class", "street", "street_limited"],
"paint": {
"line-color": "#2a2a2a",
"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", "motorway"],
"paint": {
"line-color": "#3a3a3a",
"line-width": {
"base": 1.5,
"stops": [
[10, 1],
[15, 4],
[18, 12]
]
}
}
},
{
"id": "labels",
"type": "symbol",
"source": "mapbox-streets",
"source-layer": "place_label",
"layout": {
"text-field": ["get", "name"],
"text-size": 12
},
"paint": {
"text-color": "#e0e0e0",
"text-halo-color": "#0a0a0a",
"text-halo-width": 2
}
}
]
}
```
Key features:
- Very dark background (#0a0a0a near-black)
- Subtle color differentiation (deep blues, greens)
- Light text (#e0e0e0) with dark halos
- Reduced opacity throughout
- Easy on eyes in low light
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
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
- 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
```json
{
"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]
]
}
}
}
```
Expression Pattern: Data-Driven Styling
```json
{
"paint": {
"circle-radius": [
"interpolate",
["linear"],
["get", "population"],
0,
3,
1000,
5,
10000,
8,
100000,
12,
1000000,
20
],
"circle-color": [
"case",
["<", ["get", "temperature"], 0],
"#2196f3",
["<", ["get", "temperature"], 20],
"#4caf50",
["<", ["get", "temperature"], 30],
"#ffc107",
"#f44336"
]
}
}
```
Clustering Pattern: Handle Dense POIs
```json
{
"id": "clusters",
"type": "circle",
"source": "pois",
"filter": ["has", "point_count"],
"paint": {
"circle-color": [
"step",
["get", "point_count"],
"#51bbd6", 10,
"#f1f075", 30,
"#f28cb1"
],
"circle-radius": [
"step",
["get", "point_count"],
15, 10,
20, 30,
25
]
}
},
{
"id": "cluster-count",
"type": "symbol",
"source": "pois",
"filter": ["has", "point_count"],
"layout": {
"text-field": ["get", "point_count_abbreviated"],
"text-size": 12
}
}
```
Common Modifications
Add 3D Buildings
```json
{
"id": "3d-buildings",
"type": "fill-extrusion",
"source": "composite",
"source-layer": "building",
"minzoom": 15,
"paint": {
"fill-extrusion-color": "#aaa",
"fill-extrusion-height": [
"interpolate",
["linear"],
["zoom"],
15,
0,
15.05,
["get", "height"]
],
"fill-extrusion-base": [
"interpolate",
["linear"],
["zoom"],
15,
0,
15.05,
["get", "min_height"]
],
"fill-extrusion-opacity": 0.6
}
}
```
Add Terrain/Hillshade
```json
{
"sources": {
"mapbox-dem": {
"type": "raster-dem",
"url": "mapbox://mapbox.mapbox-terrain-dem-v1"
}
},
"layers": [
{
"id": "hillshade",
"type": "hillshade",
"source": "mapbox-dem",
"paint": {
"hillshade-exaggeration": 0.5,
"hillshade-shadow-color": "#000000"
}
}
],
"terrain": {
"source": "mapbox-dem",
"exaggeration": 1.5
}
}
```
Add Custom Markers
```json
{
"id": "custom-markers",
"type": "symbol",
"source": "markers",
"layout": {
"icon-image": "custom-marker",
"icon-size": 0.8,
"icon-anchor": "bottom",
"icon-allow-overlap": true,
"text-field": ["get", "name"],
"text-offset": [0, -2],
"text-anchor": "top",
"text-size": 12
},
"paint": {
"text-color": "#ffffff",
"text-halo-color": "#000000",
"text-halo-width": 2
}
}
```
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
More from this repository8
Optimizes Mapbox web applications by eliminating initialization waterfalls, reducing load times, and improving rendering performance across data loading and map rendering.
Provides official, production-ready integration patterns for embedding Mapbox GL JS across web frameworks with best practices and setup guidance.
Validates and optimizes Mapbox styles by checking expressions, accessibility, data integrity, and performance before production deployment.
Secures Mapbox access tokens by implementing granular scope management, URL restrictions, and token rotation strategies across different environments.
Guides map designers in creating visually compelling and accessible Mapbox maps using expert cartographic principles, color theory, and typography best practices.
Provides robust, lifecycle-aware Mapbox Maps SDK integration patterns for Android using Kotlin and Jetpack Compose.
Enables seamless Mapbox Maps SDK integration in iOS apps using Swift, SwiftUI, and UIKit with best practices for lifecycle management and performance.
Helps developers seamlessly migrate from Google Maps Platform to Mapbox GL JS by providing comprehensive API translation, styling patterns, and migration strategies.