Mapbox Style Quality

# 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

```javascript
// ❌ 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

```javascript
// ✅ 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)

```javascript
// ✅ 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:**

```javascript
// ❌ 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

```javascript
// ✅ 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

```javascript
// ✅ 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

```javascript
// ✅ 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

```javascript
// ✅ 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:',