Arabic UI (arabic-ui)

Natural, high-fidelity Arabic writing, editorial prose, UX microcopy, and RTL engineering for AI agents, modern web applications, and digital products.

Most Arabic digital text and translated content suffers from العرنجية (clumsy English syntactic calques like "تم الحفظ بنجاح", "الخاص بك", "من الجدير بالذكر أن", "يلعب دورًا هامًا"), broken pluralization (ignoring the 6 grammatical categories or the dual المثنى), and bidirectional layout defects.

arabic-ui is a dual-purpose Agent Skill and engineering reference designed to instruct AI assistants (Claude Code, Antigravity, Cursor, Copilot) and writers to author both:

1. Crisp UI/UX microcopy & RTL engineering (buttons, alerts, form inputs, dynamic counters, CSS insets).
2. High-density, authentic Arabic writing & articles (blog posts, essays, documentation, technical reports, marketing copy).

🚀 Installation & Usage

Quick Install (Recommended)

To add this skill to your agent environment (Antigravity, Claude Code, Cursor, Codex):

npx skills add jkc66/arabic-ui

or with bunx:

bunx skills add jkc66/arabic-ui

Manual / Git Clone

# Global installation:
git clone https://github.com/JKc66/arabic-ui.git ~/.agents/skills/arabic-ui

# Project-level installation:
git clone https://github.com/JKc66/arabic-ui.git .agents/skills/arabic-ui

Once installed, AI agents will automatically trigger this skill whenever you ask to:

• Write, draft, or edit Arabic articles, essays, blog posts, and documentation
• Translate, review, or polish Arabic UI microcopy and marketing copy
• Localize web applications, buttons, alerts, or dashboards
• Implement RTL layouts, logical CSS, or bidirectional isolation
• Handle Arabic plural counters and number formatting

⚡ Key Pillars

1. Anti-العرنجية Guardrails (محاربة الرطانة والترجمة الحرفية)

Eliminates translationese in favor of direct, punchy Arabic:

(Explore the full 60+ term lookup table and syntactic rules from Ahmad Al-Ghamdi's book «العرنجية» in references/aranjiya-glossary.md)

2. The Golden UI Grammar Matrix

⚠️ Rule: Never use imperative verbs on buttons (use حفظ, not احفظ). Buttons represent an action/concept, while placeholders direct the user.

3. CLDR 6-Form Pluralization Engine

Arabic does not have simple singular/plural forms—it defines 6 distinct grammatical categories:

1. Zero (0): لا توجد ملفات
2. One (1): ملف واحد
3. Two (2) - المثنى: ملفان (Nominative / مرفوع) أو ملفين (Oblique / منصوب أو مجرور)
4. Few (3–10): جمع قلة مجرور (3 ملفات)
5. Many (11–99): مفرد منصوب تمييز (15 ملفًا)
6. Other (100+): مفرد مجرور (100 ملف)

Includes a zero-dependency TypeScript implementation in scripts/pluralize.ts:

import { formatArabicPlural, COMMON_ARABIC_NOUNS } from './scripts/pluralize';

formatArabicPlural(0, COMMON_ARABIC_NOUNS.app);   // "لا توجد تطبيقات"
formatArabicPlural(1, COMMON_ARABIC_NOUNS.app);   // "تطبيق واحد"
formatArabicPlural(2, COMMON_ARABIC_NOUNS.app);   // "تطبيقان"
formatArabicPlural(5, COMMON_ARABIC_NOUNS.app);   // "5 تطبيقات"
formatArabicPlural(15, COMMON_ARABIC_NOUNS.app);  // "15 تطبيقًا"
formatArabicPlural(100, COMMON_ARABIC_NOUNS.app); // "100 تطبيق"

4. RTL & BiDi Engineering Guardrails

• CSS Logical Properties: Always use logical properties (margin-inline-start, padding-inline-end, inset-inline-start) instead of physical directions (left, right).
• Inherently LTR Controls: Passwords, emails, phone numbers, and code tokens must enforce dir="ltr" and text-align: start.
• BiDi Isolation: Isolate mixed numbers and neutral characters (/, -, :) with <bdi> or <span dir="ltr"> to prevent bidirectional flip (e.g. preventing 2 GB / 10 GB from rendering backwards as 10 GB / 2 GB).
• Proclitic Typography: The conjunction Waw (و) must connect directly to the succeeding word with zero whitespace (الملفات والمجلدات).

(Read full technical specifications in references/rtl-engineering.md)

📁 Repository Structure

arabic-ui/
├── SKILL.md                          # AI Agent skill definition & dual-mode instructions
├── README.md                         # Documentation & guidelines
├── LICENSE                           # MIT License
├── references/
│   ├── aranjiya-glossary.md          # 60+ term lookup table & syntactic rules (Ahmad Al-Ghamdi)
│   ├── editorial-and-articles.md     # Long-form writing, essays & article guidelines
│   └── rtl-engineering.md            # CSS logical properties & layout specs
└── scripts/
    └── pluralize.ts                  # Production-ready CLDR Arabic pluralization engine

📄 License

MIT © JKc66