/experience-lwc-rtl-validate

name: experience-lwc-rtl-validate
description: "Use this skill to review a Lightning Web Component (.html, .js, .css files) for right-to-left (RTL) internationalization correctness, producing a finding list with code-level fixes covering CSS logical properties, bidirectional text handling, keyboard semantics, and RTL-aware SLDS class usage. TRIGGER when the user says \"review this LWC for RTL\", \"audit i18n compliance\", \"fix bidirectional text rendering\", \"replace left/right CSS with logical properties\", \"check RTL layout issues\", \"verify SLDS RTL classes\", \"review my component for Arabic/Hebrew layout\", \"ensure this LWC works in RTL locales\", or \"check bidi text handling\". DO NOT TRIGGER when the user is building a new LWC (use experience-lwc-generate), refactoring SLDS classes themselves (use design-systems-slds-apply or design-systems-slds2-migrate), or performing accessibility/security review."
metadata:
  version: "1.0"
  relatedSkills:
    - design-systems-slds-apply
    - design-systems-slds2-migrate
    - experience-lwc-generate
  cliTools:
    - tool: ["python3"]
      semver: ">=3.8"

<!-- adk-managed-skill -->

Reviewing LWC RTL

Run a structured right-to-left (RTL) internationalization compliance pass over a Lightning Web Component, producing a report of issues found and code-level fixes to bring the component into compliance with Salesforce RTL guidelines.

When to Use

• The user asks for an "RTL review", "i18n check", "RTL compliance pass", or "RTL audit" on a specific LWC.
• Preparing a component for release in RTL locales (Arabic, Hebrew, Farsi, Urdu).
• Investigating layout defects reported in RTL environments.
• Verifying SLDS class usage after a CSS refactor.

Do NOT use this skill for:

• Building new components (use `experience-lwc-generate`).
• Modifying SLDS classes themselves (use `design-systems-slds-apply` or `design-systems-slds2-migrate`).
• Accessibility or security review — run those as separate passes with the relevant tooling.
• Gating a fix behind a feature flag (apply feature-flag gating after fixes land).

Prerequisites

• Component path (LWC bundle under `modules/…`).
• Access to the component's HTML templates, JS/TS, and CSS.

Knowledge Base

The reference is the source of truth. Do not summarize from memory — open the reference, apply the guidelines, and cite the specific section you used in the report.

• RTL internationalization: [RTL Expert](references/rtl-expert.md)

Workflow

Step 1 — Scope the review

Collect the component path and identify the files to review: `.html`, `.js`/`.ts`, `.css`, and any child components owned by the same team that are invoked from the target.

Note any existing feature-flag gates (e.g., `Aura.org.rtlPhase1FixEnabled`) — findings that require code changes must respect them.

Step 2 — Read the knowledge base

Read [RTL Expert](references/rtl-expert.md) top-to-bottom before judging. It enumerates the physical-to-logical property mappings, bidirectional text handling patterns, and — critically — the SLDS constraints that override generic RTL advice.

Step 3 — CSS inspection

Run the deterministic scanner over every `.css` file in the bundle. **The scanner matches CSS declarations only — never SLDS class names in HTML `class="…"` attributes (see Step 5).** Inline `style="…"` attributes must be scanned separately (either by extracting them into a temp file or by inspecting the HTML by hand and applying the same rules).

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

Each output line has the shape `<file>:<line>: <property>: <value> -> <logical-property>: <logical-value>`. The scanner tokenizes declarations (splits on `;` inside `{…}`) so minified multi-declaration lines produce one finding per physical declaration and selector names are never rewritten. Translate each line into a Step 6 bullet (`<file>:<line> — <pattern> → <logical property>` plus a one-sentence Fix). Empty output IS a valid result — record it as "No issues found." in the report.

Scanner-recognised patterns (kept in sync with the script's regex — do not add rules here without also updating `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` (or remove and use flex/grid)
• `transform: translateX(...)` — flagged; sign-flip or use a logical alternative

`border-radius` with explicit corners is not scanned automatically — inspect corner shorthand by hand and translate to the logical corner variants.

Step 4 — HTML / JS inspection

Walk templates and JS for:

• Icon flipping hints — flag **only** icons with directional semantics that appear in **plain HTML `<img>` / inline SVG / raw Unicode / background-image CSS**. **Do NOT flag `<lightning-icon>` in LWC templates** (including directional utility names like `utility:chevronright`, `utility:chevronleft`, `utility:back`, `utility:forward`); `lightning-icon` renders through the Lightning icon service, which mirrors directional utility icons automatically in RTL locales. Treat it the same way you treat SLDS utility classes.
• `dir` attribute usage — confirm it's sourced from locale, not hardcoded.
• Keyboard arrow-key semantics — Left/Right arrow handlers should swap in RTL where navigation is directional (tab bars, sliders, tree expand/collapse).
• Directional Unicode controls — ensure user-generated text is not stripped of RLM/LRM markers when rendered.
• Inline `style="…"` with physical properties — same rules as Step 3.

Step 5 — SLDS constraints

SLDS class handling is the highest-priority RTL rule. **When