mapbox-style-quality

Mapbox スタイル品質スキル

このスキルでは、検証、アクセシビリティ、最適化ツールを通じて Mapbox スタイルの品質を確保するための専門的なガイダンスを提供します。

品質ツールを使用するタイミング

本番環境へのデプロイ前のチェックリスト

Mapbox スタイルを本番環境にデプロイする前に、次の項目を確認してください。

1. すべての式を検証する - 実行時にエラーが発生する前に構文エラーを検出します
2. 色のコントラストを確認する - テキストの読みやすさを確保します（WCAG 準拠）
3. GeoJSON ソースを検証する - データの整合性を確保します
4. スタイルを最適化する - ファイルサイズを縮小し、パフォーマンスを向上させます
5. バージョンを比較する - 変更内容を把握します
6. 空のレイヤーを削除する - 最終的なクリーンアップ手順として、表示可能な paint プロパティがないレイヤーを削除します
7. 冗長なブール式を簡素化する - 不要なブール論理を含むフィルターを整理します（例：["all", expr] → expr、["any", false, expr] → expr）

開発中

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）を使用します
• さまざまな背景の状況（マップタイル、オーバーレイ）を考慮します

変更をコミットする前

スタイルのバージョンを比較する：

• compare_styles_tool を使用して差分レポートを生成します
• すべてのレイヤーの変更、ソースの変更、式の更新を確認します
• 変更の影響を把握します
• 重要な変更をコミットメッセージに記録します

デプロイ前

スタイルを最適化する：

• optimize_style_tool を実行してファイルサイズを縮小します
• 削除済みのレイヤーを参照している未使用のソースを削除します
• プロパティが同一の重複レイヤーを削除します
• フィルター内の冗長なブール式を簡素化します（例：["all", expr] を expr にまとめる、恒真条件を削除する）
• 最終的なクリーンアップ手順として、空のレイヤー（表示可能な paint プロパティがないレイヤー）を削除します

検証のベストプラクティス

GeoJSON の検証

次の場合は必ず検証します：

• ユーザーがアップロードした 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

式の検証

次の式を検証します：

• フィルター条件（レイヤーの filter プロパティ）
• データ駆動型のスタイリング（paint および layout プロパティ）
• フィーチャー状態の式
• 動的なプロパティの計算

よくある式のエラー：

• 型の不一致（数値に文字列用の演算子を使用する）
• 演算子名が無効、または構文が誤っている
• 演算子の引数の数が誤っている
• ネストされた式のエラー
• 使用している GL JS のバージョンで利用できない演算子を使用している

予防策：

• 実行時ではなく、式を記述しながら検証します
• 代表的なデータで式をテストします
• 型チェックを使用します（expectedType パラメーター）
• コンテキスト（レイヤー、フィルター、paint、layout）内で検証します

アクセシビリティの検証

WCAG レベル：

• AA（最低基準）：通常のテキストは 4.5:1、大きなテキストは 3:1
• AAA（強化基準）：通常のテキストは 7:1、大きなテキストは 4.5:1

テキストサイズの分類：

• 通常：18pt 未満、または太字で 14pt 未満
• 大きい：18pt 以上、または太字で 14pt 以上

確認すべき一般的なシナリオ：

• マップタイル上のテキストラベル
• 背景色付きの POI ラベル
• テキスト付きのカスタムマーカー
• マップ上の UI オーバーレイ
• 凡例のテキストと記号
• 帰属表示テキスト

テスト戦略：

• 明るいマップタイルと暗いマップタイルの両方でテストします
• オーバーレイの背景（ポップアップ、モーダル）を考慮します
• さまざまな照明条件（屋外でのモバイル利用）でテストします
• ズームレベルを変えてコントラストを確認します

品質ワークフローの例

基本的な品質チェック

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

本番前の完全なワークフロー

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. 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

よくある問題と解決策

実行時の式エラー

問題： マップで実行時に式エラーが発生します
解決策： 開発中に validate_expression_tool で式を検証します
予防策： 式の検証を pre-commit フックまたは CI/CD に追加します

テキストの視認性が低い

問題： マップ上のテキストラベルが読みにくいです
解決策： check_color_contrast_tool でコントラストを確認し、WCAG AA を満たすように色を調整します
予防策： 明るい背景と暗い背景の両方でテキストをテストし、ズームレベルを変えて確認します

スタイルファイルのサイズが大きい

問題： スタイルの読み込みや転送に時間がかかります
解決策： optimize_style_tool を実行して重複を取り除き、簡素化します
予防策： 開発中に定期的に最適化し、未使用のソースはすぐに削除します

無効な GeoJSON ソース

問題： GeoJSON ソースの読み込みまたは描画に失敗します
解決策： validate_geojson_tool で検証し、座標の問題を修正して、構造を確認します
予防策： 外部の GeoJSON はすべて、スタイルに追加する前に検証します

予期しないスタイルの変更

問題： スタイルが変更されましたが、何が変更されたのかわかりません
解決策： compare_styles_tool を使って差分レポートを生成します
予防策： 重要な変更はすべて変更前後を比較し、変更内容を記録します

ツールのクイックリファレンス

ツール	使用する場面	出力
validate_geojson_tool	GeoJSON ソースの追加時	有効／無効とエラー一覧
validate_expression_tool	式の記述時	有効／無効とエラー一覧
check_color_contrast_tool	テキストラベルのスタイル設定時	合格／不合格と WCAG レベル
compare_styles_tool	変更のレビュー時	パス付きの差分レポート
optimize_style_tool	デプロイ前	最適化されたスタイルと削減量

参考ファイル

特定のトピックについて詳しく知りたい場合は、該当する参考ファイルを読み込んでください。

• references/optimization.md — 最適化の種類、戦略、推奨順序、メンテナンスのベストプラクティス
• references/comparison.md — スタイル比較のワークフロー、ignoreMetadata の使い方、リファクタリングのワークフロー
• references/ci-integration.md — Git の pre-commit フック、CI/CD パイプラインの手順、コードレビューのチェックリスト

読み込み手順： ユーザーがそのトピックについて詳しいガイダンスを必要とする場合は、参考ファイルを読み込んでください。

追加リソース

• Mapbox スタイル仕様
• WCAG 2.1 ガイドライン
• GeoJSON 仕様（RFC 7946）
• Mapbox 式リファレンス