[skill+prompt] Add mapbox-style-quality skill and prepare-style-for-production prompt with automatic validation

[mattpodwysocki]

Summary

Adds comprehensive style quality validation capabilities through a new skill and prompt, with automatic validation integrated into all style-creation workflows.

New Skill: mapbox-style-quality

Created comprehensive skill document (390+ lines) teaching AI assistants when and how to use quality validation tools:

• Pre-production checklist: Validate expressions, check accessibility, optimize styles
• Development workflows: When to use each validation tool during development
• Best practices: GeoJSON validation, expression validation, WCAG compliance
• Optimization strategies: When to optimize, recommended order, selective optimization
• Integration patterns: Git hooks, CI/CD pipelines, code review checklists
• Common issues: Runtime errors, poor readability, large file sizes with solutions

New Prompt: prepare-style-for-production

Created production-ready workflow prompt that orchestrates 5 validation tools:

1. validate_expression_tool - Validates filters, paint properties, layout properties
2. validate_geojson_tool - Validates GeoJSON sources for coordinate/structure errors
3. check_color_contrast_tool - Checks WCAG AA/AAA accessibility compliance
4. optimize_style_tool - Removes redundancies, simplifies expressions
5. compare_styles_tool - Implicit comparison for before/after analysis

Features:

• Accepts style ID or complete style JSON
• Configurable WCAG level (AA or AAA, default: AA)
• Optional optimization skip
• Generates comprehensive quality report with deployment readiness assessment

Arguments:

• style_id_or_json (required): Style ID or complete style JSON
• skip_optimization (optional): Set to "true" to skip optimization
• wcag_level (optional): "AA" or "AAA" (default: "AA")

Automatic Validation Integration

Updated all 4 style-creation prompts to automatically validate after creating styles:

Updated Prompts:

1. create-and-preview-style - Auto-validates after creation
2. build-custom-map - Auto-validates AI-generated styles
3. design-data-driven-style - Auto-validates complex expressions
4. setup-mapbox-project - Auto-validates initial style

Validation Flow:

1. Create style ✓
2. Generate preview ✓
3. Automatically validate ✓ (runs without asking)
4. Present: Preview URL + Validation report

Results Shown to Users:

• ✅ Preview URL
• ✅ Validation report:
  • Expression validation status
  • Accessibility compliance (WCAG AA)
  • Optimization recommendations
  • Overall: "Production-ready" or list of issues
• ✅ Note: "Warnings can be ignored for prototypes"

Why Automatic Validation?

Following development tool patterns (ESLint, TypeScript, test runners):

• Fast: All validation is offline (no API calls, milliseconds)
• Informational: Shows issues but doesn't block workflow
• Early detection: Catches problems before runtime
• Especially valuable for:
  • AI-generated styles (build-custom-map)
  • Complex expressions (design-data-driven-style)
  • Production deployments (all prompts)

Testing

• 15 comprehensive test cases for PrepareStyleForProductionPrompt
• Updated prompt registry tests
• All 386 tests passing ✓

Documentation

• Added mapbox-style-quality to skills list in README
• Added complete prompt documentation with usage examples
• Cross-referenced skill and prompt
• Updated all 4 style-creation prompts

Related Work

This work depends on and integrates with:

• PR Add validate_geojson_tool for offline GeoJSON validation #50: validate_geojson_tool
• PR Add validate_expression_tool for Mapbox expression validation #51: validate_expression_tool
• PR [tools] Add compare_styles_tool for style comparison #52: compare_styles_tool
• PR [tools] Add check_color_contrast_tool for WCAG accessibility compliance #53: check_color_contrast_tool
• PR [tools] Add optimize_style_tool for style optimization #54: optimize_style_tool

Example Usage

Using the Prompt Directly:

Use prompt: prepare-style-for-production
Arguments:
  style_id_or_json: "username/my-style-id"
  wcag_level: "AA"

Automatic Validation in Workflows:

When a user runs create-and-preview-style, the AI will now:

1. Create the style
2. Generate preview
3. Automatically validate (new!)
4. Show preview URL + validation report together

Benefits

• Catches issues early: Expression errors, accessibility problems, optimization opportunities
• Production-ready by default: All created styles are validated
• Educational: Users learn about quality issues as they develop
• No friction: Validation is fast and informational
• Best practices built-in: WCAG compliance checking, expression validation

---

🤖 Generated with Claude Code