hebrew-tailwind-preset

What this skill does

# Hebrew Tailwind Preset

Tailwind CSS v4.0+ recommended; v3.1+ is compatible for `dir` variants. Works with React, Vue, Angular, Next.js, and Nuxt. No network required.

## Instructions

### Step 1: Install and Configure Tailwind v4 for RTL

See `references/rtl-config.md` for complete configuration reference.

**Install the Tailwind v4 build plugin first.** Tailwind v4 dropped the automatic `tailwind.config.js` loading, so `@import "tailwindcss"` alone will not build until a build plugin is wired. Pick the one matching your toolchain:

```bash
# Vite (recommended): install the first-party Vite plugin
npm install tailwindcss @tailwindcss/vite
```

```js
// vite.config.js -- add the plugin
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});
```

```bash
# PostCSS-based toolchains (Next.js, Webpack, etc.)
npm install tailwindcss @tailwindcss/postcss postcss
```

```js
// postcss.config.mjs
export default {
  plugins: { '@tailwindcss/postcss': {} },
};
```

In v4 the `@tailwindcss/postcss` plugin handles `@import` inlining and vendor prefixing, so `postcss-import` and `autoprefixer` are no longer needed.

Then load Hebrew fonts with `font-display: swap` (via a Google Fonts `<link>` or an `@font-face` rule) to avoid a Flash of Invisible Text while the Hebrew font file loads. See Step 2 for the snippet.

**Tailwind v4 (CSS-first configuration):**
```css
/* app.css -- imported by your build entry */
@import "tailwindcss";

@theme {
  /* Hebrew font stacks */
  --font-hebrew: 'Heebo', 'Assistant', 'Noto Sans Hebrew', sans-serif;
  --font-hebrew-serif: 'Frank Ruhl Libre', 'David Libre', serif;
  --font-mono: 'Fira Code', 'Source Code Pro', monospace;

  /* Hebrew-optimized type scale */
  --text-xs: 0.8125rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;
  --text-4xl: 2.25rem;

  /* Hebrew line heights (taller than Latin defaults) */
  --leading-tight: 1.4;
  --leading-normal: 1.7;
  --leading-relaxed: 1.9;
}
```

**Tailwind v3 (JavaScript configuration):**
```js
// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,jsx,tsx}'],
  theme: {
    extend: {
      fontFamily: {
        hebrew: ['Heebo', 'Assistant', 'Noto Sans Hebrew', 'sans-serif'],
        'hebrew-serif': ['Frank Ruhl Libre', 'David Libre', 'serif'],
      },
      lineHeight: {
        'hebrew': '1.7',
        'hebrew-tight': '1.4',
        'hebrew-relaxed': '1.9',
      },
    },
  },
  plugins: [],
};
```

**Load the Hebrew fonts with `font-display: swap`.** Either add a Google Fonts `<link>` in your HTML head:

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Heebo:wght@400;500;700&family=Assistant:wght@400;600&display=swap" rel="stylesheet">
```

Or self-host with an `@font-face` rule inside the same CSS file as your `@theme` block:

```css
@font-face {
  font-family: 'Heebo';
  src: url('/fonts/heebo-variable.woff2') format('woff2');
  font-weight: 400 700;
  font-display: swap;
}
```

The `&display=swap` query param (link) and the `font-display: swap` descriptor (`@font-face`) both make the browser render fallback text immediately instead of hiding text until the Hebrew font loads.

### Step 2: Use Logical Property Utilities

Always prefer logical utilities over physical directional ones:

| Physical (avoid) | Logical (use) | RTL Behavior |
|-------------------|--------------|--------------|
| `ml-4` | `ms-4` | Right margin in RTL |
| `mr-4` | `me-4` | Left margin in RTL |
| `pl-4` | `ps-4` | Right padding in RTL |
| `pr-4` | `pe-4` | Left padding in RTL |
| `left-0` | `start-0` | Right: 0 in RTL |
| `right-0` | `end-0` | Left: 0 in RTL |
| `border-l` | `border-s` | Right border in RTL |
| `border-r` | `border-e` | Left border in RTL |
| `rounded-l-lg` | `rounded-s-lg` | Right rounded in RTL |
| `rounded-r-lg` | `rounded-e-lg` | Left rounded in RTL |
| `text-left` | `text-start` | Right-aligned in RTL |
| `text-right` | `text-end` | Left-aligned in RTL |
| `scroll-ml-4` | `scroll-ms-4` | Right scroll margin in RTL |

### Step 3: Use Dir Variants for RTL-Specific Styles

**Prerequisite:** the `rtl:` and `ltr:` variants (built into Tailwind v4) match on an ancestor's `dir` attribute. They do nothing unless an ancestor element actually carries `dir="rtl"` (or `dir="ltr"`) - normally the `<html>` element. Set `dir="rtl"` on the root before relying on any `rtl:` utility below.

When you need direction-specific overrides:

```html
<!-- Root setup -- dir="rtl" here is what activates every rtl: variant -->
<html lang="he" dir="rtl">

<!-- Dir variant usage -->
<div class="flex rtl:flex-row-reverse">
  <span class="rtl:rotate-180">&#8594;</span>
  <span>הבא</span>
</div>

<!-- Icon mirroring for directional icons -->
<button class="flex items-center gap-2">
  <svg class="rtl:scale-x-[-1]"><!-- arrow icon --></svg>
  <span>חזרה</span>
</button>

<!-- Conditional spacing that differs by direction -->
<div class="ltr:ml-auto rtl:mr-auto">
  <!-- Push to end in both directions -->
</div>
```

### Step 4: Hebrew Typography Utilities

```html
<!-- Hebrew body text with proper settings -->
<body dir="rtl" class="font-hebrew text-base leading-hebrew
                        tracking-normal">

  <!-- Hebrew heading -->
  <h1 class="text-3xl font-bold leading-hebrew-tight">
    כותרת ראשית
  </h1>

  <!-- Hebrew paragraph -->
  <p class="text-base leading-hebrew [word-spacing:0.05em]">
    טקסט גוף עם ריווח מותאם לקריאות עברית.
  </p>

  <!-- Mixed Hebrew + English content -->
  <p class="text-base leading-hebrew">
    פריט מספר <span dir="ltr" class="font-mono">ORD-12345</span> אושר
  </p>
</body>
```

### Step 5: RTL-First Component Patterns with Tailwind

**RTL-first card:**
```html
<div class="rounded-lg border border-gray-200 p-6">
  <div class="flex items-center justify-between mb-4
              border-b border-gray-100 pb-4">
    <h3 class="text-lg font-bold">כותרת הכרטיס</h3>
    <span class="text-sm text-gray-500">פעיל</span>
  </div>
  <p class="text-base leading-hebrew text-gray-700">
    תוכן הכרטיס עם טקסט בעברית.
  </p>
  <div class="mt-4 flex gap-3">
    <button class="bg-blue-600 text-white px-4 py-2 rounded-md">
      אישור
    </button>
    <button class="border border-gray-300 px-4 py-2 rounded-md">
      ביטול
    </button>
  </div>
</div>
```

**RTL-first navigation:**
```html
<nav dir="rtl" class="flex items-center justify-between
                       px-6 py-4 bg-white border-b">
  <div class="flex items-center gap-3">
    <img src="/logo.svg" alt="לוגו" class="h-8">
    <span class="font-bold text-xl">שם האתר</span>
  </div>
  <ul class="flex gap-6 text-sm font-medium">
    <li><a href="/" class="text-blue-600">ראשי</a></li>
    <li><a href="/about" class="text-gray-600">אודות</a></li>
    <li><a href="/contact" class="text-gray-600">צור קשר</a></li>
  </ul>
</nav>
```

**RTL-first sidebar layout:**
```html
<div class="grid grid-cols-[280px_1fr] min-h-screen">
  <!-- Sidebar: appears on right in RTL automatically -->
  <aside class="border-e border-gray-200 pe-6 p-4">
    <nav class="space-y-2">
      <a href="#" class="block ps-4 py-2 rounded-md
                         bg-blue-50 text-blue-700 border-s-4
                         border-blue-600">לוח בקרה</a>
      <a href="#" class="block ps-4 py-2 rounded-md
                         text-gray-600">הגדרות</a>
    </nav>
  </aside>
  <!-- Main content -->
  <main class="p-6">
    <h1 class="text-2xl font-bold mb-6">לוח בקרה</h1>
  </main>
</div>
```

### Step 6: Form Utilities for Hebrew

```html
<form dir="rtl" class="max-w-lg space-y-6">
  <div>
    <label for="name" class="block text-sm font-medium
                              text-gray-700 mb-2">שם מלא</label>
    <input id="name" type