validating-slds

SLDS 品質監査

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

対象範囲

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

対象外：

• リンター違反の修正 — 代わりに uplifting-components-to-slds2 を使用してください
• 新しいコンポーネントの構築 — 代わりに applying-slds を使用してください
• リンターの実行のみ — 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

ステップ 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 を使用しない場合があります。レポートにコンテキストを記載してください
テスト／デモ用コンポーネント	基準を緩めてください。レポートには記載しますが、警告を理由にブロックしないでください

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

---

参考資料

• 品質チェック - 検出パターンを含むすべての品質チェックの一覧
• レポート形式 - 品質レポートのテンプレートと書式ガイド
• 分析スクリプト - リンターを補完するチェックを自動分析します
• uplifting-components-to-slds2 スキル - リンター違反の修正方法
• applying-slds スキル - 正しいパターンで新しいコンポーネントを作成するためのガイド