Repository navigation
Design System
wcorn edited this page Apr 5, 2026
·
1 revision
orino의 모든 FE 화면이 따르는 공통 디자인 시스템. 색상·타이포그래피·컴포넌트·다크모드 규칙을 정의한다.
- 기술 스택: Tailwind CSS 4.x + shadcn/ui (style:
base-nova, baseColor:neutral) + @base-ui/react - 폰트: Pretendard Variable
- 아이콘: lucide-react
- CSS 정의 위치:
fe/src/index.css - shadcn 설정:
fe/components.json
모든 색상을 OKLCH (oklch(L C H)) 색 공간으로 정의한다.
- L(Lightness): 0~1
- C(Chroma): 채도
- H(Hue): 색상각 0~360
OKLCH는 지각적으로 균일하여 다크모드 대응·톤 조절이 예측 가능하다.
| 값 | 라이트 | 다크 |
|---|---|---|
--brand |
oklch(0.55 0.25 297.5) |
oklch(0.68 0.22 297.5) |
--brand-foreground |
oklch(1 0 0) |
oklch(1 0 0) |
- Hue 297.5° (보라 계열, 대략 #8b00ff)
- 라이트에서는 선명하게(L=0.55), 다크에서는 밝게(L=0.68) 조정하여 대비 확보
- Chart 색상 세트(
--chart-1~5)는 brand hue 기반 그라데이션
| 토큰 | 용도 |
|---|---|
--background / --foreground
|
페이지 바탕·기본 텍스트 |
--card / --card-foreground
|
카드 배경·텍스트 |
--popover / --popover-foreground
|
팝오버·드롭다운 |
--primary / --primary-foreground
|
기본 액션 (중립 색, 버튼 primary) |
--secondary / --secondary-foreground
|
보조 액션 |
--muted / --muted-foreground
|
약한 배경·보조 텍스트 |
--accent / --accent-foreground
|
강조 배경 (호버·선택) |
--destructive |
파괴적 액션 (삭제·오류) |
--border, --input, --ring
|
테두리·입력·포커스 링 |
--brand / --brand-foreground
|
브랜드 강조 (CTA, 로고) |
--sidebar-* |
사이드바 전용 변수 세트 |
--chart-1 ~ --chart-5
|
차트·시각화 |
사용 원칙:
- Tailwind 클래스로 사용:
bg-background,text-foreground,bg-primary text-primary-foreground등 - 하드코딩된 hex 색상 사용 금지. 항상 토큰 참조.
- 새 의미 색상이 필요하면
index.css에 토큰 추가 후 사용.
-
primary: 중립 톤. 대부분의 기본 버튼·강조 -
brand: 서비스 아이덴티티가 드러나야 하는 곳 (로고 컬러, 핵심 CTA) - 둘을 구분해서 사용
Pretendard Variable 단일 패밀리 사용.
"Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont,
system-ui, Roboto, "Helvetica Neue", "Segoe UI", "Apple SD Gothic Neo",
"Noto Sans KR", "Malgun Gothic", sans-serif
- CSS 변수:
--font-sans,--font-heading(둘 다 Pretendard) - 한국어·영문 균형이 좋고 Variable 폰트로 무게 조절 자유
Tailwind 기본 scale 사용: text-xs (0.75rem) ~ text-9xl. 커스텀 scale 없음.
가이드:
- 페이지 제목:
text-2xl~text-4xl font-semibold - 섹션 제목:
text-lg~text-xl font-semibold - 본문:
text-sm~text-base - 보조 텍스트:
text-xs text-muted-foreground
html {
@apply font-sans antialiased;
}Tailwind 기본 spacing scale을 사용한다 (0.25rem 단위).
가이드:
- 컴포넌트 내부 여백:
p-4~p-6 - 컴포넌트 간 간격:
gap-2~gap-4 - 페이지 여백:
p-6기본, 모바일p-4
| 토큰 | 값 | 용도 |
|---|---|---|
--radius |
0.5rem |
기준값 |
--radius-sm |
--radius × 0.6 |
입력·배지 |
--radius-md |
--radius × 0.8 |
버튼 |
--radius-lg |
--radius |
카드 |
--radius-xl ~ --radius-4xl
|
1.4 ~ 2.6배 | 큰 카드·모달 |
Tailwind 클래스: rounded-sm, rounded-md, rounded-lg, rounded-xl 등으로 매핑.
.dark 클래스 기반 (Tailwind @custom-variant dark).
@custom-variant dark (&:is(.dark *));<html> 요소에 .dark 클래스가 붙으면 다크 테마 적용.
위치: fe/src/shared/lib/theme.ts
type Theme = "light" | "dark" | "system";
useThemeStore: {
theme: Theme;
setTheme: (theme: Theme) => void;
}-
3가지 모드:
light/dark/system(OS 따라감) - LocalStorage 키:
theme -
system모드는prefers-color-scheme감지 + 변경 이벤트 구독
initTheme() 함수를 앱 진입 시점에 호출 (main.tsx 등).
- 색상은 토큰으로만 지정 → 다크모드 자동 대응됨
- 특정 상황에서만 다크 스타일을 따로 지정할 땐
dark:prefix:dark:bg-neutral-900 - 모든 신규 화면은 반드시 다크모드 동작 확인
- Style:
base-nova - baseColor:
neutral - CSS 변수 모드 (
cssVariables: true) - Prefix: 없음
- 위치:
fe/src/components/ui/
| 컴포넌트 | 경로 |
|---|---|
| Button | components/ui/button.tsx |
| Card | components/ui/card.tsx |
| Input | components/ui/input.tsx |
| Label | components/ui/label.tsx |
신규 컴포넌트는 npx shadcn add {component} 명령어로 추가 (CLAUDE.md 규칙 참조).
-
features/{domain}/components/— 도메인 특화 -
shared/components/— 여러 모듈이 공유하는 범용 컴포넌트 - shadcn 기본 컴포넌트를 조합해서 만든다
lucide-react 사용.
import { LogOut, Moon, Sun, Timer } from "lucide-react";- 일관된 스타일·크기 조정 용이
- 컴포넌트로 import (트리 쉐이킹)
Tailwind 기본 breakpoint 사용.
| Breakpoint | Min Width | 용도 |
|---|---|---|
sm |
640px | 모바일 가로 |
md |
768px | 태블릿 |
lg |
1024px | 데스크탑 |
xl |
1280px | 큰 데스크탑 |
2xl |
1536px | 초대형 |
가이드:
- 모바일 우선(mobile-first) 설계
- 그리드 예:
grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 - 사이드바는
md이상에서만 표시, 이하는 하단 탭 바
- 색상 대비: WCAG AA 이상 (일반 4.5:1, 큰 글씨 3:1)
- 포커스 링:
--ring토큰 활용,focus-visible스타일 필수 - 키보드 네비게이션: Tab 순서 자연스럽게
- 인터랙티브 요소는 최소 44×44px 터치 타겟
- 코드:
-
fe/src/index.css— 토큰 정의 -
fe/components.json— shadcn 설정 -
fe/src/shared/lib/theme.ts— 테마 스토어
-
- 외부: