How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/jamalmohafil/claude-skills --skill arabic-designBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Arabic Design — clean Arabic in AI-generated UI
Arabic is a cursive, connected script: letters join, and diacritics (ً ّ َ) sit above/below the baseline. Most AI-generated CSS is tuned for Latin type — and that's exactly what breaks Arabic. Apply these rules by default whenever the design contains Arabic; don't wait to be told.
Rule 1 — NEVER negative letter-spacing on Arabic (the #1 bug)
Latin design trends love tight tracking (letter-spacing: -0.02em). On Arabic, negative tracking overlaps the letter joins and crushes words into an unreadable blur. Positive tracking is just as wrong — it disconnects letters that must join.
/* ❌ WRONG — crushes connected letters into a blur */
h1 { letter-spacing: -1.5px; } /* element contains Arabic */
/* ✅ RIGHT */
h1 { letter-spacing: normal; } /* or 0 — always, for any element containing Arabic */- Any element containing Arabic (or mixed Arabic+Latin) →
letter-spacing: normal. Full stop. - Negative/positive tracking is allowed only on pure-Latin/numeric elements (big stat numbers,
$99, VS, all-caps Latin labels).
Rule 2 — Use a real Arabic font (never Latin-font fallback)
A Latin font with no Arabic glyphs silently falls back to a system font — mismatched weight, broken look. Always declare an Arabic-capable font explicitly, with a full stack:
/* pick one that matches the design's mood: */
font-family: "Cairo", "Tajawal", "IBM Plex Sans Arabic", "Noto Kufi Arabic", sans-serif; /* modern UI */
font-family: "Almarai", "Rubik", "Baloo Bhaijaan 2", sans-serif; /* rounded/friendly */
font-family: "Noto Naskh Arabic", "Amiri", serif; /* editorial/classic */- Load the Arabic weights you actually use (400/700 at minimum).
- Never apply
font-style: italicto Arabic (fake oblique breaks the script) and never rely on
text-transform (Arabic has no case).
Rule 3 — Line-height must clear the diacritics
Bold display Arabic needs vertical room, or dots/diacritics collide with the line above.
| Context | Safe line-height |
|---|---|
| Display headline (large, bold) | 1.3 |
| Mid headline | 1.35 |
| Body / captions | 1.5–1.7 |
If unsure, go looser. Clipped diacritics are an instant "looks broken" tell.
Rule 4 — Direction & bidi (the "words are reversed" family of bugs)
- Set direction once at the root (
<html dir="rtl">for Arabic-first pages) — children inherit.
Don't sprinkle dir attributes on every element.
- Use logical CSS properties so layout flips correctly:
margin-inline-start,
padding-inline-end, text-align: start — instead of margin-left, text-align: left.
- Wrap embedded Latin words/numbers inside Arabic text in an isolated span so the bidi
algorithm doesn't reorder them:
.ltr { display: inline-block; direction: ltr; } حدد أول <span class="ltr">MVP</span> قبل ما تبدأ- The `direction: ltr` parent leak (root cause of reversed word order): layout containers set to
direction: ltr for card/column order leak LTR into the Arabic text inside — so Marketplace مدمج renders as مدمج Marketplace. Fix: LTR only for layout order; every Arabic text block inside gets explicit direction: rtl.
- The `الـ` + Latin-word trap: never place the Arabic definite-article prefix (
الـ,بالـ,
للـ) immediately before an isolated Latin word — the detached letters jump to the wrong side. Drop the article (عبر CLI not عبر الـ CLI) or rephrase.
- Flip directional icons (arrows) in RTL contexts; a "next" arrow points left in Arabic UI.
Rule 5 — Punctuation & line breaks
- Use Arabic punctuation in Arabic sentences:
؟not?,،not,. - If a
?or،floats to the wrong side, the cause is almost always a straddling Latin token —
wrap it in .ltr or rephrase so the sentence doesn't break mid-clause around it.
- When splitting a headline across lines, each line must continue the sentence naturally — Arabic
readers read stacked lines as one flowing thought.
Rule 6 — Mobile legibility
Arabic letterforms are denser than Latin at the same px size. For social/mobile canvases (e.g. 1080px wide), keep body text ≥ ~36–40px and prefer heavier weights (600–800) for display text.
Pre-ship checklist
- No negative
letter-spacingon any Arabic-containing selector:
grep -nE "letter-spacing:\s*-" file.htmlEvery hit must be pure-Latin/numeric. If it wraps Arabic → normal.
- Every Arabic element has an explicit Arabic-capable
font-family. - Display Arabic has line-height ≥ 1.3; body ≥ 1.5.
- Embedded Latin words/numbers wrapped in
.ltr; noالـ/بالـ/للـdirectly before a Latin word:
grep -noE "(الـ|بالـ|للـ) ?<?[A-Za-z]" file.html- No
direction: ltrancestor leaking into Arabic text blocks. - Render and look. Screenshot the result and inspect: letters connected (not crushed, not
separated), diacritics not clipped, punctuation on the correct side, word order correct.
