design-systems-slds-apply

SLDS の適用

**Salesforce Lightning Design System（SLDS）**は、数千のアーティファクトを備えた CSS フレームワークです。このスキルでは、エージェントがアーティファクトを見つけ、正しく使用する方法を学びます。

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

**監査範囲：**付属の design-systems-slds-validate スキルアナライザーは、.css、.html、.js ファイルのみをスキャンします。LWC および類似の HTML/CSS/JS コンポーネントでは直接使用してください。JSX/TSX やその他のフレームワーク固有のテンプレート形式では、部分的な参考情報として扱い、手動レビューで補完してください。

SLDS とは？

アーティファクト	数	説明
Lightning Base Components	約70	事前構築済みの LWC コンポーネント（LWC のみ）
SLDS Blueprints	85	あらゆるフレームワークで使える CSS/HTML パターン
Styling Hooks	523	テーマ設定用の CSS カスタムプロパティ（--slds-g-*）
Utility Classes	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 Blueprint を選択してください。references/component-selection.md を参照してください。

---

基本ルール

すること

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

しないこと

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

---

フックの命名上の落とし穴

SLDS のフックファミリーは、すべてが同じ命名パターンに従うわけではありません。エージェントは {prefix}-{number} があらゆる場面で使えると思い込み、存在しないフックを頻繁に作り出します。使用する前に、付属の search-hooks.cjs スクリプトまたは assets/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>"	assets/hooks-index.json
ユーティリティクラス (slds-*)	node scripts/search-utilities.cjs --search "<class-name>"	assets/utilities-index.json
ブループリント / CSS クラス	node scripts/search-blueprints.cjs --search "<pattern>" を実行してから YAML を読む	assets/blueprints/components/*.yaml
アイコン	node scripts/search-icons.cjs --query "<description>"	assets/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"

詳細ガイド（詳しいルールを確認）

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

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

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

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

---

作成ワークフロー

フェーズ 1：必要なものを把握する

以下を確認します。

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

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

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

詳細：references/component-selection.md

フェーズ 3：スタイルを適用する

1. 読む：references/styling-decision-guide.md
2. 色：役割（surface、accent、feedback、border）を分類してから、フックを選びます
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-* フックが assets/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（任意）： コードレビューまたはデプロイ前にスコア付きレポートを作成するには、design-systems-slds-validate スキルを使って品質監査全体を実行します。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 を参照してください。

検証

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

リソース

リソース	URL
SLDS ウェブサイト	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