arabic-handler

One comprehensive skill for all Arabic handling domains — web RTL, mobile RTL, terminal RTL, document translation, UX writing, Arabic design/typography, RTL linting, and BiDi security.

---

🎯 What is this?

arabic-handler is a unified skill that consolidates 8 Arabic-related domains into a single reference. Instead of juggling multiple specialized skills, you get one comprehensive resource covering every scenario where Arabic text, RTL layout, or bidirectional content appears in a project.

Merged from 5 source repositories:

• almubarmij/arabic-ai-skills — Web RTL, Mobile RTL, Terminal RTL, Document Translation, UX Writing
• Moshe-ship/hurmoz/raqeeb — RTL Linting
• Moshe-ship/hurmoz/bidi-guard — BiDi Security (CVE-2021-42574)
• alMubarmij/Arabic-AI-Skills/arabic-terminal-rtl — Terminal Rendering
• JamalMohafil/claude-skills/arabic-design — Arabic Typography/Design

---

📦 Domains Covered

#	Domain	Key Use Cases
1	Web RTL	CSS logical properties, Tailwind RTL, React/Next.js RTL setup, BiDi text handling
2	Mobile RTL	iOS (SwiftUI/UIKit), Android (Compose/Views), React Native — sentinel checks, row composition
3	Terminal RTL	Windows Terminal, OpenCode, Codex, CLI — character+word reversal for non-BiDi terminals
4	Document Translation	DOCX → Arabic with exact structure preservation (tables, colors, sections, nested tables)
5	UX Writing Arabic	Microcopy, error/success/empty states, buttons, tone/voice, consistency, accessibility
6	Arabic Design/Typography	Font stacks, letter-spacing trap, diacritics, line-height, bidi leaks, الـ + Latin trap
7	RTL Linting (raqeeb)	0-100 RTL score, 8 category audit, CI/CD integration, auto-fix
8	BiDi Security (bidi-guard)	Trojan Source detection (CVE-2021-42574), pre-commit hooks, CI scanning

---

🚀 Quick Start

Installation (OpenCode / Codex / Cursor / Claude Code)

# Clone to your skills directory
git clone https://github.com/onepurp/arabic-handler.git ~/.config/opencode/skills/arabic-handler

# Or for Claude Code
git clone https://github.com/onepurp/arabic-handler.git ~/.claude/skills/arabic-handler

Usage

Auto-detect domain from context:

/arabic-handler

Jump to specific domain:

/arabic-handler web          # Web RTL (CSS, React, Next.js, Tailwind)
/arabic-handler mobile       # Mobile RTL (iOS, Android, RN)
/arabic-handler terminal     # Terminal RTL output
/arabic-handler document     # DOCX → Arabic translation
/arabic-handler ux           # UX writing, microcopy, error messages
/arabic-handler design       # Arabic typography, fonts, design rules
/arabic-handler lint         # raqeeb RTL linting
/arabic-handler security     # bidi-guard BiDi security scan

---

📖 Reference Files

File	Description
SKILL.md	Main skill — 1,700+ lines covering all 8 domains
references/css-logical-properties.md	Complete physical→logical CSS mapping + Tailwind utilities + Arabic font stacks
references/ux-writing-checklist.md	Pre-ship review checklist (8 sections, 60+ checks, templates)
references/arabic-glossary.md	Bilingual EN→AR glossary (UX, dev, design, Arabic-specific terms)

---

🔑 Key Features by Domain

1. Web RTL

• CSS Logical Properties — Complete mapping table (margin, padding, border, positioning, text, sizing)
• Tailwind v3.3+/v4 — Logical utilities (ms-4, me-4, ps-4, pe-4, start-4, end-4, rounded-s-lg, rounded-e-lg)
• Next.js App Router — next/font with Tajawal, locale-aware dir attribute
• BiDi Handling — unicode-bidi: isolate, .ltr-content pattern, phone/URL isolation

2. Mobile RTL

• Sentinel Check — Full-width Arabic text block to verify root RTL before any fixes
• Row Composition — Two-zone pattern: text (visual right, flexible) + accessory (visual left, pinned)
• Control Direction — Local LTR for compound controls (+/-, steppers, segmented) while row stays RTL
• Framework-Native — leading/trailing (iOS), start/end (Android), I18nManager.isRTL (RN)

3. Terminal RTL

• Character Reversal — Reverse chars inside each Arabic word
• Word Order Reversal — Reverse word order per Arabic segment
• Preserve — Code, commands, paths, URLs, JSON, English, numbers, slash commands

4. Document Translation

• 4-Phase Pipeline — Analyze → Dictionary → Generate → Verify
• 3-Level RTL — Text direction (bidi/rtl/complex_script) + Alignment (right) + Layout (columns L→R for data)
• Multi-Pass Matching — 7-pass normalization (95%+ success vs 60% exact-match)
• Nested Tables — Extract content from cells containing nested tables (checklists, forms)
• Auto Color Correction — White text on dark backgrounds

5. UX Writing Arabic

• Voice/Tone Framework — Fixed voice (wise, curious, confident), contextual tone (4 dimensions)
• Emotional Context — Positive (encouraging), Neutral (confident, value-linked), Negative (honest, solution-oriented)
• Button Patterns — Verb + Noun, Confirmation (Verb + Result), Transformation (Value + Action)
• Error/Success/Empty State Templates — Problem+Solution+Positive framing

6. Arabic Design/Typography

• Rule 1 — letter-spacing: normal ALWAYS for Arabic (negative crushes, positive disconnects)
• Rule 2 — Explicit Arabic font stacks (Cairo/Tajawal, Almarai/Rubik, Noto Naskh/Amiri)
• Rule 3 — Line-height ≥ 1.3 display, ≥ 1.5 body (diacritics need room)
• Rule 4 — Root dir="rtl" once, logical properties, isolate Latin tokens, no الـ before Latin
• Rule 6 — Mobile: ≥ 36-40px body, 600-800 weight for display

7. RTL Linting (raqeeb)

raqeeb scan ./src/           # Local files
raqeeb url "https://site.sa" # Live URL
raqeeb report ./src/ --format markdown
raqeeb fix ./src/ --yes      # Auto-fix for CI
raqeeb ci --threshold 75     # CI gate

8. BiDi Security (bidi-guard)

bidi-guard scan ./src/       # Detect U+202E (RLO), U+202D (LRO), U+2067 (RLI), etc.
bidi-guard ci                # CI integration
bidi-guard fix ./src/ --yes  # Auto-remove

---

🎨 Common Gotchas (Cross-Domain)

#	Mistake	Fix
1	text-align: left for Arabic	Use text-align: start
2	margin-left/padding-right don't flip	Use logical properties
3	flex-direction: row-reverse for RTL	row auto-reverses; row-reverse double-flips
4	Phone/URL/code inherits RTL	Wrap in <span dir="ltr">
5	Negative letter-spacing on Arabic	Always normal — crushes connected letters
6	Latin font fallback for Arabic	Explicit Arabic-capable font-family
7	No full-width for Arabic text blocks	Give text blocks full available width
8	Second local RTL override	Prefer framework-native logical direction
9	Hard-coded right/left	Use leading/trailing or start/end
10	direction: ltr parent leaks	LTR for layout only; Arabic text gets explicit direction: rtl
11	الـ before isolated Latin word	Drop article or rephrase
12	Directional icons not flipped	rtl:rotate-180 or I18nManager.isRTL
13	Multi-line DOCX cells split	Preserve \n within cells
14	No visual check after fixes	Generate comparison images/screenshot
15	English punctuation in Arabic	Use ؟ ، not ? ,
16	Buttons with bare nouns	Verb + Noun (أضف كتاباً not إضافة)

---

🛠 Requirements

Tool	Purpose
Python 3.8+	Document translation scripts
python-docx ≥ 0.8.11	DOCX manipulation
Pillow ≥ 9.0.0	Image processing
LibreOffice	DOCX → PDF (visual comparison)
Poppler (pdftoppm)	PDF → PNG (visual comparison)
pipx	Install raqeeb and bidi-guard

# Python deps
pip install python-docx Pillow

# Linting & Security tools
pipx install raqeeb
pipx install bidi-guard

---

📚 Reference Links

Resource	URL
MDN CSS Logical Properties	https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values
Tailwind RTL Support	https://tailwindcss.com/docs/hover-focus-and-other-states#rtl-support
Tailwind Logical Properties	https://tailwindcss.com/docs/margin#logical-properties
Google Fonts Arabic	https://fonts.google.com/?subset=arabic
W3C Internationalization	https://www.w3.org/International/articles/inline-bidi-markup/
CVE-2021-42574 (Trojan Source)	https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42574
Unicode BiDi Algorithm	https://unicode.org/reports/tr9/

---

🤝 Contributing

Contributions welcome! Areas for improvement:

• Additional language support (Hebrew, Urdu, Farsi, Pashto)
• Enhanced PDF-vs-DOCX gap detection
• Integration with translation APIs (Google, DeepL, LibreTranslate)
• Performance optimization for 100+ page documents
• More framework examples (Vue, Svelte, Astro, Expo)
• Automated visual regression testing

---

📄 License

MIT License — Free for personal and commercial use.

---

🙏 Credits

Built by merging and unifying these excellent open-source skills:

• almubarmij — arabic-ai-skills (5 domains)
• Moshe-ship — hurmoz/raqeeb & hurmoz/bidi-guard
• alMubarmij — Arabic-AI-Skills/arabic-terminal-rtl
• JamalMohafil — claude-skills/arabic-design

Battle-tested on production projects including:

• Financial forecasts (9 pages, 6 tables, red/pink color scheme)
• Feasibility analyses (academic formatting, multi-section)
• Business proposals (various structures)
• Mobile apps (iOS, Android, React Native)
• Web apps (React, Next.js, Vue)

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See SKILL.md and references/ directory

---

One skill. Eight domains. Zero excuses for broken Arabic UI.