Communitygithub.com

rtl-typography

페르시아어(파르시) 및 아랍어 웹 인터페이스를 위한 핵심 타이포그래피 규칙입니다. 페르시아어/아랍어 텍스트가 포함된 UI를 구축하거나 스타일링할 때, 또는 사용자가 فارسی, عربی, RTL, نیم‌فاصله, فونت فارسی를 언급할 때 사용하세요. 글꼴 선택, ZWNJ(نیم‌فاصله), 페르시아 숫자, 문장 부호, 줄 높이 및 아랍 문자에 letter-spacing 금지와 같은 금지 패턴을 다룹니다.

rtl-typography란 무엇인가요?

이 스킬은 RTL(오른쪽에서 왼쪽) 웹 인터페이스, 특히 페르시아어와 아랍어 텍스트의 타이포그래피 처리를 위한 포괄적인 규칙을 제공합니다. 주된 목적은 AI 모델이나 개발자가 RTL 텍스트를 렌더링할 때 흔히 발생하는 오류(예: 아랍 문자에 letter-spacing 적용, ZWNJ 누락, 페르시아 숫자 대신 라틴 숫자 사용, 잘못된 dir 속성 등)를 방지하는 것입니다. 이 스킬은 HTML 문서 설정(`lang`, `dir` 속성), 언어별 권장 글꼴 및 폴백 스택, ZWNJ(Zero-Width Non-Joiner, U+200C)의 올바른 사용법(복합어 및 접사 처리), 페르시아어와 아랍어 각각의 숫자 체계 및 문장 부호, 줄 높이 권장값, 그리고 복사/붙여넣기 및 선택 렌더링과 같은 고급 주제를 다룹니다. 또한 페르시아어와 아랍어 프로필 설정을 위한 `raast` CLI 도구와 ZWNJ를 자동으로 교정하는 `fix-zwnj.py` 스크립트를 함께 제공합니다. 이 스킬은 Claude Code, Cursor, Codex, Windsurf와 같은 모든 AI 에이전트 플랫폼에서 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mhmdsdqi87-cloud/TEKA_raast/tree/HEAD/skills/rtl-typography

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

RTL 타이포그래피: 페르시아어와 아랍어 제대로 하기

이 스킬은 오른쪽에서 왼쪽(RTL) 인터페이스를 위한 타이포그래피 규칙을 인코딩합니다. 페이지에 페르시아어 또는 아랍어 텍스트가 있을 때마다 이를 따르세요. 전체 페이지 빌드는 rtl-landing, 컴포넌트 패턴은 rtl-components를 참조하세요.

1. 문서 설정 — 항상 먼저

<html lang="fa" dir="rtl">
  • lang과 dir을 함께 설정하세요. 페르시아어는 lang="fa", 아랍어는 lang="ar"입니다.
  • LTR 문서에 text-align: right를 사용하여 RTL을 시뮬레이션하지 마세요. 브라우저, 스크린 리더, 양식 컨트롤, 스크롤바 모두 dir 속성을 기반으로 작동합니다.
  • 모든 정렬은 논리적 값을 사용해야 합니다: text-align: start, left가 아닙니다.

2. 글꼴

해당 언어를 위해 디자인된 글꼴을 사용하세요. 페르시아어 글리프가 없는 글꼴은 깨지거나(tofu) 보이지 않게 대체됩니다.

신뢰할 수 있는 선택 (자세한 내용 및 CDN 스니펫은 fonts.md 참조):

사용 사례페르시아어아랍어
본문/UI (기본)VazirmatnIBM Plex Sans Arabic
디스플레이/제목Lalezar, EstedadCairo, Changa
편집/세리프 느낌Markazi Text, ParastooNoto Naskh Arabic
친숙한/시스템 느낌Sahel, ShabnamTajawal, Almarai

폴백을 항상 지정하고 하나의 글꼴이 라틴 문자를 커버하도록 하는 스택 패턴:

font-family: 'Vazirmatn', Tahoma, sans-serif;

woff2만 로드하고, font-display: swap을 사용하며, 사용하는 굵기(보통 400, 500, 700)만 서브셋하세요.

3. 아랍 문자에 절대 letter-spacing 사용하지 마세요

이것은 AI 생성 RTL에서 가장 흔한 버그입니다.

아랍 문자는 필기체로 연결되어 있습니다. letter-spacing은 연결된 글리프 사이에 간격을 삽입하여 시각적으로 단어를 산산조각냅니다: «مدیریت»가 م د ی ر ی ت가 됩니다.

/* 틀림 — 연결을 끊습니다 */
.hero-title { letter-spacing: 0.05em; }

/* 옳음 — 더 넓은 디스플레이 텍스트가 필요하면 크기/굵기를 대신 사용하세요 */
.hero-title { font-weight: 800; font-size: 3rem; }

규칙: 아랍 문자 텍스트에 대해 letter-spacing: 0 또는 설정하지 마세요. 트래킹 트릭(대문자, 넓은 트래킹)은 어차피 적용되지 않습니다. 아랍 문자에는 대소문자가 없습니다.

4. 줄 높이와 리듬

아랍 문자 줄 상자는 라틴 문자보다 더 큽니다(어센더/디센더 + 발음 구별 부호). 라틴 기본값은 비좁아 보입니다.

  • 페르시아어 본문 텍스트: line-height: 1.8–2.0 (1.9가 안전한 기본값)
  • 아랍어 본문 텍스트: line-height: 1.6–1.8
  • 제목: 1.3–1.4
  • 페르시아어 텍스트는 동일한 내용에 비해 영어보다 약 10–15% 더 넓게 표시됩니다 — 더 넓은 버튼, 더 많은 단락 너비를 할당하고, 지나치게 자르지 마세요.

정렬: 시작 정렬(비정형)을 선호하세요. 카시다 지원 없이 브라우저 정렬을 하면 단어 사이에 보기 흉한 강물(rivers)이 생깁니다.

5. ZWNJ — نیم‌فاصله (U+200C)

페르시아어 복합어와 접사는 부분 사이에 Zero-Width Non-Joiner(폭 없는 비접합자)를 사용하여 작성됩니다. ZWNJ가 누락된 것은 생성된 페르시아어 텍스트에서 가장 눈에 띄는 맞춤법 결함입니다.

올바른 사용법 표

틀림 (공백 또는 연결됨)옳음 (U+200C 사용)
می رودمی‌رود
نمی شودنمی‌شود
می خواهممی‌خواهم
خانه هاخانه‌ها
کتاب هایکتاب‌های
بهترین هابهترین‌ها
خوب ترخوب‌تر
برنامه نویسیبرنامه‌نویسی
راه اندازیراه‌اندازی
ورود به سیستم می پردازدورود به سیستم می‌پردازد

경험 법칙:

  • 접두사 می, نمی, بی, هم, نا, باز + 동사/형용사 → ZWNJ: می‌گوید، نمی‌دانست، بی‌نقص، هم‌گام
  • 접미사 ها, های, تر, ترین가 단어 뒤에 올 때 → ZWNJ: پرنده‌ها، کتاب‌های، بزرگ‌تر، بزرگ‌ترین
  • 아카데미 단어 목록의 복합 명사 → ZWNJ: راه‌اندازی، برنامه‌نویسی، نرم‌افزار، ذخیره‌سازی
  • 소유 접미사 ام/ات/اش는 붙여 씁니다: کتابم، خانه‌ات — 여기에는 ZWNJ를 삽입하지 마세요.

페르시아어 텍스트를 생성할 때는 ZWNJ를 기본적으로 사용하세요(공백이 아님). 기존 텍스트를 정리하려면 번들된 스크립트를 사용하세요:

python3 scripts/fix-zwnj.py draft.md            # dry-run diff (변경 사항 미리보기)
python3 draft-output.md > fixed.md --apply ...  # --help 참조

이 스크립트는 일반적인 깨진 패턴(می رود, خانه ها, خوب تر)을 결합하고, 아랍어 ي ك를 페르시아어 ی ک로 변환하며, 코드 블록이나 URL은 건드리지 않습니다.

6. 숫자

언어숫자유니코드 범위
페르시아어۰۱۲۳۴۵۶۷۸۹U+06F0–U+06F9
아랍어٠١٢٣٤٥٦٧٨٩U+0660–U+0669
라틴 (임베디드 컨텍스트)0123456789U+0030–U+0039
  • 페르시아어로 작성된 텍스트는 페르시아 숫자를 사용합니다: «۵ دلیل», «۲۴ ساعت».
  • 가격: ۱۲۵٬۰۰۰ تومان — 천 단위 구분 기호는 U+066C (٬), 소수점은 U+066B (٫)입니다.
  • 퍼센트는 숫자 뒤에 공백 없이: ۱۲٪ (아랍어 퍼센트 기호 U+066A).
  • 수동으로 포맷하지 마세요: JS 로케일 API를 사용하세요.
(125000).toLocaleString('fa-IR')   // "۱۲۵٬۰۰۰"
(12.5).toLocaleString('fa-IR')     // "۱۲٫۵"
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.12)  // "۱۲٪"

서양 숫자는 본질적으로 LTR인 요소(전화번호, URL, 코드, 외화 가격) 안에만 유지하세요.

7. 문장 부호 — 페르시아어 텍스트의 페르시아 기호

용도페르시아어/아랍어사용 금지
쉼표، (U+060C),
물음표؟ (U+061F)?
쌍반점؛ (U+061B);
인용«متن»"متن"
소수점 / 천 단위 구분٫ ٬. ,
퍼센트٪ (U+066A)%

생략 부호는 …, 세 개의 점이 아닙니다. ، ؟ ؛ 앞에는 공백이 없고, 뒤에는 하나의 공백이 있습니다.

8. 페르시아어 vs 아랍어 — 먼저 결정하세요

이들은 다른 규칙을 가진 다른 언어입니다. 스타일링하기 전에 어느 것인지 확인하세요:

  • 숫자: fa → ۱۲۳ (U+06F0), ar → ١٢٣ (U+0660)
  • 문자: 페르시아어 ی/ک 대 아랍어 ي/ك — 페르시아어 글꼴은 페르시아어 형태를 포함해야 합니다
  • 문장 부호는 겹치지만 어조/관용구는 다릅니다
  • 아랍어 페이지에 페르시아어 전용 글꼴을 사용하면 ک/ی에 대해 잘못된 문자 형태가 표시되고 그 반대도 마찬가지입니다

기계 판독 가능한 규칙(숫자 범위, 구분 기호, 문장 부호, 접사 목록)은 raast/profiles/fa.json 및 raast/profiles/ar.json에 있습니다 — 이는 raast CLI가 사용하는 것과 동일한 파일이므로, 산문 규칙과 자동 검사가 결코 분리되지 않습니다.

9. 복사, 붙여넣기, 선택 및 렌더링

아랍 문자 텍스트는 라틴 문자보다 복사/붙여넣기 및 선택 시 깨지는 경우가 더 많습니다. 규칙:

  • 선택 렌더링: 충분한 대비를 가진 ::selection을 설정하세요(아랍 문자 글리프 클러스터는 줄 아래로 확장됩니다. 얇은 하이라이트 밴드는 시각적으로 글리프를 자릅니다). ::selection에 패딩을 추가하면 도움이 됩니다.
  • 복사/붙여넣기 무결성: 사용자가 일반 텍스트 필드에 붙여넣을 수 있는 영역에 프로그래밍 방식으로 ZWNJ를 삽입하지 마세요. 페이지 안으로 붙여넣을 때는 붙여넣은 텍스트를 바이트 단위로 정확하게 유지하세요(U+200C, U+200E/F, U+061C á랍 문자 표시를 자동으로 "정리"하지 마세요). 보이지 않는 문자를 제거하면 페르시아어 검색 및 맞춤법이 자동으로 손상됩니다.
  • 인용/출처에는 user-select: all을 사용하여 꺾쇠표(guillemets)가 분리되지 않도록 하세요.
  • 클립보드로 복사 컴포넌트(가격, 추적 번호)는 시각적으로 재정렬된 문자열이 아닌 논리적 문자열을 복사해야 합니다 — RTL 페이지 + LTR 클립보드 뷰어로 테스트하세요.
  • 글꼴 렌더링 플래그: text-rendering: optimizeLegibility를 선호하세요. 아랍 디스플레이 얼굴에 font-synthesis 굵기를 사용하지 마세요(가짜 굵기는 naskh 리듬을 깨뜨립니다) — 실제 굵기를 로드하세요.
  • 모호한 변환에 대한 경고: 아랍-인도 숫자(٠١٢)를 페르시아 숫자(۰۱۲)로 정규화하는 것은 fa 콘텐츠에서는 안전하지만, ar 콘텐츠에서는 파괴적입니다. 자동 변환은 반드시 언어별로 게이트되어야 합니다 — 결정 테이블은 references/normalization.md를 참조하세요.

10. 혼합 스크립트 기본 사항 (자세한 내용은 rtl-bidi 스킬 참조)

  • 페르시아어 텍스트 내의 전화/이메일/URL/코드: <bdi> 또는 dir="ltr" 스팬으로 감싸세요.
  • 코드 블록: RTL 페이지에서도 항상 dir="ltr" + text-align: left를 사용하세요.
  • 사용자 생성 입력: dir="auto"를 사용하여 각 입력이 자체 콘텐츠에 적응하도록 하세요.

11. 사전 점검 목록

  • <html lang="fa|ar" dir="rtl"> 설정
  • 글꼴이 언어를 커버하고 폴백이 지정됨
  • 아랍 문자 텍스트에 letter-spacing 없음
  • 본문 줄 높이 ≥ 1.8 (페르시아어)
  • 모든 접사가 실제 U+200C를 사용하며, 공백이 아님
  • 페르시아어 숫자 + ٬ ٫ ٪ ٬가 텍스트에 사용됨; 라틴 숫자는 LTR 요소에만 사용
  • 페르시아어 문장 부호 ، ؟ ؛ «»가 텍스트에 사용됨
  • 정렬은 start/end를 사용하고, 절대 left/right를 사용하지 않음

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

관련 스킬