|
| 1 | +--- |
| 2 | +name: rtl-aware-development |
| 3 | +description: 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 Development |
| 7 | + |
| 8 | +Treat direction as independent from language. Test English in both directions as well as real RTL and mixed-script content. |
| 9 | + |
| 10 | +## Guidelines |
| 11 | + |
| 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 | +```css |
| 17 | +/* Avoid */ |
| 18 | +padding-left: 12px; |
| 19 | +right: 0; |
| 20 | +border-right: 1px solid; |
| 21 | +text-align: left; |
| 22 | + |
| 23 | +/* Prefer */ |
| 24 | +padding-inline-start: 12px; |
| 25 | +inset-inline-end: 0; |
| 26 | +border-inline-end: 1px solid; |
| 27 | +text-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 | +```html |
| 33 | +<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 Matrix |
| 43 | + |
| 44 | +- English + LTR |
| 45 | +- English + forced RTL |
| 46 | +- A real RTL locale + RTL |
| 47 | +- Mixed RTL/LTR content, long labels, numbers, code, and paths |
| 48 | +- Keyboard, pointer resize, scrolling, menus/submenus, and Electron titlebar controls in both directions |
| 49 | + |
| 50 | +## References |
| 51 | + |
| 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/) |
0 commit comments