Communitygithub.com

RTL 컴포넌트 패턴

Tailwind 논리 유틸리티를 사용한 RTL 호환 컴포넌트 패턴. 페르시아어/아랍어 RTL 페이지를 위한 폼, 카드, 내비게이션, 테이블, 모달, 페이지네이션, 브레드크럼과 같은 UI 컴포넌트를 구축하거나 미러링된 레이아웃 버그를 수정할 때 사용합니다. ms/me/ps/pe 유틸리티, 아이콘 뒤집기, 사이드바 배치, shadcn/ui RTL 참고 사항을 다룹니다.

RTL 컴포넌트 패턴란 무엇인가요?

이 스킬은 Tailwind CSS와 shadcn/ui를 사용하여 RTL(오른쪽에서 왼쪽) 레이아웃을 지원하는 UI 컴포넌트를 구축하기 위한 패턴과 모범 사례를 제공합니다. Tailwind v3.3+ 및 v4의 논리적 유틸리티(예: ms/me, ps/pe, start/end)를 사용하여 구성 요소가 LTR 및 RTL 방향 모두에서 자동으로 작동하도록 합니다. 주요 내용으로는 LTR 습관을 논리적 유틸리티로 변환하는 테이블, 방향성 아이콘(예: chevron, 화살표)과 안정적인 아이콘(예: 시계, 검색, 설정)을 구별하여 적절히 뒤집는 규칙, RTL 환경에서의 폼 처리(예: `dir="auto"` 및 `text-end` 사용), 내비게이션 및 크롬 요소(사이드바, 브레드크럼, 페이지네이션)의 배치, 오버레이(시트, 드롭다운, 툴팁)의 RTL 대응, 카드 및 콘텐츠 블록의 악센트 바 방향, 모션 및 변환의 RTL 미러링 감사, shadcn/ui의 RTL 관련 참고 사항 등이 포함됩니다. 또한 `rtl-audit` 체크리스트를 통해 아이콘 뒤집기, 변환, `left`/`right` 클래스 사용을 점검하는 방법을 제시합니다.

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

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

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

문서

RTL 컴포넌트 패턴 (Tailwind + shadcn/ui)

방향에 구애받지 않는 논리적 컴포넌트. dir="rtl" 설정 후 flex/grid는 자동으로 미러링됩니다. 버그는 여기에 나열된 잔여물에 있습니다.

1. 유틸리티 변환 테이블 (암기하세요)

LTR 습관논리적 유틸리티 (항상 사용)
ml- / mr-ms- / me-
pl- / pr-ps- / pe-
left-0 / right-0start-0 / end-0
text-left / text-righttext-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 또는 flex gap-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"는 메뉴를 트리거의 오른쪽 가장자리 아래에 고정합니다; Select chevron은 ChevronDown이어야 합니다 (방향 없음, 변경 없음); InputOTP, CommandDialog, ResizablePanel은 수동 검토가 필요합니다.
  • 글꼴 토큰을 한 번 설정: Vazirmatn을 --font-sans(globals.css)에 넣어 모든 shadcn 컴포넌트가 상속하도록 합니다.

9. 감사 훅

rtl-audit 체크리스트를 통해 컴포넌트를 출시하세요 — 특히 아이콘 뒤집기, 변환 및 left/right 클래스를 확인합니다.

Individual skills in this repo

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

관련 스킬