mapbox-style-quality_skill

This skill helps you validate, optimize, and ensure Mapbox style quality with automated tooling and accessibility checks for production readiness.

JavaScript

10

GitHub Stars

2

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill mapbox/mapbox-agent-skills --skill mapbox-style-quality

AGENTS.md6.3 KB
SKILL.md11.5 KB

Overview

This skill provides expert guidance and actionable checks to validate, optimize, and ensure quality of Mapbox styles. It focuses on expression and GeoJSON validation, accessibility (color contrast) checks, style optimization, and style comparison workflows. Use it to catch runtime errors, improve performance, and meet accessibility standards before production.

How this skill works

The skill inspects style JSON, layer expressions, and declared data sources to identify syntax errors, type mismatches, invalid GeoJSON, and accessibility issues. It runs a configurable optimization pass to remove unused sources, duplicate or empty layers, and simplify expressions while producing a clear report of changes. It can also diff two style versions to highlight meaningful changes such as layer, source, and expression edits.

When to use it

Before deploying a style to production to validate and optimize final output
During development when adding GeoJSON sources or editing expressions
When auditing accessibility for label readability and WCAG compliance
While debugging runtime expression errors or rendering issues
Before merging feature branches to review unintended changes

Best practices

Validate expressions and GeoJSON early (in-editor or CI) to avoid runtime failures
Aim for WCAG AA contrast for normal text; consider AAA for critical UI elements
Run optimizations after refactors: remove unused sources, duplicates, then simplify expressions
Compare styles with metadata ignored to focus on meaningful diffs
Review optimization reports and test the optimized style before deployment

Example use cases

Pre-production pipeline: validate expressions, check contrast, optimize style, then deploy
Troubleshooting: diff a working style against a broken one to locate the offending change
Refactor cleanup: remove duplicate and empty layers after reorganizing styles
User-upload safety: validate external GeoJSON before adding it as a source
CI/CD checks: fail builds on invalid expressions or serious accessibility regressions

FAQ

It reduces redundant expression constructs (e.g., converts ["all", true] to true) to speed evaluation and reduce size.

How do I validate GeoJSON before adding it as a source?

Run a GeoJSON validation step that checks coordinate ranges, polygon ring closure, required properties, and correct coordinate order ([longitude, latitude]).

Should I always remove empty layers automatically?

Remove empty layers except for intentional background layers; review removal reports before applying to avoid deleting placeholders you still need.