experience-lwc-rtl-validate

LWC の RTL レビュー

Lightning Web コンポーネントに対して、体系的な右から左（RTL）の国際化準拠チェックを実施し、検出された問題と、Salesforce の RTL ガイドラインに準拠させるためのコードレベルの修正案をまとめたレポートを作成します。

使用する場面

• 特定の LWC に対する「RTL レビュー」「i18n チェック」「RTL 準拠チェック」または「RTL 監査」をユーザーが依頼した場合。
• RTL ロケール（アラビア語、ヘブライ語、ペルシア語、ウルドゥー語）向けにコンポーネントをリリースする準備をする場合。
• RTL 環境で報告されたレイアウトの不具合を調査する場合。
• CSS のリファクタリング後に SLDS クラスの使用状況を確認する場合。

次の用途ではこのスキルを使用しないでください。

• 新しいコンポーネントを作成する場合（experience-lwc-generate を使用してください）。
• SLDS クラス自体を変更する場合（design-systems-slds-apply または design-systems-slds2-migrate を使用してください）。
• アクセシビリティまたはセキュリティのレビューを行う場合。これらは関連ツールを使って個別に実施してください。
• 修正をフィーチャーフラグの背後で制御する場合（修正を反映した後にフィーチャーフラグによる制御を適用してください）。

前提条件

• コンポーネントのパス（modules/… 配下の LWC バンドル）。
• コンポーネントの HTML テンプレート、JS/TS、CSS へのアクセス。

ナレッジベース

参照資料を信頼できる情報源として使用してください。記憶を頼りに要約せず、参照資料を開いてガイドラインを適用し、レポートで使用した該当セクションを引用してください。

• RTL の国際化：RTL Expert

ワークフロー

ステップ 1 — レビュー範囲を定める

コンポーネントのパスを確認し、レビュー対象のファイルを特定します。.html、.js／.ts、.css、および対象コンポーネントから呼び出される、同じチームが所有する子コンポーネントを対象にします。

既存のフィーチャーフラグによる制御（例：Aura.org.rtlPhase1FixEnabled）があれば記録します。コード変更が必要な指摘への対応では、その制御を尊重する必要があります。

ステップ 2 — ナレッジベースを読む

評価を始める前に、RTL Expert を最初から最後まで読んでください。物理プロパティから論理プロパティへの対応、双方向テキストの処理パターン、そして特に、一般的な RTL のアドバイスより優先される SLDS の制約が記載されています。

ステップ 3 — CSS の検査

バンドル内のすべての .css ファイルに対して、決定論的なスキャナーを実行します。スキャナーは CSS 宣言のみを対象とし、HTML の class="…" 属性内にある SLDS クラス名には一致しません（ステップ 5 を参照）。 インラインの style="…" 属性は個別にスキャンしてください（抽出して一時ファイルに保存するか、HTML を手作業で確認し、同じルールを適用します）。

"<skill_dir>/scripts/scan-rtl-css.sh" <cssFile1> [<cssFile2> ...]

各出力行は <file>:<line>: <property>: <value> -> <logical-property>: <logical-value> の形式です。スキャナーは宣言をトークン化し（{…} 内の ; で分割）、圧縮された複数宣言の行では物理宣言ごとに 1 件の指摘を出力します。また、セレクター名が書き換えられることはありません。各行をステップ 6 の箇条書き（<file>:<line> — <pattern> → <logical property> と 1 文の Fix）に変換してください。出力が空でも有効な結果です。レポートには「問題は見つかりませんでした。」と記録してください。

スキャナーが認識するパターン（スクリプトの正規表現との整合性を保ってください。scan-rtl-css.sh も更新せずに、ここにルールを追加しないでください）：

• left / right → inset-inline-start / inset-inline-end
• margin-left / margin-right → margin-inline-start / margin-inline-end
• padding-left / padding-right → padding-inline-start / padding-inline-end
• text-align: left / right → text-align: start / end
• border-left-* / border-right-* → border-inline-start-* / border-inline-end-*
• float: left / float: right → float: inline-start / float: inline-end（または削除して flex／grid を使用）
• transform: translateX(...) — 指摘対象。符号を反転するか、論理的な代替手段を使用してください。

明示的な角を指定した border-radius は自動スキャンの対象外です。角のショートハンドを手作業で確認し、論理的な角のバリアントに置き換えてください。

ステップ 4 — HTML / JS の調査

テンプレートと JS を調べ、次の点を確認します。

• アイコンの反転に関するヒント — 通常の HTML <img> / インライン SVG / 生の Unicode / background-image CSS にある、方向性を持つアイコンのみを指摘します。LWC テンプレート内の <lightning-icon> は指摘しないでください（utility:chevronright、utility:chevronleft、utility:back、utility:forward などの方向性を持つユーティリティ名も含みます）。lightning-icon は Lightning アイコンサービスを通じてレンダリングされ、RTL ロケールでは方向性を持つユーティリティアイコンが自動的に反転します。SLDS ユーティリティクラスと同じように扱ってください。
• dir 属性の使用 — ロケールに基づいて設定されており、ハードコードされていないことを確認します。
• キーボードの矢印キーの動作 — タブバー、スライダー、ツリーの展開／折りたたみなど、ナビゲーションに方向性がある場合、RTL では左右の矢印キーのハンドラーを入れ替えます。
• 方向制御用の Unicode 文字 — ユーザーが生成したテキストをレンダリングする際、RLM/LRM マーカーが削除されないことを確認します。
• 物理プロパティを含むインライン style="…" — ステップ 3 と同じルールを適用します。

ステップ 5 — SLDS の制約

SLDS クラスの扱いは RTL ルールの中で最優先です。以下のルールで「指摘しない」とされている場合、そのクラスはレポートに問題としても、修正としても、名前変更の提案としても記載してはいけません。

1. **_left / _right サフィックスを持つ SLDS ユーティリティクラスは RTL に対応しているため、指摘してはいけません。**内部で RTL 時に自動的に反転します。これには slds-text-align_right、slds-text-align_left、slds-m-left_*、slds-m-right_*、slds-p-left_*、slds-p-right_*、slds-float_left、slds-float_right、slds-border_left、slds-border_right、およびその他の _left / _right ユーティリティファミリーが含まれます。そのまま変更せずに使用してください。
2. _start / _end 版の SLDS クラスは存在しません。slds-*_right → slds-*_end や slds-*_left → slds-*_start のように名前を変更してはいけません。そのようなクラスは存在せず、名前を変更するとスタイルシートが壊れます。SLDS ユーティリティクラスに _start / _end を追加して「修正」しようとしている場合は、そこでやめてください。正しい対応は、ルール 1 のとおりクラスを変更しないことです。
3. **slds-* クラスを変更、改名、削除してはいけません。**SLDS には RTL 対応のスタイルシートが含まれており、クラスを変更するとその仕様が損なわれます。
4. カスタム CSS が SLDS クラスで既に処理されている内容を重複して指定している場合、対応は変換ではなく削除です。重複するカスタムルールを削除し、SLDS クラスはそのままにします。削除したプロパティを論理プロパティに変換してはいけません。また、削除と変換を 2 つの選択肢として提示してはいけません。対応は削除の 1 つだけです。例：テンプレートの class="slds-button__icon_right" に対応する .css ファイルに float: right がある場合は、.custom-icon { float: right } ルール全体を削除します。「float: inline-end も提案する」ことはしないでください。配置は SLDS クラスが既に処理しているため、誤った提案になります。
5. SLDS クラスに RTL 対応の不足がある場合、SLDS クラスを変更せずに、補完するカスタム CSS を追加します。

具体的な対象外の例 — テンプレートに <span class="slds-text-align_right slds-m-right_small">…</span> があり、コンポーネントの CSS にカスタム padding-left: 4px がある場合、指摘するのは CSS の padding-left のみです（ステップ 3）。2 つの slds-*_right クラスは指摘事項ではなく、レポートに記載してはいけません。

ステップ 6 — レポートの作成

<outputDir>/rtl-review.md を、次の厳密な形式で作成します（各 ## 見出しの後には空行を入れ、各 Summary 文の末尾にはピリオドを付けます）。

## RTL

- <file>:<line> — <physical pattern> → <logical property / SLDS class>
  Fix: <one-sentence explanation>; applied: yes/no
- <file>:<line> — <physical pattern> → <logical property / SLDS class>
  Fix: <one-sentence explanation>; applied: yes/no

## Summary

- <n> issues found; <m> fixed; <k> deferred (with reason).
- <one-sentence overview of what was found and why the remaining items are correct or deferred>.
- Cite: RTL Expert — <section title>.

CSS の指摘事項については、scan-rtl-css.sh の出力を ## RTL の箇条書きに反映し、ステップ 4 の HTML/JS の指摘事項がある場合は、同じ形式の箇条書きを手作業で追加します。指摘事項がない場合は、## RTL の下に - No issues found. の箇条書きを 1 つだけ記載し、Summary には 0 issues found; 0 fixed; 0 deferred. と、概要および引用を含む 1 文を記載します。

ステップ 7 — 修正を適用する

承認された各指摘について、次の手順を実行します。

1. コンポーネントのファイル（CSS、HTML、JS/TS）を編集し、修正を適用します。
2. 既存の正しい動作と既存の機能フラグによるゲートを維持します。すでにゲートが設定されている場合（例：Aura.org.rtlPhase1FixEnabled）は、そのままにします。新しい修正について段階的なロールアウトを呼び出し元が明示的に求めている場合に限り、その修正を機能フラグで制御します。それ以外の場合は、修正を直接適用します。
3. SLDS クラスを削除または名前変更しないでください。
4. 古いコードを黙って削除しないでください。ゲートが必要な場合は、元のパスを維持します。

ステップ 8 — 検証する

• 更新したファイルに対してレビューを再実行し、修正した指摘がすべて表示されなくなったことを確認します。
• Jest テストと、コンポーネントレベルの RTL ビジュアルテストを実行します。

相互参照

• 関連スキル：
  • design-systems-slds-apply — カスタム CSS のクリーンアップを超える SLDS クラスレベルの変更に使用します。
  • design-systems-slds2-migrate — RTL のクリーンアップで、先に SLDS2 への移行が必要なクラスが見つかった場合に使用します。
  • experience-lwc-generate — パッチ適用ではなくコンポーネントの再生成が必要だとレビューで判明した場合に使用します。
  • アクセシビリティ（WCAG 2.2）とセキュリティ（LWS + Product Security）のレビューは別々に実施します。このスキルではなく、それぞれに適したツールを使って実行してください。
  • 機能フラグによる制御はこのスキルの範囲外です。呼び出し元が段階的なロールアウトを明示的に求めている場合に限り、別途適用してください（ステップ 7 を参照）。

検証

• 更新したコンポーネントの RTL ルールがすべて合格していること（バンドル内のすべての CSS ファイルに対して scripts/scan-rtl-css.sh を再実行します。完全に適用済みの各指摘について、出力が空でなければなりません）。
• SLDS クラスが変更、名前変更、削除されていないこと。
• すべての指摘が適用済みであるか、理由を明記した保留の注記があること。
• rtl-review.md がステップ 6 で定義された 2 セクションの形式（各 ## の後に空行を入れ、要約文の末尾にピリオドを付ける）になっていること。