jamalmohafil/claude-skills

arabic-design

Make AI-generated designs render Arabic text correctly — clean, connected, professional.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/jamalmohafil/claude-skills --skill arabic-design

Before 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.
Original skill document

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.

css
/* ❌ 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:

css
/* 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: italic to 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.

ContextSafe line-height
Display headline (large, bold)1.3
Mid headline1.35
Body / captions1.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:

css
  .ltr { display: inline-block; direction: ltr; }
html
  حدد أول <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

  1. No negative letter-spacing on any Arabic-containing selector:
bash
   grep -nE "letter-spacing:\s*-" file.html

Every hit must be pure-Latin/numeric. If it wraps Arabic → normal.

  1. Every Arabic element has an explicit Arabic-capable font-family.
  2. Display Arabic has line-height ≥ 1.3; body ≥ 1.5.
  3. Embedded Latin words/numbers wrapped in .ltr; no الـ/بالـ/للـ directly before a Latin word:
bash
   grep -noE "(الـ|بالـ|للـ) ?<?[A-Za-z]" file.html
  1. No direction: ltr ancestor leaking into Arabic text blocks.
  2. 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.

from this repository

More skills

All skills