mapbox-style-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mapbox Style Quality Skill

Mapbox 样式质量 Skill

This skill provides expert guidance on ensuring Mapbox style quality through validation, accessibility, and optimization tools.

本Skill通过验证、无障碍检查和优化工具，为保障Mapbox样式质量提供专业指导。

When to Use Quality Tools

质量工具的适用场景

Pre-Production Checklist

生产前检查清单

Before deploying any Mapbox style to production:

Validate all expressions - Catch syntax errors before runtime
Check color contrast - Ensure text is readable (WCAG compliance)
Validate GeoJSON sources - Ensure data integrity
Optimize style - Reduce file size and improve performance
Compare versions - Understand what changed

在将任何Mapbox样式部署到生产环境之前：

验证所有表达式 - 在运行前捕获语法错误
检查颜色对比度 - 确保文本可读（符合WCAG标准）
验证GeoJSON数据源 - 保障数据完整性
优化样式 - 减小文件体积并提升性能
版本对比 - 了解变更内容

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)

添加GeoJSON数据时：

在将外部GeoJSON作为数据源使用前，务必通过
```
validate_geojson_tool
```
进行验证

编写表达式时：

在编写表达式时，使用
```
validate_expression_tool
```
进行验证
尽早捕获类型不匹配问题（例如，对数值使用字符串操作符）
验证所使用的操作符在你的Mapbox GL JS版本中是否可用
使用预期的数据类型测试表达式

设置文本/标签样式时：

使用
```
check_color_contrast_tool
```
检查前景与背景的对比度
目标达到WCAG AA最低标准（普通文本对比度4.5:1，大文本3:1）
为提升无障碍性，可采用AAA标准（普通文本对比度7:1）
考虑不同的背景场景（地图瓦片、叠加层）

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

对比样式版本：

使用
```
compare_styles_tool
```
生成差异报告
检查所有图层变更、数据源修改及表达式更新
了解变更带来的影响
在提交信息中记录重要变更

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 boolean expressions for better performance
Remove empty layers that serve no purpose

优化样式：

运行
```
optimize_style_tool
```
减小文件体积
删除引用已删除图层的未使用数据源
移除属性完全相同的重复图层
简化布尔表达式以提升性能
删除无实际用途的空图层

Validation Best Practices

验证最佳实践

GeoJSON Validation

GeoJSON 验证

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

以下场景务必验证：

加载用户上传的GeoJSON
从外部API获取GeoJSON
处理来自第三方的GeoJSON
数据格式转换时

常见GeoJSON错误：

无效坐标范围（经度>180或<-180）
未闭合的多边形环（首尾坐标必须一致）
坐标顺序错误（应为[经度, 纬度]，而非[纬度, 经度]）
缺少必填属性（type、coordinates、geometry）
无效的几何类型或嵌套结构

示例工作流：

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)

需验证的表达式场景：

过滤条件（图层的
```
filter
```
属性）
数据驱动样式（
```
paint
```
和
```
layout
```
属性）
要素状态表达式
动态属性计算

常见表达式错误：

类型不匹配（对数值使用字符串操作符）
无效操作符名称或语法错误
操作符参数数量错误
嵌套表达式错误
使用了当前GL JS版本不支持的操作符

预防策略：

在编写表达式时即进行验证，而非等到运行时
使用代表性数据测试表达式
使用类型检查（expectedType参数）
在对应上下文（图层、过滤、绘制、布局）中进行验证

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

WCAG 等级：

AA级（最低标准）：普通文本对比度4.5:1，大文本3:1
AAA级（增强标准）：普通文本对比度7:1，大文本4.5:1

文本大小分类：

普通文本：<18pt 或 <14pt 粗体
大文本：≥18pt 或 ≥14pt 粗体

需检查的常见场景：

地图瓦片上的文本标签
带背景色的POI标签
带文本的自定义标记
地图上的UI叠加层
图例文本和符号
署名文本

测试策略：

针对浅色和深色地图瓦片进行测试
考虑叠加层背景（弹窗、模态框）
在不同光照条件下测试（如移动端户外使用场景）
在不同缩放级别下验证对比度

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)

移除未使用的数据源：

自动识别未被任何图层引用的数据源
移除后不会影响功能，安全可靠
删除图层或重构后常见此类情况

移除重复图层：

查找属性完全相同的图层（排除ID）
复制粘贴图层时可能出现
降低样式复杂度并减小文件体积

简化表达式：

将
```
["all", true]
```
转换为
```
true
```
将
```
["any", false]
```
转换为
```
false
```
将
```
["!", false]
```
转换为
```
true
```
将
```
["!", true]
```
转换为
```
false
```
提升表达式求值性能

移除空图层：

移除无绘制或布局属性的图层
保留背景图层（即使为空也有效）
清理未完成或占位用的图层

合并过滤器：

识别具有相同过滤表达式的图层组
突出显示图层合并的可能性
不会自动合并（仅提供信息参考）

Optimization Strategy

优化策略

Recommended order:

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

推荐优化顺序：

先移除未使用的数据源（减少其他检查的干扰）
移除重复图层（消除冗余）
简化表达式（提升可读性和性能）
移除空图层（最终清理）
查看合并机会（手动步骤）

选择性优化：

// All optimizations (recommended for production)
optimize_style_tool({ style })

// Specific optimizations only
optimize_style_tool({
  style,
  optimizations: ['remove-unused-sources', 'simplify-expressions']
})

部署前审核：

查看优化报告
验证体积节省情况（percentReduction）
查看变更列表（optimizations数组）
部署前测试优化后的样式

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

合并变更前：

查看功能分支中的变更内容
确保无意外修改
生成变更摘要用于PR描述

排查问题时：

对比正常版本与故障版本
确定版本间的变更内容
缩小问题根源范围

迁移过程中：

对比旧格式与新格式
验证转换后的数据完整性
记录转换差异

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

使用ignoreMetadata标记：

// Ignore metadata differences (id, owner, created, modified)
compare_styles_tool({
  styleA: oldStyle,
  styleB: newStyle,
  ignoreMetadata: true
})

关注有意义的变更：

图层的添加/移除
数据源变更
表达式修改
绘制/布局属性更新

记录重要变更：

在文档中记录破坏性变更
更新样式版本号
向团队/用户传达变更内容

Quality Workflow Examples

质量工作流示例

Basic Quality Check

基础质量检查

1. Validate expressions in style
2. Check color contrast for text layers
3. Optimize if needed

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

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

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

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

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

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

问题： 地图在运行时抛出表达式错误 解决方案： 在开发阶段使用

validate_expression_tool

验证表达式 预防措施： 将表达式验证添加到提交前钩子或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

问题： 地图上的文本标签难以辨认 解决方案： 使用

check_color_contrast_tool

检查对比度，调整颜色以符合WCAG AA标准 预防措施： 在浅色和深色背景上测试文本，在不同缩放级别下进行检查

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

问题： 样式加载或传输耗时过长 解决方案： 运行

optimize_style_tool

移除冗余内容并简化样式 预防措施： 开发期间定期优化，立即移除未使用的数据源

Invalid GeoJSON Source

无效GeoJSON数据源

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

问题： GeoJSON数据源加载或渲染失败 解决方案： 使用

validate_geojson_tool

验证，修复坐标问题，验证结构 预防措施： 在将外部GeoJSON添加到样式前进行验证

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

问题： 样式发生变更，但不清楚具体修改内容 解决方案： 使用

compare_styles_tool

生成差异报告 预防措施： 对所有重要变更进行前后对比，记录修改内容

Integration with Development Workflow

与开发工作流集成

Git Pre-Commit Hook

Git 提交前钩子

bash

undefined

bash

undefined

Validate expressions before commit

npm run validate-style

Optimize before commit (optional)

npm run optimize-style

undefined

npm run optimize-style

undefined

CI/CD Pipeline

CI/CD 流水线

1. Validate all expressions
2. Check accessibility compliance
3. Run optimization (warning if significant savings)
4. Compare with production version
5. Generate quality report

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

代码审核清单

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

Compare with previous version
Document significant changes
Validate modified expressions

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

开发阶段：

编写表达式时即进行验证
添加数据源时检查GeoJSON数据
为新文本图层测试颜色对比度

提交前：

与之前版本进行对比
记录重要变更
验证修改后的表达式

生产前：

运行完整验证套件
检查无障碍合规性
优化样式
测试优化后的版本
生成质量报告

定期维护：

定期优化以防止体积膨胀
审核并合并相似图层
更新表达式为更简洁的形式
移除已弃用或未使用的代码

Tool Quick Reference

工具速查

Tool	Use When	Output
`validate_geojson_tool`	Adding GeoJSON sources	Valid/invalid + error list
`validate_expression_tool`	Writing expressions	Valid/invalid + error list
`check_color_contrast_tool`	Styling text labels	Passes/fails + WCAG levels
`compare_styles_tool`	Reviewing changes	Diff report with paths
`optimize_style_tool`	Before deployment	Optimized style + savings

工具名称	适用场景	输出内容
`validate_geojson_tool`	添加GeoJSON数据源时	验证结果（有效/无效）+错误列表
`validate_expression_tool`	编写表达式时	验证结果（有效/无效）+错误列表
`check_color_contrast_tool`	设置文本标签样式时	检查结果（通过/不通过）+WCAG等级
`compare_styles_tool`	查看变更时	带路径的差异报告
`optimize_style_tool`	部署前	优化后的样式 + 体积节省信息

mapbox-style-quality

Original

Translation

Mapbox Style Quality Skill

Mapbox 样式质量 Skill

When to Use Quality Tools

质量工具的适用场景

Pre-Production Checklist

生产前检查清单

During Development

开发阶段

Before Committing Changes

提交变更前

Before Deployment

部署前

Validation Best Practices

验证最佳实践

GeoJSON Validation

GeoJSON 验证

Expression Validation

表达式验证

Accessibility Validation

无障碍验证

Optimization Best Practices

优化最佳实践

When to Optimize

优化时机

Optimization Types

优化类型

Optimization Strategy

优化策略

Style Comparison Workflow

样式对比工作流

When to Compare Styles

样式对比时机

Comparison Best Practices

对比最佳实践

Quality Workflow Examples

质量工作流示例

Basic Quality Check

基础质量检查

Full Pre-Production Workflow

完整生产前工作流

Troubleshooting Workflow

故障排查工作流

Refactoring Workflow

重构工作流

Common Issues and Solutions

常见问题与解决方案

Runtime Expression Errors

运行时表达式错误

Poor Text Readability

文本可读性差

Large Style File Size

样式文件体积过大

Invalid GeoJSON Source

无效GeoJSON数据源

Unexpected Style Changes

意外样式变更

Integration with Development Workflow

与开发工作流集成

Git Pre-Commit Hook

Git 提交前钩子

Validate expressions before commit

Validate expressions before commit

Optimize before commit (optional)

Optimize before commit (optional)

CI/CD Pipeline

CI/CD 流水线

Code Review Checklist

代码审核清单

Best Practices Summary

最佳实践总结

Tool Quick Reference

工具速查

Additional Resources

额外资源