applying-slds

SLDS の適用

**Salesforce Lightning Design System（SLDS）**は、数千もの成果物を備えた CSS フレームワークです。このスキルでは、それらを見つけて正しく使用する方法をエージェントに教えます。

バージョン： このスキルは SLDS v2 を対象としています。旧式の --lwc-* トークンと slds-*--modifier 構文は非推奨です。

監査範囲： 付属の validating-slds スキルアナライザーは、.css、.html、.js ファイルのみをスキャンします。LWC や同様の HTML/CSS/JS コンポーネントではそのまま使用してください。JSX/TSX やその他のフレームワーク固有のテンプレート形式では部分的な指標として扱い、手動レビューで補完してください。

SLDS とは？

成果物	数	説明
Lightning ベースコンポーネント	~70	事前構築済みの LWC コンポーネント（LWC のみ）
SLDS ブループリント	85	あらゆるフレームワークで使える CSS/HTML パターン
スタイリングフック	523	テーマ設定用の CSS カスタムプロパティ（--slds-g-*）
ユーティリティクラス	1,147	余白、レイアウト、表示状態をすばやく設定するクラス
アイコン	1,732	5 つのカテゴリにわたる SVG アイコン

---

対象範囲

このスキルで扱う内容：

• 指定された UI パターンに使用するブループリント
• フックを使用したスタイル設定方法（色、余白、タイポグラフィ、シャドウ、境界線）
• レイアウト、余白、表示状態に使用するユーティリティクラス
• 使用するアイコンとそのカテゴリ
• SLDS の命名規則、クラス構造、フックの構文

このスキルには基本的なアクセシビリティに関する注意事項（アイコンの代替テキスト、フォーカスアウトライン、色だけを唯一の識別手段にしないこと）が検証チェックリストに含まれています。WCAG への完全な準拠には、専用のアクセシビリティレビューが必要です。

このスキルでは扱わない内容（付属スキルを使用してください）：

• デザイン上の判断 -- 視覚的な階層、構成、インタラクションパターン
• LWC の仕組み -- コンポーネント構造、@wire、@api、ライフサイクル、イベント（現在は利用できません）
• アクセシビリティ全般 -- WCAG 準拠、ARIA パターン、キーボード操作、フォーカス管理、コントラスト比（現在は利用できません）

---

コンポーネント選択の優先順位

必ず次の順序に従ってください。

1. Lightning Base Components (LWC only)    ← Check first
2. SLDS Blueprints (any framework)         ← Use exact SLDS classes
3. Custom with Styling Hooks               ← Use var(--slds-g-*)
4. Custom CSS (last resort)                ← Still use hooks for values

LWC で開発する場合は、最初に LBC を確認してください：Lightning Component Library

LBC が存在しない場合（または LWC を使用しない場合）は、SLDS ブループリントを選択してください。references/component-selection.md を参照してください。

---

基本ルール

すること

• 選択の優先順位に従う：LBC > ブループリント > フック > カスタム CSS
• テーマ設定が可能な値にはすべて var(--slds-g-*, fallback) を使用する
• .slds-* を上書きするのではなく、カスタムクラス（my-*、c-*）を作成する
• 使用前に、すべてのフック、クラス、ユーティリティが存在することを確認する — 検索スクリプトを実行してください。命名パターンから成果物の存在を推測してはいけません（使用前に確認するを参照）
• サーフェスの色と、その上に表示するテキストの色を組み合わせる
• すべての <lightning-icon> に alternative-text を指定する

しないこと

• 色、余白、タイポグラフィの値をハードコードする
• .slds-* クラスを直接上書きする
• 非推奨の --lwc-* トークンを主要な値として使用する
• --slds-s-*（共有）フックを使用する -- これらは非公開／内部用です
• フックの値を再割り当てする -- var() で参照する場合にのみ使用する
• 意味を色だけで伝える
• 他のファミリーのパターンから補間してフック名を作り出す（以下の「命名上の注意点」を参照）

---

フックの命名上の注意点

SLDS のフックファミリーは、すべて同じ命名パターンに従うわけではありません。エージェントは、{prefix}-{number} がどこでも通用すると仮定し、存在しないフックを作り出しがちです。使用前に、付属の search-hooks.cjs スクリプトまたは metadata/hooks-index.json で、フックが存在することを必ず確認してください。

落とし穴 1: フォントサイズのフックには番号が付かない

誤り（存在しない）	正しい	備考
--slds-g-font-size-3	--slds-g-font-scale-1	フォントサイズは font-size-* ではなく font-scale-* を使用します
--slds-g-font-size-4	--slds-g-font-scale-2	存在するのは --slds-g-font-size-base（基本サイズ）のみです
--slds-g-font-size-8	--slds-g-font-scale-6	スケールの範囲は neg-4 から 10 までです

ルール: フォントサイズには、--slds-g-font-size-base（唯一の基本サイズ）または --slds-g-font-scale-*（番号付きスケール）を使用します。--slds-g-font-size-N は決して使用しないでください。

落とし穴 2: カラーのフックには常に番号が必要

誤り（存在しない）	正しい	備考
--slds-g-color-on-surface	--slds-g-color-on-surface-2	すべてのカラーフックには番号が必要です
--slds-g-color-on-accent	--slds-g-color-on-accent-1	強調レベルに応じて 1/2/3 を選択します
--slds-g-color-surface	--slds-g-color-surface-1	番号なしの基本形はありません

ルール: すべての --slds-g-color-* フックは番号で終わります。強調レベルで選択します: -1（低）、-2（中）、-3（高）。

落とし穴 3: すべての値にフックの相当品があるわけではない

一部の CSS 値（例: ラベルの位置合わせのための min-width: 7rem）には SLDS フックがありません。これは許容されます:

.c-field-label {
  /* No SLDS hook exists for this width; intentional custom value */
  min-width: 7rem;
}

ルール: フックが存在しない場合は、意図的であることを説明するコメントを付けて値を直接使用します。可能な限り、ハードコードされた幅の代替として SLDS グリッドユーティリティ（slds-size_*）を優先してください。

---

使用前の検証

ルール: 生成されたコードに SLDS フック、ユーティリティクラス、ブループリントクラス、またはアイコンを含める前に、それがメタデータに存在することを必ず確認してください。命名パターンに基づく推測は、存在しない成果物をでっち上げる主な原因です。

SLDS の成果物を出力する前に、適切な検索コマンドを実行してください:

成果物	検証コマンド	信頼できる情報源
スタイリングフック（--slds-g-*）	node scripts/search-hooks.cjs --prefix "<hook-name>"	metadata/hooks-index.json
ユーティリティクラス（slds-*）	node scripts/search-utilities.cjs --search "<class-name>"	metadata/utilities-index.json
ブループリント / CSS クラス	node scripts/search-blueprints.cjs --search "<pattern>" を実行してから YAML を読み取ります	metadata/blueprints/components/*.yaml
アイコン	node scripts/search-icons.cjs --query "<description>"	metadata/icon-metadata.json

検索で一致するものが返らない場合: その成果物を使用しないでください。 検索結果から代替を見つけるか、検証済みのフックを使ってカスタムで構築してください。

---

命名規則

SLDS との衝突を避けるため、カスタムクラスには一貫したプレフィックスを使用してください:

パターン	用途	例
my-*	一般的なカスタムスタイリング	my-card-header
c-*	LWC コンポーネント固有	c-accountList-row
[namespace]-*	パッケージ / アプリの名前空間	acme-dashboard-widget

避けるべきもの: 一般的な名前（container、wrapper）、SLDS に似た名前（custom-slds-button）、SLDS クラスへの BEM 適用（slds-card__custom-header）。

カスタムフックの名前空間:

:root {
  --my-app-primary: var(--slds-g-color-accent-1);
  --my-app-card-padding: var(--slds-g-spacing-4);
}

---

ナレッジマップ

このスキルは包括的な SLDS のナレッジをバンドルしています。ファイルは必要に応じて読んでください -- 最初にすべてを読む必要はありません。

判断ガイド（各タスクはここから始めます）

ファイル	読むタイミング
references/component-selection.md	コンポーネントまたはブループリントを選択するとき
references/styling-decision-guide.md	色、間隔、タイポグラフィ、影を適用するとき
references/icons-decision-guide.md	アイコンを選択または実装するとき
references/utilities-quick-ref.md	レイアウト / 間隔にユーティリティクラスを使用するとき

スクリプトの検索（特定のアーティファクトを検索）

スクリプト	検索対象	例
scripts/search-blueprints.cjs	85 個のブループリント YAML	--search "dialog"
scripts/search-hooks.cjs	523 個のスタイリングフック	--prefix "--slds-g-color-accent-"
scripts/search-icons.cjs	同義語付きの 1,732 個のアイコン	--query "save button"
scripts/search-utilities.cjs	1,147 個のユーティリティクラス	--category "grid"

詳細ガイダンス（詳しいルールを確認）

フォルダー	内容	インデックス
guidance/overviews/	基本概念（色、余白、タイポグラフィなど）	guidance/README.md
guidance/styling-hooks/	詳細な使用方法を含むフックのカテゴリー	guidance/README.md
guidance/utilities/	27 個のユーティリティクラスのカテゴリー	guidance/README.md
guidance/slds-development-guide.md	SLDS 開発ガイド全編	--

生のメタデータ（検索用の構造化データ）

メタデータの JSON ファイルを直接読み込まないでください — エージェントのコンテキストには大きすぎます（hooks-index.json は 6,000 行以上、icon-metadata.json は 38,000 行以上です）。上記の検索スクリプトを使って検索してください。

ファイル	内容	行数
metadata/blueprints/components/*.yaml	85 個のブループリント仕様（クラス、バリエーション、アクセシビリティ、HTML）	それぞれ約 50～200 行
metadata/hooks-index.json	値と CSS プロパティを含む 523 個のフック	約 6,300 行
metadata/icon-metadata.json	検索用の同義語を含む 1,732 個のアイコン	約 38,500 行
metadata/utilities-index.json	CSS ルールを含む 1,147 個のユーティリティクラス	約 6,900 行

---

作成ワークフロー

フェーズ 1：ニーズを把握する

以下を特定します。

• 必要な UI パターンは何ですか？（フォーム、テーブル、モーダル、カードなど）
• 使用するフレームワークは何ですか？（LWC、React、Vue、Angular、バニラ）
• どのようなデータを表示しますか？
• 必要な状態は何ですか？（読み込み中、空、エラー、成功）

フェーズ 2：アーティファクトを選択する

1. LWC の場合：Lightning Component Library で LBC を確認します
2. ブループリントを検索する：node scripts/search-blueprints.cjs --search "<pattern>"
3. ブループリント YAML を読む：正確なクラス、修飾子、状態、アクセシビリティ要件について、metadata/blueprints/components/<name>.yaml を確認します
4. 一致するものがない場合：フックを使ってカスタムで作成します（フェーズ 3 を参照）

詳細：references/component-selection.md

フェーズ 3：スタイリングを適用する

1. 読む：references/styling-decision-guide.md
2. 色：役割（サーフェス、アクセント、フィードバック、ボーダー）を分類し、フックを選びます
3. 余白：ユーティリティクラス（slds-p-*、slds-m-*）またはフック（--slds-g-spacing-*）を使います
4. レイアウト：グリッドユーティリティ（slds-grid、slds-col、slds-size_*）を使います
5. カスタム CSS：var(--slds-g-*, fallback) を使い、カスタムクラスのプレフィックスのみを指定します

フェーズ 4：アイコンを追加する

1. 読む：references/icons-decision-guide.md
2. 検索する：node scripts/search-icons.cjs --query "<description>"
3. LWC の場合：alternative-text を指定して <lightning-icon> を使います
4. LWC 以外の場合：slds-icon クラスと slds-assistive-text を使った SVG を使います

フェーズ 5：検証（必須 — 省略しないでください）

ステップ 1：SLDS リンターを実行します。 これは必須です。違反ゼロを目指してください。

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

リンターは、ハードコードされた値、クラスのオーバーライド、非推奨のトークンを検出します。先に進む前に、すべての違反を修正してください。 違反を許容可能なものとして正当化しないでください。

ステップ 2：独自に作成したフックがないことを確認します。 出力内のすべての --slds-g-* フックが metadata/hooks-index.json に存在することを確認します。checklists.md の T051 のチェック項目と照合してください。

ステップ 3：checklists.md に沿って、リンターでは自動化できない項目を確認します。

• すべての var(--slds-g-*) にフォールバック値が設定されている（T002）
• サーフェス／アクセント／フィードバックのカラー用フックが適切に組み合わされている（T010–T013）
• スペーシングにはフックまたはユーティリティクラスを使用し、マジックナンバーの px 値を使用していない（T020–T021）
• フォントサイズには --slds-g-font-size-N ではなく --slds-g-font-scale-* を使用している（T031）
• すべてのアイコンにアクセシビリティ用テキストが設定されている（A004）
• カスタムクラスに my-* または c-* のプレフィックスを使用している（Q010）

ステップ 4（任意）： validating-slds スキルを使用して完全な品質監査を実行し、コードレビューまたはデプロイ前にスコア付きレポートを確認します。LWC／HTML-CSS-JS コンポーネントではそのまま使用します。JSX/TSX の出力では、結果を部分的なカバレッジとして扱ってください。作業完了とする前に、B 評価（≥80）以上を目指してください。

---

クイックリファレンス

よくあるフックのパターン

/* Surface + text pairing (always use numbered variants) */
background: var(--slds-g-color-surface-1, #ffffff);
color: var(--slds-g-color-on-surface-2, #181818);

/* Standard padding */
padding: var(--slds-g-spacing-4, 1rem);

/* Card-like container */
border-radius: var(--slds-g-radius-border-2, 0.25rem);
box-shadow: var(--slds-g-shadow-1, 0 2px 4px rgba(0,0,0,0.1));

/* Accent for primary actions */
background: var(--slds-g-color-accent-1, #0176d3);
color: var(--slds-g-color-on-accent-1, #ffffff);

/* Typography -- use font-scale-*, NOT font-size-* (only font-size-base exists) */
font-size: var(--slds-g-font-scale-2, 0.875rem);

よくあるユーティリティのパターン

<div class="slds-grid slds-wrap slds-gutters">
  <div class="slds-col slds-size_1-of-1 slds-medium-size_1-of-2">...</div>
</div>


<div class="slds-p-around_medium slds-m-bottom_small">...</div>


<p class="slds-truncate" title="Full text here">Full text here</p>

---

例

意図から SLDS アーティファクトの選択に至るまでの完全なワークフローを示す実例については、examples.md を参照してください。

検証

validating-slds スキルに沿った検証チェックリストについては、checklists.md を参照してください。

リソース

リソース	URL
SLDS の Web サイト	https://www.lightningdesignsystem.com/
Lightning コンポーネントライブラリ	https://developer.salesforce.com/docs/component-library/overview/components
SLDS リンター	https://developer.salesforce.com/docs/platform/slds-linter/guide
スタイリングフックのリファレンス	https://www.lightningdesignsystem.com/2e1ef8501/p/591960-global-styling-hooks