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.

Test Matrix

• English + LTR
• English + forced RTL
• A real RTL locale + RTL
• Mixed RTL/LTR content, long labels, numbers, code, and paths
• Keyboard, pointer resize, scrolling, menus/submenus, and Electron titlebar controls in both directions

References

• RTL Styling 101, Ahmad Shadeed
• CSS-Tricks: RTL Styling 101
• CSS-Tricks: CSS Logical Properties and Values
• W3C: Structural markup and right-to-left text
• W3C: Inline bidirectional markup
• MDN: CSS logical properties and values
• MDN: dir
• MDN: scrollLeft
• web.dev: Logical properties
• Electron: Custom title bar
• WAI-ARIA: Window splitter pattern
• Kobalte: I18n Provider