{"id":15414,"plugin_id":"plugin_asdk_app_6a2c0bf33cb48191884d842b15ad3c20","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:11:22.590Z","digest":"a1b19a3bf18264a970a69811e46e86ab1bff9ff00466141bc130f360fc04df0c","against":null,"payload":{"name":"mapbox-style-quality","description":"Expert guidance on validating, optimizing, and ensuring quality of Mapbox styles through validation, accessibility checks, and optimization. Use when preparing styles for production, debugging issues, or ensuring map quality standards.","included_files":[{"relative_path":"AGENTS.md","size_in_bytes":6402},{"relative_path":"evals/evals.json","size_in_bytes":2896},{"relative_path":"references/ci-integration.md","size_in_bytes":610},{"relative_path":"references/comparison.md","size_in_bytes":1363},{"relative_path":"references/optimization.md","size_in_bytes":2674}],"skill_md_contents":"---\nname: mapbox-style-quality\ndescription: Expert guidance on validating, optimizing, and ensuring quality of Mapbox styles through validation, accessibility checks, and optimization. Use when preparing styles for production, debugging issues, or ensuring map quality standards.\n---\n\n# Mapbox Style Quality Skill\n\nThis skill provides expert guidance on ensuring Mapbox style quality through validation, accessibility, and optimization tools.\n\n## When to Use Quality Tools\n\n### Pre-Production Checklist\n\nBefore deploying any Mapbox style to production:\n\n1. **Validate all expressions** - Catch syntax errors before runtime\n2. **Check color contrast** - Ensure text is readable (WCAG compliance)\n3. **Validate GeoJSON sources** - Ensure data integrity\n4. **Optimize style** - Reduce file size and improve performance\n5. **Compare versions** - Understand what changed\n6. **Remove empty layers** - Delete layers with no visible paint properties as a final cleanup step\n7. **Simplify redundant boolean expressions** - Clean up filters with unnecessary boolean logic (e.g., `[\"all\", expr]` → `expr`, `[\"any\", false, expr]` → `expr`)\n\n### During Development\n\n**When adding GeoJSON data:**\n\n- Always validate external GeoJSON with `validate_geojson_tool` before using as a source\n\n**When writing expressions:**\n\n- Validate expressions with `validate_expression_tool` as you write them\n- Catch type mismatches early (e.g., using string operator on number)\n- Verify operator availability in your Mapbox GL JS version\n- Test expressions with expected data types\n\n**When styling text/labels:**\n\n- Check foreground/background contrast with `check_color_contrast_tool`\n- Aim for WCAG AA minimum (4.5:1 for normal text, 3:1 for large text)\n- Use AAA standard (7:1 for normal text) for better accessibility\n- Consider different background scenarios (map tiles, overlays)\n\n### Before Committing Changes\n\n**Compare style versions:**\n\n- Use `compare_styles_tool` to generate a diff report\n- Review all layer changes, source modifications, and expression updates\n- Understand the impact of your changes\n- Document significant changes in commit messages\n\n### Before Deployment\n\n**Optimize the style:**\n\n- Run `optimize_style_tool` to reduce file size\n- Remove unused sources that reference deleted layers\n- Eliminate duplicate layers with identical properties\n- Simplify redundant boolean expressions in filters (e.g., collapse `[\"all\", expr]` to `expr`, remove tautological conditions)\n- Remove empty layers (layers with no visible paint properties) as a final cleanup step\n\n## Validation Best Practices\n\n### GeoJSON Validation\n\n**Always validate when:**\n\n- Loading GeoJSON from user uploads\n- Fetching GeoJSON from external APIs\n- Processing GeoJSON from third-party sources\n- Converting between data formats\n\n**Common GeoJSON errors:**\n\n- Invalid coordinate ranges (longitude > 180 or < -180)\n- Unclosed polygon rings (first and last coordinates must match)\n- Wrong coordinate order (should be [longitude, latitude], not [latitude, longitude])\n- Missing required properties (type, coordinates, geometry)\n- Invalid geometry types or nesting\n\n**Example workflow:**\n\n```\n1. Receive GeoJSON data\n2. Validate with validate_geojson_tool\n3. If valid: Add as source to style\n4. If invalid: Fix errors, re-validate\n```\n\n### Expression Validation\n\n**Validate expressions for:**\n\n- Filter conditions (`filter` property on layers)\n- Data-driven styling (`paint` and `layout` properties)\n- Feature state expressions\n- Dynamic property calculations\n\n**Common expression errors:**\n\n- Type mismatches (string operators on numbers)\n- Invalid operator names or wrong syntax\n- Wrong number of arguments for operators\n- Nested expression errors\n- Using unavailable operators for your GL JS version\n\n**Prevention strategies:**\n\n- Validate as you write expressions, not at runtime\n- Test expressions with representative data\n- Use type checking (expectedType parameter)\n- Validate in context (layer, filter, paint, layout)\n\n### Accessibility Validation\n\n**WCAG Levels:**\n\n- **AA** (minimum): 4.5:1 for normal text, 3:1 for large text\n- **AAA** (enhanced): 7:1 for normal text, 4.5:1 for large text\n\n**Text size categories:**\n\n- **Normal**: < 18pt or < 14pt bold\n- **Large**: ≥ 18pt or ≥ 14pt bold\n\n**Common scenarios to check:**\n\n- Text labels on map tiles\n- POI labels with background colors\n- Custom markers with text\n- UI overlays on maps\n- Legend text and symbols\n- Attribution text\n\n**Testing strategy:**\n\n- Test against both light and dark map tiles\n- Consider overlay backgrounds (popups, modals)\n- Test in different lighting conditions (mobile outdoor use)\n- Verify contrast at different zoom levels\n\n## Quality Workflow Examples\n\n### Basic Quality Check\n\n```\n1. Validate expressions in style\n2. Check color contrast for text layers\n3. Optimize if needed\n```\n\n### Full Pre-Production Workflow\n\n```\n1. Validate all GeoJSON sources\n2. Validate all expressions (filters, paint, layout)\n3. Check color contrast for all text layers\n4. Compare with previous production version\n5. Optimize style\n6. Test optimized style\n7. Deploy\n```\n\n### Troubleshooting Workflow\n\n```\n1. Compare working vs. broken style\n2. Identify differences\n3. Validate suspicious expressions\n4. Check GeoJSON data if source-related\n5. Verify color contrast if visibility issue\n```\n\n## Common Issues and Solutions\n\n### Runtime Expression Errors\n\n**Problem:** Map throws expression errors at runtime\n**Solution:** Validate expressions with `validate_expression_tool` during development\n**Prevention:** Add expression validation to pre-commit hooks or CI/CD\n\n### Poor Text Readability\n\n**Problem:** Text labels are hard to read on map\n**Solution:** Check contrast with `check_color_contrast_tool`, adjust colors to meet WCAG AA\n**Prevention:** Test text on both light and dark backgrounds, check at different zoom levels\n\n### Large Style File Size\n\n**Problem:** Style takes long to load or transfer\n**Solution:** Run `optimize_style_tool` to remove redundancies and simplify\n**Prevention:** Regularly optimize during development, remove unused sources immediately\n\n### Invalid GeoJSON Source\n\n**Problem:** GeoJSON source fails to load or render\n**Solution:** Validate with `validate_geojson_tool`, fix coordinate issues, verify structure\n**Prevention:** Validate all external GeoJSON before adding to style\n\n### Unexpected Style Changes\n\n**Problem:** Style changed but unsure what modified\n**Solution:** Use `compare_styles_tool` to generate diff report\n**Prevention:** Compare before/after for all significant changes, document modifications\n\n## Tool Quick Reference\n\n| Tool                        | Use When               | Output                     |\n| --------------------------- | ---------------------- | -------------------------- |\n| `validate_geojson_tool`     | Adding GeoJSON sources | Valid/invalid + error list |\n| `validate_expression_tool`  | Writing expressions    | Valid/invalid + error list |\n| `check_color_contrast_tool` | Styling text labels    | Passes/fails + WCAG levels |\n| `compare_styles_tool`       | Reviewing changes      | Diff report with paths     |\n| `optimize_style_tool`       | Before deployment      | Optimized style + savings  |\n\n## Reference Files\n\nFor detailed guidance on specific topics, load the relevant reference:\n\n- **`references/optimization.md`** — Optimization types, strategies, recommended order, and maintenance best practices\n- **`references/comparison.md`** — Style comparison workflows, ignoreMetadata usage, and refactoring workflow\n- **`references/ci-integration.md`** — Git pre-commit hooks, CI/CD pipeline steps, and code review checklist\n\n> **Load instruction:** Read the reference file when the user needs in-depth guidance on that topic.\n\n## Additional Resources\n\n- [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/)\n- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)\n- [GeoJSON Specification (RFC 7946)](https://tools.ietf.org/html/rfc7946)\n- [Mapbox Expression Reference](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/)\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}