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

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

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

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

Tool Quick Reference

Reference Files

For detailed guidance on specific topics, load the relevant reference:

• `references/optimization.md` — Optimization types, strategies, recommended order, and maintenance best practices
• `references/comparison.md` — Style comparison workflows, ignoreMetadata usage, and refactoring workflow
• `references/ci-integration.md` — Git pre-commit hooks, CI/CD pipeline steps, and code review checklist

Load instruction: Read the reference file when the user needs in-depth guidance on that topic.

Additional Resources

• Mapbox Style Specification
• WCAG 2.1 Guidelines
• GeoJSON Specification (RFC 7946)
• Mapbox Expression Reference

Mapbox Style Quality Guide

Quick reference for style validation, accessibility, performance optimization, and testing.

Style Validation Rules

Required Elements

✅ Valid version 8 style specification ✅ At least one source defined ✅ At least one layer defined ✅ Valid layer types and properties ✅ Proper source references in layers

Common Errors

// ❌ Layer references non-existent source
{
  "id": "layer",
  "source": "missing-source" // Error!
}

// ❌ Invalid property values
{
  "paint": {
    "fill-color": "not-a-color" // Error!
  }
}

// ✅ Valid layer
{
  "id": "layer",
  "source": "valid-source",
  "type": "fill",
  "paint": {
    "fill-color": "#ff0000"
  }
}

Accessibility Standards

Color Contrast (WCAG 2.1)

Requirements:

• Normal text: 4.5:1 contrast ratio
• Large text (18pt+): 3:1 contrast ratio
• UI components: 3:1 contrast ratio

// ✅ Good contrast for labels
'text-color': '#222222',
'text-halo-color': '#ffffff',
'text-halo-width': 2,
'text-halo-blur': 1

Colorblind Accessibility

Test for:

• Deuteranopia (red-green, 8% of males)
• Protanopia (red-green, 1% of males)
• Tritanopia (blue-yellow, rare)

Rules:

• ❌ Don't rely on color alone
• ✅ Add patterns, labels, or symbols
• ✅ Use colorblind-safe palettes
• ✅ Test with colorblind simulators

Touch Targets

Mobile requirements:

• Minimum: 44x44 pixels (iOS)
• Recommended: 48x48 pixels (Material Design)

// ✅ Large enough tap targets
'icon-size': 1.2,  // Larger icons
'icon-allow-overlap': false,  // No overlapping
'symbol-spacing': 250  // Space between symbols

Performance Optimization

Layer Count

Rule: Minimize layer count

• Good: < 50 layers
• Warning: 50-100 layers
• Problem: > 100 layers

Optimization:

// ❌ Multiple layers for categories
map.addLayer({ id: 'parks', filter: ['==', 'type', 'park'] });
map.addLayer({ id: 'water', filter: ['==', 'type', 'water'] });

// ✅ One layer with data-driven styling
map.addLayer({
  id: 'features',
  paint: {
    'fill-color': ['match', ['get', 'type'], 'park', '#90EE90', 'water', '#87CEEB', '#CCCCCC']
  }
});

Source Optimization

// ✅ Set appropriate zoom ranges
{
  "type": "vector",
  "tiles": ["https://..."],
  "minzoom": 0,
  "maxzoom": 14  // Don't over-fetch
}

// ✅ Use generateId for feature state
{
  "type": "geojson",
  "data": geojson,
  "generateId": true  // Better performance
}

Paint Properties

// ✅ Use data-driven expressions efficiently
'circle-radius': [
  'interpolate', ['linear'], ['zoom'],
  8, 2,
  16, 8
]

// ❌ Avoid expensive operations in expressions
'circle-radius': [
  'sqrt',  // Expensive!
  ['*', ['get', 'value'], ['get', 'multiplier']]
]

Style Testing Checklist

Visual Testing

✅ Test at multiple zoom levels (0, 5, 10, 15, 20) ✅ Test with different data densities ✅ Check label collisions ✅ Verify symbol/icon rendering ✅ Test on desktop and mobile viewports ✅ Check dark mode compatibility

Functional Testing

// ✅ Validate style loads
map.on('style.load', () => {
  console.log('Style loaded successfully');
});

// ✅ Check for missing resources
map.on('error', (e) => {
  console.error('Style error:', e);
});

// ✅ Validate sources
const sources = map.getStyle().sources;
Object.keys(sources).forEach((id) => {
  console.log('Source:', id, sources[id]);
});

// ✅ Validate layers
const layers = map.getStyle().layers;
layers.forEach((layer) => {
  console.log('Layer:', layer.id, 'Type:', layer.type);
});

Performance Testing

// ✅ Measure style load time
const startTime = performance.now();
map.setStyle(style);
map.once('idle', () => {
  console.log('Style load time:', performance.now() - startTime, 'ms');
});

// ✅ Monitor frame rate
const fps = map.getFPS();
console.log('FPS:', fps); // Should be close to 60

// ✅ Check layer count
console.log('Layer count:', map.getStyle().layers.length);

Common Quality Issues

1. Label Collisions

// ❌ Overlapping labels
'text-allow-overlap': true  // Bad for readability

// ✅ Prevent collisions
'text-allow-overlap': false,
'text-padding': 2,
'symbol-spacing': 250

2. Inconsistent Styling

// ❌ Different styles for similar features
layer1: { 'line-width': 2 }
layer2: { 'line-width': 3 }  // Inconsistent

// ✅ Consistent styling
'line-width': [
  'match', ['get', 'class'],
  'primary', 4,
  'secondary', 2,
  1
]

3. Missing Error Handling

// ❌ No error handling
map.addSource('source', sourceData);

// ✅ Check before adding
if (!map.getSource('source')) {
  map.addSource('source', sourceData);
}

4. Poor Mobile Performance

Issues:

• Too many layers
• Large GeoJSON files
• High-resolution images
• Complex expressions

Solutions:

• Simplify geometry
• Use vector tiles
• Optimize images
• Cache data

Style Optimization Workflow

1. Validate Structure

• Check JSON syntax
• Verify all sources referenced
• Validate property types

2. Test Accessibility

• Check color contrast
• Test colorblind modes
• Verify touch targets

3. Optimize Performance

• Reduce layer count
• Simplify expressions
• Set appropriate zoom ranges
• Use feature state

4. Test Across Devices

• Desktop browsers
• Mobile browsers
• Different screen sizes
• Low-end devices

5. Monitor in Production

• Track load times
• Monitor errors
• Check tile request counts
• Measure FPS

Tools & Resources

Validation:

• Mapbox Style Specification: <https://docs.mapbox.com/mapbox-gl-js/style-spec/>
• JSON Schema validators

Accessibility:

• WebAIM Contrast Checker
• Coblis Color Blindness Simulator
• WAVE Accessibility Evaluation Tool

Performance:

• Chrome DevTools Performance tab
• Mapbox GL JS Performance metrics
• Bundle size analyzers

Quick Fixes

Slow rendering? → Reduce layer count, simplify geometry

Label collisions? → Increase text-padding, reduce symbol density

Poor mobile performance? → Use vector tiles, reduce complexity

Low contrast? → Add text halos, adjust colors

Icons not loading? → Check sprite paths, add error handlers

Integration with Development Workflow

Git Pre-Commit Hook

# 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

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

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

Best Practices Summary

Before Committing:

• Compare with previous version
• Document significant changes
• Validate modified expressions

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:

1. Remove unused sources first (reduces noise for other checks) 2. Remove duplicate layers (eliminates redundancy) 3. Simplify expressions (improves readability and performance) 4. Remove empty layers (final cleanup) 5. 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

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 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