mapbox-ops
/mapbox-ops
Mapbox GL JS v3 (web) toolkit: custom markers, symbol/geojson layers, clustering, style expressions, 3D terrain/fill-extrusion, heatmaps, choropleths, camera animation, and performance gotchas. Use for any Mapbox GL JS work — markers, layers, style, 3D, or headless map verification.
- Author
- 0xDarkMatter ↗
- Repository
- claude-mods ↗
- Licence
- MIT
- Last repository change
- 15.10.2026
Assessment and security
- Files in this package
- 22
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 4 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: assets/circular_image_marker.js, scripts/check-mapbox-facts.py, scripts/screenshot_map.py, tests/run.sh
What it does and when to use it
Mapbox GL JS v3 (web) toolkit: custom markers, symbol/geojson layers, clustering, style expressions, 3D terrain/fill-extrusion, heatmaps, choropleths, camera animation, and performance gotchas. Use for any Mapbox GL JS work — markers, layers, style, 3D, or headless map verification.
Original author description
Mapbox GL JS v3 (web) toolkit: custom markers, symbol/geojson layers, clustering, style expressions, 3D terrain/fill-extrusion, heatmaps, choropleths, camera animation, and performance gotchas. Use for any Mapbox GL JS work — markers, layers, style, 3D, or headless map verification.
How it works
- Setup invariants
- Pick the technique
- Bundled resources
- The three highest-value gotchas (full detail in the refs)
SKILL.md preview
---
name: mapbox-ops
description: "Mapbox GL JS v3 (web) toolkit: custom markers, symbol/geojson layers, clustering, style expressions, 3D terrain/fill-extrusion, heatmaps, choropleths, camera animation, and performance gotchas. Use for any Mapbox GL JS work — markers, layers, style, 3D, or headless map verification."
license: MIT
compatibility: "Web mapbox-gl-js v3.x. screenshot_map.py needs Python 3.10+ and Playwright (chromium); check-mapbox-facts.py is stdlib-only Python 3.10+."
metadata:
author: claude-mods
related-skills: "color-ops, screenshot, genart-ops, threejs-ops"
---
# Mapbox GL JS — advanced web toolkit (v3)
An advanced toolkit for building production Mapbox GL JS map experiences on the **web**:
markers, thematic dataviz, 3D, terrain, cinematic camera, style composition, performance,
and the hard-won gotchas that bite. Scope: **`mapbox-gl-js` v3.x in the browser** (CDN
`mapbox-gl-js/v3.x/`) — not the native iOS/Android SDKs (different APIs). Plain GL JS,
framework-agnostic. Several patterns were distilled from a production trail map; adapt the
constants to your own design.
## Setup invariants
- Set `mapboxgl.accessToken` before `new mapboxgl.Map(...)`.
- The map needs **`'load'`** before adding sources/layers/images. In a throttled
or background tab `'load'` can be missed — also bind `'idle'` as a one-shot
fallback guarded by an `_inited` flag (see [verification.md](references/verification.md)).
- Resolving token/style from `.env`: **read the token FIRST** (that triggers the
`.env` load), THEN read `MAPBOX_STYLE`. Reading the style before the token load
silently falls back to the default style. See [palette.md](references/palette.md).
- **Classic vs Standard style.** Several techniques here (basemap palette recolour,
the terrain boost-or-add `getStyle().layers` walk) assume a **classic** style
(Streets/Outdoors/Light/Dark `…-v12`). The v3 default **Standard** style has no
enumerable named layers — use slots + `setConfigProperty` instead. See
[v3-standard-style.md](references/v3-standard-style.md) before porting to Standard.
## Pick the technique
Read the matching reference file only when the task needs it:
| Task | Reference |
|------|-----------|
| Custom SVG/canvas markers, `addImage`/`updateImage`, namespacing, AA/fringing, circular image masks, anchoring | [references/markers.md](references/markers.md) |
| Dashed/cased trail lines, `line-dasharray` units, translucency over hillshade, colour-by-attribute, `line-gradient`/`lineMetrics` | [references/lines-and-trails.md](references/lines-and-trails.md) |
| Hillshade, dense contours, 3D terrain (`setTerrain`), boost-or-add an existing style's terrain | [references/terrain.md](references/terrain.md) |
| Symbol-layer text labels that never hide icons (`text-optional`), AllTrails-style placement | [references/labels.md](references/labels.md) |
| Recolour a base style's land/vegetation fills (palette shift / choropleth-style `match`) | [references/palette.md](references/palette.md) |
| Custom popups, circular photo cards, zoom-scaled offsets | [references/popups.md](references/popups.md) |
| Style expressions — `interpolate`/`step`/`match`/`case`, the **zoom-outermost** rule, `feature-state` in expressions | [references/expressions.md](references/expressions.md) |
| Hover/select via `feature-state` (not `setData`), `queryRenderedFeatures` caveats, clustering, GeoJSON perf, event hygiene | [references/interaction-and-performance.md](references/interaction-and-performance.md) |
| Data viz & 3D — `fill-extrusion` buildings/extruded data, heatmap layer, data-join choropleth (feature-state/`match`), proportional symbols, sky/fog | [references/dataviz-and-3d.md](references/dataviz-and-3d.md) |
| **three.js in the map** — `CustomLayerInterface` + shared GL context, animated 3D objects/models, the baked-matrix vs reconstructed-camera (Threebox `CameraSync`) fork, raycast picking, ENU-metre scene space, constant screen-size actors, terrain elevation, far-plane clipping at pitch | [references/three-custom-layer.md](references/three-custom-layer.md) |
| Camera & animation — `flyTo`/`easeTo`/`fitBounds` padding, `freeCameraOptions` cinematics/orbit, flight/first-person camera (bearing+pitch choreography; roll is MapLibre-only), animated day–night cycle (`setLights`), HUD synced to camera, point-along-line, draw-in lines, paint transitions, spinning globe, the `essential`/reduced-motion gotcha | [references/camera-and-animation.md](references/camera-and-animation.md) |
| Style library & composition — first-party style catalog, choosing a base by use case, custom/third-party styles, style switcher, light/dark, hand-rolled style JSON | [references/styles.md](references/styles.md) (+ [assets/style-catalog.json](assets/style-catalog.json)) |
| `setStyle` wiping custom layers, the 0×0 `resize()` bug, SPA teardown / WebGL-context cap, token security, readiness events | [references/lifecycle.md](references/lifecycle.md) |
| **v3 Standard style** — slots vs `beforeId`, `setConfigProperty`/`lightPreset`, why layer-walking (palette/terrain) breaks; localisation, RTL, globe | [references/v3-standard-style.md](references/v3-standard-style.md) |
| Headless screenshot + pixel-accurate marker-alignment checks (Playwright, `map.project`) | [references/verification.md](references/verification.md) |
## Bundled resources
- **Starter code** — [assets/circular_image_marker.js](assets/circular_image_marker.js):
copy into a page to register a circular photo marker (canvas → premultiplied
`ImageBitmap`, `destination-in` mask, contact + drop shadow). Browser-only snippet,
not a CLI — adapt the `frameColor`/box constants to your design.
- **Verifier script** — [scripts/screenshot_map.py](scripts/screenshot_map.py): drive
headless Chromium to screenshot a *served* map page, assert a marker projects to its
lng/lat, and surface console errors. Run it:
```bash
python -m http.server 8777 --directory <site-dir> & # serve the page
uv run --with playwright scripts/screenshot_map.py \
http://localhost:8777/preview/index.html out.png --expect 146.9 -36.1
# exit 0 = no console errors; 10 = errors found; 5 = playwright missing; 7 = map never ready
uv run --with playwright scripts/screenshot_map.py URL out.png --json | jq '.data'
```
- **Staleness verifier** — [scripts/check-mapbox-facts.py](scripts/check-mapbox-facts.py):
stdlib-only (no Playwright), guards the fast-moving facts this skill encodes
(SKILL-RESOURCE-PROTOCOL §7). `--offline` (default) asserts internal consistency —
the v3 Standard config enums (`lightPreset`/`theme`), terrain tileset IDs, the weather
(≥3.7) version gate, the no-native-camera-roll fact (roll is MapLibre GL JS v5, not
Mapbox), and every style URL/id in
[assets/style-catalog.json](assets/style-catalog.json). `--live` resolves the
third-party style URLs and probes whether Mapbox GL JS has shipped a major past v3.
```bash
python scripts/check-mapbox-facts.py --offline # exit 0 ok, 4 inconsistency
python scripts/check-mapbox-facts.py --live --json # exit 7 network, 10 drift
```
## The three highest-value gotchas (full detail in the refs)
1. **Namespace every `addImage` name** (e.g. `"rcpin-<glyph>"`). Mapbox styles ship
sprite icons literally named `parking`/`toilet`/etc — an un-namespaced
`hasImage()` returns `true` for those and your icon is **silently dropped**.
2. **Register icons as premultiplied `createImageBitmap()`**, not a raw
`HTMLImageElement`/`ImageData` — straight-alpha sources make Mapbox **fringe a
white halo** around anti-aliased edges. `updateImage(name, bmp)` recolours in place.
3. **Data-driven `icon-offset` is silently ignored in GL JS v3.** Use a *constant*
`icon-offset` (it scales with `icon-size`) or split markers into separate symbol
layers, each with its own constant anchor/offset.
Files in this package (22)
- SKILL.md 8 KB
- assets/.gitkeep 1 KB
- assets/circular_image_marker.js 5 KB
- assets/style-catalog.json 5 KB
- references/camera-and-animation.md 8 KB
- references/dataviz-and-3d.md 6 KB
- references/expressions.md 3 KB
- references/interaction-and-performance.md 3 KB
- references/labels.md 2 KB
- references/lifecycle.md 3 KB
- references/lines-and-trails.md 4 KB
- references/markers.md 7 KB
- references/palette.md 3 KB
- references/popups.md 2 KB
- references/styles.md 9 KB
- references/terrain.md 4 KB
- references/three-custom-layer.md 7 KB
- references/v3-standard-style.md 3 KB
- references/verification.md 2 KB
- scripts/check-mapbox-facts.py 16 KB
- scripts/screenshot_map.py 7 KB
- tests/run.sh 5 KB
Versions
The database has no other skills named mapbox-ops.
Database snapshot: 13.11.2026 · package version 934b9ca639ce (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mapbox-gl-js
Use when building vector web maps with mapbox-gl 3.33.0 — WebGL rendering, Style Spec layers, data-driven expressions, setTerrain raster-dem, fill-extrusion, or debugging 401 'A valid Mapbox access token is required', 'Style is not done loading', and pk./sk. token handling.… - 100web-maps-mapbox
Mapbox GL JS interactive vector maps. Use when building a map with sources and layers, expressions, clustering, 3D terrain, geocoding or directions. - 100mapbox
Mapbox is a platform for interactive web maps, geocoding and routing; Mapbox GL JS (v3) renders the maps in the browser. Use when a user asks to create interactive maps, add custom layers, implement geocoding, build navigation features, or visualize geospatial data with Mapbox. - 100geojson-mapbox-spatial-analysis
Perform in-browser spatial analysis, GeoJSON feature processing, Turf.js geometric computations (buffers, convex hulls, Voronoi polygons, centroids), and Mapbox GL JS / MapLibre vector tile styling. Trigger when rendering interactive map layers, visualizing spatial datasets, or… - 100maplibre-mapbox-migration
Migrating from Mapbox GL JS to MapLibre GL JS — package and import changes, removing the access token, choosing tile sources, plugin equivalents, and what you gain or give up. Use when moving an existing Mapbox map to MapLibre. - 100maps-geolocation
Build location-based features with mapping APIs. Use when a user asks to integrate Google Maps, Mapbox, or Leaflet, implement geocoding and reverse geocoding, calculate routes and distances, build store locators, add interactive maps to web apps, implement geofencing, work with…