Communitygithub.com

rtl-typography

Reglas tipográficas esenciales para interfaces web en persa (farsi) y árabe. Úsalo al construir o diseñar cualquier interfaz de usuario que contenga texto en persa/árabe/farsi, o cuando el usuario mencione فارسی، عربی، RTL، نیم‌فاصله، فونت فارسی. Cubre selección de fuentes, ZWNJ (نیم‌فاصله), numerales persas, puntuación, interlineado y patrones prohibidos como el letter-spacing en escritura árabe.

¿Qué es rtl-typography?

Este skill proporciona las reglas tipográficas fundamentales para interfaces de usuario en idiomas de derecha a izquierda (RTL), específicamente persa (farsi) y árabe. Está diseñado para desarrolladores que trabajan con asistentes de IA como Claude Code, Cursor o Codex, y buscan generar o estilizar correctamente contenido en estos idiomas. El skill cubre aspectos cruciales como la configuración del documento (`<html lang="fa" dir="rtl">`), la selección de fuentes nativas (Vazirmatn para persa, IBM Plex Sans Arabic para árabe), el uso correcto del separador de ancho cero (ZWNJ o نیم‌فاصله) para evitar errores ortográficos comunes, el manejo de numerales persas y árabes, y la puntuación específica de cada idioma. Además, advierte sobre errores frecuentes generados por IA, como el uso de `letter-spacing` en texto árabe (que rompe la ligadura cursiva de las letras) y la omisión del ZWNJ en palabras compuestas. Incluye una lista de verificación previa al lanzamiento y referencias a scripts de saneamiento automático.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Tipografía RTL: Persa y Árabe bien hechos

Este skill codifica la capa tipográfica para interfaces de derecha a izquierda. Síguelo siempre que el texto en la página sea persa o árabe. Para construcciones de página completa, consulta rtl-landing; para patrones de componentes, consulta rtl-components.

1. Configuración del documento — siempre primero

<html lang="fa" dir="rtl">
  • Establece lang Y dir juntos. lang="fa" para persa, lang="ar" para árabe.
  • Nunca simules RTL con text-align: right en un documento LTR. Los navegadores, lectores de pantalla, controles de formulario y barras de desplazamiento dependen de dir.
  • Cada alineación debe usar valores lógicos: text-align: start, no left.

2. Fuentes

Usa una fuente diseñada para el idioma. Una fuente que carece de glifos persas muestra formas rotas/tofu o sustituciones silenciosas.

Opciones fiables (detalles + fragmentos CDN en fonts.md):

Caso de usoPersaÁrabe
Cuerpo/UI (predeterminado)VazirmatnIBM Plex Sans Arabic
Pantalla/titularesLalezar, EstedadCairo, Changa
Editorial/sensación serifMarkazi Text, ParastooNoto Naskh Arabic
Sensación familiar/sistemaSahel, ShabnamTajawal, Almarai

Patrón de pila — siempre nombra un fallback, y deja que una fuente cubra el latín:

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

Carga solo woff2, usa font-display: swap, subconjunta los pesos que usas (400, 500, 700 suele ser suficiente).

3. NUNCA uses letter-spacing en escritura árabe

Este es el error RTL generado por IA más común.

Las letras de la escritura árabe son cursivas y están unidas. letter-spacing inserta espacios entre glifos unidos, rompiendo visualmente las palabras: «مدیریت» se convierte en م د ی ر ی ت.

/* INCORRECTO — rompe la unión */
.hero-title { letter-spacing: 0.05em; }

/* CORRECTO — si necesitas texto de pantalla más ancho, usa tamaño/peso en su lugar */
.hero-title { font-weight: 800; font-size: 3rem; }

Regla: letter-spacing: 0 o sin establecer para cualquier texto en escritura árabe. Los trucos de tracking (mayúsculas, tracking ancho) no aplican de todos modos — la escritura árabe no tiene mayúsculas/minúsculas.

4. Interlineado y ritmo

Los cuadros de línea de la escritura árabe son más altos que los latinos (ascendentes/descendentes + diacríticos). Los valores predeterminados latinos se ven apretados.

  • Texto de cuerpo persa: line-height: 1.8–2.0 (1.9 es un valor predeterminado seguro)
  • Texto de cuerpo árabe: line-height: 1.6–1.8
  • Titulares: 1.3–1.4
  • El texto persa ocupa aproximadamente un 10–15% más de ancho que el inglés para el mismo contenido — presupuesta botones más anchos, más ancho de párrafo, no trunques en exceso.

Justificación: prefiere texto alineado al inicio (desigual). La justificación del navegador sin soporte de kashida crea feos ríos entre palabras.

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

Los compuestos y afijos persas se escriben con un separador de ancho cero (ZWNJ) entre las partes. La falta de ZWNJ es el defecto ortográfico más visible en el texto persa generado.

Tabla de uso correcto

Incorrecto (espacio o unido)Correcto (con U+200C)
می رودمی‌رود
نمی شودنمی‌شود
می خواهممی‌خواهم
خانه هاخانه‌ها
کتاب هایکتاب‌های
بهترین هابهترین‌ها
خوب ترخوب‌تر
برنامه نویسیبرنامه‌نویسی
راه اندازیراه‌اندازی
ورود به سیستم می پردازدورود به سیستم می‌پردازد

Reglas generales:

  • Prefijos می, نمی, بی, هم, نا, باز + verbo/adjetivo → ZWNJ: می‌گوید، نمی‌دانست، بی‌نقص، هم‌گام
  • Sufijos ها, های, تر, ترین después de una palabra → ZWNJ: پرنده‌ها، کتاب‌های، بزرگ‌تر، بزرگ‌ترین
  • Sustantivos compuestos de la lista de palabras de la Academia → ZWNJ: راه‌اندازی، برنامه‌نویسی، نرم‌افزار، ذخیره‌سازی
  • Los sufijos posesivos ام/ات/اش se escriben unidos: کتابم، خانه‌ات — NO insertes ZWNJ ahí.

Al generar texto persa, escribe ZWNJ de forma nativa (no un espacio). Para sanitizar texto existente, usa el script incluido:

python3 scripts/fix-zwnj.py draft.md            # vista previa de diferencias
python3 draft-output.md > fixed.md --apply ...  # ver --help

El script une patrones rotos comunes (می رود, خانه ها, خوب تر), convierte el árabe ي ك al persa ی ک, y nunca toca bloques de código ni URLs.

6. Numerales

IdiomaDígitosRango Unicode
Persa۰۱۲۳۴۵۶۷۸۹U+06F0–U+06F9
Árabe٠١٢٣٤٥٦٧٨٩U+0660–U+0669
Latín (contextos incrustados)0123456789U+0030–U+0039
  • El texto escrito en persa usa dígitos persas: «۵ دلیل»، «۲۴ ساعت».
  • Precios: ۱۲۵٬۰۰۰ تومان — el separador de miles es U+066C (٬), el decimal es U+066B (٫).
  • Porcentaje después del número, sin espacio: ۱۲٪ (signo de porcentaje árabe U+066A).
  • Nunca formatees estos a mano: usa las APIs de locale de JS.
(125000).toLocaleString('fa-IR')   // "۱۲۵٬۰۰۰"
(12.5).toLocaleString('fa-IR')     // "۱۲٫۵"
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.12)  // "۱۲٪"

Mantén los dígitos occidentales solo dentro de átomos inherentemente LTR: números de teléfono, URLs, código, precios en moneda extranjera.

7. Puntuación — signos persas en texto persa

PropósitoPersa/ÁrabeNo uses
Coma، (U+060C),
Signo de interrogación؟ (U+061F)?
Punto y coma؛ (U+061B);
Comillas«متن»"متن"
Decimal / miles٫ ٬. ,
Porcentaje٪ (U+066A)%

La elipsis es …, no tres puntos. Sin espacio antes de ، ؟ ؛; un espacio después.

8. Persa vs Árabe — decide primero

Son idiomas diferentes con diferentes convenciones. Confirma cuál antes de estilizar:

  • Dígitos: fa → ۱۲۳ (U+06F0), ar → ١٢٣ (U+0660)
  • Letras: Persa ی/ک vs Árabe ي/ك — una fuente persa debe incluir formas persas
  • La puntuación se superpone pero el tono/idioma difiere
  • Una fuente solo persa en una página árabe muestra formas de letras incorrectas para ک/ی y viceversa

Las convenciones legibles por máquina (rangos de dígitos, separadores, puntuación, listas de afijos) viven en raast/profiles/fa.json y raast/profiles/ar.json — los mismos archivos que consume la CLI raast, por lo que las reglas en prosa y las comprobaciones automatizadas nunca se desvían.

9. Copiar, pegar, selección y renderizado

El texto en escritura árabe se rompe más a menudo en copiar/pegar y selección que el latín. Reglas:

  • Renderizado de selección: establece ::selection con suficiente contraste (los grupos de glifos de escritura árabe se extienden debajo de la línea; una banda de resaltado delgada los corta visualmente). El padding en ::selection ayuda.
  • Integridad de copiar/pegar: nunca insertes ZWNJ mediante programación en áreas donde los usuarios puedan pegar en campos de texto sin formato; al pegar en la página, mantén el texto pegado byte exacto (sin "limpieza" automática de U+200C, U+200E/F, U+061C marca de letra árabe). Eliminar caracteres invisibles corrompe silenciosamente la búsqueda y ortografía persa.
  • user-select: all en citas para que los guillemets permanezcan adjuntos.
  • Componentes de copiar al portapapeles (precio, número de seguimiento) deben copiar la cadena lógica, no la visualmente reordenada — prueba con una página RTL + un visor de portapapeles LTR.
  • Banderas de renderizado de fuentes: prefiere text-rendering: optimizeLegibility; NO uses pesos de font-synthesis en caras de visualización árabe (la negrita falsa rompe el ritmo del naskh) — carga pesos reales.
  • Advertencias sobre transformaciones ambiguas: normalizar dígitos arábigo-indios (٠١٢) a persas (۰۱۲) es seguro en contenido fa, destructivo en contenido ar. Cualquier conversión automática debe estar controlada por idioma — consulta references/normalization.md para la tabla de decisiones.

10. Conceptos básicos de escritura mixta (detalles en el skill rtl-bidi)

  • Teléfono/email/URL/código dentro de texto persa: envuélvelo en <bdi> o un span con dir="ltr".
  • Bloques de código: siempre dir="ltr" + text-align: left, incluso en páginas RTL.
  • Entradas generadas por el usuario: dir="auto" para que cada entrada se adapte a su propio contenido.

11. Lista de verificación previa al lanzamiento

  • <html lang="fa|ar" dir="rtl"> establecido
  • La fuente cubre el idioma; fallback nombrado
  • letter-spacing ausente en texto de escritura árabe
  • Interlineado del cuerpo ≥ 1.8 (persa)
  • Todos los afijos usan U+200C real, no espacios
  • Dígitos persas + ٬ ٫ ٪ ٬ en el texto; dígitos latinos solo en átomos LTR
  • Puntuación persa ، ؟ ؛ «» en el texto
  • Las alineaciones usan start/end, nunca left/right

Individual skills in this repo

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

Skills relacionados