---
name: persian-fonts
description: Persian (Farsi) and Latin font selection for FlatRender — which font to use where, with a Persian-first priority. Use when choosing typefaces for a template or UI, pairing display vs body fonts, handling RTL/Persian numerals, or adding a new font to the Remotion project. Persian fonts are the priority.
---

# Persian-first typography

This is an Iran-facing product: **Persian (Farsi) is the default and the priority**. Latin is secondary. Get the Persian type right first.

## What the project already uses
- **Vazirmatn** — the default Persian face everywhere. Remotion bundles `services/remotion/public/fonts/vazirmatn-{400,600,700,800,900}.woff2` and exposes `FONT` from `src/lib/fonts.ts` (use `fontFamily: FONT` + `direction: "rtl"` in every composition).
- Web app: `globals.css` has a `[dir="rtl"]` block that FORCES Vazirmatn on all elements — don't fight it with utility classes; work with it.
- Latin pairing in the web app: **Plus Jakarta Sans** + **Inter**.

## Persian font palette (pick by role)
| Font | Character | Use for |
|---|---|---|
| **Vazirmatn** | clean, neutral, many weights | DEFAULT — body, UI, most template text |
| **Estedad** | modern, geometric, friendly | headings, modern brand templates |
| **Yekan Bakh** | contemporary sans, professional | corporate/business templates |
| **Shabnam / Sahel** | soft, readable | body text, calm/elegant designs |
| **IRANSans / IRANYekan** | familiar Iranian UI standard | UI-style promos, app mockups |
| **Morabba** | bold display, rounded | big punchy headlines, posters |
| **Gandom** | strong display | impactful titles, sale/sport |
| **Lalezar** | playful, heavy, fun | kids, party, birthday, casual |
| **Shekari / Vahid** | decorative/calligraphic | festive, traditional (Nowruz, wedding, Yalda) |
| **Nastaliq (e.g. IranNastaliq)** | classical calligraphy | very formal/traditional, invitations — use sparingly, hard to read small |

Pairing rule: one display face for the headline + Vazirmatn (or Shabnam) for everything else. Don't mix two display faces.

## Match font to template mood
- Corporate / SaaS → Estedad / Yekan Bakh + Vazirmatn.
- Festive (birthday, party) → Lalezar / Morabba + Vazirmatn.
- Traditional / occasion (Nowruz, wedding, Yalda, Eid) → a decorative/Nastaliq display for the greeting + Vazirmatn for details.
- Sale / bold promo → Gandom / Morabba (heavy) + Vazirmatn.
- Minimal / elegant → Shabnam / Sahel, lighter weights.

## Persian typesetting rules
- **RTL:** always `direction: "rtl"`; align right or center. Mixed Persian+Latin/numbers needs care (bidi) — test the actual string.
- **Numerals:** decide Persian (۱۲۳) vs Latin (123) and be consistent. For Persian digits, format with `toLocaleString('fa-IR')` or use a font that supports Persian numerals. Years/prices in templates are usually Persian digits (۱۴۰۶, ۲۹۹٬۰۰۰).
- **Weights:** Persian script needs a bit more weight to feel solid — headings 700-900, body 400-600. Avoid ultra-thin for small text.
- **Line-height:** Persian needs slightly more (`lineHeight` 1.4-1.6 for body) — descenders/diacritics need room.
- **ZWNJ (نیم‌فاصله, `‌`):** preserve it in words like «می‌شود», «نیم‌فاصله» — don't strip it.
- **No fake bold/italic:** use real weights; Persian has no italic — don't slant it.

## Adding a new font to a Remotion template
1. Get the woff2 (license-checked — Vazirmatn/Estedad/Shabnam are SIL OFL, free for commercial; verify others). Place in `services/remotion/public/fonts/`.
2. Register it (a `@font-face` injected via `<style>` in the composition, or `@remotion/fonts` `loadFont`) and expose a `FONT_X` const next to `FONT` in `lib/fonts.ts`.
3. Use `fontFamily: FONT_X` only for that template's display text; keep body on Vazirmatn.
4. Embed the actual weights you use (don't ship 9 weights if you use 2) to keep bundles small.

## Licensing
Prefer SIL OFL / free-for-commercial Persian fonts (Vazirmatn, Estedad, Shabnam, Sahel, Samim, Gandom, Morabba — most from the `font-store`/Google Persian sets are OFL). Verify each before shipping in an exported-video product; keep a license record.

Related: `remotion-template-composition`, `remotion-design-styles`.