티쳐스온 디자인 시스템

모바일은 React Native + StyleSheet, 어드민은 Next.js + Tailwind. 1:1 미러 불가 — 상태 컬럼으로 일치도 표시.

기본 컴포넌트 (가이드 9·10·11)

레이아웃·정보 표시

Chip · Badge · 도메인 마이크로

모달·피커

플랫폼 특수 (양쪽 미러 불가)

1. 가이드 ↔ 코드 동시 변경 — 가이드만 고치고 코드 안 바꾸면 명세서가 거짓이 됨. 반대도 마찬가지.
2. 인라인 발견 시 컴포넌트로 승격 — 같은 className·StyleSheet 패턴이 2곳 이상에서 반복되면 추출 후 본 표에 등록.
3. ⚠ 항목은 작업 백로그 — "한쪽 인라인" 상태 행은 다음 디자인 마이그레이션 PR 의 후보. 상태 컬럼이 ✓ 또는 △ 가 될 때까지 추적.
4. 🌐 플랫폼 특수는 미러 시도 금지 — 본질적으로 다른 패러다임 (예: 휠 피커 vs 드롭다운) 은 억지로 통일하지 말 것. 같은 결과를 내는 다른 UI 로 처리.
5. 새 컴포넌트 추가 절차: 코드 작성 → 가이드 9.X 또는 해당 섹션 명세 추가 → 본 표에 행 추가. 셋이 한 PR.

각 색에 600 (hover/pressed) · 700 (강조 텍스트) 단계도 정의되어 있음. 위는 50/500 두 단계만 표시.

각 카테고리는 50/700 두 단계만 정의. Semantic 과 hex 가 절대 겹치지 않도록 분리됨 (프로그램=teal · 실시지원=orange · 교사연수=rose).

캘린더 그리드의 일·토 요일 시각 구분 전용 색. 캘린더 외 사용 금지 — Semantic / Category 와 의미가 다르다 (위험·주요액션·교육유형 의미가 아니라, 단순 "주말 표시" 의 시각 관행).

토큰: cal-sun-600 (#DC2626) · cal-sat-600 (#2563EB). 어드민 Tailwind config + 모바일 theme.colors 양쪽에 동일 hex 정의. 인라인 hex (text-red-600 / #E84040 등) 사용 금지.

강사 평점 표시 전용 황금 톤. 평점 자리 외 사용 금지 — warning 과 hex 가 비슷하지만 의미가 다르다 (경고 ≠ 평점). 별 ⭐ 아이콘 + 숫자 chip 한정.

어드민·모바일 양쪽에 동일 hex 정의. warning-50/700 과 hex 비슷해도 의미 분리 위해 별도 토큰 사용.

위계는 3 차원 (사이즈 + 굵기 + 색)으로 구성. 한 차원만 바꿔도 위계 표현 가능 — 다 강조하면 위계가 무너진다.

권장 조합

Tailwind 클래스 매핑 — 어드민 코드에서 사용

scale 외 사이즈 (12, 14) 가 필요하면 Tailwind 기본 text-xs (12px) / text-sm (14px) 사용. text-[XXpx] 임의값 금지.

Don't:
· 모든 텍스트에 font-semibold (600) 적용 — 위계 무너짐, "다 굵어 보임" (이게 가장 흔한 실수)
· 부제에 semibold/bold — 부제는 medium (500), 색으로 위계 (neutral-500)
· 한 카드에 굵은 텍스트 (700+) 3 개 이상 — 시선 분산. 주목 1~2 개로 제한
· caption (13) 사이즈에 700 이상 굵기 — 작고 굵으면 부담스러움. 600 까지
· body 15 + bold + neutral-900 다 한 번에 — 강조 너무 강함. 사이즈 ↑ 또는 색만 ↑ 중 하나로

사이즈: sm 32h · md 40h · lg 48h. 한 화면에 Primary 는 최대 1개 — 가장 중요한 액션만.

bg: neutral-0 · border: neutral-200 · radius: lg(16) · padding: 2xl(24) · shadow: card

scrim: scrim-modal (0.6) · content radius: lg · shadow: floating · max-width: 420 · padding: 2xl

어드민 코드에서 가이드 컴포넌트를 직접 사용. 인라인 className 반복 금지 (상세: § 10.7 액션 슬롯).

추가 컴포넌트 (Input · Toast 등) 는 추출 시점에 본 표 갱신.

페이지 위계: Page → Section → Sub-section → Card. 각 위계마다 정해진 세로 간격을 사용한다.

페이지 컨테이너 max-width: 1280px 가운데 정렬 권장. 그 이상 넓이는 가독성 저하.

Card 는 5 영역의 조합. 모두 옵션 — 필요한 것만 사용. 영역 사이는 24px (sp-2xl) 분리.

Card 변형 4종

Don't: Card 안에 또 Card 넣지 않기 — divider 로 영역 구분. Border 와 Shadow 둘 다 쓰는 게 기본 (Standard 변형).

Banner — 페이지·카드 상단의 정적 알림. Toast — 화면 우상단 일시 알림 (3초). Inline message — 인풋 아래 에러 등 흐름 안.

구조: padding 12px 16px · border-radius r-md(12) · border 1px neutral-200 (4면 균일) · 아이콘 + 텍스트 + 옵션 닫기.
의미는 bg 색 + 텍스트 색으로 전달. border 는 형태 분리용 neutral 톤 — 한 면만 강조하는 left-stripe 패턴 안 씀.

Read-only 정보를 의미 단위로 묶어서 표현. 한 그룹은 7~8개 필드 이내. 그룹마다 emoji + 헤더 + divider, 그 아래 Label-Value 가로 페어 list.

그룹 분리 원칙: 도메인 단위로 묶음. "공고 정보" / "학교 정보" / "강사 정보" / "정산 정보" 등. 한 그룹 7~8 필드 초과면 sub-그룹 또는 별도 카드로 분리.
Don't: 4-column field grid (deprecated · 공간 비효율) · Label/Value 같은 무게 (위계 무너짐) · 한 그룹에 10+ 필드 (스캔 어려움) · 메모를 본 그룹 밖 별도 카드로 (그룹 안 collapsible 권장).

데이터가 없거나·로딩 중이거나·실패한 상태. 화면이 비어 보이지 않도록 명시적 처리.

Don't: "데이터 없음" 만 적기 (다음 액션 제시 필요) · 무한 회전 스피너 (스켈레톤 권장) · Stack trace 그대로 노출.

입력이 필요한 화면 (등록·수정·설정) 의 표준 패턴. Form Field · Form Section · Required marker · Inline validation 4가지를 일관되게 적용.

구성 사양

📱 모바일은 OptionGroup 칩으로 대체: RN 에서 네모 체크박스는 손가락 hit 영역 작아 칩 패러다임 사용 (FormFields::OptionGroup · MultiOptionGroup). 같은 의미 (다중 선택) 를 어드민은 ☑, 모바일은 활성 chip 으로 표현. § 0.1 매핑 표 △ (UX 차이) 분류.

검증 시점

Don't:
· Label 없이 placeholder 만 — 입력 시 라벨 사라져 사용성·접근성 저하
· Inline label (라벨이 input 좌측에) — 모바일·반응형에서 깨짐. 위쪽 stack 권장
· 필수 항목인데 * 표시 없음 — 사용자가 어떤 게 필수인지 모름
· helper text 와 error 둘 다 빨간색 — 구분 안 됨. helper 는 neutral, error 만 danger
· 폼 전체 에러 toast 만 — 어떤 필드가 문제인지 모름. 인라인 + 토스트 병행
· Submit 버튼이 회색 (Secondary) — Primary 가 명확해야 함

적용 자리: AllowanceAddModal 금액, ObserverManageModal 참관비, CreatePostScreen 페이 입력 (1차시·연강·공강), 향후 모든 금액 입력. 컴포넌트는 FormFields::MoneyInput primitive 와 WonInputField (라벨 동반 wrapper).

날짜 입력은 Calendar Modal Trigger 패턴 사용. 텍스트 표시 + 📅 아이콘 → 클릭 시 캘린더 모달이 열려 날짜 선택. 잘못된 날짜 입력 불가능.

적용 자리: CreatePostScreen 강의일 (이미 사용 중), 향후 생년월일·일정 입력 등 모든 날짜 자리. 컴포넌트는 CalendarModal + 트리거 버튼 (DateInputField 추출 예정).

연락처는 마스킹 자동 패턴 사용. 사용자는 11자리 숫자만 입력 → 자동으로 010-1234-5678 형태로 표시·저장. 폼 안에서 다른 텍스트 input 과 시각 통일.

적용 자리: SignUp 연락처, MyInfoScreen 본인 연락처, InstructorProfileScreen 강사 연락처 입력, 향후 모든 휴대폰 번호 입력. 컴포넌트는 FormFields::PhoneInput primitive + PhoneInputField (라벨 동반 wrapper).

페이지·카드·모달 어디든 "액션 영역" 은 동일한 룰을 따른다. 위치(컨테이너)는 슬롯마다 다르지만, 내부 레이아웃·정렬 우선순위·오버플로 규칙은 5자리 모두 동일. 슬롯마다 따로 결정하면 정합성이 깨진다.

5 자리 인벤토리

내부 레이아웃 — 5 자리 공통

flex items-center gap-2

단일 액션  → 그대로
주요 + 보조 1쌍 → [Secondary] [Primary]   (Primary 가 오른쪽 끝)
3개 이상       → … 드롭다운 메뉴로 묶음
destructive 포함 → 다른 액션과 거리 (gap-3) 또는 별도 그룹

버튼 사이즈 — 슬롯별 매핑

오버플로 — 좌측·우측 분담

• 좌측 title 영역: flex-1 min-w-0 + 길면 truncate
• 우측 액션 영역: flex-shrink-0 + whitespace-nowrap (절대 줄바꿈 금지)
• 모바일 좁아질 때: ② ③ 만 wrap 허용. ① ④ ⑤ 는 wrap 금지 — 페이지·모달 헤더는 깔끔 유지

컴포넌트 매핑 — 인라인 className 금지

모든 액션 버튼은 @/components/ui/Button 사용. 인라인 className 으로 버튼 스타일 새로 작성하지 말 것 — 사이즈·variant 흩어짐의 시작.

Don't (전체 룰: § 운영 룰)

• 한 슬롯에 같은 variant 2개 (Primary 둘 두지 말 것 — 결정점 흐려짐)
• 액션 4개 이상 — 드롭다운 강제. 4개 모두 펴두지 말 것
• destructive 를 Primary 위치 (오른쪽 끝) 에 두기 — 실수 유발
• Cancel 류 ghost 버튼을 우측 끝 — Primary 가 가장 오른쪽이어야 액션 무게 일관
• 인라인 className="bg-... border-... rounded-..." 로 가이드 Button 외관만 흉내 — 외관 유사해도 사이즈·variant 시스템 안 따름

/posts·/instructors·/schedule·/education-schedule·/posts/complete-batch·/hq-users 등 모든 리스트 페이지가 따르는 공통 룰. 페이지마다 다르게 결정하면 사용자 학습 비용 누적. 본 명세는 어드민 코드 (components/ui/FilterToolbar.tsx, components/Pagination.tsx, lib/pagination.ts) 의 실제 구현과 일치한다.

B 패턴 (Notion DB · Vercel Dashboard 영감) — 필터 칩 누적식 + "+필터 추가" popover + 우측 검색 + 표 하단 페이지네이션. 옛 패턴 (FilterBar form + 표 위 페이지네이션) 은 deprecated.

기본 레이아웃 — 위에서 아래로

① PageHeader        제목 + 우측 액션 (예: + 새 항목)
② FilterToolbar     [필터 칩들] [+필터 추가] ...flex-1... [검색 input]
③ DataTable         실제 데이터
④ Pagination        표 하단 — [범위·총합] [페이지 번호] [페이지당 토글]

FilterToolbar — 검색·필터 통합 row

옛 FilterBar (form 래퍼 + select 들) 를 대체하는 클라이언트 컴포넌트. 각 필터 차원을 칩으로 표현하고 popover 로 값을 바꾼다.

• 필터 칩 — 적용 중인 필터만 표시. 칩 클릭 시 값 popover (radio 선택). × 버튼으로 제거
• +필터 추가 popover — 점선 border 버튼. 클릭 시 차원 목록 popover (검색 가능, 그룹 헤딩 "필터 차원" / "빠른 필터"). 이미 적용된 차원은 비활성
• 검색 input — 우측 (flex-1 으로 밀어냄), w-56 h-8, 🔍 아이콘. placeholder 에 검색 범위 명시 ("학교·지역 검색")
• 검색 동작 — 300ms debounce 후 URL ?q= 자동 반영. 별도 제출 버튼 없음 (Enter 도 불필요)
• URL 동기화 — 모든 필터 변경 시 router.replace(`?${...}`). useTransition 으로 부드러운 전환. ?page= 는 필터/검색 변경 시 항상 제거
• 차원 정의 — FilterDimension[] (key · label · icon · desc · values[]). values 는 single-select. optgroup 으로 묶기 가능 (예: '내 담당' / '다른 담당자')

필터 차원 표준 — 페이지별 매핑

페이지 사이즈 — 표준 (유지)

Pagination — 표 하단 통일 (좌·중·우 3분할)

위치: DataTable 다음 줄, 표 하단 중앙. 검색·필터 영역과 분리 — 같은 row 에 섞지 않는다.

• 좌 — 범위·총합 (1–20 / 163건). 굵게 강조된 범위 + 회색 총합
• 중 — 페이지 번호 ‹ 1 2 3 … 9 ›. 7페이지 이하면 그대로 다 표시, 초과면 양 끝 + 현재 주변만 (pageRange() 헬퍼)
• 현재 페이지 = bg-neutral-900 text-neutral-0 굵게. 비활성 = text-neutral-300
• 우 — 페이지당 토글 (20 / 50 / 100). 활성 = bg-neutral-900 text-neutral-0
• 현재 페이지가 총 페이지 초과 시 자동 보정 (clampPage())
• 빈 결과 (total === 0) 시: Pagination 자체 비표시 (return null). DataTable empty row 가 안내
• 1 페이지뿐이면 (max ≤ 1) 중앙 번호 영역 비움 — 좌측 카운트 + 우측 페이지당 토글만

두 가지 Pagination — URL 기반 vs 클라이언트 상태

Don't (전체 룰: § 운영 룰)

• 옛 FilterBar, FilterChip, FilterChipGroup 사용 — 삭제된 컴포넌트. 새 페이지는 FilterToolbar
• Pagination 을 표 위에 두기 — 검색·필터 영역과 시각 충돌. 표 하단 통일
• 검색·필터·페이지네이션을 한 row 에 섞기 — 시각 noise. 검색·필터 row 와 페이지네이션 row 분리
• 페이지 사이즈를 [20, 50, 100] 외로 (예: 25, 30, 200)
• 무한 스크롤로 갈아 끼우기 — 어드민은 비교·운영 화면이라 페이지 단위. 모바일은 FlatList(무한) 별개
• 검색에 별도 제출 버튼 ("검색" / Enter) 강요 — 300ms debounce 자동 검색이 표준 (URL 동기화는 코드 안에서 처리)
• 필터 칩에 적용되지 않은 차원도 다 노출 — 칩은 "적용 중" 만 표시. 추가는 "+필터 추가" popover
• FilterToolbar / Pagination 위치 페이지마다 다르게 — 사용자 학습 비용

Modal (9. 컴포넌트) 의 변형 — 사용자 확인이 필요한 경우만 사용. 일반 폼·복잡한 UI 는 Modal 을 그대로 쓰고, "정말 하시겠어요?" 류는 Alert.

구조: 아이콘(40px, 토큰 색) + 제목(cardTitle) + 설명(body neutral-700, 2~3줄) + Cancel + Primary (우측 정렬, gap 8). max-width 420px.
Don't: Cancel 을 Primary 색으로 (실수 유발) · 5+ 줄 설명 (대신 Modal 사용) · 자동 dismiss (Alert 는 항상 명시적 액션 필요).

"여기에 안 본 게 있어요" 를 알리는 시각 마커. 3 종.

위치 룰: 아이콘 위 → 우상단 / 메뉴 항목 옆 → 우측 / 탭바 아이콘 위 → 우상단.
Don't: 모든 항목에 Dot (신호 가치 사라짐) · 다양한 색 사용 (warning/info dot 등 — 한 의미로 통일) · 큰 dot 으로 시각 압도.

알림 카테고리 후보

도입 시 결정 항목

• 채널: Expo Push → APNs (iOS) / FCM (Android)
• 권한 요청 시점: 회원가입 직후 vs 첫 알림 발송 직전
• 알림음·진동: 카테고리별 차등 (중요만 진동) vs 일률
• 페이로드 구조: title / body / data (postId, type, etc.)
• 앱 내 노티 센터 연동: Push 도착 시 앱 내 Badge·Dot 동시 갱신
• 읽음 처리: 알림 탭 → Badge dismiss + paid_at 같은 read flag 갱신
• 설정 화면: 사용자가 카테고리별 on/off 가능

참고: 11.2 의 Badge/Dot 은 Push 와 무관하게 앱 내에서 작동. Push 도입 후엔 두 시스템이 서로 동기화 (push 도착 → in-app dot 켜짐).

Alert (11.1) 의 multi-option 변형. 3개 이상 옵션 중 하나 선택이 필요할 때만 사용. RN Alert.alert 의 OS 기본 multi-button 알럿을 브랜드 톤으로 대체. 옵션이 2개 이하면 Alert (11.1) 의 [Cancel] [Primary] 패턴이 더 자연스럽다 — ActionSheet 는 진짜 옵션 분기일 때만.

아이콘 미사용: Alert 와 달리 ActionSheet 는 아이콘 없음. 옵션 종류라 정보·경고·위험 톤이 의미 없고, 옵션 시각이 우선이라 단순화.
Don't: 옵션 5개 이상 (드롭다운 메뉴 사용) · 옵션끼리 시각 위계 다르게 (모두 동등 옵션) · destructive 를 우측 끝 (실수 유발 — 옵션 위치는 의미 없으므로 destructive 는 마지막 또는 별도 표시).

룰: 작은 아이콘이라도 패딩으로 감싸 최소 44, 권장 48 의 탭 영역을 확보. 32 이하는 사용 금지.

모든 화면 컨테이너는 SafeAreaView 또는 useSafeAreaInsets 를 사용. 상단·하단 시스템 영역 침범 금지.

모바일 모든 화면 하단의 표준 탭바. 좌·우·아래 띄워 둥근 알약 모양으로 배치 — 콘텐츠 위에 떠 있는 형태.

Don't: 화면 하단에 직사각형 (전체 폭) 으로 붙이지 말 것 — 우리 앱 표준은 떠있는 알약. borderTopWidth 사용 금지 (그림자로 분리).

Android 그림자 주의: Android 일부 디바이스에서 음수 offset (위쪽 그림자) 이 잘릴 수 있음 — `elevation` prop 보강 또는 `BlurView` 대안.

채팅 화면 (말풍선·읽음 라인·system 메시지·tooltip 카드) 은 본 가이드의 일반 패턴과 시각 언어가 다름. 별도 도메인 문서 (docs/chat-design.md) 로 분리.

단, "읽음" 표시 색은 본 가이드 토큰과 hex 가 같지만 의미가 다르므로 (warning ≠ 읽음), 도메인 전용 토큰 1개를 본 가이드 § 1 에 등록 — chat-read.

말풍선·tooltip·system message 등 나머지 채팅 토큰은 docs/chat-design.md 참조.

본문 4.5:1 이상 · 큰 글자 (18pt+ or 14pt bold) 3:1 이상 · UI 컴포넌트·아이콘 3:1 이상.

신규 토큰 추가 시 WebAIM Contrast Checker 로 검증 후 본 표 갱신.

• 모든 인터랙티브 요소 (button·link·input·select) Tab focusable
• Tab 순서 = 시각 흐름 (좌→우, 상→하). DOM 순서 = 시각 순서 유지 (CSS order·flex-direction reverse 신중)
• 모달 안 focus trap — 첫 Tab 이 모달 첫 요소, 마지막 Tab 이 모달 첫 요소로 순환
• Esc 로 모달 닫기 + focus 복귀 (트리거 button 으로)
• Enter/Space 로 button 활성화 (native button 사용 시 자동)

focus:outline-none 단독 사용 금지. 반드시 시각 대체 (ring·shadow·border) 동반.

Don't: outline:none + 대체 없음. 키보드 사용자가 현재 위치 모름.

색만으로 의미 전달 금지. 텍스트 라벨·아이콘·패턴 병행 필수.

• color: red 만으로 에러 표시 — 텍스트·아이콘 병행
• outline:none 단독 + 대체 없음 — 키보드 사용자 위치 상실
• 모달에 role="dialog" 없음 — 스크린리더 컨텍스트 미인식
• 아이콘 단독 button 에 aria-label 없음 — 스크린리더는 빈 button 으로 인식
• 토큰 추가 시 색 대비 검증 누락 — § 15.1 표 갱신 필수

lucide-react 채택. 1,000+ 아이콘 · 1.5px stroke · 24×24 grid · MIT · Tree-shakable. RN 은 lucide-react-native.

Don't: 18, 22, 28 같은 임의 값 — 4 단계 외 사용 금지. 디자이너 제공 SVG 도 토큰 사이즈로 export.

기본 currentColor (텍스트 색 따라감) 사용. 의미 강조 시에만 v2 토큰 명시.

코드에 박혀있는 이모지·텍스트 기호 → lucide 컴포넌트 교체 매핑.

• 이모지 (🔒/⚠/✓) 직접 사용 — 플랫폼별 렌더 다름·다국어 부적절·접근성 약함
• 텍스트 화살표 (←/→) 직접 사용 — 폰트별 모양 다름. ChevronLeft 등 사용
• 임의 사이즈 (18, 22, 28) — 4 단계 토큰만
• 색 직접 박기 — currentColor 또는 v2 토큰만
• 아이콘 단독 button 에 aria-label 누락 — § 15.4 강제

"취소"/"닫기"/"뒤로"/"확인" 혼용 금지. 다음 표대로 통일.

구체 동사 우선: "확인" 대신 "삭제"·"저장"·"제출" 같이 결과를 명시. 사용자가 "확인" 누른 다음 무엇이 일어날지 모르면 안 됨.

비어있는 자리에는 현재 상태 + 다음 행동 힌트 두 줄. "—" 만 쓰지 말 것.

금지: "에러 발생" / "실패했습니다" / "Unknown error" 같은 무의미 메시지. 항상 왜 + 무엇 명시.

• "~해요" 체 기본 (격식 ↓ 친근 ↑) — 토스·당근 표준
• 완료 → 과거형 "됐어요" (현재완료 어색)
• 오류 → 현재형 "안 돼요" / "못 해요"
• 금지: "~하십시오" (군대 톤) · "~합니다" (격식 과함) · "~함" (반말)

• "확인" 만으로 끝나는 confirm 버튼 — 결과 동사 (삭제·저장·제출) 명시
• "취소"/"닫기"/"뒤로" 자리별 룰 무시 — § 17.2 표 따름
• Empty state 에 "—" 만 표시 — 현재 상태 + 다음 행동 힌트 동반
• "에러 발생" 같은 무의미 에러 — 왜 + 무엇 명시
• 한 화면에 "~해요" 와 "~합니다" 혼용 — 한 톤으로 통일

신규 핵심 결정 (토큰 이름·구조 변경, 새 컴포넌트 추출 기준 등) 은 ADR 추가. 형식:

• 상태: Proposed / Accepted / Superseded by ADR-N
• 결정: 한 줄 요약
• 맥락: 왜 결정 필요했나 (배경)
• 근거: 왜 이 선택인가 (장점·트레이드오프)
• 대안: 검토했지만 채택 안 한 옵션
• 벤치마크: 외부 시스템 비교 (Material·Polaris·HIG·토스 등)

참고: ADR 패턴은 Michael Nygard 의 ADR template 따름. 소프트웨어 아키텍처 문서 표준.