design-systems-slds-validate

SLDS 品質監査

Lightning Web Components の SLDS 準拠状況を監査し、自動スコアカードと必須の手動レビューゲートを生成します。SLDS リンターの出力に補足的な静的解析を組み合わせ、リンターが検出できない問題も見つけます。

対象範囲

以下にも有効です：プロジェクトまたはコンポーネントセット全体の SLDS 準拠状況の監査、変更を加えた後の品質比較。

対象外：

• リンター違反の修正 — 代わりに design-systems-slds2-migrate を使用してください
• 新しいコンポーネントの構築 — 代わりに design-systems-slds-apply を使用してください
• リンターを実行するだけ — npx @salesforce-ux/slds-linter@latest lint . を直接実行してください
• WCAG アクセシビリティの完全な監査 — このスキルが確認するのは属性の有無（ラベル、代替テキスト、フォーカスインジケーター）のみです。コントラスト比、キーボード操作の流れ、スクリーンリーダーの動作は確認しません
• .css、.html、.js ファイルを超えるフレームワーク固有のテンプレート監査 — JSX/TSX/Vue/Svelte の出力には、追加の手動レビューが必要です

---

品質検証プロセス

1. Run SLDS Linter     → Collect violation counts (linter's job)
2. Run Analyze Script  → Check what linter doesn't cover (supplementary)
3. Agent Review        → Required manual review gate
4. Score & Grade       → Compute automated score + final recommendation
5. Generate Report     → Produce formatted scorecard

ステップ 1：SLDS リンターを実行する

リンターを実行し、違反のベースラインデータを収集します。

npx @salesforce-ux/slds-linter@latest lint <component-path> 2>&1

ルールごとに違反数を数えます。これらの値は リンター準拠度スコアに直接反映されます。

ルール	影響
slds/class-override	テーマ設定とダークモードが機能しなくなります
slds/lwc-token-to-slds-hook	SLDS 1 の技術的負債になります
slds/no-hardcoded-values	テーマ設定とアクセシビリティが機能しなくなります

リンター準拠度スコア = 100 - (total_violations × 10)、最小値は 0 です。

リンターを利用できない場合（Node.js がない、ネットワークにアクセスできない、CI サンドボックスの制限がある場合）：このステップをスキップし、レポートのヘッダーに「リンター未実行」と記載して、リンター準拠度を N/A とし、残り 4 カテゴリーの比率を 100% に再調整して総合スコアを算出します。

Overall (linter unavailable) = (Theming × 0.29) + (Accessibility × 0.29)
                              + (CodeQuality × 0.21) + (ComponentUsage × 0.21)

ステップ 2：補足解析を実行する

解析スクリプトを実行し、リンターがカバーしていない問題を検出します。付属の解析ツールは .css、.html、.js ファイルのみをスキャンします。

node scripts/analyze-quality.cjs <component-path>

スクリプトは、重要度別に整理された検出結果を JSON 形式で出力します。確認項目は次のとおりです。

CSS チェック（リンターを補完）

チェック	検出する内容	重要度
フォールバックの欠落	フォールバック値のない var(--slds-g-*)	Critical
独自定義されたフック（T051）	hooks-index.json にない --slds-g-* トークン（--hooks-index が必要）	Critical
フックのペア	対応する前景フックのない背景フック	Warning
!important	詳細度の上書き	Warning
マジックピクセル値	スペーシングフックを使用していないハードコードの px	Warning
大きすぎる z-index	99 を超える z-index 値	Warning
アウトラインの削除	代替のフォーカススタイルがない outline: none	Warning

JS チェック

チェック	検出する内容	重要度
インラインスタイルの代入	.style.*= によるプロパティへの直接代入	Warning
SLDS クラスの操作	動的な .classList.add('slds-*') による操作	Warning

HTML チェック

チェック	検出する内容	重要度
LBC 入力ラベル	label 属性のない <lightning-input>	Critical
アイコンの代替テキスト	alternative-text のない <lightning-icon>	Critical
画像の代替テキスト	alt のない <img>	Critical
見出しの階層	見出しレベルの飛び（h2 から h4 など）	Warning
正の tabindex	0 または -1 以外の tabindex 値	Warning
クリック可能な div	<button> ではなく <div onclick> を使用	Warning
インラインスタイル	style="..." 属性	Warning
ネイティブ要素	LBC の代替要素がある場合の <input>、<button>、<select>	Warning

フックペアの検証

スクリプトは、背景フックと前景フックが意味的にペアになっているかを確認します。

surface-* backgrounds     → on-surface-* text
surface-container-* bg    → on-surface-* text
accent-* backgrounds      → on-accent-* text
accent-container-* bg     → on-accent-* text

制限事項： フックのペアはセレクターごとではなく、ファイル単位で確認されます。.classA に surface-1 があり、.classB に on-accent-1 があるファイルは、surface ファミリーと accent ファミリーの両方が含まれるため、チェックを通過します。ステップ 3 の手動レビューで、セレクターごとにペアが正しいか確認してください。

フックの誤作成の検出（T051）

このスクリプトは、CSS 内のすべての --slds-g-* トークンを hooks-index.json と照合します。メタデータに見つからないフックは重大な問題としてフラグ付けされます。これにより、命名パターンからフックを作り出すという、エージェントによくある誤りを検出できます。

ステップ 3：エージェントによる手動レビュー

これらのチェックにはコンポーネントの目的を理解する必要があり、確実な自動化はできません。それぞれをレビューし、問題を次のいずれかに分類してください。

• ブロッキング — ブループリント構造の誤り、必須状態の不足、またはコンポーネントが本番運用に適さない状態にする意味上・インタラクション上の問題
• 参考事項 — 改善する価値はあるものの、それだけではリリースを妨げないもの

レビュー領域	確認する内容
ローディング状態	データ取得中にスピナーまたはスケルトンを表示しますか？
エラー状態	ユーザーに、対処可能なメッセージとともにエラーを提示していますか？
空の状態	データがない場合に、意味のある空の状態を表示していますか？
無効状態	インタラクティブな要素は、無効状態を見た目と機能の両面で適切に処理していますか？
セマンティック HTML	適切な箇所で <nav>、<article>、<section> を使用していますか？
SLDS ブループリントへの準拠	カード、モーダル、フォームは SLDS ブループリントの構造に従っていますか？

手動レビューの結果は自動化されませんが、最終的な推奨事項には影響します。自動評価だけを最終判断として報告しないでください。

ステップ 4：自動スコアと最終的な推奨事項を算出する

コンポーネントの複雑さ

スコアを算出する前に、スコアの背景を示すため、コンポーネントを分類してください。

複雑さ	基準	レポートの注記
小規模	1～2 ファイル、合計 100 行未満	スコアの信頼度が高い（対象範囲が小さい）
中規模	3～6 ファイル、合計 100～500 行	一般的なコンポーネントを反映したスコア
大規模	7 ファイル以上、合計 500 行以上	問題の絶対数を反映したスコア。適切に構築された大規模コンポーネントでも、スコアが低くなる場合があります

レポートのヘッダーに複雑さの分類を含めてください。これにより、1000 行のコンポーネントの「B」と 20 行のコンポーネントの「B」を誤って同等に解釈するのを防げます。

自動スコアの計算式

Category Score = 100 - (critical_issues × 10) - (warnings × 3) - (info × 1)
Minimum score: 0

カテゴリーと重み

カテゴリー	重み	参照元
リンター準拠	30%	SLDS リンターの出力（ステップ 1）
テーマ設定	20%	スクリプト：フォールバック、フックの対応付け（ステップ 2）
アクセシビリティ	20%	スクリプト：ラベル、代替テキスト、フォーカス（ステップ 2）
コード品質	15%	スクリプト：!important、インラインスタイル、z-index（ステップ 2）
コンポーネントの使用状況	15%	スクリプト：ネイティブ要素（ステップ 2）、およびセマンティクス／ブループリントの手動レビュー（ステップ 3）

自動総合スコア

Overall = (Linter × 0.30) + (Theming × 0.20) + (Accessibility × 0.20)
        + (CodeQuality × 0.15) + (ComponentUsage × 0.15)

自動評価のグレード基準

スコア	グレード	意味
90-100	A	自動評価で優秀
80-89	B	自動評価で良好
70-79	C	自動評価で許容範囲
60-69	D	自動評価で弱い
0-59	F	自動評価で不合格

手動レビューの判定基準

自動スコアを算出した後、手動レビューの結果を適用します。

判定	適用する状況	最終的な推奨事項への影響
合格	手動レビューで問題が見つからない	最終的な推奨事項は自動スコアに従います
参考事項あり	ブロッキングではない手動レビューの問題のみ	最終的な推奨事項は、最良でも「フォローアップありで準備完了」となります
ブロッキング	ブロッキングに該当する問題が 1 件以上ある	自動グレードにかかわらず、最終的な推奨事項は 本番運用の準備ができていません となります

最終的な推奨事項のルール

自動スコアと手動レビューの判定基準の両方を使用してください。

最終的な推奨事項	条件
本番運用の準備完了	自動グレードが A/B、重大な問題がなく、手動レビュー判定が合格
フォローアップありで準備完了	自動グレードが A/B、重大な問題がなく、手動レビュー判定が参考事項あり
要修正	重大な問題がある、自動グレードが C/D、または手動レビュー判定がブロッキング
不合格	自動グレードが F

Step 5: 品質レポートの生成

report-format.md のテンプレートを使用して、最終レポートを作成します。初回の出力では、デフォルトでコンパクト形式を使用し、依頼に応じて各セクションを詳しく説明します。

レポートには以下が含まれます：

• 自動評価と最終的な推奨事項を含むエグゼクティブサマリー
• 手動レビューゲートの結果（Pass、Advisory、またはBlocking）
• 視覚的なインジケーター付きのカテゴリ別スコア
• 重大度別に整理された詳細な調査結果
• 具体的なコードの場所と推奨事項
• 必須アクションのチェックリスト

---

クイック検証モード

完全な分析を行わずに迅速に品質を確認するには：

1. リンターを実行します：npx @salesforce-ux/slds-linter@latest lint <path>
2. 種類ごとに違反の数を集計します
3. 概要のみを報告します

Quick Quality Check: <component-name>
─────────────────────────────────────
Linter Violations:
  • Class Override:     0
  • Deprecated Tokens:  3
  • Hardcoded Values:   5

Quick Automated Grade: C (estimated)
Run full validation for detailed report.

---

エッジケースと誤検出

状況	ガイダンス
ヘッドレスコンポーネント（JS のみ、HTML なし）	HTML チェックを省略し、CSS とリンターのカテゴリのみを採点します
ラッパー／コンテナーコンポーネント	CSS が最小限でも問題ない場合があります。フックの使用率が低くても減点しないでください
意図的なネイティブ要素	カスタム SLDS ブループリント内の <button> は正しい使用方法です。slds-* ブループリント構造内にある場合は C002 を抑制します
LEX 以外のコンポーネント	LWR／Experience Cloud のコンポーネントでは Lightning Base Components を使用しない場合があります。レポートにコンテキストを記載してください
テスト／デモ用コンポーネント	基準を緩和します。レポートには記載しますが、警告を理由にブロックしないでください

チェックで誤検出が発生した場合は、黙って除外せず、理由を添えてレポートに「suppressed」と記載してください。

---

参考資料

• 品質チェック - 検出パターンを含む、すべての品質チェックの完全な一覧
• レポート形式 - 品質レポートのテンプレートと書式ガイド
• 分析スクリプト - リンターを補完するチェックを自動分析します
• design-systems-slds2-migrate skill - リンター違反の修正方法
• design-systems-slds-apply skill - 正しいパターンで新しいコンポーネントを構築するためのガイド