Compétence Mapbox Style Quality

Cette compétence fournit des conseils experts pour assurer la qualité des styles Mapbox grâce à des outils de validation, d'accessibilité et d'optimisation.

Quand utiliser les outils Quality

Checklist avant production

Avant de déployer un style Mapbox en production :

1. Valider toutes les expressions - Détecter les erreurs de syntaxe avant l'exécution
2. Vérifier le contraste des couleurs - S'assurer que le texte est lisible (conformité WCAG)
3. Valider les sources GeoJSON - S'assurer de l'intégrité des données
4. Optimiser le style - Réduire la taille du fichier et améliorer les performances
5. Comparer les versions - Comprendre ce qui a changé
6. Supprimer les couches vides - Supprimer les couches sans propriétés de peinture visibles comme étape de nettoyage final
7. Simplifier les expressions booléennes redondantes - Nettoyer les filtres avec une logique booléenne inutile (par ex., ["all", expr] → expr, ["any", false, expr] → expr)

En cours de développement

Lors de l'ajout de données GeoJSON :

• Toujours valider les GeoJSON externes avec validate_geojson_tool avant de les utiliser comme source

Lors de l'écriture d'expressions :

• Valider les expressions avec validate_expression_tool en les écrivant
• Détecter les erreurs de type rapidement (par ex., utiliser un opérateur string sur un nombre)
• Vérifier la disponibilité des opérateurs dans votre version de Mapbox GL JS
• Tester les expressions avec les types de données attendus

Lors du style des textes/étiquettes :

• Vérifier le contraste avant-plan/arrière-plan avec check_color_contrast_tool
• Viser un minimum WCAG AA (4,5:1 pour texte normal, 3:1 pour texte large)
• Utiliser la norme AAA (7:1 pour texte normal) pour une meilleure accessibilité
• Considérer différents scénarios d'arrière-plan (tuiles de carte, superpositions)

Avant de valider les modifications

Comparer les versions de style :

• Utiliser compare_styles_tool pour générer un rapport diff
• Examiner tous les changements de couches, modifications de sources et mises à jour d'expressions
• Comprendre l'impact de vos modifications
• Documenter les changements significatifs dans les messages de commit

Avant le déploiement

Optimiser le style :

• Exécuter optimize_style_tool pour réduire la taille du fichier
• Supprimer les sources non utilisées qui référencent des couches supprimées
• Éliminer les couches dupliquées avec des propriétés identiques
• Simplifier les expressions booléennes redondantes dans les filtres (par ex., réduire ["all", expr] à expr, supprimer les conditions tautologiques)
• Supprimer les couches vides (couches sans propriétés de peinture visibles) comme étape de nettoyage final

Bonnes pratiques de validation

Validation GeoJSON

Toujours valider quand :

• Chargement de GeoJSON à partir de fichiers utilisateur
• Récupération de GeoJSON depuis des API externes
• Traitement de GeoJSON de sources tierces
• Conversion entre formats de données

Erreurs GeoJSON courantes :

• Plages de coordonnées invalides (longitude > 180 ou < -180)
• Anneaux de polygone non fermés (les première et dernière coordonnées doivent correspondre)
• Ordre des coordonnées incorrect (doit être [longitude, latitude], pas [latitude, longitude])
• Propriétés requises manquantes (type, coordinates, geometry)
• Types de géométrie invalides ou imbrication incorrecte

Exemple de workflow :

1. Recevoir les données GeoJSON
2. Valider avec validate_geojson_tool
3. Si valide : Ajouter comme source au style
4. Si invalide : Corriger les erreurs, revalider

Validation d'expressions

Valider les expressions pour :

• Conditions de filtre (propriété filter sur les couches)
• Style piloté par les données (propriétés paint et layout)
• Expressions d'état des entités
• Calculs de propriétés dynamiques

Erreurs d'expression courantes :

• Erreurs de type (opérateurs string sur nombres)
• Noms d'opérateurs invalides ou syntaxe incorrecte
• Nombre incorrect d'arguments pour les opérateurs
• Erreurs d'expression imbriquées
• Utilisation d'opérateurs non disponibles pour votre version de GL JS

Stratégies de prévention :

• Valider en écrivant les expressions, pas à l'exécution
• Tester les expressions avec des données représentatives
• Utiliser la vérification de type (paramètre expectedType)
• Valider en contexte (couche, filtre, paint, layout)

Validation d'accessibilité

Niveaux WCAG :

• AA (minimum) : 4,5:1 pour texte normal, 3:1 pour texte large
• AAA (amélioré) : 7:1 pour texte normal, 4,5:1 pour texte large

Catégories de taille de texte :

• Normal : < 18pt ou < 14pt gras
• Large : ≥ 18pt ou ≥ 14pt gras

Scénarios courants à vérifier :

• Étiquettes de texte sur tuiles de carte
• Étiquettes POI avec couleurs d'arrière-plan
• Marqueurs personnalisés avec texte
• Superpositions d'interface utilisateur sur cartes
• Texte et symboles de légende
• Texte d'attribution

Stratégie de test :

• Tester sur tuiles de carte claires et sombres
• Considérer les arrière-plans de superposition (popups, modales)
• Tester dans différentes conditions d'éclairage (utilisation mobile en extérieur)
• Vérifier le contraste à différents niveaux de zoom

Exemples de workflow Quality

Vérification Quality basique

1. Valider les expressions dans le style
2. Vérifier le contraste des couleurs pour les couches de texte
3. Optimiser si nécessaire

Workflow complet avant production

1. Valider toutes les sources GeoJSON
2. Valider toutes les expressions (filtres, paint, layout)
3. Vérifier le contraste des couleurs pour toutes les couches de texte
4. Comparer avec la version de production précédente
5. Optimiser le style
6. Tester le style optimisé
7. Déployer

Workflow de dépannage

1. Comparer le style fonctionnel avec le style défaillant
2. Identifier les différences
3. Valider les expressions suspectes
4. Vérifier les données GeoJSON si lié à la source
5. Vérifier le contraste des couleurs en cas de problème de visibilité

Problèmes courants et solutions

Erreurs d'expression à l'exécution

Problème : La carte lance des erreurs d'expression à l'exécution Solution : Valider les expressions avec validate_expression_tool en cours de développement Prévention : Ajouter la validation d'expression aux hooks de pre-commit ou CI/CD

Mauvaise lisibilité du texte

Problème : Les étiquettes de texte sont difficiles à lire sur la carte Solution : Vérifier le contraste avec check_color_contrast_tool, ajuster les couleurs pour respecter WCAG AA Prévention : Tester le texte sur arrière-plans clairs et sombres, vérifier à différents niveaux de zoom

Taille de fichier de style importante

Problème : Le style met longtemps à charger ou transférer Solution : Exécuter optimize_style_tool pour supprimer les redondances et simplifier Prévention : Optimiser régulièrement en cours de développement, supprimer immédiatement les sources non utilisées

Source GeoJSON invalide

Problème : La source GeoJSON ne charge pas ou ne s'affiche pas Solution : Valider avec validate_geojson_tool, corriger les problèmes de coordonnées, vérifier la structure Prévention : Valider tous les GeoJSON externes avant d'ajouter au style

Modifications de style inattendues

Problème : Le style a changé mais vous n'êtes pas sûr de ce qui a été modifié Solution : Utiliser compare_styles_tool pour générer un rapport diff Prévention : Comparer avant/après pour tous les changements significatifs, documenter les modifications

Référence rapide des outils

Fichiers de référence

Pour des conseils détaillés sur des sujets spécifiques, charger la référence appropriée :

• references/optimization.md — Types d'optimisation, stratégies, ordre recommandé et bonnes pratiques de maintenance
• references/comparison.md — Workflows de comparaison de style, utilisation ignoreMetadata et workflow de refactorisation
• references/ci-integration.md — Hooks de pre-commit Git, étapes de pipeline CI/CD et checklist de révision de code

Instruction de chargement : Lire le fichier de référence quand l'utilisateur a besoin de conseils approfondis sur ce sujet.

Ressources supplémentaires

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