Padrões de Componentes RTL (Tailwind + shadcn/ui)
Componentes lógicos e independentes de direção. Após dir="rtl", flex/grid espelham automaticamente — os bugs residem nos resquícios listados aqui.
1. Tabela de tradução de utilitários (memorize isto)
| Hábito LTR | Lógico (use sempre) |
|---|---|
ml- / mr- | ms- / me- |
pl- / pr- | ps- / pe- |
left-0 / right-0 | start-0 / end-0 |
text-left / text-right | text-start / text-end |
border-l- / border-r- | border-s- / border-e- |
rounded-l- / rounded-r- | rounded-s- / rounded-e- |
ml-auto (empurrar para o lado final) | ms-auto |
Estes existem no Tailwind v3.3+ e v4. Usá-los significa que o componente funciona em AMBAS as direções gratuitamente.
2. Ícones direcionais — a lista de inversão
Inverta APENAS ícones verdadeiramente direcionais. Nunca inverta aqueles semanticamente estáveis.
Inverter (rtl:-scale-x-100 ou SVG pré-invertido, ou rtl:rotate-180 para setas):
- chevrons/setas para próximo/anterior, botões de voltar, separadores de breadcrumb
- indentar/recuar, responder (seta de compartilhar), avançar, refazer
- marcadores de linha do tempo, ícones de "expandir painel lateral"
NÃO inverter:
- relógio, cadeado, pesquisa, configurações, check, coração, estrela, upload/download, wifi, sino
<!-- seta 'próximo' em RTL aponta para a esquerda -->
<svg class="rtl:rotate-180">…</svg>
Para shadcn/ui + lucide: <ChevronLeft className="rtl:rotate-180" /> está errado duas vezes — em vez disso, use apenas o glifo correto para a direção que você está servindo. Para um produto exclusivamente RTL: próximo = ChevronLeft, voltar = ChevronRight.
3. Formulários
- Rótulos ficam no início da linha (inline-start) acima do input (padrão).
- Inputs de texto:
dir="auto"para nome/mensagem;dir="ltr"+text-endpara telefone, email, ID nacional, inputs de preço (o conteúdo é LTR, mas o posicionamento permanece à direita). - Complementos de grupo de input: moeda «تومان» após o número → lado visual esquerdo; use padding lógico em ambos os lados, nunca codifique
pr. - Ícones de validação: coloque com
end-0, nãoright-0. - Texto de erro: Persa, com «؛» e ZWNJ correto: «ایمیل معتبر نیست»، «رمز عبور باید ۸ نویسه یا بیشتر باشد».
4. Navegação & chrome
- Sidebar:
start-0(renderiza à direita em RTL). A variante recolhida apenas com ícones mantém os tooltips invertidos (side="start"nos tooltips do Radix). - Breadcrumbs: separador =
ChevronLeft(direção "para frente" em RTL), último item é o atual. - Paginação: os números das páginas ascendem para a ESQUERDA: ۱ ۲ ۳ ۴ com próximo = ChevronLeft.
Prevfica no lado direito visualmente. - Abas: a ordem flui da direita para a esquerda; a linha ativa via
border-bestá correta. - Tabela: a ordem das colunas espelha automaticamente; alinhe células numéricas com
text-ende deixe os números em dígitos persas manterem suas próprias execuções LTR.
5. Sobreposições
- Diálogos/Sheets:
Sheet side="start"= gaveta do lado direito em páginas RTL. - Dropdown/Popover: Radix usa
side/align—align="start"segue o início da linha (direita). A colisão padrão funciona bem com RTL. - Toasts: posicione
bottom-start(visualmente canto inferior direito para RTL) para que não entrem em conflito com CTAs no final da linha. - Tooltips em texto persa truncado: Radix mede corretamente; certifique-se de que
max-westá definido — a elipse persa funciona normalmente.
6. Cards & blocos de conteúdo
- Barra de destaque na borda do início da linha:
border-s-2 border-s-emerald-500(renderiza à direita). - Linhas de metadados (autor · data · tempo de leitura): ponto separador com
ms-2 me-2ou flexgap-2. - Cards com ações: ação primária no final da linha? Não — na leitura RTL, o CTA primário convencionalmente fica no final da linha (esquerda) nos rodapés do card, espelhando as convenções LTR.
7. Movimento & transformações
dir NÃO espelha transformações. Audite cada:
translate-x-*(sliders, off-canvas, marquee) → precisa de um gêmeo RTL explícitorotate-45decorativo → geralmente ok- Swipe de carrossel: embla/swiper — defina a opção
direction: rtlou eles rolarão para trás - Barras de progresso: preenchimento ancorado em
start-0, cresce em direção à esquerda; porcentagens como ۷۰٪ - Brilho de esqueleto (skeleton shimmer): o keyframe
translate-xdeve espelhar ou o brilho deslizará na direção errada
Padrões de animação conscientes de direção
/* Gaveta off-canvas: entra a partir do início da linha, sai para o início da linha.
Um par de declarações atende a ambas as direções. */
.drawer { transform: translateX(calc(var(--dir-sign, -1) * 100%)); }
[dir="rtl"] .drawer { --dir-sign: 1; }
.drawer.open { transform: translateX(0); }
/* Ícones de ênfase/bounce: inverta a animação inteira, não o elemento em pleno voo */
[dir="rtl"] .cta-arrow { animation: nudge-rtl 1.2s infinite; }
@keyframes nudge-rtl { 50% { transform: translateX(-4px); } }
/* Contadores numéricos e preenchimento de progresso: anime o tamanho lógico inline, não 'left' */
@keyframes fill { from { inline-size: 0 } }
inset-inline-startlógico do CSS + troca de sinal de propriedade personalizada supera a duplicação de keyframes inteiros por direção.prefers-reduced-motion: reduce→ desative nudges/marquees, mantenha fades de opacidade.
8. Anotações RTL do shadcn/ui (tokens v4, estilo New York)
- A maioria dos primitivos está limpa para RTL quando o aplicativo define
dir="rtl"no<html>. - Ajustes conhecidos:
DropdownMenuContent align="start"mantém os menus ancorados sob a borda direita do gatilho; o chevron doSelectdeve serChevronDown(sem direção, sem alteração);InputOTP,CommandDialogeResizablePanelprecisam de revisão manual. - Defina os tokens de fonte uma vez: coloque Vazirmatn em
--font-sans(globals.css) para que cada componente shadcn o herde.
9. Hook de auditoria
Entregue os componentes através da lista de verificação rtl-audit — especialmente inversões de ícones, transformações e classes left/right.