Communitygithub.com

rtl-typography

Regras centrais de tipografia para interfaces web em persa (farsi) e árabe. Use ao construir ou estilizar qualquer UI contendo texto em persa/árabe/farsi, ou quando o usuário mencionar فارسی، عربی، RTL، نیم‌فاصله، فونت فارسی. Abrange seleção de fontes, ZWNJ (نیم‌فاصله), numerais persas, pontuação, entrelinha e padrões proibidos como letter-spacing em script árabe.

O que é rtl-typography?

Esta skill codifica a camada tipográfica para interfaces da direita para a esquerda (RTL), focada em persa (farsi) e árabe. Ela garante que textos em persa ou árabe sejam renderizados corretamente, seguindo as melhores práticas e convenções específicas dessas línguas. A skill é essencial para evitar erros comuns gerados por IA, como o uso de `letter-spacing` em script árabe (que quebra a junção das letras) e a ausência do caractere ZWNJ (U+200C, ou نیم‌فاصله) em palavras persas compostas. Ela também orienta sobre a escolha de fontes adequadas, como Vazirmatn para persa e IBM Plex Sans Arabic para árabe, além de definir valores corretos de entrelinha (line-height), uso de numerais persas versus árabes, e pontuação específica (como ، ؟ «»). A skill é compatível com qualquer plataforma que utilize HTML e CSS (como Claude Code, Cursor, Codex) e fornece um checklist de pré-implantação para garantir a conformidade tipográfica.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mhmdsdqi87-cloud/TEKA_raast/tree/HEAD/skills/rtl-typography

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Tipografia RTL: Persa & Árabe feitos corretamente

Esta skill codifica a camada tipográfica para interfaces da direita para a esquerda (RTL). Siga-a sempre que o texto na página for persa ou árabe. Para builds de página completa, veja rtl-landing; para padrões de componentes, veja rtl-components.

1. Configuração do documento — sempre primeiro

<html lang="fa" dir="rtl">
  • Defina lang E dir juntos. lang="fa" para persa, lang="ar" para árabe.
  • Nunca simule RTL com text-align: right em um documento LTR. Navegadores, leitores de tela, controles de formulário e barras de rolagem dependem de dir.
  • Cada alinhamento deve usar valores lógicos: text-align: start, não left.

2. Fontes

Use uma fonte projetada para o idioma. Uma fonte que não tenha glifos persas renderiza formas quebradas/tofu ou substitui silenciosamente.

Escolhas confiáveis (detalhes + snippets CDN em fonts.md):

Caso de usoPersaÁrabe
Corpo/UI (padrão)VazirmatnIBM Plex Sans Arabic
Display/títulosLalezar, EstedadCairo, Changa
Editorial/serifaMarkazi Text, ParastooNoto Naskh Arabic
Sensação familiar/sistemaSahel, ShabnamTajawal, Almarai

Padrão de pilha — sempre nomeie um fallback e deixe uma fonte cobrir o latim:

font-family: 'Vazirmatn', Tahoma, sans-serif;

Carregue apenas woff2, use font-display: swap, subconjunto dos pesos que você usa (400, 500, 700 geralmente é suficiente).

3. NUNCA use letter-spacing em script árabe

Este é o bug RTL mais comum gerado por IA.

As letras do script árabe são cursivas e ligadas. letter-spacing insere espaços entre glifos unidos, quebrando visualmente as palavras: «مدیریت» se torna م د ی ر ی ت.

/* ERRADO — quebra a junção */
.hero-title { letter-spacing: 0.05em; }

/* CERTO — se precisar de texto mais largo, use tamanho/peso */
.hero-title { font-weight: 800; font-size: 3rem; }

Regra: letter-spacing: 0 ou não definido para qualquer texto em script árabe. Truques de tracking (maiúsculas, tracking largo) não se aplicam de qualquer forma — o script árabe não tem caixa alta.

4. Entrelinha e ritmo

As caixas de linha do script árabe são mais altas que as do latim (ascendentes/descendentes + diacríticos). Os padrões latinos parecem apertados.

  • Texto corporal persa: line-height: 1.8–2.0 (1.9 é um padrão seguro)
  • Texto corporal árabe: line-height: 1.6–1.8
  • Títulos: 1.3–1.4
  • O texto persa ocupa ~10–15% mais largura que o inglês para o mesmo conteúdo — planeje botões mais largos, mais largura de parágrafo, não corte demais.

Justificação: prefira alinhamento inicial (texto irregular). A justificação do navegador sem suporte a kashida cria rios feios entre as palavras.

5. ZWNJ — نیم‌فاصله (U+200C)

Compostos e afixos persas são escritos com um Zero-Width Non-Joiner (ZWNJ) entre as partes. A falta de ZWNJ é o defeito de ortografia mais visível em cópias persas geradas.

Tabela de uso correto

Errado (espaço ou unido)Correto (com U+200C)
می رودمی‌رود
نمی شودنمی‌شود
می خواهممی‌خواهم
خانه هاخانه‌ها
کتاب هایکتاب‌های
بهترین هابهترین‌ها
خوب ترخوب‌تر
برنامه نویسیبرنامه‌نویسی
راه اندازیراه‌اندازی
ورود به سیستم می پردازدورود به سیستم می‌پردازد

Regras práticas:

  • Prefixos می, نمی, بی, هم, نا, باز + verbo/adjetivo → ZWNJ: می‌گوید، نمی‌دانست، بی‌نقص، هم‌گام
  • Sufixos ها, های, تر, ترین após uma palavra → ZWNJ: پرنده‌ها، کتاب‌های، بزرگ‌تر، بزرگ‌ترین
  • Substantivos compostos da lista de palavras da Academia → ZWNJ: راه‌اندازی، برنامه‌نویسی، نرم‌افزار، ذخیره‌سازی
  • Sufixos possessivos ام/ات/اش são escritos unidos: کتابم، خانه‌ات — NÃO insira ZWNJ ali.

Ao gerar cópia persa, escreva ZWNJ nativamente (não um espaço). Para sanitizar texto existente, use o script incluso:

python3 scripts/fix-zwnj.py draft.md            # simulação (diff)
python3 draft-output.md > fixed.md --apply ...  # veja --help

O script une padrões quebrados comuns (می رود, خانه ها, خوب تر), converte ي ك árabe para ی ک persa e nunca toca em blocos de código ou URLs.

6. Numerais

IdiomaDígitosFaixa Unicode
Persa۰۱۲۳۴۵۶۷۸۹U+06F0–U+06F9
Árabe٠١٢٣٤٥٦٧٨٩U+0660–U+0669
Latim (contextos incorporados)0123456789U+0030–U+0039
  • Cópia escrita em persa usa dígitos persas: «۵ دلیل»، «۲۴ ساعت».
  • Preços: ۱۲۵٬۰۰۰ تومان — separador de milhares é U+066C (٬), decimal é U+066B (٫).
  • Porcentagem após o número, sem espaço: ۱۲٪ (sinal de porcentagem árabe U+066A).
  • Nunca formate estes manualmente: use APIs de locale JS.
(125000).toLocaleString('fa-IR')   // "۱۲۵٬۰۰۰"
(12.5).toLocaleString('fa-IR')     // "۱۲٫۵"
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.12)  // "۱۲٪"

Mantenha dígitos ocidentais apenas dentro de átomos inerentemente LTR: números de telefone, URLs, código, preços em moeda estrangeira.

7. Pontuação — marcas persas em texto persa

FinalidadePersa/ÁrabeNão use
Vírgula، (U+060C),
Ponto de interrogação؟ (U+061F)?
Ponto e vírgula؛ (U+061B);
Aspas«متن»"متن"
Decimal / milhares٫ ٬. ,
Porcentagem٪ (U+066A)%

Reticências são …, não três pontos. Sem espaço antes de ، ؟ ؛; um espaço depois.

8. Persa vs Árabe — decida primeiro

São idiomas diferentes com convenções diferentes. Confirme qual deles antes de estilizar:

  • Dígitos: fa → ۱۲۳ (U+06F0), ar → ١٢٣ (U+0660)
  • Letras: Persa ی/ک vs Árabe ي/ك — uma fonte persa deve incluir formas persas
  • A pontuação se sobrepõe, mas tom/expressão idiomática diferem
  • Uma fonte apenas persa em uma página árabe mostra formas de letras erradas para ک/ی e vice-versa

As convenções legíveis por máquina (faixas de dígitos, separadores, pontuação, listas de afixos) estão em raast/profiles/fa.json e raast/profiles/ar.json — os mesmos arquivos que a CLI raast consome, para que as regras em prosa e as verificações automatizadas nunca se desviem.

9. Copiar, colar, seleção e renderização

O texto em script árabe quebra em copiar/colar e seleção com mais frequência que o latim. Regras:

  • Renderização de seleção: defina ::selection com contraste suficiente (aglomerados de glifos em script árabe se estendem abaixo da linha; uma faixa de destaque fina os corta visualmente). Preenchimento em ::selection ajuda.
  • Integridade de copiar/colar: nunca insira ZWNJ programaticamente em áreas nas quais os usuários possam colar em campos de texto simples; ao colar na página, mantenha o texto colado exato em bytes (sem "limpeza" automática de U+200C, U+200E/F, U+061C marca de letra árabe). Remover caracteres invisíveis corrompe silenciosamente a pesquisa e a ortografia persas.
  • user-select: all em citações para que os guillemets permaneçam anexados.
  • Componentes de copiar para a área de transferência (preço, número de rastreamento) devem copiar a string lógica, não a reordenada visualmente — teste com uma página RTL + visualizador de área de transferência LTR.
  • Flags de renderização de fonte: prefira text-rendering: optimizeLegibility; NÃO use pesos font-synthesis em faces de exibição árabes (negrito falso quebra o ritmo naskh) — carregue pesos reais.
  • Avisos sobre transformações ambíguas: normalizar dígitos indo-arábicos (٠١٢) para persas (۰۱۲) é seguro em conteúdo fa, destrutivo em conteúdo ar. Qualquer conversão automatizada deve ter portão de idioma — veja references/normalization.md para a tabela de decisão.

10. Noções básicas de script misto (detalhes na skill rtl-bidi)

  • Telefone/e-mail/URL/código dentro de texto persa: envolva em <bdi> ou um span dir="ltr".
  • Blocos de código: sempre dir="ltr" + text-align: left, mesmo em páginas RTL.
  • Entradas geradas pelo usuário: dir="auto" para que cada entrada se adapte ao seu próprio conteúdo.

11. Lista de verificação pré-implantação

  • <html lang="fa|ar" dir="rtl"> definido
  • Fonte cobre o idioma; fallback nomeado
  • letter-spacing ausente em texto em script árabe
  • Entrelinha do corpo ≥ 1.8 (persa)
  • Todos os afixos usam U+200C real, não espaços
  • Dígitos persas + ٬ ٫ ٪ ٬ na cópia; dígitos latinos apenas em átomos LTR
  • Pontuação persa ، ؟ ؛ «» na cópia
  • Alinhamentos usam start/end, nunca left/right

Individual skills in this repo

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

Habilidades Relacionadas