When a component library's elements render in a right-to-left language, what should mirror, and which icons should not flip?

## Reading direction versus physical direction **Right-to-left (RTL)** languages such as Arabic and Hebrew are read from the right edge of the line to the left. In an RTL interface the whole layout follows: the first item of a row sits on the right, text aligns to the right, and "forward" points left. **Mirroring** is the mapping of a left-to-right design onto that direction. The question for every part of an element is: **does its direction come from reading order, or from something else?** If it comes from reading order, it mirrors. If it comes from the physical world, a clock face or a brand, it stays. ## What mirrors Take a utility company's billing portal launching in Arabic: - **Element order in a row**: the bill-summary card's icon, title and amount run from right to left. - **Start and end alignment**: text and actions that sat at the left edge now sit at the right edge. - **Back and next arrows**: "back to account" points right; "next bill" points left. - **Chevrons** in pagination, breadcrumbs and expandable rows follow the reading direction. - **Steppers and progress**: the steps for setting up a payment plan run right to left, and the usage-progress bar fills from the right, the start edge. - **Motion with direction**: a drawer that slid in from the left slides in from the right. ## What does not mirror | Kind | Billing-portal example | Why it stays | |---|---|---| | Icons of physical objects | Light bulb, water drop, download tray | They depict things, not reading order | | Clocks and timers | "Payment pending" clock | Clock hands turn the same way in every locale | | Brand marks | The utility's logo | A logo is a fixed mark | | Media controls (common practice) | Play button on a "how to read your meter" video | Most systems treat them as depicting playback direction | | Numbers | Account number, meter reading, amount | Digits keep their order even inside RTL text | Some icons are genuinely debated — undo and redo, a checkmark, a chart's time axis — and systems decide them differently. The safe rule is to **decide once, record the decision on the icon, and apply it everywhere**, rather than leave each product team to guess. ## Numbers and embedded left-to-right text Arabic and Hebrew write numbers with the most significant digit on the left, so an account number reads left to right even in an RTL sentence. The same goes for embedded left-to-right fragments such as an email address or a meter serial number. The text engine's **bidirectional algorithm** handles most of this, but elements that display such values should isolate them as their own direction run, so neighbouring punctuation and placeholders do not jump around. Some locales also use their own digit shapes. Which digits to show is a locale formatting decision made by the app, not something the element should change on its own. ## How a library makes this automatic 1. **Direction comes from context**: the app sets the direction for its locale at the root, and every element inherits it rather than taking a per-instance option. 2. **Layout is expressed in start and end**, not left and right, so it flips with the inherited direction. 3. **Every icon carries a directional flag** in the icon set's metadata; the icon element mirrors only flagged icons in RTL. 4. **Asymmetric details** — a corner radius on one side, a shadow offset, an indent — are defined on the start or end side, not a physical one. ## Common mistakes - Mirroring **every** icon, which flips logos, clocks and text-bearing icons into nonsense. - Mirroring **nothing** but the text alignment, leaving arrows that point backwards. - Reversing the characters of numbers or email addresses. - Shipping a separate RTL copy of each element, which then drifts from the original.