rtl-skill / codex
AGENTS.md1 starsChanged 12 days agoMITView on GitHub
Arabic, Persian (Farsi), Urdu and Hebrew are written from right to left. A correct RTL interface is not a mirrored screenshot. The layout mirrors, but phone numbers, code, URLs, media controls and logos keep their own direction. Follow this guide whenever you write or change UI that will be shown in an RTL language, and check the result in a browser before you call the work done. Set both attributes on the root element: Physical properties stay on the same…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- rtlSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
14 rules. About 0 are common, 4 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
Do not use CSS direction: rtl instead of the attribute.
- Distinctive: line 85
Keep a physical value only when the thing must not mirror, such as a video scrubber or a code block.
- Distinctive: line 109
check marks, clocks, timers and other icons that show time running clockwise
- Very specific: line 127
If an icon already has a transform (rotation, animation), combine them in one declaration, otherwise the RTL rule replaces the other …
- Very specific: line 167
Do not fix order with invisible marks (RLM U+200F, LRM U+200E) sprinkled by hand.
- Very specific: line 192
Prefer type="text" inputmode="numeric" over type="number" for codes and phone numbers.
- Very specific: line 193
Put the "show password" toggle, the clear button and the error icon on the start or end side with logical properties, not with right: 8px.
- Distinctive: line 198
Use a font that has Arabic glyphs.
- Very specific: line 221
Avoid text-align: justify on narrow Arabic columns.
- Very specific: line 222
Do not use word-break: break-all on Arabic.
- Distinctive: line 236
Test with real translations, not lorem ipsum, and with the longest language you ship.
- Very specific: line 252
Always pass a region (ar-QA, not ar), and choose the digit system on purpose.
- Very specific: line 281
Use the rtl: and ltr: variants for what logical utilities cannot say: rtl:-scale-x-100 on directional icons, ltr:-translate-x-full …
- Very specific: line 324
Look at the page in the browser in RTL before you finish.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- rtl-skill:start --><!-- Generated by rtl-skill from skill-src/guide.md. Update it with: rtl-skill install codex -->Right-to-left (RTL) interfaces
Arabic, Persian (Farsi), Urdu and Hebrew are written from right to left. A correct RTL interface is not a mirrored screenshot. The layout mirrors, but phone numbers, code, URLs, media controls and logos keep their own direction. Follow this guide whenever you write or change UI that will be shown in an RTL language, and check the result in a browser before you call the work done.
Quick checklist
<html lang="ar" dir="rtl">(with the right language) is set from the active locale in one place.- No
leftorrightin layout CSS. Use logical properties:margin-inline-start,padding-inline-end,inset-inline-start,border-inline-start,text-align: start. - Flex rows and grid columns are left alone. They already follow
dir. Never addrow-reverseto "make it RTL". - Directional icons (back, next, chevrons, arrows, send, reply, undo) are mirrored in RTL. Media controls, check marks, clocks and logos are not.
- Phone numbers, order ids, code, URLs, emails and Latin names inside RTL text are isolated with
<bdi>ordir="ltr". - Email, URL, phone and code inputs have
dir="ltr". Free-text inputs havedir="auto". - Arabic-script text has a font with Arabic glyphs, a line-height of at least 1.5 for body text, no letter-spacing and no italics.
- Boxes that hold text have no fixed width or height. Translated labels change length, and Arabic lines are taller.
- Numbers, dates and currency go through
Intlwith a full locale such asar-QA, and the digit system is a deliberate choice. - Progress bars, sliders, steppers and carousels run from the right. Chart axes follow a documented product decision.
- Transforms (
translateX,transform-origin) and JavaScript that reads or setsleftare made direction-aware.
Document direction and language
Set both attributes on the root element:
<html lang="ar-QA" dir="rtl">dirdrives layout, the Unicode bidi algorithm,:dir()and[dir="rtl"]selectors, and Tailwind'srtl:variant.langdrives font fallback, hyphenation, quotation marks,:lang()selectors and the screen reader voice.- Do not use CSS
direction: rtlinstead of the attribute. Assistive technology,[dir]selectors and Tailwind variants do not see CSS direction. - Derive both from the locale in one place:
const RTL = new Set(['ar', 'fa', 'he', 'ur', 'ps', 'sd', 'ug', 'ckb', 'dv', 'yi']);
export function directionOf(locale) {
const loc = new Intl.Locale(locale);
const info = loc.getTextInfo ? loc.getTextInfo() : loc.textInfo; // Chromium, Safari, Node
if (info && info.direction) return info.direction;
return RTL.has(loc.language) ? 'rtl' : 'ltr'; // Firefox has no textInfo
}
document.documentElement.lang = locale;
document.documentElement.dir = directionOf(locale);- An English block inside an Arabic page gets
dir="ltr" lang="en"on its own container. Do not flip the whole page. - Content whose language you do not know (comments, chat messages, names, search results) gets
dir="auto"on each item, so each item takes the direction of its first strong letter.
Logical CSS properties
Physical properties stay on the same side whatever the direction. Logical properties follow dir.
| Physical (stays put) | Logical (flips with dir) |
margin-left, margin-right | margin-inline-start, margin-inline-end |
padding-left, padding-right | padding-inline-start, padding-inline-end |
left, right on positioned boxes | inset-inline-start, inset-inline-end |
border-left, border-right | border-inline-start, border-inline-end |
border-top-left-radius | border-start-start-radius |
border-top-right-radius | border-start-end-radius |
border-bottom-left-radius | border-end-start-radius |
border-bottom-right-radius | border-end-end-radius |
text-align: left / right | text-align: start / end |
float: left / right | float: inline-start / inline-end |
clear: left / right | clear: inline-start / inline-end |
margin: 0 16px 0 0 | margin-block: 0; margin-inline: 0 16px |
width, height | inline-size, block-size (optional) |
- Symmetric values are fine:
margin: 0 auto,padding: 8px 16px,left: 0; right: 0. - Four-value shorthands for
margin,padding,inset,border-widthandborder-radiusare physical. Split them into-blockand-inlinepairs. - These never flip on their own:
transform: translateX(),transform-origin: left,background-position: left,object-position,box-shadowx offsets, and gradients that sayto right. Override them for RTL:
.drawer { transform: translateX(-100%); }
[dir="rtl"] .drawer { transform: translateX(100%); }
.shadow-start { box-shadow: 4px 0 8px rgb(0 0 0 / 0.1); }
[dir="rtl"] .shadow-start { box-shadow: -4px 0 8px rgb(0 0 0 / 0.1); }:dir(rtl)works in all current browsers and also matches elements whose direction comes from an ancestor.[dir="rtl"] &works everywhere.- Keep a physical value only when the thing must not mirror, such as a video scrubber or a code block.
Flex, grid and positioning
display: flexwithflex-direction: rowalready starts from the right in RTL.justify-content: flex-startmeans the right side. Do not addrow-reverseororderfor RTL: withdir="rtl"set, that reverses twice and puts the first item on the left.- Grid columns,
grid-column: 1 / 3andgrid-template-areasfollowdirtoo. - Push an item to the end with
margin-inline-start: auto(Tailwindms-auto), notmargin-left: auto. - Absolutely positioned boxes (badges, close buttons, tooltips):
inset-inline-end: 8px, notright: 8px. - Off-canvas menus: in an RTL document, overflow to the left becomes scrollable. A
position: absolutedrawer parked atleft: -300px(fine in LTR) adds a horizontal scrollbar to the RTL page.position: fixedboxes never add one.visibility: hiddenandopacity: 0do not help a parked box: it still widens the page. Usedisplay: nonefor closed panels, or keep them in place withinset-inline-startand hide them there. - Horizontal scroll containers:
scrollLeftis 0 at the start edge and negative toward the end in RTL in all current browsers. UsescrollBy({ left: dir === 'rtl' ? -step : step })orscrollIntoView({ inline: 'start' }). - JavaScript positioning for tooltips, popovers and dropdowns: read
getComputedStyle(el).directionand place relative to the start edge, or use a positioning library that supports-start/-endplacements in RTL. - Fixed widths wider than a phone screen (
width: 480pxon a card,min-widthon a table) overflow to the left in RTL. Usemax-inline-size: 100%. Long URLs and codes can do the same, so give themoverflow-wrap: anywhere.
Icons: mirror or not
Mirror in RTL. These point along the reading direction or through content:
- back and forward, previous and next, chevrons in breadcrumbs, pagination, list rows and "read more" links
- send, reply, reply all, forward (mail), undo and redo, log out and exit, indent and outdent
- arrows on steppers and progress, and any icon that shows lines of text (swap "align left" and "align right")
Do not mirror:
- media controls: play, pause, fast forward, rewind, skip. They follow tape direction, not reading direction.
- check marks, clocks, timers and other icons that show time running clockwise
- logos, brand marks, flags, and icons that contain Latin letters or digits
- most real-world objects (a phone handset, a camera, a magnifying glass) unless your design system says otherwise
How to mirror:
[dir="rtl"] .icon-directional { transform: scaleX(-1); }<a href="/orders?page=2" aria-label="الصفحة التالية">
<svg class="icon icon-directional" aria-hidden="true"><use href="#chevron-right"></use></svg>
</a>- Tailwind:
class="rtl:-scale-x-100"on the icon. - Or swap the asset by direction:
isRtl ? <ChevronLeft /> : <ChevronRight />. - If an icon already has a transform (rotation, animation), combine them in one declaration, otherwise the RTL rule replaces the other transform. Or use the separate
scale: -1 1property, which stacks withtransform. - Give icon-only buttons an
aria-labelthat names the action ("التالي", "رجوع"). Screen readers need it, and so does any checker that has to decide which way the icon should point.
Arrow characters: → and ← (and ➜, ⇒) are not mirrored by the bidi algorithm. "اقرأ المزيد →" shows an arrow pointing back. Write ← for "forward" in RTL text, or use a mirrored icon. Paired characters ( ) [ ] { } < > « » ‹ › are mirrored automatically inside RTL runs, so ‹ in RTL text already shows the right way.
Numbers, phone numbers, code and URLs inside RTL text
The Unicode bidi algorithm reorders runs of text. Runs of a single direction are safe. Trouble starts when weak or neutral characters (digits, +, -, #, (), .) sit at the edges of a Latin or number run inside RTL text. These are real Chromium renderings, read left to right:
| Source text | Shows on screen |
اتصل بنا على +974 5555 1234 | 1234 5555 974+ (groups reversed) |
رقم ٥٥٥٥ ١٢٣٤ | ١٢٣٤ ٥٥٥٥ |
رقم الطلب #A-1029 | A-1029# |
تعلم C++ اليوم | ++C |
استدع print() أولا | ()print |
C# و .NET | #C and NET. |
قطر +974 | 974+ |
Isolate the island so it is laid out on its own, left to right:
<p>اتصل بنا على <bdi dir="ltr">+974 5555 1234</bdi></p>
<p>رقم الطلب <span dir="ltr">#A-1029</span></p>
<p>استدع <code dir="ltr">print()</code> أولا</p><bdi>isolates its content. Adddir="ltr"when you know the content is LTR. Without it,<bdi>guesses from the first strong letter.<span dir="ltr">isolates too: in HTML, any element with adirattribute getsunicode-bidi: isolate.- In CSS:
.ltr { direction: ltr; unicode-bidi: isolate; }. - In plain strings where you cannot add markup (
title,placeholder,<option>,aria-label, notifications,document.title), wrap the value in Unicode isolates: LRIU+2066... PDIU+2069for LTR, or FSIU+2068... PDI when the direction is unknown.
const ltr = (s) => `\u2066${s}\u2069`;
t('call_us', { phone: ltr('+974 5555 1234') });- Code blocks:
<pre dir="ltr">and<code dir="ltr">. Inline code inside Arabic text needs it too. - Ranges and fractions in running Arabic text (
من 10 إلى 20,2020-2024) are read right to left by Arabic readers. Leave them as they are. - User content in either direction:
dir="auto"on each message, andunicode-bidi: plaintextfor multi-paragraph text where each paragraph may differ. - Do not fix order with invisible marks (RLM
U+200F, LRMU+200E) sprinkled by hand. Isolation is easier to read and does not leak into copy and paste.
Forms and mixed-direction inputs
<label for="email">البريد الإلكتروني</label>
<input id="email" type="email" dir="ltr" autocomplete="email" placeholder="name@example.com">
<label for="phone">رقم الجوال</label>
<input id="phone" type="tel" dir="ltr" inputmode="tel" autocomplete="tel" placeholder="+974 5555 1234">
<label for="name">الاسم</label>
<input id="name" dir="auto" autocomplete="name">dir="ltr"on email, URL, IBAN, card number, coupon code, username and password fields, and on any phone field that is nottype="tel". Chromium and WebKit already rendertype="tel"left to right, but a phone number intype="text"shows as1234 5555 974+. Email and URL fields stay RTL, so the trailing.or/of a half-typed value jumps to the front:name@doha.shows as.name@doha.- With
dir="ltr"the value is aligned left. To keep it on the right edge like the other fields, addtext-align: rightto that input. The value keeps its LTR order. dir="auto"for names, addresses, messages and search boxes, which people type in either script.- Accept Arabic-Indic digits. Many people type
٥٥٥٥on an Arabic keyboard. Normalize before validating:
// U+0660..U+0669 (Arabic-Indic) and U+06F0..U+06F9 (Persian) -> 0..9
const toLatinDigits = (s) => s.replace(/[\u0660-\u0669\u06F0-\u06F9]/g, (d) => String(d.charCodeAt(0) & 0xf));- Prefer
type="text" inputmode="numeric"overtype="number"for codes and phone numbers. - Put the "show password" toggle, the clear button and the error icon on the start or end side with logical properties, not with
right: 8px. - Label and checkbox spacing: use
gapon a flex row instead ofmargin-lefton the label.
Arabic typography
- Use a font that has Arabic glyphs. A Latin web font with a generic fallback leaves Arabic to whatever font the operating system picks, at a different size and weight:
:root { font-family: "Inter", system-ui, sans-serif; }
:lang(ar) { font-family: "IBM Plex Sans Arabic", "Noto Sans Arabic", "Segoe UI", Tahoma, sans-serif; }
:lang(fa) { font-family: "Vazirmatn", "Noto Sans Arabic", Tahoma, sans-serif; }
:lang(ur) { font-family: "Noto Nastaliq Urdu", "Noto Naskh Arabic", serif; line-height: 2.2; }
:lang(he) { font-family: "Heebo", "Noto Sans Hebrew", "Segoe UI", Arial, sans-serif; }- Good families with Arabic: IBM Plex Sans Arabic, Noto Sans Arabic, Noto Naskh Arabic, Cairo, Tajawal, Almarai, Readex Pro, and Vazirmatn for Persian. Load only the weights you use. Arabic fonts are large, and
unicode-rangelets Latin and Arabic come from separate files. - Line height: Arabic has tall ascenders, deep descenders and marks above and below the letters. Use at least 1.5 for body text and about 1.25 for headings. Nastaliq (Urdu) needs about 2 to 2.3.
- Never put
letter-spacingon Arabic-script text. Arabic letters join, and spacing pulls them apart: Safari (WebKit) draws every letter disconnected. Current Chromium ignores letter-spacing on Arabic, so the page looks fine in Chrome and breaks in Safari and other iOS browsers. Reset it after the rule that sets it:
.btn, .eyebrow { letter-spacing: 0.08em; }
:lang(ar) .btn, :lang(ar) .eyebrow,
:lang(fa) .btn, :lang(fa) .eyebrow,
:lang(ur) .btn, :lang(ur) .eyebrow { letter-spacing: 0; }text-transform: uppercaseand small caps do nothing for Arabic, so do not rely on case for emphasis. Most Arabic fonts have no italic and the browser fakes a slant. Use weight or color, and set:lang(ar) em, :lang(ar) i { font-style: normal; }.- Arabic looks smaller than Latin at the same
font-size. Many products raise Arabic body text by 1 or 2 pixels. - Avoid
text-align: justifyon narrow Arabic columns. Browsers stretch the spaces instead of using kashida, which leaves rivers. - Do not use
word-break: break-allon Arabic. It splits joined words. Useoverflow-wrap: anywhereonly for long Latin tokens such as URLs.
Truncation and text that grows
- Translated labels change length, and Arabic lines are taller than Latin ones. Do not give buttons, tabs, badges, chips or table headers a fixed
widthorheight. Usemin-inline-size,padding-inlineandmin-block-size, and let them grow. overflow: hiddenwith a fixedheightcuts off Arabic marks below the baseline even when the text fits on one line.- Truncate on purpose, never by accident:
.title { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } /* the ellipsis lands on the left in RTL */
.excerpt { display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }- Give truncated user content
dir="auto"so the ellipsis sits at the end of each item in its own direction. - Test with real translations, not lorem ipsum, and with the longest language you ship.
Dates, numbers and currency with Intl
Pass a full locale to Intl. Do not build these strings by hand. Output below is from Chromium 156:
const d = new Date(Date.UTC(2026, 9, 30));
new Intl.NumberFormat('ar-QA').format(1234.5); // "١٬٢٣٤٫٥"
new Intl.NumberFormat('ar-QA-u-nu-latn').format(1234.5); // "1,234.5"
new Intl.NumberFormat('ar-QA', { style: 'currency', currency: 'QAR' }).format(1250.5); // "١٬٢٥٠٫٥٠ ر.ق." wrapped in U+200F marks
new Intl.DateTimeFormat('ar-QA', { dateStyle: 'long' }).format(d); // "٣٠ أكتوبر ٢٠٢٦"
new Intl.DateTimeFormat('fa-IR', { dateStyle: 'long' }).format(d); // "۸ آبان ۱۴۰۵" (Solar Hijri calendar)- Digits depend on the locale.
ar-QA,ar-SAandar-EGgive Arabic-Indic digits (١٢٣).ar-AE,ar-MAand plainargive Latin digits (123).fagives Persian digits (۱۲۳), which differ from Arabic ones for 4, 5 and 6.heandur-PKgive Latin digits. - Always pass a region (
ar-QA, notar), and choose the digit system on purpose. Many Gulf products show Latin digits in Arabic UI with-u-nu-latn. Never mix digit systems on one screen. - Calendars:
fa-IRformats in the Solar Hijri calendar by default. Ask for one explicitly when it matters:ar-SA-u-ca-islamic-umalqurafor Hijri,-u-ca-gregoryfor Gregorian. - Currency and percent strings from Intl contain invisible direction marks (
U+200F,U+200E,U+061C). Keep them, and normalize them away before comparing strings in tests. - Arabic has six plural categories (zero, one, two, few, many, other). Use
Intl.PluralRules('ar')or ICU MessageFormat, nevercount === 1 ? a : b. new Intl.RelativeTimeFormat('ar', { numeric: 'auto' }).format(-1, 'day')gives "أمس".Intl.ListFormatjoins lists with the right conjunction.
Charts, progress bars and sliders
- Progress bars, steppers, sliders, carousels and rating stars run from the right in RTL. Native
<progress>and<input type="range">already do. Custom ones break when built withleft: 0,transform-origin: leftortranslateX:
/* breaks: still fills from the left in RTL */
.bar-fill { transform-origin: left; transform: scaleX(var(--progress)); }
/* works: size it and let it flow from the start side */
.bar-fill { inline-size: calc(var(--progress) * 100%); }- Charts: for bar and column charts, mirror the category order and put the value axis on the right. For time series, make one product decision and document it: some Arabic products mirror time to run right to left, many financial ones keep it left to right.
- Chart.js:
scales.x.reverse: true,scales.y.position: 'right', andrtl: trueonplugins.legendandplugins.tooltip. - ECharts:
xAxis.inverse: true,yAxis.position: 'right'. - Recharts:
<XAxis reversed />and<YAxis orientation="right" />.
- Chart.js:
- SVG text: set
direction: rtlon<text>elements with Arabic. With it,text-anchor: startanchors the right edge. - Carousels: swipe and arrow keys reverse. In RTL, ArrowLeft means "next". Swiper reads
dir="rtl"from its container. Embla takesdirection: 'rtl'.
Tailwind CSS
- Logical utilities (v3.3 and later):
ms-*andme-*(margin-inline),ps-*andpe-*(padding-inline),start-*andend-*(inset-inline),border-sandborder-e,rounded-s-*,rounded-e-*,rounded-ss-*,rounded-se-*,rounded-es-*,rounded-ee-*,text-startandtext-end,scroll-ms-*.float-startandfloat-endarrived in v3.4. - Replace on sight:
ml-2withms-2,pr-4withpe-4,left-0withstart-0,text-leftwithtext-start,rounded-l-lgwithrounded-s-lg,border-rwithborder-e,ml-autowithms-auto. - Use the
rtl:andltr:variants for what logical utilities cannot say:rtl:-scale-x-100on directional icons,ltr:-translate-x-full rtl:translate-x-fullon a closed drawer. space-x-*uses physical margins in v3. Addrtl:space-x-reverse, or better, usegap-*. In v4,space-x-*uses logical margins.- The
rtl:variant matches[dir="rtl"]on an ancestor (v4 also matches:dir(rtl)). Setdiron<html>, not only through CSS.
React
// Next.js App Router: app/[locale]/layout.tsx
export default async function RootLayout({ children, params }) {
const { locale } = await params;
return (
<html lang={locale} dir={directionOf(locale)}>
<body>{children}</body>
</html>
);
}- In client-rendered apps, set
document.documentElement.dirandlangin an effect when the locale changes. Adiron a wrapper div is not enough: portals (modals, toasts, menus) render outside it. - Inline styles support logical properties:
style={{ marginInlineStart: 8 }}instead ofmarginLeft. - Component libraries have an RTL switch. Use it instead of overriding their CSS: MUI
createTheme({ direction: 'rtl' })plus an Emotion cache withstylis-plugin-rtl, Radix<DirectionProvider dir="rtl">, Ant Design<ConfigProvider direction="rtl">, Mantine<DirectionProvider>. - Mirror directional icons in one wrapper instead of at every call site:
- React Native:
I18nManager.forceRTL(true)and restart the app. UsemarginStart,marginEnd,paddingStart,startandendinstead of left and right, andI18nManager.isRTLfor icons.
Vue
import { watch } from 'vue';
watch(locale, (value) => {
document.documentElement.lang = value;
document.documentElement.dir = directionOf(value);
}, { immediate: true });- Nuxt:
useHead({ htmlAttrs: { lang, dir } }). <Teleport to="body">content inherits the direction of<html>, which is one more reason to setdirthere.- Bind logical inline styles:
:style="{ marginInlineStart: '8px' }". - Vuetify and Quasar have RTL options. Turn them on instead of overriding their CSS.
Check your work
Look at the page in the browser in RTL before you finish. If the project has rtl-check (from github.com/Ifazawezk/rtl-skill), run it against the running page and fix every error it reports:
npx rtl-check http://localhost:3000/ar --out rtl-reportIt opens the page in Chromium, renders it in RTL and LTR, and reports missing dir and lang, physical CSS, layout that does not mirror, LTR islands rendered out of order, LTR fields without dir, icons that point the wrong way, overflow past the viewport, clipped text and letter-spacing on Arabic. rtl-report/annotated.png marks every finding on a screenshot.
<!-- rtl-skill:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

