rtl-aware-development

Source excerpt starting at line 1.

1---2name: rtl-aware-development3description: OpenCode Desktop should be RTL-aware. Use when implementing or reviewing RTL/LTR behavior in the web app, desktop app, CSS, menus, scrolling, resizing, icons, mixed-direction text, or Electron title bars.4---5 6# RTL-Aware Development7 8Treat direction as independent from language. Test English in both directions as well as real RTL and mixed-script content.9 10## Guidelines11 12- 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.13- 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.14- Prefer logical CSS for semantic layout. Reserve physical coordinates for pointer positions, canvas geometry, native window controls, and other genuinely physical placement.15 16```css17/* Avoid */18padding-left: 12px;19right: 0;20border-right: 1px solid;21text-align: left;22 23/* Prefer */24padding-inline-start: 12px;25inset-inline-end: 0;26border-inline-end: 1px solid;27text-align: start;28```29 30- 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.31 32```html33<span class="file-row"><bdi dir="auto">README.md</bdi></span> <bdi dir="ltr"><code>C:\src\app.ts</code></bdi>34```35 36- 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.37- 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.38- Do not assume LTR scrolling. RTL `scrollLeft` can start at `0` and become negative. Prefer `scrollIntoView({ inline: "nearest" })` or a tested direction-normalizing helper.39- 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`.40- 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.41 42## Test Matrix43 44- English + LTR45- English + forced RTL46- A real RTL locale + RTL47- Mixed RTL/LTR content, long labels, numbers, code, and paths48- Keyboard, pointer resize, scrolling, menus/submenus, and Electron titlebar controls in both directions49 50## References51 52- [RTL Styling 101, Ahmad Shadeed](https://rtlstyling.com/posts/rtl-styling/)53- [CSS-Tricks: RTL Styling 101](https://css-tricks.com/rtl-styling-101/)54- [CSS-Tricks: CSS Logical Properties and Values](https://css-tricks.com/css-logical-properties-and-values/)55- [W3C: Structural markup and right-to-left text](https://www.w3.org/International/questions/qa-html-dir)56- [W3C: Inline bidirectional markup](https://www.w3.org/International/articles/inline-bidi-markup/)57- [MDN: CSS logical properties and values](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Logical_properties_and_values)58- [MDN: `dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/dir)59- [MDN: `scrollLeft`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollLeft)60- [web.dev: Logical properties](https://web.dev/learn/css/logical-properties/)61- [Electron: Custom title bar](https://www.electronjs.org/docs/latest/tutorial/custom-title-bar)62- [WAI-ARIA: Window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)63- [Kobalte: I18n Provider](https://kobalte.dev/docs/core/components/i18n-provider/)64