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

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.

rtl-aware-development

让 AI 帮你安装

RTL-Aware Development

Guidelines

Test Matrix

References

链接

创作者

RTL-Aware Development

Guidelines

Test Matrix

References