Add mapbox-data-visualization-patterns skill

[mattpodwysocki]

Summary

Adds comprehensive data visualization skill covering choropleth maps, heat maps, 3D extrusions, bubble maps, line visualization, and animated data patterns.

What's Included

SKILL.md - Comprehensive data visualization guide covering:

• Visualization Types - Choropleth, heat maps, 3D extrusions, bubble maps, line visualization
• Data-Driven Styling - Mapbox expressions (interpolate, step, match, case)
• Color Scales - Accessible ColorBrewer scales with examples
• Animation - Time-series animation and real-time data updates
• Performance - Vector tiles, feature state, filtering, progressive loading
• Legends & UI - Interactive controls and data inspectors
• Best Practices - Color accessibility, data preprocessing, error handling
• Common Use Cases - Elections, COVID tracking, real estate, traffic

AGENTS.md - Compressed quick reference (2-4KB) with:

• Visualization type decision matrix
• Code patterns for all viz types
• Performance guidelines
• Color scale examples
• Quick decision guide

Visualization Type Decision Matrix

Data Type	Visualization	Layer Type	Use For
Regional/Polygons	Choropleth	fill	Statistics, demographics, elections
Point Density	Heat Map	heatmap	Crime, events, incident clustering
Point Magnitude	Bubble/Circle	circle	Earthquakes, sales, metrics
3D Data	Extrusions	fill-extrusion	Buildings, elevation, volume
Flow/Network	Lines	line	Traffic, routes, connections

Patterns Covered

Choropleth Maps

• Linear interpolation for continuous scales
• Step intervals for discrete buckets
• Case-based for categorical data
• Interactive hover effects
• Color accessibility considerations

Heat Maps

• Density visualization with intensity weighting
• Zoom-based radius and opacity
• Smooth transitions between zoom levels
• Individual points at high zoom

Bubble Maps

• Exponential scaling for magnitude
• Color coding by additional dimensions
• Stroke styling for clarity
• Interactive popups with data

3D Extrusions

• Height-based visualization
• Base height for terrain
• Color gradients by height or data
• Pitch and bearing controls

Line Visualization

• Width by traffic/flow volume
• Color by speed/congestion
• Opacity and styling options

Animated Data

• Time-series with playback controls
• Real-time updates via WebSocket/polling
• Smooth property transitions
• Performance-optimized updates

Performance Techniques

Data Size Guidelines:

• < 1 MB: GeoJSON direct load
• 1-10 MB: Consider vector tiles

• 10 MB: Vector tiles required

Optimization Patterns:

• Feature state for hover/selection (no geometry updates)
• Client-side filtering (no data reloading)
• Progressive loading (viewport-based)
• Debounced updates for smooth UX

Color Accessibility

Includes ColorBrewer scales:

• Sequential (single hue)
• Diverging (two hues)
• Qualitative (distinct categories)
• Color-blind friendly alternatives

Common Use Cases

Complete examples for:

• Election results maps
• COVID-19 case tracking
• Real estate price visualization
• Traffic flow analysis
• Weather data
• Sales territory analysis

Testing

• SKILL.md includes comprehensive patterns for all visualization types
• AGENTS.md is concise and actionable
• Code examples are complete and tested
• Covers choropleth, heat maps, 3D, bubbles, lines
• Includes animation and performance patterns
• Accessibility considerations included
• Updated README.md and skills/README.md
• Follows existing skill standards

---

Part of tutorial-based skills series (3 of 3). Completes the set with navigation patterns and store locator patterns.

[AndrewSepic]

I've made some small suggestions/requests. Outside of that, the only thing I think that is missing here is Clustering for point density visualization. Clustering is not just about performance improvements, but is also a valuable point density visualization. Generally when Heatmaps are used, clustering is also a viable visualization technique.

This would probably just mention clustering as a client side technique (visualization purposes only) and not go into server side clustering/tilesets etc..

[AndrewSepic]

This idea is a little bit dated, and incomplete. The most likely use case is to extrude polygons from the buildings layer of the basemap. This example shows how you would do that IF you happened to have a your own data source or if you extracted the basemap building layer into a buildings source (not shown). I think it would be better if we used the snippet from https://docs.mapbox.com/mapbox-gl-js/example/3d-buildings/

As the source code here and preface it with a Note that this only works in 'classic' styles, (streets-v12, dark-v11, light-v11` etc.. And 3d Buildings with much greater detail are available by default in the Mapbox Standard style.

[AndrewSepic]

It could be worth mentioning that all the code snippets below use Style expressions to style the feature based on property data of the feature.

 ['get', 'value'], // value or your custom property within feature.properties

We never demonstrate what the feature data looks like.. and this may be helpful

 {
      "type": "Feature",
      "geometry": {
        "coordinates": [
          -77.0323,
          38.9131
        ],
        "type": "Point"
      },
      "properties": {
        "magnitude": 7.8
      }

 ['get', 'magnitude'],

[mattpodwysocki]

All review comments have been addressed:

✅ Added Clustering - Added comprehensive clustering section as a point density visualization technique alongside heat maps, including:

• Client-side clustering implementation with code examples
• Cluster styling by point count
• Click to expand functionality
• Custom cluster properties (sum, max aggregations)
• Comparison table: clustering vs heatmaps

✅ Feature Data Structure - Added "Data Structure" section explaining:

• How GeoJSON features are structured
• How ['get', 'property'] expressions access feature properties
• Example feature with properties

✅ 3D Buildings Update - Updated 3D buildings example to:

• Use basemap buildings from composite source
• Insert layer beneath symbol layers for proper ordering
• Add note about classic styles only (Standard style has 3D buildings by default)
• Keep custom data example for reference

✅ Feature State sourceLayer - Fixed feature state example to:

• Show both GeoJSON source (no sourceLayer needed)
• Show vector source (sourceLayer required)
• Clear distinction between the two cases

✅ Bubble Map Color - Already using magnitude for both radius and color

All changes validated and tests passing. Ready for re-review! 🚀

[AndrewSepic]

Looks good! Thanks @mattpodwysocki