mapbox-style-quality

Mapbox Style Quality Skill

This skill provides expert guidance on ensuring Mapbox style quality through validation, accessibility, and optimization tools.

When to Use Quality Tools

Pre-Production Checklist

Before deploying any Mapbox style to production:

1. Validate all expressions - Catch syntax errors before runtime
2. Check color contrast - Ensure text is readable (WCAG compliance)
3. Validate GeoJSON sources - Ensure data integrity
4. Optimize style - Reduce file size and improve performance
5. Compare versions - Understand what changed
6. Remove empty layers - Delete layers with no visible paint properties as a final cleanup step
7. Simplify redundant boolean expressions - Clean up filters with unnecessary boolean logic (e.g., ["all", expr] → expr, ["any", false, expr] → expr)

During Development

When adding GeoJSON data:

• Always validate external GeoJSON with validate_geojson_tool before using as a source

When writing expressions:

• Validate expressions with validate_expression_tool as you write them
• Catch type mismatches early (e.g., using string operator on number)
• Verify operator availability in your Mapbox GL JS version
• Test expressions with expected data types

When styling text/labels:

• Check foreground/background contrast with check_color_contrast_tool
• Aim for WCAG AA minimum (4.5:1 for normal text, 3:1 for large text)
• Use AAA standard (7:1 for normal text) for better accessibility
• Consider different background scenarios (map tiles, overlays)

Before Committing Changes

Compare style versions:

• Use compare_styles_tool to generate a diff report
• Review all layer changes, source modifications, and expression updates
• Understand the impact of your changes
• Document significant changes in commit messages

Before Deployment

Optimize the style:

• Run optimize_style_tool to reduce file size
• Remove unused sources that reference deleted layers
• Eliminate duplicate layers with identical properties
• Simplify redundant boolean expressions in filters (e.g., collapse ["all", expr] to expr, remove tautological conditions)
• Remove empty layers (layers with no visible paint properties) as a final cleanup step