# Hebrew Rtl Best Practices

> Implement right-to-left (RTL) layouts for Hebrew web applications. Use when user asks about RTL layout, Hebrew text direction, bidirectional (bidi) text, Hebrew CSS, \"right to left\", or needs to build a Hebrew web UI. Covers CSS logical properties, the :dir() pseudo-class, Tailwind RTL, React/Next.js RTL setup, icon mirroring, Hebrew typography, and font selection. Activate for: ימין לשמאל, כיו…

- **Type:** Skill
- **Install:** `agentstack add skill-squadcodercom-squadcoder-hebrew-rtl-best-practices`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [squadcodercom](https://agentstack.voostack.com/s/squadcodercom)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [squadcodercom](https://github.com/squadcodercom)
- **Source:** https://github.com/squadcodercom/squadcoder/tree/main/.squadcoder/skills/hebrew-rtl-best-practices
- **Website:** https://squadcoder.com

## Install

```sh
agentstack add skill-squadcodercom-squadcoder-hebrew-rtl-best-practices
```

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

## About

# Hebrew 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.

When you genuinely need a direction-specific rule that logical properties cannot express, prefer the `:dir()` pseudo-class over `[dir="rtl"]` attribute selectors:

```css
/* Modern: matches the resolved direction, including dir="auto" and inheritance */
.chevron:dir(rtl) { transform: scaleX(-1); }

/* Older approach: only matches an explicit dir attribute on/above the element */
[dir="rtl"] .chevron { transform: scaleX(-1); }
```

`:dir()` is part of Selectors Level 4 and resolves the *computed* direction, so it also works for elements whose direction comes from `dir="auto"` or from an ancestor, where an attribute selector would miss them. Browser support: Chrome and Edge shipped it in version 120 (late 2023), Firefox has supported it for years, and Safari added it in 16.4. For older-browser support, keep an `[dir="rtl"]` fallback rule or use a logical property instead. Check current support at https://caniuse.com/css-dir-pseudo.

### Step 3: Handle Bidirectional Text
When mixing Hebrew 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 Hebrew text: Wrap in ``

**Numbers and dates:** Standalone numbers and DD/MM/YYYY dates inside Hebrew text usually render fine because digits are weak-LTR, but a number that is immediately followed by a sign, currency, or a second number can flip. When a value must keep a fixed visual order, isolate it with `` or `unicode-bidi: isolate` rather than trusting the default bidi resolution.

**`` vs ``:** use `` only when you want to *force* a direction (it overrides the bidi algorithm). For user-generated or unknown-direction content, prefer ``, which *isolates* the content so its direction is auto-detected and cannot leak into the surrounding text:

```html

שלום, {{ userName }}, ברוך הבא
```

For free-text fields, `dir="auto"` (or `unicode-bidi: plaintext` in CSS) lets the browser pick the base direction per value, which is the correct default for comments, names, and search queries where you do not know the language in advance.

**Shadows and gradients do not auto-flip.** CSS logical properties mirror layout, but `box-shadow`, `text-shadow`, and `linear-gradient` offsets/angles are physical and stay fixed when direction flips. A shadow offset of `4px 4px` that looks correct in LTR will point the "wrong" way relative to an RTL layout. Flip these explicitly with a `:dir(rtl)` (or `[dir="rtl"]`) override when their direction is meaningful.

### Step 4: Mirror Directional Icons

Icon mirroring is one of the highest-frequency RTL bugs. The rule: mirror icons whose meaning is tied to reading direction, leave everything else alone.

**Mirror these** (their direction encodes "forward/back/next/previous" relative to reading order):
- Navigation arrows, back/forward buttons, breadcrumb chevrons
- "Send" / submit arrows, carousel and pagination arrows
- Indentation, list-nesting, and reply arrows
- Progress indicators that imply forward motion

**Do NOT mirror these** (mirroring makes them wrong or unrecognizable):
- Logos and brand marks
- Checkmarks and X / close icons
- Media play buttons (a play button always points right, it refers to the timeline, not reading direction)
- Clocks and analog-time icons (clockwise is universal)
- Icons depicting real-world objects with a fixed orientation (a phone handset, a magnifying glass with the handle, most product icons)

Technique, mirror with a horizontal flip transform:

```css
/* Flip only when the document direction is RTL */
.icon-directional:dir(rtl) { transform: scaleX(-1); }
```

```html

  

```

Many icon sets (for example Material Symbols) already ship RTL-aware variants, prefer those over flipping when available, because a flipped icon can mis-render fine detail or embedded text.

### Step 5: Hebrew Typography
Recommended font stack:
```css
font-family: 'Heebo', 'Assistant', 'Rubik', 'Noto Sans Hebrew', sans-serif;
```

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

### Step 6: 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 { Heebo } from 'next/font/google';

const heebo = Heebo({
  subsets: ['hebrew', '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:**

MUI v6 and v7 use the official fork `@mui/stylis-plugin-rtl`, not the older community `stylis-plugin-rtl` package. The official fork fixes CSS-layers issues and supports current Stylis versions.

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

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

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

Confirm the exact import name and setup against the current MUI RTL guide (https://mui.com/material-ui/customization/right-to-left/) for your MUI version.

### Step 7: Common Pitfalls to Check
1. Directional icons -- mirror them (see Step 4 for which icons to flip and which to leave)
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 Hebrew readers
8. Shadows and gradients -- physical offsets/angles do not auto-flip (see Step 3)

## Examples

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

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 Hebrew 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 Hebrew"

```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 Hebrew font stack recommendations for sans-serif, serif, and monospace. Consult when converting any LTR stylesheet to RTL-compatible logical properties or choosing Hebrew web fonts.

## Gotchas
- CSS `text-align: left` is wrong for Hebrew. 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 |
| MDN `:dir()` pseudo-class | https://developer.mozilla.org/en-US/docs/Web/CSS/:dir | Syntax, behavior vs `[dir]` attribute selectors |
| Can I use: `:dir()` | https://caniuse.com/css-dir-pseudo | Current browser support table |
| MDN `` element | https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/bdi | Isolating user-generated bidi content |
| 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 |
| MUI Right-to-left | https://mui.com/material-ui/customization/right-to-left/ | `@mui/stylis-plugin-rtl` setup for current MUI |
| Google Fonts Hebrew | https://fonts.google.com/?subset=hebrew | Available Hebrew 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:** [squadcodercom](https://github.com/squadcodercom)
- **Source:** [squadcodercom/squadcoder](https://github.com/squadcodercom/squadcoder)
- **License:** MIT
- **Homepage:** https://squadcoder.com

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-squadcodercom-squadcoder-hebrew-rtl-best-practices
- Seller: https://agentstack.voostack.com/s/squadcodercom
- 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%.