uplifting-components-to-slds2

目標

SLDS リンターと体系的なガイダンスを活用し、すべてのスタイリングフックカテゴリにわたる違反の修正を支援して、Lightning Web Components を SLDS 1 から SLDS 2 へ段階的に移行します。

SLDS 2 のスタイリングフックカテゴリ

カテゴリ	フックのプレフィックス	置き換えるもの
色	--slds-g-color-*	ハードコードされた色、--lwc-color* トークン
余白	--slds-g-spacing-*	ハードコードされたマージン、パディング、間隔
サイズ	--slds-g-sizing-*	ハードコードされた幅、高さ、寸法
タイポグラフィ	--slds-g-font-*	ハードコードされたフォントサイズ、太さ、行の高さ
ボーダー／角丸	--slds-g-radius-border-*, --slds-g-sizing-border-*	ハードコードされた border-radius、border-width
シャドウ	--slds-g-shadow-*	ハードコードされた box-shadow の値

色のフックは、コンテキストに応じた選択が必要なため、最も慎重な判断を要します。色以外のフックは、ほとんどが番号付きスケールで、対応関係も明確です。

前提条件

• Node.js 14.x 以降がインストールされていること
• コンポーネントの CSS ファイルとマークアップファイル（LWC の場合は .html、Aura の場合は .cmp）にアクセスできること
• リンターを実行するためのターミナル／コマンドラインへのアクセス
• バックアップ用の Git リポジトリ（推奨）

---

ワークフロー

1. **REQUIRED — ALWAYS run first:** npx @salesforce-ux/slds-linter@latest lint --fix . — NEVER skip this step. This handles simple violations automatically.
2. Review linter output -> Identify remaining manual fixes needed
3. Fix by violation type -> Use per-rule reference guides
4. Choose the right hook -> Context-first, inspect HTML before deciding
5. Validate -> Re-run linter and confirm zero errors

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

必須：このステップは省略できません。

npx @salesforce-ux/slds-linter@latest lint --fix .

リンターはすべての CSS ファイルとマークアップファイル（LWC の場合は .html、Aura の場合は .cmp）を解析し、単純な違反を自動修正したうえで、手動での対応が必要な残りの問題を報告します。

ステップ 2：リンターの出力を分析する

リンターは次の形式で違反を報告します。

componentName.css
  15:3  warning  Overriding slds-button isn't supported. To differentiate SLDS and
                 custom classes, create a CSS class in your namespace.
                 Examples: myapp-input, myapp-button.                        slds/no-slds-class-overrides

  23:5  error    The '--lwc-colorBackground' design token is deprecated. Replace it with
                 the SLDS 2 styling hook and set the fallback to '--lwc-colorBackground'.
                 1. --slds-g-color-surface-2
                 2. --slds-g-color-surface-container-2                      slds/lwc-token-to-slds-hook

  30:8  warning  Consider replacing the #ffffff static value with an SLDS 2 styling hook
                 that has a similar value:
                 1. --slds-g-color-surface-1
                 2. --slds-g-color-surface-container-1
                 3. --slds-g-color-on-accent-1
                 4. --slds-g-color-on-accent-2
                 5. --slds-g-color-on-accent-3                              slds/no-hardcoded-values-slds2

  31:15  error   Consider removing t(fontSizeMedium) or replacing it with
                 var(--slds-g-font-size-base, var(--lwc-fontSizeMedium, 0.8125rem)).
                 Set the fallback to t(fontSizeMedium). For more info, see
                 Styling Hooks on lightningdesignsystem.com.               slds/no-deprecated-tokens-slds1

違反の種類は 4 つあり、それぞれに固有の修正方法があります（ステップ 3 を参照）。

重要：リンターはハードコードされた値をすべて検出します。色、余白、サイズ、タイポグラフィ、ボーダー、シャドウの値は修正しますが、レイアウト値（100%、auto、0、inherit、none）は対象外にします。修正する値と対象外にする値の完全な振り分け表は、rule-no-hardcoded-values.md を参照してください。

ステップ 3：種類ごとに違反を修正する

各ルールには、詳細な例と判断ロジックを記載した専用のリファレンスガイドがあります。

違反ルール	概要	リファレンス
slds/no-hardcoded-values-slds2	ハードコードされた値を、SLDS フックと元の値をフォールバックとして使う形に置き換えます	rule-no-hardcoded-values.md
slds/lwc-token-to-slds-hook	--lwc-* トークンを SLDS 2 フックに置き換え、LWC トークンはフォールバックとして残します	rule-lwc-token-to-slds-hook.md
slds/no-slds-class-overrides	コンポーネント名をプレフィックスにしたクラスを作成し、SLDS クラスと併せてマークアップに追加します	rule-no-slds-class-overrides.md
slds/no-deprecated-tokens-slds1	古い t()／token() 構文を、SLDS 2 フックと LWC フォールバックに置き換えます	rule-no-deprecated-tokens-slds1.md

必ずフォールバック値を含めてください — var(--slds-g-hook, originalValue) の originalValue には、元の CSS にある値をそのまま指定します。

クラスのオーバーライド：クイックリファレンス

クラスのオーバーライドには、CSS とマークアップ（.html または .cmp）の両方を変更する必要があります。この手順は最も見落とされやすいため、注意してください。

1. CSS：.slds-* セレクターを {componentName}-{sldsElementPart}（キャメルケース）に変更します
2. マークアップ：新しいクラスを SLDS クラスと併せて追加します — SLDS クラスは削除しないでください

/* Before */ .slds-button { border-radius: 8px; }
/* After */  .myComponent-button { border-radius: 8px; }

 <button class="slds-button myComponent-button">Click</button>

子孫セレクター、複数クラスのセレクター、命名規則については、rule-no-slds-class-overrides.md を参照してください。

ステップ 4: 適切なフックを選択する

カラーフックはコンテキストに基づく選択が必要です。必須: 違反に色プロパティ(color、background-color、background、fill、border-color)が関与する場合、フックを選択する前に必ず color-hooks-decision-guide.md を読む必要があります。 リンターは使用可能なフックを特定の順序なしで列挙します — 最初の候補を選んではいけません。このガイドには、正しいフックを決定するプロパティベースのルールが含まれています。

非カラーフックはよりシンプルです — CSS の値を番号付きスケールに一致させます。スペーシング、サイズ、タイポグラフィ、ボーダー、角丸、シャドウをカバーする値からフックへの参照表については、non-color-hooks-decision-guide.md を参照してください。

ステップ 5: 検証と確認

リンターフィードバックループ — エラーがゼロになるまで繰り返します:

1. npx @salesforce-ux/slds-linter@latest lint .
2. Review errors -> fix by type (Step 3)
3. Re-run linter
4. Repeat until output shows: 0 errors

---

検証

• CSS セレクターに .slds-* クラスが含まれていない
• SLDS 2 の代替がない var(--lwc-*) トークンが含まれていない
• すべてのフックにフォールバック値が含まれている
• 背景色/前景色のフックが同じファミリーのものである
• 元の SLDS クラスが HTML 内で保持されている
• スペーシングに番号付きフックを使用している(名前付きの spacing-medium などではない)
• タイポグラフィに番号付きフックを使用している(名前付きの font-weight-bold などではない)
• コンポーネントがライトモード/ダークモードおよび密度設定で正しくレンダリングされる

完全な検証チェックリストについては、migration-checklist.md を参照してください。

---

出力

SLDS リンター違反がゼロの、完全に移行された CSS(およびクラスオーバーライドが修正された更新済み HTML マークアップ)を返してください。すべてのスタイリングフックには、元の CSS 値を保持するフォールバック値を含める必要があります。

---

高度なパターン

透明度のための Color-Mix

ハードコードされた値が rgba() や透明度を使用している場合、SLDS フックとともに color-mix() を使用して不透明度を保持します:

/* Before */
border-color: rgba(186, 5, 23, 0.7);

/* After — use oklab color space for perceptual consistency */
border-color: color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);

計算式: X% の不透明度を実現するには、color-mix で (100 - X)% の透明を使用します。

• 70% の不透明度 → transparent 30%
• 50% の不透明度 → transparent 50%

フォールバックとして不透明な rgb()(rgba() ではなく)を使用してください — 透明度は color-mix が処理します。

トークンを使用した calc() 式

t('calc(...)') や非推奨トークンを含む calc() を移行する場合:

/* Before — Aura t() with calc */
height: t('calc(' + lineHeightButton + ' + 2px)');

/* After — if calc is still needed */
height: calc(var(--lwc-lineHeightButton) + 2px);

/* After — if calc was unnecessary, simplify */
height: var(--lwc-lineHeightButton);

--lwc-* トークンが置き換えられる calc() の場合:

/* Before */
padding: calc(var(--lwc-spacingMedium) + 4px);

/* After */
padding: calc(var(--slds-g-spacing-4, var(--lwc-spacingMedium)) + 4px);

ヒント: 多くの場合、calc() は不要であり、簡略化できます。結果が既存のフックの値と一致するか確認してください。

---

主要な制約

• フック名を勝手に考案しない — SLDS デザインシステムに文書化されているフックのみを使用してください
• 常にフォールバック値を含める — フォールバックは、ソース CSS の正確な元の値でなければなりません
• ハードコードされた数値を決して変更しない — 100%、50%、200px、1.5、auto、0、inherit、none、flex: 1 などの値は構造的/レイアウト上の値です。これらをフックに置き換えたり削除したりしないでください — これらはスタイリングフックの候補ではありません
• 完全一致しない場合はそのままにする — ハードコードされた値がどのフックのレンダリング値にも近く対応しない場合は、無理に合わせるのではなく変更せずにそのままにしてください
• フック番号を元の値の強度に一致させる — デフォルトで -1 にしないでください。元の値に最も近いバリアントを選択してください。color-hooks-decision-guide.md を参照してください
• 番号付きスケールのみ — spacing-medium、font-weight-bold、radius-large のような名前付きフックは存在しません

トラブルシューティング

問題	解決策
リンターがカラー用フックの候補を2つ以上提示する	HTML のコンテキストを確認して、要素の意味上の役割を判断します。color-hooks-decision-guide.md を参照してください
移行後に見た目が変わった	フォールバック値が元の値と一致していることを確認し、surface と container のファミリーを確認します
ハードコードされた値に対応するフックがない	変更せず、そのままにします。カスタムフック名を作らないでください
100% や auto などに対してリンターが「Remove the static value」と表示する	変更せず、そのままにします。これらはレイアウト値です。削除するとレンダリングが崩れます
CSS クラスの命名エラー	正確な camelCase のコンポーネント名を使用します。MyComponent-button ではなく myComponent-button とします
余白やサイズが一致しない	non-color-hooks-decision-guide.md の値とフックの対応表を確認し、余白とサイズの使い分けを確認します
名前付きフックが機能しない（例：spacing-medium）	名前付きフックは存在しません。番号付きスケールを使用します。16px には spacing-4、インラインの太字強調（見出し以外）には font-weight-7 を使用します
コンポーネントのコンパクト密度での表示が異なる	密度に応じて変化するコンポーネントには、密度対応フック（--slds-g-spacing-var-*）を使用します

---

参考資料

• カラー用フックの判断ガイド — 5種類すべてのカラー用フックファミリー、判断ツリー、背景色と前景色の組み合わせ、パレットのアクセシビリティ
• カラー以外のフックの判断ガイド — 余白、サイズ、タイポグラフィ、境界線、角丸、シャドウのフックと参照表
• ルール：ハードコードされた値を使用しない — リンターの動作、修正するかスキップするかの判断、置換パターン、ユーティリティクラスのワークフロー
• ルール：LWC トークンから SLDS フックへの置換 — 非推奨の --lwc-* トークンの置換パターン
• ルール：非推奨の SLDS1 トークンを使用しない — レガシーな t()／token() Aura 構文の置換パターン
• ルール：SLDS クラスを上書きしない — クラスの名前変更と HTML の更新
• 移行例 — シナリオと複雑さごとの変更前／変更後の例
• 一般的なパターン — 上書きしてはならないクラス、非推奨の SLDS 2 クラス、パレットのフォールバック、SLDS 2 に同等のものがないトークン
• 移行チェックリスト — 検証項目の完全なチェックリスト