Mapbox 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",

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", 

Reference Files

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

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

• Not done: Test at zoom levels: 4, 8, 12, 16, 20
• Not done: Verify on mobile (375px width)
• Not done: Verify on desktop (1920px width)
• Not done: Test with dense data
• Not done: Test with sparse data
• Not done: Check label collision
• Not done: Verify color contrast (WCAG)
• Not done: 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