Communitygithub.com

arabic-rtl-ui

Builds and audits correct right-to-left (RTL) Arabic interfaces in React, Next.js, Tailwind CSS and plain HTML/CSS - document direction, logical CSS properties, icon mirroring, Arabic vs Western digits, Arabic fonts, bidirectional (bidi) text with phone numbers, emails and codes, forms, tables and an RTL test pass. Use when building or fixing an Arabic or bilingual (Arabic/English) UI, when a layout breaks after switching to Arabic, when numbers or punctuation jump to the wrong side, or when the user says «واجهة عربية»، «اتجاه من اليمين لليسار»، «RTL»، «الأرقام تظهر معكوسة»، «تعريب الواجهة».

arabic-rtl-ui란 무엇인가요?

arabic-rtl-ui is a Claude Code agent skill that builds and audits correct right-to-left (RTL) Arabic interfaces in React, Next.js, Tailwind CSS and plain HTML/CSS - document direction, logical CSS properties, icon mirroring, Arabic vs Western digits, Arabic fonts, bidirectional (bidi) text with phone numbers, emails and codes, forms, tables and an RTL test pass. Use when building or fixing an Arabic or bilingual (Arabic/English) UI, when a layout breaks after switching to Arabic, when numbers or punctuation jump to the wrong side, or when the user says «واجهة عربية»، «اتجاه من اليمين لليسار»، «RTL»، «الأرقام تظهر معكوسة»، «تعريب الواجهة».

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MahsumahCloud/saudi-claude-skills/tree/HEAD/skills/arabic-rtl-ui

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Arabic RTL UI

Arabic version: SKILL.ar.md. Answer in the language the user writes in.

Arabic is written right to left, but numbers, Latin brand names, emails, URLs and code inside Arabic text still run left to right. A correct Arabic UI does not just flip everything. It sets direction once at the root, uses direction-agnostic (logical) styling, mirrors only what has a direction, and isolates the left-to-right pieces so the Unicode Bidirectional Algorithm does not reorder them.

When to use

  • Building a new Arabic-only or Arabic/English interface.
  • Adding an Arabic locale to an existing LTR product.
  • Bug reports such as: "the back arrow points the wrong way", "the phone number shows as 0055 5 12...", "the full stop appears at the start of the line", "the padding is on the wrong side in Arabic".
  • Reviewing a pull request that touches layout, icons, forms or number formatting in an Arabic product.

When NOT to use

  • Copy and wording quality in Arabic. Use arabic-copywriting.
  • Hijri/Gregorian date logic. Use hijri-dates.
  • Field validation rules (IBAN, VAT number, mobile). Use saudi-validators.
  • Hebrew, Persian or Urdu UIs share the mechanics but have their own fonts, digits and conventions. Adapt with care.

Method

  1. Set direction and language at the root. Put lang and dir on <html>, not on <body> or a wrapper div. Screen readers, hyphenation, font selection and the :dir() selector all read it from there.
    <html lang="ar" dir="rtl">
    
    For a mixed page, set lang/dir on the element that changes language (for example an English quote inside an Arabic page: <blockquote lang="en" dir="ltr">).
  2. Set direction per locale in the framework.
    • Next.js App Router: route on app/[locale]/layout.tsx and render <html lang={locale} dir={locale === 'ar' ? 'rtl' : 'ltr'}>. Calculate dir on the server, so the first paint is already RTL with no flash of mirrored layout.
    • React SPA: set document.documentElement.dir and .lang when the locale changes, before rendering the new strings.
    • Use the locale (ar, ar-SA) to decide direction. Do not use the user's country.
  3. Replace physical CSS with logical CSS. Every left/right in spacing, borders, positioning and text alignment becomes inline-start/inline-end. Physical values stay only for things that really are physical, such as a map overlay or a drawing canvas.
  4. In Tailwind, use logical utilities first, variants second. Use ms-*, me-*, ps-*, pe-*, start-*, end-*, text-start, text-end, rounded-s-*, rounded-e-*, border-s, border-e. Use rtl: and ltr: variants only for real exceptions, such as flipping an icon (rtl:-scale-x-100).
  5. Decide which icons mirror. Go through the icon set once and tag each icon "mirror" or "keep" (rules below). Apply the mirroring centrally with CSS, not per screen.
  6. Pick a digit policy. Decide once per product whether to show Western digits (0-9) or Arabic-Indic digits (٠-٩), and enforce it through Intl.NumberFormat with an explicit numbering system. Never rely on the default.
  7. Isolate LTR fragments. Wrap user-supplied or LTR data inside Arabic text (phone numbers, emails, URLs, order IDs, SKUs, code, English names) in <bdi> or in an element with dir="ltr" / unicode-bidi: isolate.
  8. Fix forms. Arabic text fields inherit RTL. Fields that hold LTR data (email, URL, phone, IBAN, card number, username, code) get dir="ltr" and inputmode/type hints. Free-text fields that may hold either language get dir="auto".
  9. Choose and tune the font. Use a font with real Arabic glyph coverage. Give Arabic a slightly taller line height than Latin. Remove letter-spacing on Arabic, and do not fake italics.
  10. Test in both directions with the checklist below before merging.

Logical property map

Physical (avoid)Logical (use)Tailwind
margin-leftmargin-inline-startms-4
margin-rightmargin-inline-endme-4
padding-left / padding-rightpadding-inline-start / padding-inline-endps-4 / pe-4
left: 0 / right: 0inset-inline-start: 0 / inset-inline-end: 0start-0 / end-0
text-align: lefttext-align: starttext-start
border-leftborder-inline-startborder-s
border-top-left-radiusborder-start-start-radiusrounded-ss-lg
float: leftfloat: inline-startfloat-start

margin-top/margin-bottom map to margin-block-start/margin-block-end. For horizontal Arabic text, block and physical vertical are the same, so converting them is optional.

Mirroring rules

Mirror when the icon shows direction of reading or movement through content:

  • Back / forward / next / previous arrows and chevrons, breadcrumb separators.
  • "Reply", "undo/redo" when drawn as curved arrows pointing along the text.
  • Progress bars, steppers, sliders and carousels (they fill or move from the start side).
  • List bullets with a direction, text-indent and outdent icons, and "send" icons drawn as an arrow along the line.

Keep as-is when the icon shows a real-world object or a universal convention:

  • Media controls: play, pause, fast-forward and rewind refer to tape direction, not reading direction.
  • Clocks, refresh/rotate (clockwise is clockwise in every culture), and checkmarks.
  • Logos, brand marks and product screenshots.
  • Phone numbers, code snippets, math and Latin text.
  • Icons of physical objects (camera, cart, lock), unless the object has a reading direction, such as a document with text lines.
  • Chart axes: time series may run either way. Pick one convention for the product, label the axis clearly, and test with users. Do not mirror half the charts.
/* Mirror only icons tagged as directional */
[dir="rtl"] .icon--directional { transform: scaleX(-1); }

Digits and numbers

  • new Intl.NumberFormat("ar-SA").format(1234.5) returns ١٬٢٣٤٫٥ (Arabic-Indic digits and Arabic separators) in Node.js 22. new Intl.NumberFormat("ar") returns 1,234.5 in the same runtime. Defaults depend on the locale tag and on the ICU/CLDR version, so they differ across browsers and runtimes.
  • State the numbering system explicitly:
    const fmt = new Intl.NumberFormat("ar-SA-u-nu-latn", { style: "currency", currency: "SAR" });
    fmt.format(1234.5); // "‏1,234.50 ر.س.‏" (Western digits, Arabic currency symbol)
    
    The output contains invisible right-to-left marks (U+200F). Do not compare formatted strings in tests by eye. Compare against the formatter's own output, or strip the marks first.
  • Parse user input after normalising Arabic-Indic (٠-٩) and Eastern Arabic/Persian (۰-۹) digits to ASCII. Users type both.
  • Keep machine values (IDs, amounts sent to APIs, invoice numbers) in ASCII digits. Format only at display time.

Bidi pitfalls

  • Neutral characters (spaces, punctuation, +, -, /, () take their direction from their neighbours. That is why +966 5x xxx xxxx inside an Arabic sentence can show as xxxx xxx 5x 966+, and why a full stop typed after an English word can jump to the far side.
  • Prefer isolates over marks. <bdi>, dir on an element, or unicode-bidi: isolate (CSS) correspond to the Unicode isolate characters U+2066 LRI, U+2067 RLI, U+2068 FSI and U+2069 PDI. The older marks (U+200E LRM, U+200F RLM) and embeddings (U+202A-U+202E) still work, but they leak into surrounding text and are hard to debug. Use raw control characters only in plain-text channels such as SMS, push notifications and <title>, where markup is not available.
  • Text that comes from users or a database and whose direction you do not know: use <bdi> or dir="auto". The browser then picks the direction from the first strong character.
  • Never build an Arabic sentence by concatenating translated fragments around a variable. Word order changes. Use full ICU MessageFormat strings with placeholders.

Forms

  • Labels, help text and errors follow the page direction. Set text-align: start, never left.
  • Email, URL, phone, IBAN, card, username, OTP code: dir="ltr", and keep the placeholder LTR too (placeholder="05xxxxxxxx"). In an RTL page you may still align the text to the inline end so it lines up with the other fields. Pick one rule and apply it everywhere.
  • Free text (name, address, notes, search): dir="auto". The field switches when the user starts typing in English.
  • Icons inside inputs (search magnifier, clear button, password eye): position them with inset-inline-start/inset-inline-end.
  • Validation messages appear under or beside the field on the inline-end side. Never rely on a red border on the left only.

Tables

  • With dir="rtl" on an ancestor, column order reverses automatically. The first column (usually the name or ID) appears on the right. Do not reorder data in code.
  • Align text columns to start. For numeric and amount columns, choose end alignment with tabular figures (font-variant-numeric: tabular-nums) so decimals line up.
  • Sticky first columns use inset-inline-start: 0, not left: 0.
  • Sort indicators and pagination arrows follow the mirroring rules.

Fonts

  • Choose a typeface designed with Arabic, for example from the Arabic subset on Google Fonts. Do not let the browser fall back to a system font halfway through a word.
  • Load the Arabic subset and declare an Arabic-first font stack for :lang(ar).
  • Arabic letters connect. Any letter-spacing other than normal breaks the joins. Reset it on :lang(ar) even if the Latin design uses tracking.
  • Arabic has tall ascenders, deep descenders and diacritics. Give it more line height than Latin (start around 1.6-1.8 for body text and tune visually). Avoid fixed-height containers that clip marks.
  • Do not use font-style: italic unless the font ships a real Arabic italic. Browsers otherwise slant the glyphs, which reads as a rendering error. Use weight or colour for emphasis.
  • Uppercase transforms do nothing to Arabic. Design emphasis that does not depend on text-transform.

Checklist

  • <html lang dir> set from the locale on the server, with no flash of wrong direction.
  • No left/right/ml-/mr-/pl-/pr-/text-left/text-right in components, except documented physical cases.
  • Directional icons tagged and mirrored centrally. Media, clock, check and logo icons untouched.
  • Digit policy decided and every number formatted with an explicit nu- extension.
  • Number input parsing accepts ٠-٩ and ۰-۹.
  • Phone, email, URL, IBAN, IDs and code isolated with <bdi>/dir="ltr" in text and in inputs.
  • Free-text inputs use dir="auto".
  • Translations are full sentences with placeholders, not concatenated fragments.
  • Arabic font loaded, letter-spacing reset, line height increased, no synthetic italics.
  • Tables: start-aligned text, end-aligned tabular numbers, logical sticky columns.
  • Keyboard Tab order follows visual order in RTL (do not override with positive tabindex).
  • Screen reader announces Arabic content with an Arabic voice (correct lang).
  • Screenshots taken in both ltr and rtl for every changed screen.
  • Long Arabic strings tested for overflow, truncation and wrapping.

Do / Don't

DoDon't
Set dir once on <html> and let it cascadeAdd dir="rtl" to random divs to patch spacing
Use ms-4, ps-4, start-0, text-startWrite rtl:mr-4 ltr:ml-4 pairs everywhere
Mirror arrows, chevrons, progress, slidersMirror play buttons, clocks, checkmarks, logos
Format numbers with -u-nu-latn or -u-nu-arab on purposeTrust the browser default digits
Wrap phone numbers and emails in <bdi>Insert random LRM characters until it "looks right"
dir="ltr" on email/phone/IBAN inputs, dir="auto" on free textForce the whole form to LTR
Reset letter-spacing for ArabicApply Latin tracking or faux italics to Arabic
Write full ICU messages with placeholdersConcatenate "تم حذف " + n + " ملف"

Examples

React + Tailwind: card header

Before:

<div className="flex items-center pl-4 border-l-4 border-emerald-500">
  <ArrowLeft className="mr-2" />
  <span className="text-left">رجوع</span>
  <span className="ml-auto">+966 55 123 4567</span>
</div>

Problems: physical padding, border and margins. The back arrow points left in RTL, where "back" means right. The phone number is not isolated and will reorder.

After:

<div className="flex items-center ps-4 border-s-4 border-emerald-500">
  <ArrowLeft className="me-2 rtl:-scale-x-100" aria-hidden />
  <span className="text-start">رجوع</span>
  <bdi className="ms-auto" dir="ltr">+966 55 123 4567</bdi>
</div>

Next.js App Router layout

// app/[locale]/layout.tsx
const RTL = new Set(["ar", "fa", "he", "ur"]);
export default async function RootLayout({ children, params }) {
  const { locale } = await params;
  const lang = locale.split("-")[0];
  return (
    <html lang={locale} dir={RTL.has(lang) ? "rtl" : "ltr"}>
      <body>{children}</body>
    </html>
  );
}

Plain CSS

Before:

.sidebar { position: fixed; left: 0; border-right: 1px solid #ddd; padding-left: 24px; }
.badge   { margin-left: 8px; letter-spacing: .05em; font-style: italic; }

After:

.sidebar { position: fixed; inset-inline-start: 0; border-inline-end: 1px solid #ddd; padding-inline-start: 24px; }
.badge   { margin-inline-start: 8px; }
:lang(ar) .badge { letter-spacing: normal; font-style: normal; font-weight: 600; }
:lang(ar) body { line-height: 1.7; }
[dir="rtl"] .icon--directional { transform: scaleX(-1); }

Bidi in text

Before: <p>للتواصل: [email protected].</p>. The full stop may render on the wrong side of the email. After: <p>للتواصل: <bdi>[email protected]</bdi>.</p>

Forms

<label for="email">البريد الإلكتروني</label>
<input id="email" type="email" dir="ltr" autocomplete="email" placeholder="[email protected]">

<label for="iban">رقم الآيبان</label>
<input id="iban" dir="ltr" inputmode="text" autocomplete="off" placeholder="SA00 0000 0000 0000 0000 0000">

<label for="notes">ملاحظات</label>
<textarea id="notes" dir="auto"></textarea>

Testing

  1. Toggle dir on <html> in DevTools and walk every changed screen in both directions.
  2. Use a pseudo-locale (long Arabic strings with a Latin word and a number inside) to expose overflow and bidi bugs before real translations arrive.
  3. Tab through each form in RTL. Focus must move in visual reading order (right to left, top to bottom).
  4. Run a screen reader (VoiceOver or NVDA) on one Arabic page and confirm it switches to an Arabic voice.
  5. Check one screen on a real phone in Arabic system language. Mobile keyboards and native date pickers behave differently from desktop.
  6. Add visual regression snapshots for rtl alongside ltr.

References

관련 스킬