# 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/letter-spacing#internationalization_concerns) between letters. And digits: `Intl.NumberFormat('ar-EG').format(2005)` gives `٢٬٠٠٥`, a year with a thousands separator, so years get [`useGrouping: false`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#usegrouping).

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.

````markdown
---
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>`,
`&rlm;` (U+200F) and `&lrm;` (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.
````
