Communitygithub.com

rtl-typography

Grundlegende Typografieregeln für persische (Farsi) und arabische Web-Oberflächen. Verwende dies beim Erstellen oder Gestalten jeder Benutzeroberfläche mit persischem/arabischem/Farsi-Text oder wenn der Nutzer فارسی، عربی، RTL، نیم‌فاصله، فونت فارسی erwähnt. Deckt Schriftauswahl, ZWNJ (نیم‌فاصله), persische Ziffern, Zeichensetzung, Zeilenhöhe und verbotene Muster wie Buchstabenabstand bei arabischer Schrift ab.

Was ist rtl-typography?

Der Skill `rtl-typography` bietet eine umfassende, detaillierte Anleitung zur korrekten Typografie für rechts-nach-links (RTL) Sprachen, speziell Persisch (Farsi) und Arabisch. Er ist für KI-Agenten (wie Claude Code, Cursor, Codex) konzipiert, die Web-UI-Komponenten oder -Seiten generieren. Der Skill stellt sicher, dass die Ausgabe kulturell und sprachlich korrekt ist und häufige, von KI generierte Fehler vermeidet. Dazu gehören die korrekte Dokument-Einrichtung (`<html dir='rtl'>`), die Auswahl geeigneter Schriftarten (z.B. Vazirmatn für Persisch), die Verwendung von Zero-Width Non-Joiner (ZWNJ) für persische Affixe, die Beibehaltung der richtigen persischen Ziffern und Zeichensetzung (wie ‚٬‘ und ‚،‘) und vor allem das Verbot von `letter-spacing` (Buchstabenabstand) bei arabischer Schrift, da dies die verbundenen Buchstaben zerstört. Zudem behandelt der Skill Aspekte wie Zeilenhöhe, gemischte Schriftsysteme mit `<bdi>` und eine Checkliste für die Implementierung.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

RTL-Typografie: Persisch & Arabisch richtig gemacht

Dieser Skill kodiert die Typografie-Ebene für rechts-nach-links-Oberflächen. Folge ihm immer, wenn der Text auf der Seite Persisch oder Arabisch ist. Für komplette Seitenaufbauten siehe rtl-landing, für Komponentenmuster siehe rtl-components.

1. Dokument-Einrichtung — immer zuerst

<html lang="fa" dir="rtl">
  • Setze lang UND dir gemeinsam. lang="fa" für Persisch, lang="ar" für Arabisch.
  • Simuliere RTL niemals mit text-align: right in einem LTR-Dokument. Browser, Screenreader, Formularelemente und Bildlaufleisten richten sich nach dir.
  • Jede Ausrichtung muss logische Werte verwenden: text-align: start, nicht left.

2. Schriftarten

Verwende eine Schriftart, die für die Sprache entwickelt wurde. Eine Schriftart, der persische Glyphen fehlen, erzeugt defekte/Tofu-Formen oder ersetzt sie stillschweigend.

Zuverlässige Optionen (Details + CDN-Snippets in fonts.md):

VerwendungszweckPersischArabisch
Fließtext/UI (Standard)VazirmatnIBM Plex Sans Arabic
Auszeichnung/ÜberschriftenLalezar, EstedadCairo, Changa
Redaktionell/Serifen-StilMarkazi Text, ParastooNoto Naskh Arabic
Vertrautes/System-StilSahel, ShabnamTajawal, Almarai

Stapelmuster — benenne immer einen Fallback und lasse eine Schriftart Latein abdecken:

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

Lade nur woff2, verwende font-display: swap, subsette die verwendeten Schriftstärken (400, 500, 700 reichen normalerweise).

3. NIEMALS Buchstabenabstand bei arabischer Schrift verwenden

Dies ist der häufigste KI-generierte RTL-Fehler.

Arabische Schriftzeichen sind kursiv und verbunden. letter-spacing fügt Lücken zwischen verbundenen Glyphen ein und zerbricht Wörter optisch: «مدیریت» wird zu م د ی ر ی ت.

/* FALSCH — zerstört die Verbindung */
.hero-title { letter-spacing: 0.05em; }

/* RICHTIG — falls breiterer Darstellungstext benötigt wird, stattdessen Größe/Schriftstärke verwenden */
.hero-title { font-weight: 800; font-size: 3rem; }

Regel: letter-spacing: 0 oder nicht gesetzt für jeden arabischen Text. Tracking-Tricks (Großbuchstaben, breites Tracking) treffen ohnehin nicht zu — die arabische Schrift hat keine Groß-/Kleinschreibung.

4. Zeilenhöhe und Rhythmus

Zeilenboxen arabischer Schrift sind höher als lateinische (Ober-/Unterlängen + Diakritika). Lateinische Standardwerte wirken gedrängt.

  • Persischer Fließtext: line-height: 1.8–2.0 (1.9 ist ein sicherer Standardwert)
  • Arabischer Fließtext: line-height: 1.6–1.8
  • Überschriften: 1.3–1.4
  • Persischer Text läuft ~10–15 % breiter als Englisch für denselben Inhalt — kalkuliere breitere Buttons, mehr Absatzbreite ein, kürze nicht übermäßig.

Blocksatz: Bevorzuge start-ausgerichteten (gebrochenen) Text. Browser-Blocksatz ohne Kashida-Unterstützung erzeugt hässliche Flüsse zwischen Wörtern.

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

Persische Zusammensetzungen und Affixe werden mit einem Zero-Width Non-Joiner zwischen den Teilen geschrieben. Fehlender ZWNJ ist der sichtbarste Rechtschreibfehler in generierten persischen Texten.

Tabelle zur korrekten Verwendung

Falsch (Leerzeichen oder verbunden)Richtig (mit U+200C)
می رودمی‌رود
نمی شودنمی‌شود
می خواهممی‌خواهم
خانه هاخانه‌ها
کتاب هایکتاب‌های
بهترین هابهترین‌ها
خوب ترخوب‌تر
برنامه نویسیبرنامه‌نویسی
راه اندازیراه‌اندازی
ورود به سیستم می پردازدورود به سیستم می‌پردازد

Faustregeln:

  • Präfixe می, نمی, بی, هم, نا, باز + Verb/Adjektiv → ZWNJ: می‌گوید، نمی‌دانست، بی‌نقص، هم‌گام
  • Suffixe ها, های, تر, ترین nach einem Wort → ZWNJ: پرنده‌ها، کتاب‌های، بزرگ‌تر، بزرگ‌ترین
  • Zusammengesetzte Substantive aus der Akademie-Wortliste → ZWNJ: راه‌اندازی، برنامه‌نویسی، نرم‌افزار، ذخیره‌سازی
  • Possessivsuffixe ام/ات/اش werden verbunden geschrieben: کتابم، خانه‌ات — füge dort KEINEN ZWNJ ein.

Beim Generieren von persischen Texten schreibe ZWNJ nativ (kein Leerzeichen). Um vorhandenen Text zu bereinigen, verwende das beiliegende Skript:

python3 scripts/fix-zwnj.py draft.md            # Trockentest-Diff
python3 draft-output.md > fixed.md --apply ...  # siehe --help

Das Skript verbindet häufige defekte Muster (می رود, خانه ها, خوب تر), konvertiert arabisches ي ك in persisches ی ک und verändert niemals Codeblöcke oder URLs.

6. Ziffern

SpracheZiffernUnicode-Bereich
Persisch۰۱۲۳۴۵۶۷۸۹U+06F0–U+06F9
Arabisch٠١٢٣٤٥٦٧٨٩U+0660–U+0669
Lateinisch (eingebettete Kontexte)0123456789U+0030–U+0039
  • In persischer Sprache verfasster Text verwendet persische Ziffern: «۵ دلیل»، «۲۴ ساعت».
  • Preise: ۱۲۵٬۰۰۰ تومان — Tausendertrennzeichen ist U+066C (٬), Dezimaltrennzeichen ist U+066B (٫).
  • Prozent nach der Zahl, kein Leerzeichen: ۱۲٪ (arabisches Prozentzeichen U+066A).
  • Formatiere diese niemals von Hand: Verwende JS-Locale-APIs.
(125000).toLocaleString('fa-IR')   // "۱۲۵٬۰۰۰"
(12.5).toLocaleString('fa-IR')     // "۱۲٫۵"
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.12)  // "۱۲٪"

erhalte westliche Ziffern nur in inhärent LTR-Atomen: Telefonnummern, URLs, Code, Preise in Fremdwährung.

7. Zeichensetzung — persische Zeichen in persischem Text

ZweckPersisch/ArabischNicht verwenden
Komma، (U+060C),
Fragezeichen؟ (U+061F)?
Semikolon؛ (U+061B);
Anführungszeichen«متن»"متن"
Dezimal / Tausender٫ ٬. ,
Prozent٪ (U+066A)%

Auslassungspunkte sind …, nicht drei Punkte. Kein Leerzeichen vor ، ؟ ؛; ein Leerzeichen danach.

8. Persisch vs. Arabisch — zuerst entscheiden

Es sind unterschiedliche Sprachen mit unterschiedlichen Konventionen. Bestätige vor dem Gestalten, welche verwendet wird:

  • Ziffern: fa → ۱۲۳ (U+06F0), ar → ١٢٣ (U+0660)
  • Buchstaben: Persisch ی/ک vs. Arabisch ي/ك — eine persische Schriftart muss persische Formen enthalten
  • Zeichensetzung überschneidet sich, aber Tonfall/Sprachgebrauch unterscheiden sich
  • Eine nur für Persisch geeignete Schriftart zeigt auf einer arabischen Seite falsche Buchstabenformen für ک/ی und umgekehrt

Die maschinenlesbaren Konventionen (Ziffernbereiche, Trennzeichen, Zeichensetzung, Affixlisten) befinden sich in raast/profiles/fa.json und raast/profiles/ar.json — denselben Dateien, die auch die raast CLI verwendet, sodass Prosa-Regeln und automatisierte Prüfungen nie auseinanderdriften.

9. Kopieren, Einfügen, Auswahl & Darstellung

Text in arabischer Schrift bricht beim Kopieren/Einfügen und bei der Auswahl häufiger als lateinischer Text. Regeln:

  • Darstellung der Auswahl: setze ::selection mit ausreichendem Kontrast (Glyphencluster arabischer Schrift erstrecken sich unter die Grundlinie; ein dünner Hervorhebungsbalken schneidet sie optisch ab). Ein Innenabstand bei ::selection hilft.
  • Integrität von Kopieren/Einfügen: füge ZWNJ niemals programmatisch in Bereiche ein, in die Benutzer in Klartextfelder einfügen könnten; beim Einfügen auf die Seite hin behalte den eingefügten Text bytegenau bei (keine automatische "Bereinigung" von U+200C, U+200E/F, U+061C arabisches Buchstabenzeichen). Das Entfernen unsichtbarer Zeichen beschädigt stillschweigend die persische Suche und Rechtschreibung.
  • user-select: all bei Zitaten/Quellenangaben, damit Guillemets verbunden bleiben.
  • In-die-Zwischenablage-Kopierkomponenten (Preis, Sendungsnummer) müssen die logische Zeichenfolge kopieren, nicht die visuell neu angeordnete — teste mit einer RTL-Seite + LTR-Zwischenablage-Viewer.
  • Schriftdarstellungsflags: bevorzuge text-rendering: optimizeLegibility; verwende KEINE font-synthesis-Gewichtungen bei arabischen Auszeichnungsschriftarten (gefälschtes Fett zerstört den Naskh-Rhythmus) — lade echte Gewichtungen.
  • Warnungen zu mehrdeutigen Transformationen: Das Normalisieren arabisch-indischer Ziffern (٠١٢) zu persischen (۰۱۲) ist in fa-Inhalten sicher, in ar-Inhalten zerstörend. Jede automatisierte Konvertierung muss sprachabhängig sein — siehe references/normalization.md für die Entscheidungstabelle.

10. Grundlagen gemischter Schriftsysteme (Details im rtl-bidi-Skill)

  • Telefon/E-Mail/URL/Code innerhalb von persischem Text: umschließe mit <bdi> oder einem dir="ltr"-Span.
  • Codeblöcke: immer dir="ltr" + text-align: left, auch auf RTL-Seiten.
  • Benutzereingaben: dir="auto", sodass jede Eingabe sich an ihren eigenen Inhalt anpasst.

11. Vorab-Checkliste

  • <html lang="fa|ar" dir="rtl"> gesetzt
  • Schriftart deckt die Sprache ab; Fallback benannt
  • letter-spacing fehlt bei arabischem Text
  • Zeilenhöhe Fließtext ≥ 1.8 (Persisch)
  • Alle Affixe verwenden echten U+200C, keine Leerzeichen
  • Persische Ziffern + ٬ ٫ ٪ ٬ im Text; lateinische Ziffern nur in LTR-Atomen
  • Persische Zeichensetzung ، ؟ ؛ «» im Text
  • Ausrichtungen verwenden start/end, niemals left/right

Individual skills in this repo

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

Verwandte Skills