hebrew-tailwind-preset

希伯来语 Tailwind 预设

推荐使用 Tailwind CSS v4（当前版本 v4.3，2026 年 5 月）；v3.3+ 也可用：逻辑工具类已经引入，且 rtl:/ltr: 变体在 v3.3.0 中标记为稳定。适用于 React、Vue、Angular、Next.js 和 Nuxt。无需网络。

使用说明

第 1 步：为 RTL 安装并配置 Tailwind v4

完整的配置参考请见 references/rtl-config.md。

首先安装 Tailwind v4 构建插件。 Tailwind v4 通过构建插件（Vite、PostCSS 或 webpack）运行，并在 CSS 中配置；tailwind.config.js 不再自动加载。请选择与你的工具链匹配的插件：

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

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

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

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

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

在 v4 中，@tailwindcss/postcss 插件负责 @import 内联和厂商前缀，因此不再需要 postcss-import 和 autoprefixer。对于不使用 PostCSS 的纯 webpack 构建，v4.2 新增了一个 loader：npm install @tailwindcss/webpack，然后在 .css 规则的 use 数组中，将 '@tailwindcss/webpack' 列在 'css-loader' 之后。

接着使用 font-display: swap（通过 Google Fonts 的 <link> 或 @font-face 规则）加载希伯来语字体，以避免希伯来语字体文件加载期间出现不可见文本闪烁（Flash of Invisible Text）。加载代码片段位于下方配置块之后。

Tailwind v4（CSS 优先配置）：

/* app.css -- imported by your build entry */
@import "tailwindcss";

@theme {
  /* Hebrew font stacks */
  --font-sans: 'Heebo', 'Assistant', 'Noto Sans Hebrew', sans-serif; /* default font for html, body and form controls */
  --font-hebrew: 'Heebo', 'Assistant', 'Noto Sans Hebrew', sans-serif;
  --font-hebrew-serif: 'Frank Ruhl Libre', 'David Libre', serif;
  --font-mono: 'Cousine', 'Fira Code', monospace; /* Cousine carries Hebrew glyphs for code comments; Fira Code does not */

  /* 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).
     The --leading-* namespace generates leading-<name> utilities,
     so these names are what make leading-hebrew, leading-hebrew-tight
     and leading-hebrew-relaxed exist. Naming them --leading-tight /
     --leading-normal / --leading-relaxed instead would only override
     the built-in scale and leave every leading-hebrew* class empty. */
  --leading-hebrew: 1.7;
  --leading-hebrew-tight: 1.4;
  --leading-hebrew-relaxed: 1.9;
}

Tailwind v3（JavaScript 配置）：

// 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: [],
};

使用 font-display: swap 加载希伯来语字体。 可以在 HTML head 中添加 Google Fonts 的 <link>：

<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&family=Cousine&display=swap" rel="stylesheet">

也可以在与 @theme 块相同的 CSS 文件中，通过 @font-face 规则自托管：

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

&display=swap 查询参数（link）和 font-display: swap 描述符（@font-face）都会给字体设置极短的阻塞期和无限的交换期：浏览器几乎立即显示回退文本，并在希伯来语字体到达后随时替换，而不是在加载期间隐藏文本。

Next.js：通过 @theme inline 接入 next/font。 当你使用 next/font 自托管时（Next.js 推荐做法：无外部请求、无布局偏移），字体会以 CSS 变量的形式暴露出来。将 --font-sans 指向它，因为 Preflight 从 --font-sans 获取页面的默认字体，表单控件会继承它（font: inherit），这样希伯来语就会成为所有位置的默认字体，而无需在每个元素上添加 font-hebrew 类：

/* app/globals.css */
@import "tailwindcss";
@theme inline {
  --font-sans: var(--font-heebo); /* --font-heebo comes from next/font */
  --font-hebrew: var(--font-heebo);
}

// app/layout.tsx
import './globals.css';
import { Heebo } from 'next/font/google';
const heebo = Heebo({ subsets: ['hebrew', 'latin'], variable: '--font-heebo' });
// <html lang="he" dir="rtl" className={heebo.variable}> ... </html>

将 heebo.variable 保留在 <html> 上，而不是 <body> 上。Preflight 在 html 上应用默认字体，因此定义在更下层的变量永远无法到达它——无论是否使用 inline——页面会静默回退到 Tailwind 的默认无衬线字体栈。为什么还需要 inline：引用另一个变量的主题变量会在定义该主题变量的位置（:root）解析，而不是在使用该工具类的位置解析。使用 inline 时，Tailwind 会将 var(--font-heebo) 直接写入诸如 font-hebrew 的工具类中，因此它们在使用该类的位置都能正确解析。两种情况下构建都会成功，这就是这两个错误都容易被忽略的原因。

步骤 2：使用逻辑属性工具类

Tailwind v4 原生的逻辑工具类和 rtl:/ltr: 变体本身就涵盖了 RTL，因此不再需要旧的社区插件 tailwindcss-rtl。始终优先使用逻辑工具类，而不是物理方向工具类：

物理方向（避免使用）	逻辑方向（使用）	RTL 行为
ml-4	ms-4	RTL 下为右边距
mr-4	me-4	RTL 下为左边距
pl-4	ps-4	RTL 下为右内边距
pr-4	pe-4	RTL 下为左内边距
left-0	inset-s-0	RTL 下为 right: 0（v4.2+；start-0 是已废弃的别名）
right-0	inset-e-0	RTL 下为 left: 0（v4.2+；end-0 是已废弃的别名）
border-l	border-s	RTL 下为右边框
border-r	border-e	RTL 下为左边框
rounded-l-lg	rounded-s-lg	RTL 下为右侧圆角
rounded-r-lg	rounded-e-lg	RTL 下为左侧圆角
text-left	text-start	RTL 下为右对齐
text-right	text-end	RTL 下为左对齐
scroll-ml-4	scroll-ms-4	RTL 下为右侧滚动外边距
mt-4 / mb-4	mbs-4 / mbe-4	块轴外边距（v4.2+）
pt-4 / pb-4	pbs-4 / pbe-4	块轴内边距（v4.2+）
border-t / border-b	border-bs / border-be	块轴边框（v4.2+）
top-0 / bottom-0	inset-bs-0 / inset-be-0	块轴 inset（v4.2+）
w-40 / h-20	inline-40 / block-20	逻辑尺寸（v4.2+，另有 min-inline-*、max-block-*）

Tailwind v4.2 inset 重命名。 自 v4.2 起（2026 年 2 月 18 日，在 v4.3 博客文章中再次提及），逻辑定位工具类 start-*/end-* 已被废弃，改用 inset-s-*/inset-e-*（以便与 inset-bs-*/inset-be-* 保持一致）。旧名称仍然可用，但在新代码中优先使用 inset-s-0/inset-e-0。此重命名仅影响 inset/定位；外边距/内边距/边框工具类 ms-*/me-*/ps-*/pe-*/border-s/border-e 保持不变。任意值也可以与逻辑工具类组合使用（例如 ms-[3px]、inset-s-[10px]）。

使用 @source，而不是 content 数组。 Tailwind v4 会自动检测你的模板，因此 v3 用户会去查找 content: [...] 键，却什么也找不到。Tailwind 不会扫描的路径（外部 UI 包、.gitignore 中的任何内容）需要在 CSS 中注册，相对于样式表：@source "../node_modules/@acmecorp/ui-lib";。这对于存放在共享组件库中的希伯来语标记尤为重要。

步骤 3：使用 Dir 变体处理 RTL 特定样式

变体的匹配方式。 在 v4 中，rtl: 编译为 :where(:dir(rtl), [dir="rtl"], [dir="rtl"] *)，而 ltr: 编译为对应的镜像选择器。在依赖下方任何 rtl: 工具类之前，请先在 <html> 上设置 dir="rtl"。有两个后果很容易被忽视。首先，ltr: 工具类在完全没有 dir 的页面上已经生效，因为默认方向就是 LTR。其次，在 RTL 页面内嵌套一个解析为 LTR 的 dir="auto" 孤岛，会同时匹配两种变体：rtl: 通过 [dir="rtl"] * 分支匹配，ltr: 通过 :dir(ltr) 匹配。对于此类孤岛中混合希伯来语/英语的用户内容，请使用逻辑工具类（ms-*、text-start），而不是 rtl:/ltr: 组合。

v4 中的深色模式。 v3 的 darkMode 配置键已被移除。在 v4 中，你需要通过 CSS 中的 @custom-variant dark (&:where(.dark, .dark *)); 选择加入基于类的深色模式，然后可以与方向自由组合，例如 class="dark:bg-gray-900 rtl:bg-linear-to-l"。在 <html> 上设置 dir="rtl"，并在同一元素上切换 .dark。

当你需要方向特定的覆盖时：

<html lang="he" dir="rtl">


<a class="inline-flex items-center gap-2">
  <span>הבא</span>
  <span class="rtl:-scale-x-100">&#8594;</span>
</a>




<button class="flex items-center gap-2">
  <svg class="rtl:scale-x-[-1]"></svg>
  <span>חזרה</span>
</button>


<div class="ms-auto">...</div>

步骤 4：希伯来语排版工具类

<body dir="rtl" class="font-hebrew text-base leading-hebrew
                        tracking-normal">

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

  
  <p class="text-base leading-hebrew">
    טקסט גוף בעברית.
  </p>

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

步骤 5：使用 Tailwind 的 RTL 优先组件模式

RTL 优先卡片：

<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 优先导航：

<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 优先侧边栏布局：

<div class="grid grid-cols-[280px_1fr] min-h-screen">
  
  <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 class="p-6">
    <h1 class="text-2xl font-bold mb-6">לוח בקרה</h1>
  </main>
</div>

步骤 6：希伯来语表单工具类

<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="text"
           class="w-full px-4 py-3 border border-gray-300
                  rounded-md text-base font-hebrew
                  focus:outline-none focus:ring-2
                  focus:ring-blue-500">
  </div>

  <div>
    <label for="phone" class="block text-sm font-medium
                               text-gray-700 mb-2">טלפון</label>
    <input id="phone" type="tel" dir="ltr"
           placeholder="05X-XXXXXXX"
           class="w-full px-4 py-3 border border-gray-300
                  rounded-md text-base
                  focus:outline-none focus:ring-2
                  focus:ring-blue-500">
  </div>

  <div>
    <label for="message" class="block text-sm font-medium
                                 text-gray-700 mb-2">הודעה</label>
    <textarea id="message" rows="4"
              class="w-full px-4 py-3 border border-gray-300
                     rounded-md text-base font-hebrew
                     leading-hebrew
                     focus:outline-none focus:ring-2
                     focus:ring-blue-500"></textarea>
  </div>

  <button type="submit"
          class="w-full bg-blue-600 text-white py-3
                 rounded-md font-medium text-base
                 hover:bg-blue-700 transition-colors">
    שליחה
  </button>
</form>

示例

示例 1：为希伯来语项目设置 Tailwind

用户说："为我的希伯来语 Web 应用配置 Tailwind" 结果：将希伯来语字体族添加到 Tailwind 主题，配置针对希伯来语优化的行高，在根 HTML 元素上设置 dir="rtl"，并演示使用逻辑工具类（ms-/me-/ps-/pe-）而非物理工具类（ml-/mr-/pl-/pr-）。

示例 2：将 LTR Tailwind 组件转换为 RTL

用户说："让这个 Tailwind 组件在希伯来语 RTL 下正常工作" 结果：将所有物理工具类替换为逻辑等价类（ml- 替换为 ms-，pl- 替换为 ps-，text-left 替换为 text-start，border-l 替换为 border-s，rounded-l 替换为 rounded-s），为方向性图标添加 rtl: 变体，并在文本元素上设置 font-hebrew 类。

示例 3：使用 Tailwind 构建希伯来语仪表盘

用户说："使用 Tailwind 创建一个希伯来语管理仪表盘布局" 结果：构建带有 RTL 侧边栏（border-e、pe-6）的网格布局，使用希伯来语字体和 RTL 流的导航，使用逻辑间距的卡片组件，以及具有正确希伯来语排版的表单元素（font-hebrew、leading-hebrew）。

捆绑资源

参考资料

• references/rtl-config.md -- 完整的 Tailwind CSS RTL 配置参考：v4 CSS-first 和 v3 JavaScript 配置示例、完整的物理到逻辑工具类映射表、dir 变体使用模式、希伯来语字体栈预设、排版令牌定义，以及从物理工具类到逻辑工具类的迁移指南。

注意事项

• Tailwind CSS v3+ 支持 RTL 变体（rtl: 前缀），但 Agent 往往不使用它们，而是在本应使用 ms-4（margin-start）以实现 RTL 兼容时硬编码 mr-4。
• space-x-* 在 Tailwind v4 中确实能感知方向：它会编译为 margin-inline-start / margin-inline-end，因此它在 dir="rtl" 下已经会自动翻转，无需覆盖。不要添加 rtl:space-x-reverse — 那会设置 --tw-space-x-reverse: 1，并将间距移到错误的一侧。space-x-reverse 仅用于以反向 DOM 顺序渲染的子元素（flex-row-reverse），在这种情况下无论方向如何它都应放在同一元素上。Agent 记忆中的物理 margin 行为是 Tailwind v3 的。gap-4 仍然是 flex 和 grid 的更好选择，因为 space-x-* 在换行行上会失效。
• 希伯来语的自定义字体声明必须包含 font-display: swap 以防止 FOIT（不可见文本闪烁）。Agent 可能会遗漏这一点，导致希伯来语文本在字体加载期间消失。
• Tailwind 的 text-left 和 text-right 是物理属性。请使用 text-start 和 text-end 类以实现 RTL 感知对齐。Agent 默认使用物理方向类。
• 渐变和阴影方向是物理的，而非逻辑的：bg-linear-to-r 和偏移阴影在 RTL 下不会翻转。当方向有意义时，添加 rtl: 覆盖（例如 rtl:bg-linear-to-l）。请使用 v4 的 bg-linear-* 名称；bg-gradient-* 仍会作为遗留别名编译，但不再是文档中的拼写。

参考链接

来源	URL	检查内容
Tailwind CSS 主题文档	https://tailwindcss.com/docs/theme	当前配置语法、v4 迁移说明
Tailwind RTL / 逻辑属性	https://tailwindcss.com/docs/hover-focus-and-other-states#rtl-support	rtl: 和 ltr: 变体
Google Fonts – Heebo	https://fonts.google.com/specimen/Heebo	希伯来语 UI 字体、字重、加载片段
Google Fonts – Assistant	https://fonts.google.com/specimen/Assistant	希伯来语正文字体
MDN font-display	https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-display	swap 值和 FOIT 缓解

故障排除

错误：“Tailwind 逻辑工具类不生效”

原因：使用的 Tailwind 版本较旧，不支持逻辑属性 解决方案：逻辑工具类（ms-、me-、ps-、pe-，以及 inset 的 inset-s-/inset-e-，旧称 start-/end-）需要 Tailwind v3.3+，也正是该版本将 rtl:/ltr: 变体标记为稳定。在 v3.0-3.2 上这些变体仍属实验性并会打印警告，因此应升级，而不是退回到 rtl:mr-4 ltr:ml-4 这类配对写法。Tailwind v4 内置完整的逻辑属性支持；inset-s-*/inset-e-* 命名在 v4.2 中引入（旧的 start-*/end-* 仍可解析）。

错误：“font-hebrew 类无法应用字体”

原因：未在 Tailwind 配置中定义希伯来语字体族 解决方案：在 Tailwind 主题的 fontFamily.hebrew 下添加希伯来语字体栈。确保已导入字体 CSS（Google Fonts 链接或本地 @font-face）。确认类名与配置键一致。

错误：“RTL 下侧边栏出现在错误的一侧”

原因：Grid 或 flex 布局未遵循 dir 属性 解决方案：CSS Grid 和 Flexbox 会自动遵循 dir="rtl"。确保在 html 元素上设置了 dir="rtl"。边框使用逻辑属性（用 border-e 代替 border-r），内边距同理（用 pe- 代替 pr-）。保持 CSS 的 direction 值与 HTML 的 dir 属性一致——优先通过 dir 属性设置方向，以便层叠和 rtl:/ltr: 变体保持同步；如果你确实在 CSS 中设置了 direction，请确保它与 dir 一致。