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

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

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 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).

bash

"<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 a rule below says "do NOT flag", that class must not appear as a finding in the report — not as an issue, not as a "fix", not as a rename suggestion.

SLDS utility classes with
_left
/
_right
suffixes are RTL-aware and MUST NOT be flagged. They already mirror automatically in RTL under the hood — this includes
```
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
```
, and the rest of the
```
_left
```
/
```
_right
```
utility family. Leave them exactly as written.
_start
/
_end
variants of SLDS classes DO NOT EXIST. Never rename
```
slds-*_right
```
→
```
slds-*_end
```
or
```
slds-*_left
```
→
```
slds-*_start
```
. There is no such class; the rename would break the stylesheet. If you are tempted to "fix" an SLDS utility class by adding
```
_start
```
/
```
_end
```
, STOP — the correct action is to leave the class alone (see rule 1).
Never modify, rename, or remove any
slds-*
class. SLDS ships RTL-aware stylesheets; altering classes breaks the contract.
If custom CSS duplicates what an SLDS class already handles, the fix is removal — not conversion. Delete the redundant custom rule; leave the SLDS class alone. Do NOT convert the removed property to its logical equivalent, and do NOT offer removal + conversion as two alternatives; there is one fix, and it is deletion. Example:
```
float: right
```
in a
```
.css
```
file next to
```
class="slds-button__icon_right"
```
in the template — delete the entire
```
.custom-icon { float: right }
```
rule. Do not "also suggest
```
float: inline-end
```
" — that would be wrong; the SLDS class already handles placement.
If an SLDS class has an RTL gap, add complementary custom CSS rather than altering the SLDS class.

Concrete negative example — a template with

<span class="slds-text-align_right slds-m-right_small">…</span>

alongside a custom

padding-left: 4px

in the component's CSS: the ONLY finding is the CSS

padding-left

(Step 3). The two

slds-*_right

classes are not findings and must not appear in the report.

Step 6 — Produce the report

Write

<outputDir>/rtl-review.md

in this exact shape (blank line after each

##

heading; every summary sentence ends with a period):

markdown

## 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>.

Populate the

## RTL

bullets from the

scan-rtl-css.sh

output for CSS findings, and append hand-authored bullets in the same shape for the Step 4 HTML/JS findings. When there are no findings, emit the single bullet

- No issues found.

under

## RTL

and a

Summary

that reports

0 issues found; 0 fixed; 0 deferred.

plus a one-sentence overview and citation.

Step 7 — Apply fixes

For each accepted finding:

Edit the component files (CSS, HTML, JS/TS) to apply the fix.
Preserve existing correct behavior and existing feature-flag gates. If a gate is already configured (e.g.,
```
Aura.org.rtlPhase1FixEnabled
```
), leave it untouched. Only when the caller has explicitly required a phased rollout for a new fix, wrap that fix behind a feature flag; otherwise apply the fix directly.
Do NOT remove or rename SLDS classes.
Do NOT silently delete old code — preserve the original path where a gate is required.

Step 8 — Verify

Re-run the review against the updated files; every fixed finding must no longer appear.
Run Jest tests and any component-level RTL visual tests.

Cross-References

Related skills:
- ```
design-systems-slds-apply
```
  — for SLDS class-level changes beyond custom CSS cleanup.
- ```
design-systems-slds2-migrate
```
  — when RTL cleanup surfaces classes that need SLDS2 migration first.
- ```
experience-lwc-generate
```
  — when the review surfaces a need to regenerate the component rather than patch it.
- Accessibility (WCAG 2.2) and security (LWS + Product Security) reviews are separate passes — run them with the appropriate tooling for each, not this skill.
- Feature-flag gating is out of scope for this skill; apply it separately only when the caller has explicitly required a phased rollout (see Step 7).

Verification

All RTL rules are green on the updated component (re-run
```
scripts/scan-rtl-css.sh
```
against every CSS file in the bundle — it must return empty for every fully-applied finding).
No SLDS class was modified, renamed, or removed.
Every finding has either been applied or has an explicit deferred note with a reason.
The
```
rtl-review.md
```
matches the two-section shape defined in Step 6 (blank line after each
```
##
```
; period-terminated summary sentences).

experience-lwc-rtl-validate

NPX Install

Tags

SKILL.md Content