Communitygithub.com

rtl-components

使用 Tailwind 邏輯工具(logical utilities)建構符合 RTL(從右到左)規範的 UI 元件模式。適用於波斯語/阿拉伯語 RTL 頁面中的表單、卡片、導覽、表格、模態框、分頁、麵包屑等任何 UI 元件,或用於修復鏡像佈局錯誤。涵蓋 ms/me/ps/pe 工具、圖示翻轉、側邊欄佈局以及 shadcn/ui RTL 相關筆記。

rtl-components 是什麼?

這項技能(rtl-components)提供一套完整且可立即應用的模式與規則,專門用於在使用 Tailwind CSS 和 shadcn/ui 的環境中,建構與修復從右到左(RTL)語系(如波斯語、阿拉伯語)的 UI 元件。其核心目標是透過邏輯屬性(logical properties)取代傳統的實體定位(如 left/right),並明確列出常見的 RTL 陷阱與解決方案,幫助開發者避免常見的鏡像佈局錯誤。技能內容涵蓋了 Tailwind 的邏輯工具對照表(如 ms/me 取代 ml/mr)、方向性圖示的正確翻轉規則、表單輸入欄位在 RTL 下的對齊與方向處理、導覽元件(側邊欄、麵包屑、分頁)的鏡像行為、覆蓋層元件(對話框、選單、提示框)的適用配置、卡片與內容區塊的邊飾對齊,以及動畫與變形的方向感知處理。此外,也針對 shadcn/ui 元件庫提供了具體的 RTL 調整筆記,例如字型設定與選單定位。這項技能適用於 Claude Code、Cursor 或 Codex 等 AI 代理,協助開發者在開發階段直接產出正確的 RTL 元件,或在 code review 時快速識別並修正 RTL 相關的 bug,大幅提升多語系產品的開發效率與品質。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mhmdsdqi87-cloud/TEKA_raast/tree/HEAD/skills/rtl-components

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

RTL 元件模式(Tailwind + shadcn/ui)

邏輯性、方向無關的元件。設定 dir="rtl" 後,flex/grid 會自動鏡像化——但錯誤通常存在於此處列出的遺留問題中。

1. 工具轉換對照表(請牢記)

LTR 習慣用法邏輯屬性(永遠使用)
ml- / mr-ms- / me-
pl- / pr-ps- / pe-
left-0 / right-0start-0 / end-0
text-left / text-righttext-start / text-end
border-l- / border-r-border-s- / border-e-
rounded-l- / rounded-r-rounded-s- / rounded-e-
ml-auto(推到遠端)ms-auto

這些類別存在於 Tailwind v3.3+ 和 v4。使用它們意味著元件在兩個方向都能自動運作。

2. 方向性圖示——翻轉清單

僅翻轉真正具有方向性的圖示。切勿翻轉語意穩定的圖示。

需要翻轉(使用 rtl:-scale-x-100、預先翻轉的 SVG,或對箭頭使用 rtl:rotate-180):

  • 用於上一步/下一步的 chevron/箭頭、返回按鈕、麵包屑分隔符號
  • 縮排/凸排、回覆(分享箭頭)、轉寄、重做
  • 時間軸標記、「展開側面板」圖示

不要翻轉:

  • 時鐘、鎖定、搜尋、設定、勾選記號、愛心、星號、上傳/下載、WiFi、鈴鐺
<!-- RTL 中,下一頁箭頭指向左方 -->
<svg class="rtl:rotate-180">…</svg>

對於 shadcn/ui + lucide:<ChevronLeft className="rtl:rotate-180" /> 是錯的兩次——相反,只需根據您提供的方向使用正確的圖形。對於僅限 RTL 的產品:下一頁 = ChevronLeft,返回 = ChevronRight。

3. 表單

  • 標籤位於輸入框上方的內聯起始處(標準做法)。
  • 文字輸入框:名稱/訊息使用 dir="auto";電話、電子郵件、身分證字號、價格輸入框使用 dir="ltr" + text-end(內容是 LTR,但位置保持在右側)。
  • 輸入框群組附加元件:貨幣「تومان」放在數字之後 → 視覺上在左側;兩邊使用邏輯內邊距,永遠不要硬編碼 pr。
  • 驗證圖示:使用 end-0 而非 right-0 定位。
  • 錯誤文字:使用波斯語,包含「؛」和正確的 ZWNJ:「ایمیل معتبر نیست」、「رمز عبور باید ۸ نویسه یا بیشتر باشد」。

4. 導覽與版面

  • 側邊欄:start-0(在 RTL 中渲染在右側)。僅顯示圖示的折疊變體需保持工具提示翻轉(在 Radix 工具提示中使用 side="start")。
  • 麵包屑:分隔符號 = ChevronLeft(RTL 的「前進向下」方向),最後一項為當前項目。
  • 分頁:頁碼向左遞增:۱ ۲ ۳ ۴,下一頁 = ChevronLeft。Prev 在視覺上位於右側。
  • 標籤頁:順序從右到左流動;使用 border-b 的活躍底線沒問題。
  • 表格:欄位順序自動鏡像;將數字儲存格對齊 text-end 並讓波斯數字保持其自身的 LTR 順序。

5. 覆蓋層

  • 對話框/面板:Sheet side="start" = RTL 頁面中的右側抽屜。
  • 下拉選單/彈出視窗:Radix 使用 side/align——align="start" 跟隨內聯起始處(右側)。預設碰撞處理在 RTL 下運作正常。
  • 提示通知:定位 bottom-start(視覺上在 RTL 中為右下角),這樣它們就不會與內聯結束處的行動號召按鈕衝突。
  • 被截斷的波斯文字上的工具提示:Radix 測量正常;確保設定 max-w——波斯語的省略號運作正常。

6. 卡片與內容區塊

  • 內聯起始邊緣的重點條:border-s-2 border-s-emerald-500(渲染在右側)。
  • 元資料列(作者 · 日期 · 閱讀時間):分隔點使用 ms-2 me-2 或 flex gap-2。
  • 帶操作的卡片:主要操作在內聯結束處?不——在 RTL 閱讀中,主要行動號召按鈕傳統上位於卡片頁尾的內聯結束處(左側),鏡像 LTR 慣例。

7. 動畫與變形

dir 不會鏡像變形。檢查每一個:

  • translate-x-*(滑桿、螢幕外畫布、跑馬燈)→ 需要明確的 RTL 對應版本
  • rotate-45 裝飾性 → 通常沒問題
  • 輪播滑動:embla/swiper——設定 direction: rtl 選項,否則它們會反向滾動
  • 進度條:填滿動畫錨定在 start-0,向左增長;百分比顯示為 ۷۰٪
  • 骨架屏閃爍動畫:關鍵影格 translate-x 必須鏡像,否則閃爍效果會朝錯誤方向滑動

方向感知動畫模式

/* 螢幕外畫布抽屜:從內聯起始處進入,從內聯起始處退出。
   一組宣告對即可服務兩個方向。 */
.drawer { transform: translateX(calc(var(--dir-sign, -1) * 100%)); }
[dir="rtl"] .drawer { --dir-sign: 1; }
.drawer.open { transform: translateX(0); }

/* 彈跳 / 強調圖示:翻轉整個動畫,而不是在動畫中途翻轉元素 */
[dir="rtl"] .cta-arrow { animation: nudge-rtl 1.2s infinite; }
@keyframes nudge-rtl { 50% { transform: translateX(-4px); } }

/* 數字計數器和進度填充:對邏輯內聯大小進行動畫,而不是 left */
@keyframes fill { from { inline-size: 0 } }
  • CSS 邏輯屬性 inset-inline-start + 自定義屬性符號切換,勝過為每個方向複製整個關鍵影格。
  • prefers-reduced-motion: reduce → 停用輕推/跑馬燈效果,保持透明度淡入淡出。

8. shadcn/ui RTL 注意事項(v4 tokens,New York 風格)

  • 當應用程式在 <html> 上設定 dir="rtl" 時,大多數基本元件在 RTL 下是乾淨的。
  • 已知需要調整的地方:DropdownMenuContent align="start" 使選單保持在觸發器右邊緣下方;Select 的 chevron 應為 ChevronDown(無方向性,無需更改);InputOTP、CommandDialog 和 ResizablePanel 需要手動檢查。
  • 設定一次字型 tokens:將 Vazirmatn 放入 --font-sans(globals.css)中,以便每個 shadcn 元件都繼承它。

9. 審計鉤子

在發布元件之前,通過 rtl-audit 檢查清單——特別是圖示翻轉、變形以及 left/right 類別。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能