What my RTL skill tells coding agents about Arabic pages
In my i18n work Arabic is usually the source language and English the mirror, so every coding agent I use needs the same RTL rules. I keep them in one skill, rtl-arabic-web. It went into my project-template library in September 2026, and identical copies now sit in my site’s repo and in two shop sites’ repos.
Two of its rules are easy to miss in an English-first stylesheet. letter-spacing on Arabic cuts the joins between letters. And digits: Intl.NumberFormat('ar-EG').format(2005) gives ٢٬٠٠٥, a year with a thousands separator, so years get useGrouping: false.
Save it as .claude/skills/rtl-arabic-web/SKILL.md in any repo with Arabic, Hebrew, Persian or Urdu UI. Changes from my copy: a real phone number and a username swapped for placeholders, a bidi example replaced with one that breaks the way it claims, the scrollLeft line updated for current browsers, one CSS tip I couldn’t verify removed, and some wording trimmed. No rules added.
- name
- rtl-arabic-web
- description
- Building or reviewing right-to-left web UI, especially Arabic-first sites. Covers CSS logical properties, bidi text handling (mixed Arabic/Latin, numbers, phone numbers), Arabic typography rules, what to mirror and what never to mirror, digit systems, and RTL-specific JS pitfalls. Use when a page has dir="rtl", lang="ar"/"he"/"fa"/"ur", Arabic content, or when adding RTL support to an LTR layout.
RTL & Arabic Web
RTL is not "LTR with the text moved over". Direction is a layout axis, and Arabic is a
cursive script with its own typographic rules. Most RTL bugs come from three habits:
hardcoding left/right, letting the bidi algorithm run unbounded on mixed content, and
applying Latin typographic tricks to a script that doesn't have them.
1. Logical properties, always
Physical properties break the moment direction flips. Use the logical equivalent so one
stylesheet serves both directions with no [dir="rtl"] override block.
| Never | Always |
|---|---|
margin-left / margin-right |
margin-inline-start / margin-inline-end |
padding-left / padding-right |
padding-inline-start / padding-inline-end |
left / right (offsets) |
inset-inline-start / inset-inline-end |
border-left / border-right |
border-inline-start / border-inline-end |
border-radius: a b c d |
border-start-start-radius etc., or keep symmetric |
text-align: left / right |
text-align: start / end |
float: left / right |
float: inline-start / inline-end |
width / height (when flow-relative) |
inline-size / block-size |
Flexbox and grid are already direction-aware: flex-direction: row and grid column order
flip automatically under dir="rtl". Do not "fix" them with row-reverse; that
double-flips and breaks LTR. Only use row-reverse when you want the order reversed
relative to reading direction in both directions.
gap, place-items, and justify-content: start/end are safe. justify-content: left/right is physical.
The exception: box-shadow, text-shadow, translate, and background-position take
physical coordinates with no logical form. If a shadow implies a light source tied to the
layout, flip the x-offset under [dir="rtl"]. Leave ambient shadows (0 4px 12px) alone.
2. Bidi: isolate every foreign run
The Unicode bidi algorithm reorders text at render time, and it does not know where your data ends. A string in the other direction (an Arabic username in an English page, a Latin brand in Arabic) can pull the neighbouring digits and punctuation into its own run.
The classic break, in an LTR page: <li>User إيان: 90 posts</li> displays the 90 next to
the Arabic name, on the wrong side of the colon.
Fix: wrap untrusted or mixed runs in <bdi>:
<li>User <bdi>إيان</bdi>: 90 posts</li>
<p>الإصدار <bdi dir="ltr">v2.1.0</bdi></p>
<bdi> defaults to dir="auto", which picks direction from the first strong character,
right for user-generated content whose language you don't know at build time.
For CSS-only isolation on a container: unicode-bidi: isolate (or isolate-override to
force a direction). Avoid unicode-bidi: bidi-override: it disables the algorithm rather
than scoping it, and mangles genuinely mixed strings.
Neutral characters are the trap. Digits, punctuation, spaces and symbols have no
inherent direction; they inherit from the surrounding run. When you can't wrap in <bdi>,
‏ (U+200F) and ‎ (U+200E) pin a neutral character to a direction.
Never mirror these: phone numbers, times (10:30), numeric dates, IP addresses, file
paths, math, and code. They are LTR sequences made of neutrals and digits. Give them
dir="ltr":
<span class="phone" dir="ltr">+963 9XX XXX XXX</span>
Without it, the leading + jumps to the far end and the number reads wrong.
3. Arabic typography
Arabic is cursive: letters join. Latin display tricks do nothing or destroy legibility.
letter-spacingis forbidden. It severs the joins between letters. Setletter-spacing: 0explicitly if a reset or a Latin design system applied one.text-transform: uppercasedoes nothing. Arabic has no case. If the design depends on the weight of caps, solve it with weight, size or color.font-style: italicproduces synthetic oblique, which looks broken in Arabic. Use weight or color for emphasis.- Line height must be larger. Tall ascenders, deep descenders and diacritics clip at Latin line heights. Use 1.7 to 2.0 for body text, never below 1.5.
- Font size runs slightly larger. Bump Arabic body text 1 to 2px over the Latin size.
- Justified text is risky. Browsers justify Arabic poorly (no proper kashida), so
text-align: justifyleaves gaps. Prefertext-align: start. - Don't fake bold. Load a real heavy weight; synthesized bold smears the joins.
Typefaces that work for Arabic UI: Tajawal, Cairo, IBM Plex Sans Arabic, Noto Sans Arabic / Noto Kufi Arabic, Rubik, Almarai, Readex Pro. Check that the weights you use exist in the family; a missing 800 is synthesized silently.
Give the Arabic family a real fallback chain:
font-family: 'Tajawal', 'Segoe UI', Tahoma, Arial, sans-serif;
4. Digits: pick a system and hold it
Arabic content uses Western digits (0-9) or Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩). Mixing
them in one interface looks careless.
new Intl.NumberFormat('ar-EG').format(2005) // "٢٬٠٠٥" Arabic-Indic
new Intl.NumberFormat('ar-EG-u-nu-latn').format(2005) // "2,005" Western
new Intl.NumberFormat('ar').format(2005) // locale-dependent: avoid
Years are not quantities. Format them with no grouping:
new Intl.NumberFormat('ar-EG', { useGrouping: false }).format(2005) // "٢٠٠٥"
Format digits in JS so the DOM text is right for copy-paste, screen readers and search. Keep identifiers, phone numbers, prices with currency codes, and anything the user might copy in Western digits unless the design says otherwise.
5. Mirror, or don't
Mirror anything whose meaning is tied to reading direction:
- Directional arrows: back/forward, next/previous, breadcrumb chevrons, carousel controls
- Progress bars and steppers
- Text-alignment icons, indent/outdent, list bullets
- Speech bubble tails, drawer and sidebar slide direction
→in copy: use←in RTL, or drop arrows from text
Never mirror what has an absolute meaning:
- Logos and brand marks
- Media controls (play ▶ always points right)
- Clocks and anything clockwise (undo/redo curves, spinners, refresh)
- Checkmarks, question-mark icons
- Time-axis charts, unless your audience expects otherwise (ask, don't assume)
- Photos, screenshots, maps
- Code blocks, terminal output
[dir="rtl"] .icon-arrow { transform: scaleX(-1); }
For inline SVG you control, draw a real RTL variant when the flipped one would look wrong.
6. JS and DOM pitfalls
element.scrollLeftis zero or negative in RTL in current browsers (very old Chrome used positive values). Never compare it against a positive number. UsescrollIntoView(), orMath.abs(el.scrollLeft)when you must.getBoundingClientRect()is physical.rect.leftis the visual left in both directions, not the start edge.- Keyboard arrows. In RTL, ArrowLeft moves forward through a horizontal list. Roving-tabindex widgets (tabs, toolbars, menubars) must swap their handling.
- Swipe and drag gestures in carousels need the same swap.
- Third-party widgets (maps, charts, date pickers, editors) often ignore
dir="rtl". Wrap one in an LTR island (dir="ltr") rather than fighting it. Intl.DateTimeFormatwith an Arabic locale gives Arabic month names and the right digits. Don't hand-roll month arrays.
7. Setup and review checklist
Direction and language are separate attributes, and screen readers need the language:
<html lang="ar" dir="rtl">
Set lang on any run that switches language:
<p>ندرّس لغة <span lang="en">Python</span> في السنة الثانية.</p>
Before shipping:
- No
left:/right:/margin-left/padding-rightleft in the stylesheet (grep -nE '(margin|padding|border)-(left|right)|[^-]\b(left|right):') - No
letter-spacingon Arabic text -
line-height≥ 1.7 on Arabic body copy - Phone numbers, emails, URLs and code carry
dir="ltr" - One digit system site-wide; years have no thousands separator
- Directional icons mirror; logos and media controls don't
- Layout checked at 360px: Arabic words don't hyphenate and wrap in longer chunks
- Arrow-key navigation feels forward-is-left in horizontal widgets
- Tested with real Arabic content, not lorem ipsum
When adding RTL to an existing LTR site, converting to logical properties is less work than
keeping a parallel [dir="rtl"] override sheet, and it can't drift out of sync.
---
name: rtl-arabic-web
description: Building or reviewing right-to-left web UI, especially Arabic-first sites. Covers CSS logical properties, bidi text handling (mixed Arabic/Latin, numbers, phone numbers), Arabic typography rules, what to mirror and what never to mirror, digit systems, and RTL-specific JS pitfalls. Use when a page has dir="rtl", lang="ar"/"he"/"fa"/"ur", Arabic content, or when adding RTL support to an LTR layout.
---
# RTL & Arabic Web
RTL is not "LTR with the text moved over". Direction is a layout axis, and Arabic is a
cursive script with its own typographic rules. Most RTL bugs come from three habits:
hardcoding `left`/`right`, letting the bidi algorithm run unbounded on mixed content, and
applying Latin typographic tricks to a script that doesn't have them.
## 1. Logical properties, always
Physical properties break the moment direction flips. Use the logical equivalent so one
stylesheet serves both directions with no `[dir="rtl"]` override block.
| Never | Always |
|---|---|
| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` |
| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` |
| `left` / `right` (offsets) | `inset-inline-start` / `inset-inline-end` |
| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` |
| `border-radius: a b c d` | `border-start-start-radius` etc., or keep symmetric |
| `text-align: left` / `right` | `text-align: start` / `end` |
| `float: left` / `right` | `float: inline-start` / `inline-end` |
| `width` / `height` (when flow-relative) | `inline-size` / `block-size` |
Flexbox and grid are already direction-aware: `flex-direction: row` and grid column order
flip automatically under `dir="rtl"`. Do not "fix" them with `row-reverse`; that
double-flips and breaks LTR. Only use `row-reverse` when you want the order reversed
*relative to* reading direction in both directions.
`gap`, `place-items`, and `justify-content: start/end` are safe. `justify-content:
left/right` is physical.
**The exception:** `box-shadow`, `text-shadow`, `translate`, and `background-position` take
physical coordinates with no logical form. If a shadow implies a light source tied to the
layout, flip the x-offset under `[dir="rtl"]`. Leave ambient shadows (`0 4px 12px`) alone.
## 2. Bidi: isolate every foreign run
The Unicode bidi algorithm reorders text at render time, and it does not know where your
data ends. A string in the other direction (an Arabic username in an English page, a Latin
brand in Arabic) can pull the neighbouring digits and punctuation into its own run.
The classic break, in an LTR page: `<li>User إيان: 90 posts</li>` displays the `90` next to
the Arabic name, on the wrong side of the colon.
**Fix: wrap untrusted or mixed runs in `<bdi>`:**
```html
<li>User <bdi>إيان</bdi>: 90 posts</li>
<p>الإصدار <bdi dir="ltr">v2.1.0</bdi></p>
```
`<bdi>` defaults to `dir="auto"`, which picks direction from the first strong character,
right for user-generated content whose language you don't know at build time.
For CSS-only isolation on a container: `unicode-bidi: isolate` (or `isolate-override` to
force a direction). Avoid `unicode-bidi: bidi-override`: it disables the algorithm rather
than scoping it, and mangles genuinely mixed strings.
**Neutral characters are the trap.** Digits, punctuation, spaces and symbols have no
inherent direction; they inherit from the surrounding run. When you can't wrap in `<bdi>`,
`‏` (U+200F) and `‎` (U+200E) pin a neutral character to a direction.
**Never mirror these:** phone numbers, times (`10:30`), numeric dates, IP addresses, file
paths, math, and code. They are LTR sequences made of neutrals and digits. Give them
`dir="ltr"`:
```html
<span class="phone" dir="ltr">+963 9XX XXX XXX</span>
```
Without it, the leading `+` jumps to the far end and the number reads wrong.
## 3. Arabic typography
Arabic is cursive: letters join. Latin display tricks do nothing or destroy legibility.
- **`letter-spacing` is forbidden.** It severs the joins between letters. Set
`letter-spacing: 0` explicitly if a reset or a Latin design system applied one.
- **`text-transform: uppercase` does nothing.** Arabic has no case. If the design depends on
the weight of caps, solve it with weight, size or color.
- **`font-style: italic` produces synthetic oblique**, which looks broken in Arabic. Use
weight or color for emphasis.
- **Line height must be larger.** Tall ascenders, deep descenders and diacritics clip at
Latin line heights. Use **1.7 to 2.0** for body text, never below 1.5.
- **Font size runs slightly larger.** Bump Arabic body text 1 to 2px over the Latin size.
- **Justified text is risky.** Browsers justify Arabic poorly (no proper kashida), so
`text-align: justify` leaves gaps. Prefer `text-align: start`.
- **Don't fake bold.** Load a real heavy weight; synthesized bold smears the joins.
**Typefaces that work for Arabic UI:** Tajawal, Cairo, IBM Plex Sans Arabic, Noto Sans
Arabic / Noto Kufi Arabic, Rubik, Almarai, Readex Pro. Check that the weights you use exist
in the family; a missing 800 is synthesized silently.
Give the Arabic family a real fallback chain:
```css
font-family: 'Tajawal', 'Segoe UI', Tahoma, Arial, sans-serif;
```
## 4. Digits: pick a system and hold it
Arabic content uses Western digits (`0-9`) or Arabic-Indic digits (`٠١٢٣٤٥٦٧٨٩`). Mixing
them in one interface looks careless.
```js
new Intl.NumberFormat('ar-EG').format(2005) // "٢٬٠٠٥" Arabic-Indic
new Intl.NumberFormat('ar-EG-u-nu-latn').format(2005) // "2,005" Western
new Intl.NumberFormat('ar').format(2005) // locale-dependent: avoid
```
**Years are not quantities.** Format them with no grouping:
```js
new Intl.NumberFormat('ar-EG', { useGrouping: false }).format(2005) // "٢٠٠٥"
```
Format digits in JS so the DOM text is right for copy-paste, screen readers and search.
Keep identifiers, phone numbers, prices with currency codes, and anything the user might
copy in Western digits unless the design says otherwise.
## 5. Mirror, or don't
**Mirror** anything whose meaning is tied to reading direction:
- Directional arrows: back/forward, next/previous, breadcrumb chevrons, carousel controls
- Progress bars and steppers
- Text-alignment icons, indent/outdent, list bullets
- Speech bubble tails, drawer and sidebar slide direction
- `→` in copy: use `←` in RTL, or drop arrows from text
**Never mirror** what has an absolute meaning:
- Logos and brand marks
- Media controls (play ▶ always points right)
- Clocks and anything clockwise (undo/redo curves, spinners, refresh)
- Checkmarks, question-mark icons
- Time-axis charts, unless your audience expects otherwise (ask, don't assume)
- Photos, screenshots, maps
- Code blocks, terminal output
```css
[dir="rtl"] .icon-arrow { transform: scaleX(-1); }
```
For inline SVG you control, draw a real RTL variant when the flipped one would look wrong.
## 6. JS and DOM pitfalls
- **`element.scrollLeft` is zero or negative in RTL** in current browsers (very old Chrome
used positive values). Never compare it against a positive number. Use
`scrollIntoView()`, or `Math.abs(el.scrollLeft)` when you must.
- **`getBoundingClientRect()` is physical.** `rect.left` is the visual left in both
directions, not the start edge.
- **Keyboard arrows.** In RTL, ArrowLeft moves *forward* through a horizontal list.
Roving-tabindex widgets (tabs, toolbars, menubars) must swap their handling.
- **Swipe and drag gestures** in carousels need the same swap.
- **Third-party widgets** (maps, charts, date pickers, editors) often ignore `dir="rtl"`.
Wrap one in an LTR island (`dir="ltr"`) rather than fighting it.
- **`Intl.DateTimeFormat`** with an Arabic locale gives Arabic month names and the right
digits. Don't hand-roll month arrays.
## 7. Setup and review checklist
Direction and language are separate attributes, and screen readers need the language:
```html
<html lang="ar" dir="rtl">
```
Set `lang` on any run that switches language:
```html
<p>ندرّس لغة <span lang="en">Python</span> في السنة الثانية.</p>
```
Before shipping:
- [ ] No `left:`/`right:`/`margin-left`/`padding-right` left in the stylesheet
(`grep -nE '(margin|padding|border)-(left|right)|[^-]\b(left|right):'`)
- [ ] No `letter-spacing` on Arabic text
- [ ] `line-height` ≥ 1.7 on Arabic body copy
- [ ] Phone numbers, emails, URLs and code carry `dir="ltr"`
- [ ] One digit system site-wide; years have no thousands separator
- [ ] Directional icons mirror; logos and media controls don't
- [ ] Layout checked at 360px: Arabic words don't hyphenate and wrap in longer chunks
- [ ] Arrow-key navigation feels forward-is-left in horizontal widgets
- [ ] Tested with real Arabic content, not lorem ipsum
When adding RTL to an existing LTR site, converting to logical properties is less work than
keeping a parallel `[dir="rtl"]` override sheet, and it can't drift out of sync.