18 KiB

Raw Permalink Blame History

shadcn/ui 디자인 시스템 적용 가이드

본 문서는 프로젝트에 shadcn/ui 디자인 시스템을 적용하기 위한 가이드입니다. 참고: shadcn/ui 공식 사이트

📋 목차

디자인 철학
색상 시스템
타이포그래피
컴포넌트 디자인 패턴
스페이싱 시스템
애니메이션
반응형 디자인
접근성
적용 방법

디자인 철학

핵심 원칙

Beautifully designed components: 아름답고 모던한 UI 컴포넌트 사용
Customizable & Extendable: 커스터마이징 가능하고 확장 가능한 구조
Open Source & Open Code: 오픈 소스 정신에 따른 투명한 코드

디자인 특징

✨ 미니멀하고 모던한 인터페이스
🎨 CSS 변수 기반의 테마 시스템
🌓 다크/라이트 모드 지원
♿ 접근성 우선 설계
📱 모바일 우선 반응형 디자인

색상 시스템

CSS 변수 기반 테마

프로젝트의 모든 색상은 CSS 변수로 관리하며, HSL 색상 포맷을 사용합니다.

라이트 모드

:root {
    /* 배경 및 전경색 */
    --background: 0 0% 100%;           /* 흰색 배경 */
    --foreground: 222.2 84% 4.9%;     /* 거의 검은색 텍스트 */
    
    /* 카드 */
    --card: 0 0% 100%;                /* 카드 배경 */
    --card-foreground: 222.2 84% 4.9%; /* 카드 텍스트 */
    
    /* 팝오버 */
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    
    /* 주요 색상 */
    --primary: 222.2 47.4% 11.2%;     /* 진한 파란색 */
    --primary-foreground: 210 40% 98%; /* 주요 버튼 텍스트 */
    
    /* 보조 색상 */
    --secondary: 210 40% 96.1%;       /* 연한 회색 */
    --secondary-foreground: 222.2 47.4% 11.2%;
    
    /* 음소거 색상 */
    --muted: 210 40% 96.1%;           /* 비활성 배경 */
    --muted-foreground: 215.4 16.3% 46.9%; /* 비활성 텍스트 */
    
    /* 강조 색상 */
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    
    /* 위험 색상 */
    --destructive: 0 84.2% 60.2%;     /* 빨간색 */
    --destructive-foreground: 210 40% 98%;
    
    /* 테두리 및 입력 */
    --border: 214.3 31.8% 91.4%;      /* 연한 회색 테두리 */
    --input: 214.3 31.8% 91.4%;       /* 입력 필드 테두리 */
    --ring: 222.2 84% 4.9%;           /* 포커스 링 */
    
    /* 모서리 둥글기 */
    --radius: 0.5rem;                  /* 8px */
}

다크 모드

.dark {
    --background: 222.2 84% 4.9%;     /* 거의 검은색 */
    --foreground: 210 40% 98%;        /* 흰색 텍스트 */
    
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    
    --primary: 210 40% 98%;           /* 밝은 색상 */
    --primary-foreground: 222.2 47.4% 11.2%;
    
    --secondary: 217.2 32.6% 17.5%;   /* 어두운 회색 */
    --secondary-foreground: 210 40% 98%;
    
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
}

색상 사용 방법

/* HSL 함수를 사용하여 CSS 변수 적용 */
.element {
    background: hsl(var(--primary));
    color: hsl(var(--primary-foreground));
}

/* 투명도 추가 */
.element-transparent {
    background: hsl(var(--primary) / 0.5); /* 50% 투명도 */
}

타이포그래피

폰트 패밀리

body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, 
                 "Helvetica Neue", Arial, sans-serif;
    font-feature-settings: "rlig" 1, "calt" 1;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
}

텍스트 크기 스케일

클래스	크기	줄 높이	사용처
`.text-xs`	0.75rem (12px)	1rem	작은 설명, 캡션
`.text-sm`	0.875rem (14px)	1.25rem	본문 보조 텍스트
`.text-base`	1rem (16px)	1.5rem	기본 본문
`.text-lg`	1.125rem (18px)	1.75rem	큰 본문
`.text-xl`	1.25rem (20px)	1.75rem	소제목
`.text-2xl`	1.5rem (24px)	2rem	중제목
`.text-3xl`	1.875rem (30px)	2.25rem	큰 제목
`.text-4xl`	2.25rem (36px)	2.5rem	메인 제목

폰트 가중치

.font-normal { font-weight: 400; }    /* 일반 텍스트 */
.font-medium { font-weight: 500; }    /* 약간 굵은 텍스트 */
.font-semibold { font-weight: 600; }  /* 중간 굵기 제목 */
.font-bold { font-weight: 700; }      /* 굵은 제목 */

컴포넌트 디자인 패턴

1. 카드 (Card)

기본 카드 스타일

.card {
    background: hsl(var(--card));
    color: hsl(var(--card-foreground));
    border-radius: var(--radius);
    border: 1px solid hsl(var(--border));
    padding: 1.5rem;
    box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
    transition: all 0.2s ease-in-out;
}

.card:hover {
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

사용 예시

<div class="card">
    <h3 class="text-lg font-semibold">카드 제목</h3>
    <p class="text-sm text-muted-foreground">카드 설명 텍스트</p>
</div>

2. 버튼 (Button)

버튼 기본 스타일

.btn {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    border-radius: var(--radius);
    font-size: 0.875rem;
    font-weight: 500;
    transition: all 0.15s ease-in-out;
    cursor: pointer;
    outline: none;
    border: none;
}

버튼 변형

/* Primary 버튼 */
.btn-primary {
    background: hsl(var(--primary));
    color: hsl(var(--primary-foreground));
    padding: 0.5rem 1rem;
}

.btn-primary:hover {
    background: hsl(var(--primary) / 0.9);
}

/* Secondary 버튼 */
.btn-secondary {
    background: hsl(var(--secondary));
    color: hsl(var(--secondary-foreground));
    padding: 0.5rem 1rem;
}

/* Outline 버튼 */
.btn-outline {
    border: 1px solid hsl(var(--border));
    background: transparent;
    padding: 0.5rem 1rem;
}

/* Ghost 버튼 */
.btn-ghost {
    background: transparent;
    color: hsl(var(--foreground));
    padding: 0.5rem 1rem;
}

.btn-ghost:hover {
    background: hsl(var(--accent));
}

버튼 크기

.btn-sm { 
    height: 2rem; 
    padding: 0 0.75rem; 
    font-size: 0.75rem; 
}

.btn-md { 
    height: 2.5rem; 
    padding: 0 1rem; 
}

.btn-lg { 
    height: 3rem; 
    padding: 0 2rem; 
    font-size: 1rem; 
}

사용 예시

<button class="btn btn-primary btn-md">저장</button>
<button class="btn btn-secondary btn-md">취소</button>
<button class="btn btn-outline btn-sm">편집</button>
<button class="btn btn-ghost">더보기</button>

3. 입력 필드 (Input)

입력 필드 스타일

.input {
    display: flex;
    height: 2.5rem;
    width: 100%;
    border-radius: var(--radius);
    border: 1px solid hsl(var(--input));
    background: hsl(var(--background));
    padding: 0.5rem 0.75rem;
    font-size: 0.875rem;
    transition: all 0.15s ease-in-out;
}

.input:focus {
    outline: none;
    border-color: hsl(var(--ring));
    box-shadow: 0 0 0 3px hsl(var(--ring) / 0.1);
}

.input:disabled {
    cursor: not-allowed;
    opacity: 0.5;
}

.input::placeholder {
    color: hsl(var(--muted-foreground));
}

사용 예시

<input type="text" class="input" placeholder="이름을 입력하세요">
<input type="email" class="input" placeholder="이메일" disabled>

4. 폼 그룹 (Form Group)

폼 그룹 스타일

.form-group {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
    margin-bottom: 1rem;
}

.form-label {
    font-size: 0.875rem;
    font-weight: 500;
    color: hsl(var(--foreground));
}

.form-description {
    font-size: 0.75rem;
    color: hsl(var(--muted-foreground));
}

.form-error {
    font-size: 0.75rem;
    color: hsl(var(--destructive));
}

사용 예시

<div class="form-group">
    <label class="form-label">이메일</label>
    <input type="email" class="input" placeholder="your@email.com">
    <span class="form-description">로그인에 사용할 이메일 주소입니다.</span>
</div>

<div class="form-group">
    <label class="form-label">비밀번호</label>
    <input type="password" class="input">
    <span class="form-error">비밀번호는 8자 이상이어야 합니다.</span>
</div>

스페이싱 시스템

간격 유틸리티 클래스

클래스	크기	픽셀	사용처
`.space-xs`	0.25rem	4px	매우 작은 간격
`.space-sm`	0.5rem	8px	작은 간격
`.space-md`	0.75rem	12px	중간 간격
`.space-lg`	1rem	16px	기본 간격
`.space-xl`	1.5rem	24px	큰 간격
`.space-2xl`	2rem	32px	매우 큰 간격
`.space-3xl`	3rem	48px	초대형 간격

.space-xs { gap: 0.25rem; }
.space-sm { gap: 0.5rem; }
.space-md { gap: 0.75rem; }
.space-lg { gap: 1rem; }
.space-xl { gap: 1.5rem; }
.space-2xl { gap: 2rem; }
.space-3xl { gap: 3rem; }

Border Radius (모서리 둥글기)

.rounded-none { border-radius: 0; }
.rounded-sm { border-radius: 0.25rem; }   /* 4px */
.rounded { border-radius: var(--radius); }  /* 8px (기본값) */
.rounded-md { border-radius: 0.5rem; }     /* 8px */
.rounded-lg { border-radius: 0.75rem; }    /* 12px */
.rounded-xl { border-radius: 1rem; }       /* 16px */
.rounded-full { border-radius: 9999px; }   /* 완전한 원형 */

애니메이션 및 트랜지션

기본 트랜지션

.transition-all {
    transition-property: all;
    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
    transition-duration: 150ms;
}

.transition-colors {
    transition-property: color, background-color, border-color;
    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
    transition-duration: 150ms;
}

페이드 인 애니메이션

@keyframes fadeIn {
    from { 
        opacity: 0; 
        transform: translateY(4px); 
    }
    to { 
        opacity: 1; 
        transform: translateY(0); 
    }
}

.animate-in {
    animation: fadeIn 200ms ease-out;
}

사용 예시

<div class="card transition-all">Hover me</div>
<div class="animate-in">Fade in content</div>

섀도우 시스템

그림자 레벨

.shadow-none { box-shadow: none; }
.shadow-sm { box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); }
.shadow { box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06); }
.shadow-md { box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06); }
.shadow-lg { box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05); }
.shadow-xl { box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04); }

사용 가이드

shadow-sm: 미묘한 깊이가 필요한 카드
shadow: 일반적인 카드 및 요소
shadow-md: 드롭다운, 메뉴
shadow-lg: 모달, 대화상자
shadow-xl: 팝업, 알림

레이아웃 패턴

Flexbox 유틸리티

.flex { display: flex; }
.flex-col { flex-direction: column; }
.items-center { align-items: center; }
.items-start { align-items: flex-start; }
.items-end { align-items: flex-end; }
.justify-center { justify-content: center; }
.justify-between { justify-content: space-between; }
.justify-end { justify-content: flex-end; }

.gap-2 { gap: 0.5rem; }
.gap-4 { gap: 1rem; }
.gap-6 { gap: 1.5rem; }

Grid 유틸리티

.grid { display: grid; }
.grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.grid-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }

사용 예시

<!-- Flexbox 레이아웃 -->
<div class="flex items-center justify-between gap-4">
    <span>제목</span>
    <button class="btn btn-primary">저장</button>
</div>

<!-- Grid 레이아웃 -->
<div class="grid grid-cols-3 gap-4">
    <div class="card">카드 1</div>
    <div class="card">카드 2</div>
    <div class="card">카드 3</div>
</div>

반응형 디자인

브레이크포인트

/* Mobile First 접근 방식 */
@media (min-width: 640px) {  /* sm: 태블릿 세로 */
    /* 스타일 */
}

@media (min-width: 768px) {  /* md: 태블릿 가로 */
    /* 스타일 */
}

@media (min-width: 1024px) { /* lg: 노트북 */
    /* 스타일 */
}

@media (min-width: 1280px) { /* xl: 데스크톱 */
    /* 스타일 */
}

@media (min-width: 1536px) { /* 2xl: 대형 데스크톱 */
    /* 스타일 */
}

반응형 그리드 예시

.responsive-grid {
    display: grid;
    grid-template-columns: 1fr;
    gap: 1rem;
}

@media (min-width: 640px) {
    .responsive-grid {
        grid-template-columns: repeat(2, 1fr);
    }
}

@media (min-width: 1024px) {
    .responsive-grid {
        grid-template-columns: repeat(3, 1fr);
    }
}

@media (min-width: 1280px) {
    .responsive-grid {
        grid-template-columns: repeat(4, 1fr);
    }
}

접근성 (Accessibility)

포커스 관리

*:focus-visible {
    outline: 2px solid hsl(var(--ring));
    outline-offset: 2px;
}

스크린 리더 전용 텍스트

.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border-width: 0;
}

접근성 체크리스트

✅ 모든 인터랙티브 요소는 키보드로 접근 가능
✅ 포커스 상태가 명확하게 표시됨
✅ 색상 대비가 WCAG AA 기준 이상
✅ 적절한 ARIA 레이블 사용
✅ 의미있는 HTML 요소 사용 (semantic HTML)

상태 표시

상태별 스타일

.state-loading {
    opacity: 0.6;
    cursor: wait;
}

.state-success {
    color: hsl(142.1 76.2% 36.3%);  /* 녹색 */
}

.state-error {
    color: hsl(var(--destructive));  /* 빨간색 */
}

.state-warning {
    color: hsl(48 96% 53%);  /* 노란색 */
}

적용 방법

1. CSS 변수 설정

css/common.css 파일에 CSS 변수를 추가합니다:

:root {
    /* 위에서 정의한 CSS 변수들 추가 */
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    /* ... 나머지 변수들 */
}

2. 컴포넌트 스타일 추가

css/components.css 파일에 컴포넌트 스타일을 추가합니다:

/* 버튼, 카드, 입력 필드 등 컴포넌트 스타일 */

3. HTML에서 사용

<!DOCTYPE html>
<html lang="ko">
<head>
    <link rel="stylesheet" href="css/common.css">
    <link rel="stylesheet" href="css/components.css">
</head>
<body>
    <div class="card">
        <h2 class="text-2xl font-bold">제목</h2>
        <p class="text-sm text-muted-foreground">설명</p>
        <button class="btn btn-primary">저장</button>
    </div>
</body>
</html>

사용 원칙

✅ DO (권장사항)

CSS 변수를 사용하여 색상 관리
일관된 스페이싱과 border-radius 사용
접근성을 고려한 마크업
모바일 우선 반응형 디자인
의미있는 클래스명 사용

❌ DON'T (피해야 할 것)

인라인 스타일 사용
하드코딩된 색상값
불필요한 !important 사용
키보드 접근이 불가능한 요소
색상에만 의존한 정보 전달

예제 컴포넌트

로그인 폼

<div class="card" style="max-width: 400px; margin: 2rem auto;">
    <h2 class="text-2xl font-bold mb-6">로그인</h2>
    
    <div class="form-group">
        <label class="form-label">이메일</label>
        <input type="email" class="input" placeholder="your@email.com">
    </div>
    
    <div class="form-group">
        <label class="form-label">비밀번호</label>
        <input type="password" class="input" placeholder="••••••••">
    </div>
    
    <div class="flex gap-2">
        <button class="btn btn-primary flex-1">로그인</button>
        <button class="btn btn-outline">취소</button>
    </div>
</div>

대시보드 카드 그리드

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    <div class="card">
        <h3 class="text-lg font-semibold">총 매출</h3>
        <p class="text-3xl font-bold mt-2">₩12,345,678</p>
        <span class="text-sm state-success">+12.5% 전월 대비</span>
    </div>
    
    <div class="card">
        <h3 class="text-lg font-semibold">신규 고객</h3>
        <p class="text-3xl font-bold mt-2">234</p>
        <span class="text-sm state-error">-5.2% 전월 대비</span>
    </div>
    
    <div class="card">
        <h3 class="text-lg font-semibold">주문 건수</h3>
        <p class="text-3xl font-bold mt-2">1,234</p>
        <span class="text-sm state-success">+8.1% 전월 대비</span>
    </div>
</div>

참고 자료

변경 이력

날짜	버전	변경 내용
2025-10-26	1.0	초기 문서 작성

18 KiB Raw Permalink Blame History

shadcn/ui 디자인 시스템 적용 가이드

📋 목차

디자인 철학

핵심 원칙

디자인 특징

색상 시스템

CSS 변수 기반 테마

라이트 모드

다크 모드

색상 사용 방법

타이포그래피

폰트 패밀리

텍스트 크기 스케일

폰트 가중치

컴포넌트 디자인 패턴

1. 카드 (Card)

기본 카드 스타일

사용 예시

2. 버튼 (Button)

버튼 기본 스타일

버튼 변형

버튼 크기

사용 예시

3. 입력 필드 (Input)

입력 필드 스타일

사용 예시

4. 폼 그룹 (Form Group)

폼 그룹 스타일

사용 예시

스페이싱 시스템

간격 유틸리티 클래스

Border Radius (모서리 둥글기)

애니메이션 및 트랜지션

기본 트랜지션

페이드 인 애니메이션

사용 예시

섀도우 시스템

그림자 레벨

사용 가이드

레이아웃 패턴

Flexbox 유틸리티

Grid 유틸리티

사용 예시

반응형 디자인

브레이크포인트

반응형 그리드 예시

접근성 (Accessibility)

포커스 관리

스크린 리더 전용 텍스트

접근성 체크리스트

상태 표시

상태별 스타일

적용 방법

1. CSS 변수 설정

2. 컴포넌트 스타일 추가

3. HTML에서 사용

사용 원칙

✅ DO (권장사항)

❌ DON'T (피해야 할 것)

예제 컴포넌트

로그인 폼

대시보드 카드 그리드

참고 자료

변경 이력

18 KiB

Raw Permalink Blame History