# 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. Do NOT use for Arabic RTL (similar but different typography) unless user explicitly asks for shared RTL patterns, or for native mobile RTL (React Native I18nManager, SwiftUI, Android) which is out of scope. Use when this capability is needed. - Skill: `tomevault-io/hebrew-rtl-best-practices` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hebrew-rtl-best-practices` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hebrew-rtl-best-practices/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hebrew-rtl-best-practices --- # 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<{ locale: string }>; }) { 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

``` 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: [skills-il/localization](https://github.com/skills-il/localization) — distributed by [TomeVault](https://tomevault.io).