# Arabic Rtl Best Practices

> Implement right-to-left (RTL) layouts for Arabic web and mobile applications. Use when user asks about RTL layout, Arabic text direction, bidirectional (bidi) text, Arabic CSS, "right to left", or needs to build Arabic UI. Covers CSS logical properties, Tailwind RTL, React/Next.js RTL setup, Arabic typography, and font selection. Do NOT use for Arabic RTL (similar but different typography) unless…

- **Type:** Skill
- **Install:** `agentstack add skill-almubarmij-arabic-ai-skills-arabic-rtl-best-practices`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [alMubarmij](https://agentstack.voostack.com/s/almubarmij)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [alMubarmij](https://github.com/alMubarmij)
- **Source:** https://github.com/alMubarmij/Arabic-AI-Skills/tree/main/arabic-rtl-best-practices

## Install

```sh
agentstack add skill-almubarmij-arabic-ai-skills-arabic-rtl-best-practices
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Arabic RTL Best Practices

## Instructions

### Step 1: Set Up Document Direction
Always start with the HTML attribute (not just CSS):

```html

```

This tells browsers, screen readers, and CSS to use RTL as the base direction.

### Step 2: Use CSS Logical Properties
NEVER use physical directional properties for layout:

| Physical (avoid) | Logical (use) |
|-------------------|--------------|
| `margin-left` | `margin-inline-start` |
| `margin-right` | `margin-inline-end` |
| `padding-left` | `padding-inline-start` |
| `padding-right` | `padding-inline-end` |
| `border-left` | `border-inline-start` |
| `text-align: left` | `text-align: start` |
| `text-align: right` | `text-align: end` |
| `float: left` | `float: inline-start` |
| `left: 10px` | `inset-inline-start: 10px` |

This ensures the layout automatically mirrors in RTL mode.

### Step 3: Handle Bidirectional Text
When mixing Arabic and English/numbers:

```css
/* Isolate embedded LTR content */
.ltr-content {
  unicode-bidi: isolate;
  direction: ltr;
}

/* For inline elements with mixed content */
.bidi-override {
  unicode-bidi: bidi-override;
}
```

Common bidi issues:
- Phone numbers appearing reversed: Wrap in ``
- Punctuation at wrong end of sentence: Use `unicode-bidi: isolate`
- URLs/emails in Arabic text: Wrap in ``

### Step 4: Arabic Typography
Recommended font stack:
```css
font-family: 'Tajawal', 'Assistant', 'Rubik', 'Noto Sans Arabic', sans-serif;
```

Typography settings:
```css
body[dir="rtl"] {
  font-size: 16px; /* Arabic needs slightly larger than Latin */
  line-height: 1.7;
  letter-spacing: normal; /* NEVER add letter-spacing for Arabic */
  word-spacing: 0.05em; /* Slight word spacing improves readability */
}
```

### Step 5: Framework-Specific Setup

**Tailwind CSS RTL (v3.3+ / v4):**

Prefer logical property utilities over `rtl:`/`ltr:` variants:

| Physical class | Logical class | CSS property |
|---------------|--------------|-------------|
| `ml-4` | `ms-4` | `margin-inline-start` |
| `mr-4` | `me-4` | `margin-inline-end` |
| `pl-4` | `ps-4` | `padding-inline-start` |
| `pr-4` | `pe-4` | `padding-inline-end` |
| `left-4` | `start-4` | `inset-inline-start` |
| `right-4` | `end-4` | `inset-inline-end` |
| `rounded-l-lg` | `rounded-s-lg` | `border-start-start-radius` + `border-end-start-radius` |
| `rounded-r-lg` | `rounded-e-lg` | `border-start-end-radius` + `border-end-end-radius` |

```html

...

...
```

Reserve `rtl:` / `ltr:` variants only for cases logical properties cannot handle (e.g., directional icons, transforms).

**Tailwind v4 note:** v4 uses CSS-first configuration (`@import "tailwindcss"` in CSS) instead of `tailwind.config.js`. Logical utilities work identically in both v3 and v4.

**Next.js App Router:**
```tsx
// app/layout.tsx
import { Tajawal } from 'next/font/google';

const tajawal = Tajawal({
  subsets: ['arabic', 'latin'],
  weight: ['400', '500', '700'],
});

export default async function RootLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise;
}) {
  const { locale } = await params;
  const isRTL = locale === 'he';

  return (
    
      {children}
    
  );
}
```

`next/font` self-hosts the font (no external Google Fonts requests, zero layout shift).

**React with MUI:**
```jsx
import { createTheme, ThemeProvider } from '@mui/material/styles';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import rtlPlugin from 'stylis-plugin-rtl';
import { prefixer } from 'stylis';

const cacheRtl = createCache({
  key: 'muirtl',
  stylisPlugins: [prefixer, rtlPlugin],
});

const theme = createTheme({ direction: 'rtl' });
```

### Step 6: Common Pitfalls to Check
1. Icons with directional meaning (arrows, back buttons) -- mirror them
2. Progress bars -- should fill from right to left
3. Sliders/carousels -- swipe direction should reverse
4. Form labels -- should be right-aligned
5. Breadcrumbs -- separator direction should reverse
6. Tables -- header alignment and cell alignment
7. Charts -- x-axis may need to reverse for Arabic readers

## Examples

### Example 1: Convert LTR Component to RTL
User says: "Make this card component work in Arabic"

Before (LTR-only):
```css
.card {
  margin-left: 16px;
  padding-right: 12px;
  text-align: left;
  border-left: 3px solid blue;
}
```

After (RTL-compatible):
```css
.card {
  margin-inline-start: 16px;
  padding-inline-end: 12px;
  text-align: start;
  border-inline-start: 3px solid blue;
}
```

With Tailwind, replace `ml-4 pr-3 text-left border-l-4` with `ms-4 pe-3 text-start border-s-4`.

### Example 2: Bidi Text Issue
User says: "Numbers are showing backwards in my Arabic text"

```html

התקשרו אלינו: 050-321-4450

התקשרו אלינו: 050-321-4450
```

Use `unicode-bidi: isolate` on the containing span for CSS-only solutions.

### Example 3: Tailwind RTL Navigation
User says: "My sidebar is on the wrong side in Arabic"

```html

...

...

  

```

## Bundled Resources

### References
- `references/css-logical-properties.md` — Complete physical-to-logical CSS property mapping table (margin, padding, border, positioning, text alignment, sizing) plus Arabic font stack recommendations for sans-serif, serif, and monospace. Consult when converting any LTR stylesheet to RTL-compatible logical properties or choosing Arabic web fonts.

## Gotchas
- CSS `text-align: left` is wrong for Arabic. Use `text-align: start` which respects the document direction. Agents frequently hardcode `left` alignment in CSS.
- `margin-left` and `padding-right` do not flip in RTL mode. Use CSS logical properties: `margin-inline-start` and `padding-inline-end` instead. Agents trained on LTR CSS will generate physical properties.
- Flexbox `row` direction auto-reverses in RTL, but `row-reverse` also reverses, causing a double-flip back to LTR order. Agents may add `row-reverse` thinking it creates RTL, but it actually creates LTR within an RTL context.
- Phone numbers, credit card numbers, and code snippets must remain LTR even inside RTL containers. Wrap them in `` or use `direction: ltr` on the containing element. Agents often let these inherit RTL.

## Reference Links

| Source | URL | What to Check |
|--------|-----|---------------|
| MDN CSS Logical Properties | https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values | Full property list, browser support tables |
| Tailwind CSS RTL Support | https://tailwindcss.com/docs/hover-focus-and-other-states#rtl-support | `rtl:` / `ltr:` variant syntax |
| Tailwind Logical Properties | https://tailwindcss.com/docs/margin#logical-properties | `ms-*`, `me-*`, `ps-*`, `pe-*` utilities |
| Google Fonts Arabic | https://fonts.google.com/?subset=arabic | Available Arabic font families |
| W3C Internationalization | https://www.w3.org/International/articles/inline-bidi-markup/ | Unicode bidi algorithm, markup best practices |

## Troubleshooting

### Error: "Text alignment looks wrong"
Cause: Using `text-align: left` instead of `text-align: start`
Solution: Replace all `left`/`right` in text-align with `start`/`end`.

### Error: "Layout not mirroring"
Cause: Using physical margin/padding instead of logical properties
Solution: Replace all `margin-left`/`margin-right` with `margin-inline-start`/`margin-inline-end`.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alMubarmij](https://github.com/alMubarmij)
- **Source:** [alMubarmij/Arabic-AI-Skills](https://github.com/alMubarmij/Arabic-AI-Skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-almubarmij-arabic-ai-skills-arabic-rtl-best-practices
- Seller: https://agentstack.voostack.com/s/almubarmij
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.