diff --git a/skills/mapbox-cartography/AGENTS.md b/skills/mapbox-cartography/AGENTS.md index 66b5e76..c53a05c 100644 --- a/skills/mapbox-cartography/AGENTS.md +++ b/skills/mapbox-cartography/AGENTS.md @@ -72,6 +72,30 @@ Quick reference for map design, color theory, visual hierarchy, and accessibilit - Areas: Inside polygon - Avoid label collisions (use `text-allow-overlap: false`) +### 5. Layer Order + +Bottom to top. Anything the user generated sits on top of the basemap, and POI +symbols sit below it — a route or marker the user is actively following must never +be occluded by basemap POIs. + +1. Background (solid color or pattern) +2. Landuse (parks, residential, commercial) +3. Water bodies (oceans, lakes, rivers) +4. Terrain/hillshade (if using elevation) +5. Buildings (3D or 2D footprints) +6. Roads (highways to local streets) +7. Borders (country, state lines) +8. Labels (place names, street names) +9. POI symbols +10. User-generated content (routes, markers) — topmost + +### 6. Feature Zoom Thresholds + +Mapbox's hosted Streets style shows most POIs around zoom 14. For custom styles, +**start POIs at zoom 12** — neighborhood scale, where density is manageable and +users are browsing. Zoom 14 is at the late end but acceptable; zoom 10 is +metro-area scale and far too early, producing severe icon clutter. + ## Color Best Practices ### Accessible Color Contrast diff --git a/skills/mapbox-style-patterns/AGENTS.md b/skills/mapbox-style-patterns/AGENTS.md index eedc78f..80b623c 100644 --- a/skills/mapbox-style-patterns/AGENTS.md +++ b/skills/mapbox-style-patterns/AGENTS.md @@ -233,21 +233,74 @@ map.addLayer({ }); ``` +**The base map matters as much as the fill.** Data colors need an uncontested +background, so pair a choropleth with a minimal grayscale base: + +- Grayscale palette throughout — never a standard streets or otherwise colorful style +- Gray/desaturated water, **not** blue: blue water competes directly with a red/blue + political choropleth +- Minimal road detail — major roads only at low zoom, or none at all +- Major city labels only for orientation, not the full POI and street label set + ### Route Visualization +A route needs **two** layers: a wider casing behind, and a narrower colored line on +top. A single line has no contrast against roads of a similar color, and reads as +just another street. + ```javascript +// Casing first (wider, darker) so it renders behind +map.addLayer({ + id: 'route-casing', + type: 'line', + source: 'route', + paint: { 'line-color': '#0d47a1', 'line-width': 9 } +}); + map.addLayer({ id: 'route', type: 'line', source: 'route', - paint: { - 'line-color': '#0080ff', - 'line-width': 5, - 'line-opacity': 0.8 - } + paint: { 'line-color': '#0080ff', 'line-width': 5, 'line-opacity': 0.8 } }); ``` +### Delivery Zones by Status + +Zones carry a status, so the fill must be data-driven. A single static `fill-color` +across all zones throws away the information the user needs. + +```javascript +'fill-color': [ + 'match', ['get', 'status'], + 'available', '#4caf50', + 'busy', '#ff9800', + 'unavailable', '#f44336', + '#9e9e9e' // fallback +] +``` + +### Pulsing Marker (Active Delivery / Live Location) + +Drive a second circle layer beneath the marker with `requestAnimationFrame`, +updating paint properties each frame — there is no built-in pulse. + +```javascript +function pulseCustomerMarker() { + const duration = 2000; + const start = performance.now(); + + function animate(time) { + const phase = ((time - start) % duration) / duration; + map.setPaintProperty('customer-pulse', 'circle-radius', 12 + phase * 12); + map.setPaintProperty('customer-pulse', 'circle-opacity', 0.3 * (1 - phase)); + requestAnimationFrame(animate); + } + + requestAnimationFrame(animate); +} +``` + ### 3D Buildings ```javascript diff --git a/skills/mapbox-style-quality/AGENTS.md b/skills/mapbox-style-quality/AGENTS.md index ced9c02..9ce75d2 100644 --- a/skills/mapbox-style-quality/AGENTS.md +++ b/skills/mapbox-style-quality/AGENTS.md @@ -2,6 +2,41 @@ Quick reference for style validation, accessibility, performance optimization, and testing. +## Validation Tools + +These MCP tools do the work described in this guide — reach for them rather than +eyeballing a style or relying on generic web validators. + +| Tool | Use it for | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `validate_geojson_tool` | Validate external GeoJSON **before** adding it as a source — catches invalid coordinates, unclosed rings, wrong coordinate order | +| `validate_expression_tool` | Validate expressions as you write them, during development, so type mismatches never reach runtime | +| `check_color_contrast_tool` | Check foreground/background contrast for text layers against WCAG AA (4.5:1 normal, 3:1 large) | +| `compare_styles_tool` | Diff a style against the previous production version to surface unintended changes | +| `optimize_style_tool` | Reduce style size before deploying | + +**Pre-deploy order:** validate GeoJSON sources → validate expressions → check label +contrast → compare against the previous production style → optimize → review the +report (`percentReduction`, `changes`) and test before shipping. + +**What `optimize_style_tool` does, in order:** removes unused sources left behind by +deleted layers, eliminates duplicate layers with identical paint properties, +simplifies redundant boolean expressions in filters (collapsing `["all", expr]` to +`expr`, dropping tautological conditions), then removes empty layers as a final +cleanup step. + +**Automate it.** Catching expression and contrast errors by hand is a losing game — +wire validation into a pre-commit hook and CI so a broken expression cannot reach +production: + +``` +1. Validate all expressions +2. Check accessibility compliance +3. Run optimization (warn if significant savings) +4. Compare with the production version +5. Generate a quality report +``` + ## Style Validation Rules ### Required Elements @@ -295,11 +330,13 @@ if (!map.getSource('source')) { **Validation:** +- `validate_geojson_tool`, `validate_expression_tool`, `compare_styles_tool`, + `optimize_style_tool` (see [Validation Tools](#validation-tools)) - Mapbox Style Specification: -- JSON Schema validators **Accessibility:** +- `check_color_contrast_tool` for WCAG AA/AAA checks on label layers - WebAIM Contrast Checker - Coblis Color Blindness Simulator - WAVE Accessibility Evaluation Tool