rtl-aware-development

RTL-Aware Development

Treat direction as independent from language. Test English in both directions as well as real RTL and mixed-script content.

Guidelines

• Set lang and dir on the document, and propagate direction through component providers used by portaled menus and popovers. Do not change the selected locale merely to force RTL.
• Keep DOM and focus order semantic. Flexbox and Grid already follow dir; do not add row-reverse, CSS order, or reversed markup just to mirror a layout.
• Prefer logical CSS for semantic layout. Reserve physical coordinates for pointer positions, canvas geometry, native window controls, and other genuinely physical placement.

/* Avoid */
padding-left: 12px;
right: 0;
border-right: 1px solid;
text-align: left;

/* Prefer */
padding-inline-start: 12px;
inset-inline-end: 0;
border-inline-end: 1px solid;
text-align: start;

• Isolate mixed-direction text. Use dir="auto" or <bdi> for unknown text; keep code, URLs, IDs, and filesystem paths LTR without forcing the surrounding component LTR.

<span class="file-row"><bdi dir="auto">README.md</bdi></span> <bdi dir="ltr"><code>C:\src\app.ts</code></bdi>

• Mirror directional meaning, not every image. Back/forward, previous/next, disclosure, indentation, and directional progress may need mirroring. Do not mirror brands, clocks, media controls, charts, or text. Reverse physical gradients, translateX, SVG transforms, and animation deltas explicitly.
• Map interactions through direction. clientX remains physical; resizing a logical edge needs an RTL-aware delta. Logical previous/next keyboard controls may swap ArrowLeft/ArrowRight. Follow the relevant WAI-ARIA widget pattern.
• Do not assume LTR scrolling. RTL scrollLeft can start at 0 and become negative. Prefer scrollIntoView({ inline: "nearest" }) or a tested direction-normalizing helper.
• For Electron title bars, prefer native caption controls and use titleBarOverlay plus env(titlebar-area-*) for the safe content rectangle. Keep Windows/macOS native-control avoidance and trafficLightPosition physical; keep app navigation inside that rectangle logical. Mark interactive titlebar children app-region: no-drag.
• Verify behavior, not screenshots alone. Check computed styles, pseudo-element geometry, hit zones, focus order, keyboard behavior, submenu direction, zoom/scaling, and both LTR and RTL scroll endpoints.