Skip to content

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

1. 색상 시스템

1.1 색 공간: OKLCH

모든 색상을 OKLCH (oklch(L C H)) 색 공간으로 정의한다.

  • L(Lightness): 0~1
  • C(Chroma): 채도
  • H(Hue): 색상각 0~360

OKLCH는 지각적으로 균일하여 다크모드 대응·톤 조절이 예측 가능하다.

1.2 브랜드 색상

값 라이트 다크
--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 기반 그라데이션

1.3 의미 토큰 (Semantic Tokens)

토큰 용도
--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에 토큰 추가 후 사용.

1.4 primary vs brand

  • primary: 중립 톤. 대부분의 기본 버튼·강조
  • brand: 서비스 아이덴티티가 드러나야 하는 곳 (로고 컬러, 핵심 CTA)
  • 둘을 구분해서 사용

2. 타이포그래피

2.1 폰트

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 폰트로 무게 조절 자유

2.2 텍스트 크기

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

2.3 기본 설정

html {
  @apply font-sans antialiased;
}

3. 간격·레이아웃

Tailwind 기본 spacing scale을 사용한다 (0.25rem 단위).

가이드:

  • 컴포넌트 내부 여백: p-4 ~ p-6
  • 컴포넌트 간 간격: gap-2 ~ gap-4
  • 페이지 여백: p-6 기본, 모바일 p-4

4. 라운딩 (Border Radius)

토큰 값 용도
--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 등으로 매핑.

5. 다크모드

5.1 구현 방식

.dark 클래스 기반 (Tailwind @custom-variant dark).

@custom-variant dark (&:is(.dark *));

<html> 요소에 .dark 클래스가 붙으면 다크 테마 적용.

5.2 테마 스토어

위치: 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 감지 + 변경 이벤트 구독

5.3 초기화

initTheme() 함수를 앱 진입 시점에 호출 (main.tsx 등).

5.4 사용 규칙

  • 색상은 토큰으로만 지정 → 다크모드 자동 대응됨
  • 특정 상황에서만 다크 스타일을 따로 지정할 땐 dark: prefix: dark:bg-neutral-900
  • 모든 신규 화면은 반드시 다크모드 동작 확인

6. 컴포넌트

6.1 shadcn/ui 기반

  • Style: base-nova
  • baseColor: neutral
  • CSS 변수 모드 (cssVariables: true)
  • Prefix: 없음
  • 위치: fe/src/components/ui/

6.2 설치된 컴포넌트 (2026-04-06 기준)

컴포넌트 경로
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 규칙 참조).

6.3 도메인 컴포넌트

  • features/{domain}/components/ — 도메인 특화
  • shared/components/ — 여러 모듈이 공유하는 범용 컴포넌트
  • shadcn 기본 컴포넌트를 조합해서 만든다

6.4 아이콘

lucide-react 사용.

import { LogOut, Moon, Sun, Timer } from "lucide-react";
  • 일관된 스타일·크기 조정 용이
  • 컴포넌트로 import (트리 쉐이킹)

7. 반응형

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 이상에서만 표시, 이하는 하단 탭 바

8. 접근성 (Accessibility)

  • 색상 대비: WCAG AA 이상 (일반 4.5:1, 큰 글씨 3:1)
  • 포커스 링: --ring 토큰 활용, focus-visible 스타일 필수
  • 키보드 네비게이션: Tab 순서 자연스럽게
  • 인터랙티브 요소는 최소 44×44px 터치 타겟

9. 참조

Clone this wiki locally