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:

Validate all expressions - Catch syntax errors before runtime
Check color contrast - Ensure text is readable (WCAG compliance)
Validate GeoJSON sources - Ensure data integrity
Optimize style - Reduce file size and improve performance
Compare versions - Understand what changed

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 boolean expressions for better performance
Remove empty layers that serve no purpose

Validation Best Practices

GeoJSON Validation

Always validate when:

Loading GeoJSON from user uploads
Fetching GeoJSON from external APIs
Processing GeoJSON from third-party sources
Converting between data formats

Common GeoJSON errors:

Invalid coordinate ranges (longitude > 180 or < -180)
Unclosed polygon rings (first and last coordinates must match)
Wrong coordinate order (should be [longitude, latitude], not [latitude, longitude])
Missing required properties (type, coordinates, geometry)
Invalid geometry types or nesting

Example workflow:

1. Receive GeoJSON data
2. Validate with validate_geojson_tool
3. If valid: Add as source to style
4. If invalid: Fix errors, re-validate

Expression Validation

Validate expressions for:

Filter conditions (
```
filter
```
property on layers)
Data-driven styling (
```
paint
```
and
```
layout
```
properties)
Feature state expressions
Dynamic property calculations

Common expression errors:

Type mismatches (string operators on numbers)
Invalid operator names or wrong syntax
Wrong number of arguments for operators
Nested expression errors
Using unavailable operators for your GL JS version

Prevention strategies:

Validate as you write expressions, not at runtime
Test expressions with representative data
Use type checking (expectedType parameter)
Validate in context (layer, filter, paint, layout)

Accessibility Validation

WCAG Levels:

AA (minimum): 4.5:1 for normal text, 3:1 for large text
AAA (enhanced): 7:1 for normal text, 4.5:1 for large text

Text size categories:

Normal: < 18pt or < 14pt bold
Large: ≥ 18pt or ≥ 14pt bold

Common scenarios to check:

Text labels on map tiles
POI labels with background colors
Custom markers with text
UI overlays on maps
Legend text and symbols
Attribution text

Testing strategy:

Test against both light and dark map tiles
Consider overlay backgrounds (popups, modals)
Test in different lighting conditions (mobile outdoor use)
Verify contrast at different zoom levels

Optimization Best Practices

When to Optimize

Before production deployment:

After all development changes are complete
After merging multiple feature branches
When style has grown significantly over time
Before major releases or launches

Benefits of optimization:

Faster initial load times
Reduced bandwidth usage
Better runtime performance
Cleaner, more maintainable code

Optimization Types

Remove unused sources:

Automatically identifies sources not referenced by any layer
Safe to remove without affecting functionality
Common after deleting layers or refactoring

Remove duplicate layers:

Finds layers with identical properties (excluding ID)
Can occur when copying/pasting layers
Reduces style complexity and file size

Simplify expressions:

Converts
```
["all", true]
```
→
```
true
```
Converts
```
["any", false]
```
→
```
false
```
Converts
```
["!", false]
```
→
```
true
```
Converts
```
["!", true]
```
→
```
false
```
Improves expression evaluation performance

Remove empty layers:

Removes layers with no paint or layout properties
Preserves background layers (valid even when empty)
Cleans up incomplete or placeholder layers

Consolidate filters:

Identifies groups of layers with identical filter expressions
Highlights opportunities for layer consolidation
Doesn't automatically consolidate (informational only)

Optimization Strategy

Recommended order:

Remove unused sources first (reduces noise for other checks)
Remove duplicate layers (eliminates redundancy)
Simplify expressions (improves readability and performance)
Remove empty layers (final cleanup)
Review consolidation opportunities (manual step)

Selective optimization:

// All optimizations (recommended for production)
optimize_style_tool({ style })

// Specific optimizations only
optimize_style_tool({
  style,
  optimizations: ['remove-unused-sources', 'simplify-expressions']
})

Review before deploying:

Check the optimization report
Verify size savings (percentReduction)
Review the list of changes (optimizations array)
Test the optimized style before deployment

Style Comparison Workflow

When to Compare Styles

Before merging changes:

Review what changed in your feature branch
Ensure no unintended modifications
Generate change summary for PR description

When investigating issues:

Compare working version vs. broken version
Identify what changed between versions
Narrow down root cause of problems

During migrations:

Compare old format vs. new format
Verify data integrity after conversion
Document transformation differences

Comparison Best Practices

Use ignoreMetadata flag:

// Ignore metadata differences (id, owner, created, modified)
compare_styles_tool({
  styleA: oldStyle,
  styleB: newStyle,
  ignoreMetadata: true
})

Focus on meaningful changes:

Layer additions/removals
Source changes
Expression modifications
Paint/layout property updates

Document significant changes:

Note breaking changes in documentation
Update style version numbers
Communicate changes to team/users

Quality Workflow Examples

Basic Quality Check

1. Validate expressions in style
2. Check color contrast for text layers
3. Optimize if needed

Full Pre-Production Workflow

1. Validate all GeoJSON sources
2. Validate all expressions (filters, paint, layout)
3. Check color contrast for all text layers
4. Compare with previous production version
5. Optimize style
6. Test optimized style
7. Deploy

Troubleshooting Workflow

1. Compare working vs. broken style
2. Identify differences
3. Validate suspicious expressions
4. Check GeoJSON data if source-related
5. Verify color contrast if visibility issue

Refactoring Workflow

1. Create backup of current style
2. Make refactoring changes
3. Compare before vs. after
4. Validate all modified expressions
5. Optimize to clean up
6. Review size impact

Common Issues and Solutions

Runtime Expression Errors

Problem: Map throws expression errors at runtime Solution: Validate expressions with

validate_expression_tool

during development Prevention: Add expression validation to pre-commit hooks or CI/CD

Poor Text Readability

Problem: Text labels are hard to read on map Solution: Check contrast with

check_color_contrast_tool

, adjust colors to meet WCAG AA Prevention: Test text on both light and dark backgrounds, check at different zoom levels

Large Style File Size

Problem: Style takes long to load or transfer Solution: Run

optimize_style_tool

to remove redundancies and simplify Prevention: Regularly optimize during development, remove unused sources immediately

Invalid GeoJSON Source

Problem: GeoJSON source fails to load or render Solution: Validate with

validate_geojson_tool

, fix coordinate issues, verify structure Prevention: Validate all external GeoJSON before adding to style

Unexpected Style Changes

Problem: Style changed but unsure what modified Solution: Use

compare_styles_tool

to generate diff report Prevention: Compare before/after for all significant changes, document modifications

Integration with Development Workflow

Git Pre-Commit Hook

bash

# Validate expressions before commit
npm run validate-style

# Optimize before commit (optional)
npm run optimize-style

CI/CD Pipeline

1. Validate all expressions
2. Check accessibility compliance
3. Run optimization (warning if significant savings)
4. Compare with production version
5. Generate quality report

Code Review Checklist

All expressions validated
Text contrast meets WCAG AA
GeoJSON sources validated
Style optimized for production
Changes documented in comparison report

Best Practices Summary

During Development:

Validate expressions as you write them
Check GeoJSON data when adding sources
Test color contrast for new text layers

Before Committing:

Compare with previous version
Document significant changes
Validate modified expressions

Before Production:

Run full validation suite
Check accessibility compliance
Optimize style
Test optimized version
Generate quality report

Regular Maintenance:

Periodically optimize to prevent bloat
Review and consolidate similar layers
Update expressions to use simpler forms
Remove deprecated or unused code

Tool Quick Reference

Tool	Use When	Output
`validate_geojson_tool`	Adding GeoJSON sources	Valid/invalid + error list
`validate_expression_tool`	Writing expressions	Valid/invalid + error list
`check_color_contrast_tool`	Styling text labels	Passes/fails + WCAG levels
`compare_styles_tool`	Reviewing changes	Diff report with paths
`optimize_style_tool`	Before deployment	Optimized style + savings

mapbox-style-quality

NPX Install

SKILL.md Content