RTL 컴포넌트 패턴 (Tailwind + shadcn/ui)
방향에 구애받지 않는 논리적 컴포넌트. dir="rtl" 설정 후 flex/grid는 자동으로 미러링됩니다. 버그는 여기에 나열된 잔여물에 있습니다.
1. 유틸리티 변환 테이블 (암기하세요)
| LTR 습관 | 논리적 유틸리티 (항상 사용) |
|---|---|
ml- / mr- | ms- / me- |
pl- / pr- | ps- / pe- |
left-0 / right-0 | start-0 / end-0 |
text-left / text-right | text-start / text-end |
border-l- / border-r- | border-s- / border-e- |
rounded-l- / rounded-r- | rounded-s- / rounded-e- |
ml-auto (먼 쪽으로 밀기) | ms-auto |
이 유틸리티들은 Tailwind v3.3+ 및 v4에 존재합니다. 이것들을 사용하면 컴포넌트가 양방향에서 추가 작업 없이 작동합니다.
2. 방향성 아이콘 — 뒤집기 목록
진정한 방향성 아이콘만 뒤집으세요. 의미상 안정적인 아이콘은 절대 뒤집지 마세요.
뒤집기 (rtl:-scale-x-100 또는 사전 뒤집힌 SVG, 또는 화살표의 경우 rtl:rotate-180):
- 다음/이전, 뒤로 버튼, 브레드크럼 구분자를 위한 chevron/화살표
- 들여쓰기/내어쓰기, 답장(공유 화살표), 전달, 다시 실행
- 타임라인 마커, "사이드 패널 확장" 아이콘
뒤집지 마세요:
- 시계, 잠금, 검색, 설정, 체크, 하트, 별, 업로드/다운로드, 와이파이, 벨
<!-- RTL에서 다음 화살표는 왼쪽을 가리킵니다 -->
<svg class="rtl:rotate-180">…</svg>
shadcn/ui + lucide의 경우: <ChevronLeft className="rtl:rotate-180" />는 두 번 잘못되었습니다. 대신 제공하는 방향에 맞는 올바른 글리프를 사용하세요. RTL 전용 제품의 경우: 다음 = ChevronLeft, 뒤로 = ChevronRight.
3. 폼
- 레이블은 입력 위의 인라인 시작(inline-start)에 위치합니다 (표준).
- 텍스트 입력: 이름/메시지에는
dir="auto"; 전화번호, 이메일, 주민등록번호, 가격 입력에는dir="ltr"+text-end(내용은 LTR이지만 배치는 오른쪽 유지). - 입력 그룹 애드온: 통화 «تومان»은 숫자 뒤에 → 시각적으로 왼쪽; 양쪽에 논리적 패딩 사용, 절대
pr을 하드코딩하지 마세요. - 유효성 검사 아이콘:
right-0대신end-0으로 배치. - 오류 텍스트: 페르시아어, «؛» 및 올바른 ZWNJ 사용: «ایمیل معتبر نیست», «رمز عبور باید ۸ نویسه یا بیشتر باشد».
4. 내비게이션 및 크롬
- 사이드바:
start-0(RTL에서 오른쪽에 렌더링됨). 아이콘만 있는 축소된 변형은 툴팁 뒤집기를 유지합니다 (Radix 툴팁에서side="start"). - 브레드크럼: 구분자 =
ChevronLeft(RTL "앞으로-아래로" 방향), 마지막 항목은 현재 항목. - 페이지네이션: 페이지 번호는 왼쪽으로 오름차순: ۱ ۲ ۳ ۴ 다음 = ChevronLeft.
Prev는 시각적으로 오른쪽에 있습니다. - 탭: 순서는 오른쪽 → 왼쪽; 활성 밑줄은
border-b로 충분합니다. - 테이블: 열 순서 자동 미러링; 숫자 셀은
text-end로 정렬하고 페르시아 숫자가 자체 LTR 실행을 유지하도록 합니다.
5. 오버레이
- 대화상자/시트:
Sheet side="start"= RTL 페이지에서 오른쪽 서랍. - 드롭다운/팝오버: Radix는
side/align사용 —align="start"는 인라인 시작(오른쪽)을 따릅니다. 기본 충돌 처리는 RTL에서 잘 작동합니다. - 토스트:
bottom-start위치 (RTL에서 시각적으로 오른쪽 아래)로 인라인 끝(inline-end)의 CTA와 충돌하지 않도록 합니다. - 잘린 페르시아어 텍스트의 툴팁: Radix가 잘 측정합니다.
max-w가 설정되었는지 확인 — 페르시아어 생략 부호는 정상적으로 작동합니다.
6. 카드 및 콘텐츠 블록
- 인라인 시작 가장자리의 악센트 바:
border-s-2 border-s-emerald-500(오른쪽에 렌더링됨). - 메타 행 (작성자 · 날짜 · 읽는 시간): 구분 점은
ms-2 me-2또는 flexgap-2. - 액션이 있는 카드: 기본 작업이 인라인 끝(inline-end)? 아닙니다 — RTL 읽기에서 기본 CTA는 관례적으로 카드 하단의 인라인 끝(왼쪽)에 위치하여 LTR 관례를 미러링합니다.
7. 모션 및 변환
dir은 변환을 미러링하지 않습니다. 다음을 모두 감사하세요:
translate-x-*(슬라이더, 오프캔버스, 마키) → 명시적인 RTL 쌍 필요rotate-45장식용 → 일반적으로 괜찮음- 캐러셀 스와이프: embla/swiper —
direction: rtl옵션 설정 또는 스크롤이 반대 방향으로 감 - 진행률 표시줄: 채우기는
start-0에 고정, 왼쪽으로 성장; 백분율은 ۷۰٪로 표시 - 스켈레톤 심머: keyframe
translate-x는 미러링되어야 하며, 그렇지 않으면 심머가 잘못된 방향으로 움직입니다.
방향 인식 애니메이션 패턴
/* 오프캔버스 서랍: 인라인 시작에서 들어오고 인라인 시작으로 나갑니다.
하나의 선언 쌍으로 양방향을 제공합니다. */
.drawer { transform: translateX(calc(var(--dir-sign, -1) * 100%)); }
[dir="rtl"] .drawer { --dir-sign: 1; }
.drawer.open { transform: translateX(0); }
/* 바운스/강조 아이콘: 전체 애니메이션을 뒤집고, 요소 자체를 비행 중에 뒤집지 마세요 */
[dir="rtl"] .cta-arrow { animation: nudge-rtl 1.2s infinite; }
@keyframes nudge-rtl { 50% { transform: translateX(-4px); } }
/* 숫자 카운터 및 진행률 채우기: left가 아닌 논리적 인라인 크기 애니메이션 */
@keyframes fill { from { inline-size: 0 } }
- CSS 논리적
inset-inline-start+ 사용자 정의 속성 부호 전환은 방향별로 전체 키프레임을 복제하는 것보다 낫습니다. prefers-reduced-motion: reduce→ 넛지/마키를 비활성화하고 불투명도 페이드는 유지합니다.
8. shadcn/ui RTL 참고 사항 (v4 토큰, New York 스타일)
- 대부분의 기본 요소는 앱이
<html>에dir="rtl"을 설정할 때 RTL에 깔끔합니다. - 알려진 수정 사항:
DropdownMenuContent align="start"는 메뉴를 트리거의 오른쪽 가장자리 아래에 고정합니다;Selectchevron은ChevronDown이어야 합니다 (방향 없음, 변경 없음);InputOTP,CommandDialog,ResizablePanel은 수동 검토가 필요합니다. - 글꼴 토큰을 한 번 설정: Vazirmatn을
--font-sans(globals.css)에 넣어 모든 shadcn 컴포넌트가 상속하도록 합니다.
9. 감사 훅
rtl-audit 체크리스트를 통해 컴포넌트를 출시하세요 — 특히 아이콘 뒤집기, 변환 및 left/right 클래스를 확인합니다.