# UI Design System — Warm Humanist

> **AI 도구를 위한 참고 문서입니다.** 이 파일에 정의된 토큰과 컴포넌트를 프로젝트에 그대로 적용할 수 있습니다.

---

## 철학 (Philosophy)

따뜻한 색채와 인간적인 타이포그래피로 사용자에게 친근하고 편안한 경험을 제공합니다.
형식적인 엄격함 대신 유기적인 리듬과 여유로운 공백을 사용합니다.

| 원칙 | 설명 |
|------|------|
| **Warmth first** | 모든 디자인 결정은 임상적이지 않고 환영받는 느낌을 주어야 합니다 |
| **Generous spacing** | 여백은 배려와 명확성을 전달합니다 |
| **Organic rhythm** | 크기와 무게의 미세한 변화가 자연스러운 흐름을 만듭니다 |
| **Accessible contrast** | 모든 텍스트는 WCAG AA 최소 4.5:1을 충족합니다 |
| **Human-scale type** | 폰트 선택은 기술보다 인간성을 우선합니다 |
| **Soft structure** | 구조는 존재하지만 강요되지 않습니다 |
| **Tactile feel** | 그림자와 둥근 모서리가 물리적 인터페이스의 느낌을 제공합니다 |

---

## 색상 시스템 (Color System)

### Design Tokens

| Token | Light | Dark | Description |
|-------|-------|------|-------------|
| `--color-bg` | `#faf6f0` | `#1c1410` | 따뜻한 크림 / 깊은 다크 브라운 |
| `--color-surface` | `#ffffff` | `#2a1f16` | 카드 및 패널 표면 |
| `--color-surface-raised` | `#fff9f4` | `#332519` | 상위 레이어 표면 |
| `--color-text` | `#2d1f0e` | `#f0e8dc` | 기본 텍스트 |
| `--color-text-muted` | `#8a6a4a` | `#c4a882` | 보조 텍스트 |
| `--color-border` | `#e8d8c4` | `#4a3728` | 구분선 및 테두리 |
| `--color-border-focus` | `#c96a2a` | `#e07f40` | 포커스 링 |
| `--color-point` | `#c96a2a` | `#e07f40` | Terracotta 강조색 |
| `--color-point-light` | `#f5e6d8` | `#3d2415` | 강조색 배경 틴트 |
| `--color-point-dark` | `#a85420` | `#c96a2a` | 강조색 호버 |
| `--color-overlay` | `rgba(45,31,14,0.5)` | `rgba(0,0,0,0.6)` | 모달 오버레이 |

### Color CSS

```css
:root {
  --color-bg:            #faf6f0;
  --color-surface:       #ffffff;
  --color-surface-raised:#fff9f4;
  --color-text:          #2d1f0e;
  --color-text-muted:    #8a6a4a;
  --color-border:        #e8d8c4;
  --color-border-focus:  #c96a2a;
  --color-point:         #c96a2a;
  --color-point-light:   #f5e6d8;
  --color-point-dark:    #a85420;
  --color-overlay:       rgba(45, 31, 14, 0.5);
}

.dark {
  --color-bg:            #1c1410;
  --color-surface:       #2a1f16;
  --color-surface-raised:#332519;
  --color-text:          #f0e8dc;
  --color-text-muted:    #c4a882;
  --color-border:        #4a3728;
  --color-border-focus:  #e07f40;
  --color-point:         #e07f40;
  --color-point-light:   #3d2415;
  --color-point-dark:    #c96a2a;
  --color-overlay:       rgba(0, 0, 0, 0.6);
}
```

### Usage Rules

- `--color-point` (terracotta): 호버, 포커스 링, 활성 상태, 레이블
- 박스 섀도우 허용: `0 1px 4px rgba(45, 31, 14, 0.08)` — 카드 elevation
- Border-radius: 카드와 버튼에 6px, 배지에 full-pill (9999px)

### 접근성 대비비 (Accessibility Contrast)

| 조합 | 비율 | WCAG |
|------|------|------|
| `--color-text` on `--color-bg` | 11.2:1 | AAA |
| `--color-text` on `--color-surface` | 12.1:1 | AAA |
| `--color-text-muted` on `--color-bg` | 4.8:1 | AA |
| `--color-point` on `--color-bg` | 4.6:1 | AA |
| `#fff` on `--color-point` | 4.9:1 | AA |
| `--color-text` (dark) on `--color-bg` (dark) | 10.3:1 | AAA |

---

## 타이포그래피 (Typography)

### 폰트 스택

- **Heading:** Noto Serif KR (Google Fonts) — 한글 지원 인문주의 세리프, 따뜻하고 품격 있는 서체
- **Body:** Noto Sans KR (Google Fonts) — 한글 지원 서체, 가독성 높고 친근한 sans-serif

```html
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Noto+Serif+KR:wght@400;600&family=Noto+Sans+KR:wght@400;600;700&display=swap"
  rel="stylesheet"
/>
```

### 폰트 CSS 변수

```css
:root {
  --font-heading: 'Noto Serif KR', 'Nanum Myeongjo', Georgia, serif;
  --font-body:    'Noto Sans KR', 'Nanum Gothic', system-ui, sans-serif;
  --font-mono:    'JetBrains Mono', 'Fira Code', monospace;
}
```

### 타입 스케일

| Role | Size | Weight | Line Height | Letter Spacing |
|------|------|--------|-------------|----------------|
| Display | 3rem | 700 | 1.05 | -0.01em |
| H1 | 2rem | 700 | 1.15 | -0.01em |
| H2 | 1.5rem | 600 | 1.2 | 0 |
| H3 | 1.25rem | 600 | 1.3 | 0 |
| Body | 1rem | 400 | 1.7 | 0 |
| Body Bold | 1rem | 700 | 1.7 | 0 |
| Caption | 0.75rem | 400 | 1.5 | 0 |
| Kicker | 0.6875rem | 600 | 1 | 0.15em |

### 타이포그래피 CSS

```css
/* Base */
body {
  font-family: var(--font-body);
  font-size: 1rem;
  line-height: 1.7;
  color: var(--color-text);
  background: var(--color-bg);
}

/* Headings */
h1, h2, h3, h4 {
  font-family: var(--font-heading);
  color: var(--color-text);
  line-height: 1.2;
  margin-top: 0;
}

h1 { font-size: 2rem;   font-weight: 700; letter-spacing: -0.01em; }
h2 { font-size: 1.5rem; font-weight: 600; }
h3 { font-size: 1.25rem; font-weight: 600; }

/* Display */
.display {
  font-family: var(--font-heading);
  font-size: clamp(2.25rem, 5vw, 3rem);
  font-weight: 700;
  line-height: 1.05;
  letter-spacing: -0.01em;
}

/* Kicker — section labels, eyebrows */
.kicker {
  font-family: var(--font-body);
  font-size: 0.6875rem;
  font-weight: 600;
  line-height: 1;
  letter-spacing: 0.15em;
  text-transform: uppercase;
  color: var(--color-point);
}

/* Body text */
p { margin-top: 0; margin-bottom: 1rem; }
p:last-child { margin-bottom: 0; }

/* Italic accent */
em, .italic-accent {
  font-style: italic;
  font-family: var(--font-heading);
}

/* Prose */
.prose {
  max-width: 65ch;
  line-height: 1.75;
}
.prose h2 { margin-top: 2.5rem; }
.prose p + p { margin-top: 0.75rem; }
```

---

## 간격 시스템 (Spacing System)

기본 단위: 4px (0.25rem). 4px 배수를 사용합니다.

```css
:root {
  --space-1:  0.25rem;  /* 4px */
  --space-2:  0.5rem;   /* 8px */
  --space-3:  0.75rem;  /* 12px */
  --space-4:  1rem;     /* 16px */
  --space-5:  1.25rem;  /* 20px */
  --space-6:  1.5rem;   /* 24px */
  --space-8:  2rem;     /* 32px */
  --space-10: 2.5rem;   /* 40px */
  --space-12: 3rem;     /* 48px */
  --space-16: 4rem;     /* 64px */
  --space-20: 5rem;     /* 80px */
  --space-24: 6rem;     /* 96px */
}
```

---

## 경계 시스템 (Border & Radius)

```css
:root {
  --radius-sm:   4px;
  --radius-md:   6px;
  --radius-lg:   12px;
  --radius-full: 9999px;
  --border-width: 1px;
  --shadow-card: 0 1px 4px rgba(45, 31, 14, 0.08);
  --shadow-raised: 0 4px 16px rgba(45, 31, 14, 0.12);
  --shadow-focus: 0 0 0 3px rgba(201, 106, 42, 0.25);
}
```

---

## 레이아웃 시스템 (Layout System)

### 컨테이너

```css
.container {
  width: 100%;
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: clamp(1rem, 4vw, 3rem);
}

.container-narrow {
  max-width: 760px;
  margin-inline: auto;
  padding-inline: clamp(1rem, 4vw, 2rem);
}
```

### 그리드

```css
.grid {
  display: grid;
  gap: var(--space-6);
}

.grid-2 { grid-template-columns: repeat(2, 1fr); }
.grid-3 { grid-template-columns: repeat(3, 1fr); }
.grid-auto {
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
}

@media (max-width: 768px) {
  .grid-2,
  .grid-3 { grid-template-columns: 1fr; }
}
```

### 섹션

```css
.section {
  padding-block: var(--space-16);
}

.section-sm {
  padding-block: var(--space-8);
}
```

---

## 컴포넌트 (Components)

### Card

```html
<article class="card">
  <p class="kicker">카테고리</p>
  <h3 class="card-title">카드 제목</h3>
  <p class="card-body">카드 내용입니다. 친근하고 읽기 편한 텍스트 스타일을 사용합니다.</p>
  <a href="#" class="card-link">더 보기 →</a>
</article>
```

```css
.card {
  background: var(--color-surface);
  border: var(--border-width) solid var(--color-border);
  border-radius: var(--radius-md);
  padding: var(--space-6);
  box-shadow: var(--shadow-card);
  transition: box-shadow 0.2s ease, transform 0.2s ease;
}

.card:hover {
  box-shadow: var(--shadow-raised);
  transform: translateY(-2px);
}

.card-title {
  font-family: var(--font-heading);
  font-size: 1.125rem;
  font-weight: 600;
  margin-top: var(--space-2);
  margin-bottom: var(--space-2);
}

.card-body {
  color: var(--color-text-muted);
  font-size: 0.9375rem;
  line-height: 1.65;
  margin-bottom: var(--space-4);
}

.card-link {
  font-size: 0.875rem;
  font-weight: 600;
  color: var(--color-point);
  text-decoration: none;
}
.card-link:hover {
  text-decoration: underline;
}
```

---

### Button

```html
<!-- Primary -->
<button class="btn btn-primary">확인</button>

<!-- Secondary -->
<button class="btn btn-secondary">취소</button>

<!-- Ghost -->
<button class="btn btn-ghost">더보기</button>
```

```css
.btn {
  display: inline-flex;
  align-items: center;
  gap: var(--space-2);
  padding: 0.625rem 1.25rem;
  font-family: var(--font-body);
  font-size: 0.9375rem;
  font-weight: 700;
  line-height: 1;
  border-radius: var(--radius-md);
  border: var(--border-width) solid transparent;
  cursor: pointer;
  transition: background 0.15s ease, color 0.15s ease, box-shadow 0.15s ease;
  text-decoration: none;
}

.btn:focus-visible {
  outline: none;
  box-shadow: var(--shadow-focus);
}

/* Primary */
.btn-primary {
  background: var(--color-point);
  color: #ffffff;
  border-color: var(--color-point);
}
.btn-primary:hover {
  background: var(--color-point-dark);
  border-color: var(--color-point-dark);
}

/* Secondary */
.btn-secondary {
  background: transparent;
  color: var(--color-text);
  border-color: var(--color-border);
}
.btn-secondary:hover {
  border-color: var(--color-point);
  color: var(--color-point);
}

/* Ghost */
.btn-ghost {
  background: transparent;
  color: var(--color-point);
  border-color: transparent;
}
.btn-ghost:hover {
  background: var(--color-point-light);
}

/* Sizes */
.btn-sm {
  padding: 0.4rem 0.875rem;
  font-size: 0.8125rem;
}

.btn-lg {
  padding: 0.875rem 1.75rem;
  font-size: 1.0625rem;
}
```

---

### Badge / Tag

```html
<span class="badge">추천</span>
<span class="badge badge-muted">임시</span>
<span class="tag">디자인</span>
```

```css
.badge {
  display: inline-flex;
  align-items: center;
  padding: 0.2em 0.75em;
  font-family: var(--font-body);
  font-size: 0.6875rem;
  font-weight: 700;
  letter-spacing: 0.06em;
  text-transform: uppercase;
  border-radius: var(--radius-full);
  background: var(--color-point-light);
  color: var(--color-point-dark);
}

.badge-muted {
  background: transparent;
  color: var(--color-text-muted);
  border: 1px solid var(--color-border);
}

.tag {
  display: inline-flex;
  align-items: center;
  padding: 0.25em 0.625em;
  font-size: 0.75rem;
  font-weight: 600;
  border-radius: var(--radius-sm);
  background: var(--color-point-light);
  color: var(--color-point);
}
```

---

### Form Inputs

```html
<div class="field">
  <label class="label" for="name">이름</label>
  <input class="input" id="name" type="text" placeholder="홍길동" />
  <p class="field-hint">실명을 입력해 주세요.</p>
</div>

<div class="field">
  <label class="label" for="message">메시지</label>
  <textarea class="input input-textarea" id="message" rows="4"></textarea>
</div>
```

```css
.field {
  display: flex;
  flex-direction: column;
  gap: var(--space-2);
}

.label {
  font-size: 0.875rem;
  font-weight: 600;
  color: var(--color-text);
}

.input {
  width: 100%;
  padding: 0.625rem 0.875rem;
  font-family: var(--font-body);
  font-size: 1rem;
  line-height: 1.5;
  color: var(--color-text);
  background: var(--color-surface);
  border: var(--border-width) solid var(--color-border);
  border-radius: var(--radius-md);
  transition: border-color 0.15s ease, box-shadow 0.15s ease;
  appearance: none;
}

.input:hover {
  border-color: var(--color-text-muted);
}

.input:focus {
  outline: none;
  border-color: var(--color-border-focus);
  box-shadow: var(--shadow-focus);
}

.input-textarea {
  resize: vertical;
  min-height: 100px;
}

.field-hint {
  font-size: 0.8125rem;
  color: var(--color-text-muted);
  margin: 0;
}
```

---

### 링크 (Links)

```css
a {
  color: var(--color-point);
  text-decoration: underline;
  text-decoration-color: transparent;
  text-underline-offset: 3px;
  transition: text-decoration-color 0.15s ease;
}

a:hover {
  text-decoration-color: var(--color-point);
}

a:focus-visible {
  outline: 2px solid var(--color-border-focus);
  outline-offset: 2px;
  border-radius: 2px;
}
```

---

### Divider

```css
.divider {
  border: none;
  border-top: var(--border-width) solid var(--color-border);
  margin-block: var(--space-8);
}

/* Ornamental divider with center dot */
.divider-ornament {
  display: flex;
  align-items: center;
  gap: var(--space-4);
  color: var(--color-text-muted);
  font-size: 1.25rem;
}
.divider-ornament::before,
.divider-ornament::after {
  content: '';
  flex: 1;
  border-top: 1px solid var(--color-border);
}
```

---

### Blockquote

```html
<blockquote class="blockquote">
  <p>좋은 디자인은 사람들이 느끼는 것이지, 보는 것이 아닙니다.</p>
  <cite>— Unknown</cite>
</blockquote>
```

```css
.blockquote {
  margin: var(--space-8) 0;
  padding: var(--space-5) var(--space-6);
  border-left: 3px solid var(--color-point);
  background: var(--color-point-light);
  border-radius: 0 var(--radius-md) var(--radius-md) 0;
}

.blockquote p {
  font-family: var(--font-heading);
  font-size: 1.125rem;
  font-style: italic;
  color: var(--color-text);
  margin-bottom: var(--space-2);
}

.blockquote cite {
  font-size: 0.8125rem;
  color: var(--color-text-muted);
  font-style: normal;
}
```

---

## 헤더 / 네비게이션 (Header & Navigation)

```html
<header class="site-header">
  <div class="container site-header__inner">
    <a href="/" class="site-header__logo">Brand</a>
    <nav class="site-nav">
      <a href="/about" class="nav-link">소개</a>
      <a href="/work" class="nav-link">작업</a>
      <a href="/contact" class="nav-link">연락</a>
    </nav>
    <button class="btn btn-primary btn-sm">시작하기</button>
  </div>
</header>
```

```css
.site-header {
  position: sticky;
  top: 0;
  z-index: 100;
  background: var(--color-bg);
  border-bottom: var(--border-width) solid var(--color-border);
  backdrop-filter: blur(8px);
  -webkit-backdrop-filter: blur(8px);
}

.site-header__inner {
  display: flex;
  align-items: center;
  gap: var(--space-6);
  height: 4rem;
}

.site-header__logo {
  font-family: var(--font-heading);
  font-size: 1.25rem;
  font-weight: 700;
  color: var(--color-text);
  text-decoration: none;
  margin-right: auto;
}

.site-nav {
  display: flex;
  gap: var(--space-4);
}

.nav-link {
  font-size: 0.9375rem;
  font-weight: 600;
  color: var(--color-text-muted);
  text-decoration: none;
  padding: var(--space-2) var(--space-3);
  border-radius: var(--radius-md);
  transition: color 0.15s ease, background 0.15s ease;
}

.nav-link:hover,
.nav-link[aria-current="page"] {
  color: var(--color-point);
  background: var(--color-point-light);
}
```

---

## 푸터 (Footer)

```html
<footer class="site-footer">
  <div class="container site-footer__inner">
    <p class="site-footer__brand">Brand</p>
    <p class="site-footer__copy">© 2025 Brand. All rights reserved.</p>
    <nav class="site-footer__nav">
      <a href="/privacy">개인정보처리방침</a>
      <a href="/terms">이용약관</a>
    </nav>
  </div>
</footer>
```

```css
.site-footer {
  border-top: var(--border-width) solid var(--color-border);
  padding-block: var(--space-8);
  background: var(--color-bg);
}

.site-footer__inner {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: var(--space-4);
}

.site-footer__brand {
  font-family: var(--font-heading);
  font-weight: 700;
  color: var(--color-text);
  margin: 0;
  margin-right: auto;
}

.site-footer__copy {
  font-size: 0.8125rem;
  color: var(--color-text-muted);
  margin: 0;
}

.site-footer__nav {
  display: flex;
  gap: var(--space-4);
}

.site-footer__nav a {
  font-size: 0.8125rem;
  color: var(--color-text-muted);
  text-decoration: none;
}
.site-footer__nav a:hover {
  color: var(--color-point);
}
```

---

## 히어로 섹션 (Hero Section)

```html
<section class="hero">
  <div class="container">
    <p class="kicker">Warm Humanist Design System</p>
    <h1 class="hero__headline">
      사람을 위한<br /><em>따뜻한 디자인</em>
    </h1>
    <p class="hero__subhead">
      친근하고 편안한 인터페이스로 사용자와 진정한 연결을 만듭니다.
      인간적인 타이포그래피와 따뜻한 색채가 모든 곳에.
    </p>
    <div class="hero__actions">
      <a href="#" class="btn btn-primary btn-lg">시작하기</a>
      <a href="#" class="btn btn-ghost btn-lg">더 알아보기</a>
    </div>
  </div>
</section>
```

```css
.hero {
  padding-block: var(--space-20) var(--space-16);
}

.hero__headline {
  font-family: var(--font-heading);
  font-size: clamp(2.25rem, 5vw, 3.5rem);
  font-weight: 700;
  line-height: 1.08;
  letter-spacing: -0.02em;
  max-width: 14ch;
  margin-bottom: var(--space-5);
}

.hero__subhead {
  max-width: 44ch;
  font-size: 1.125rem;
  line-height: 1.65;
  color: var(--color-text-muted);
  margin-bottom: var(--space-8);
}

.hero__actions {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-4);
}
```

---

## 다크 모드 (Dark Mode)

### 구현 원칙

- CSS 클래스 기반: `<html class="dark">`
- JS로 시스템 설정 감지 및 수동 토글 지원
- 깜빡임 없는 초기화를 위해 인라인 스크립트 사용

### 깜빡임 방지 스크립트 (No-Flash Script)

Next.js `_document.tsx` 또는 `<head>` 에 삽입:

```html
<script>
  (function () {
    try {
      var stored = localStorage.getItem('theme');
      var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      if (stored === 'dark' || (!stored && prefersDark)) {
        document.documentElement.classList.add('dark');
      }
    } catch (e) {}
  })();
</script>
```

### 토글 버튼

```html
<button
  id="theme-toggle"
  aria-label="다크 모드 전환"
  class="btn btn-ghost btn-sm"
>
  ☀️ / 🌙
</button>
```

```js
const toggle = document.getElementById('theme-toggle');
toggle.addEventListener('click', () => {
  const isDark = document.documentElement.classList.toggle('dark');
  localStorage.setItem('theme', isDark ? 'dark' : 'light');
});
```

### 다크 모드 조정 (선택적 미세 조정)

```css
/* 이미지 밝기 살짝 낮추기 */
.dark img:not([src*=".svg"]) {
  filter: brightness(0.9);
}

/* 고정 컬러 아이콘이 있을 때 반전 */
.dark .icon-invert {
  filter: invert(1);
}
```

---

## 애니메이션 & 트랜지션

```css
:root {
  --transition-fast:   150ms ease;
  --transition-base:   200ms ease;
  --transition-slow:   350ms ease;
  --transition-spring: 350ms cubic-bezier(0.34, 1.56, 0.64, 1);
}

/* 모션 감소 선호 */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## 상태 패턴 (State Patterns)

### 호버

모든 인터랙티브 요소에 `transition` 적용. 변화는 미묘하게 — 이동 2px 이하, 색상 전환 150-200ms.

### 포커스

```css
/* 전역 포커스 스타일 */
:focus-visible {
  outline: 2px solid var(--color-border-focus);
  outline-offset: 2px;
}
```

### 비활성화 (Disabled)

```css
.btn:disabled,
.input:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}
```

### 로딩

```css
.loading {
  opacity: 0.7;
  cursor: wait;
  pointer-events: none;
}

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50%       { opacity: 0.5; }
}

.skeleton {
  background: var(--color-border);
  border-radius: var(--radius-md);
  animation: pulse 1.5s ease-in-out infinite;
}
```

---

## 코드 & 모노스페이스

```css
code, kbd, samp {
  font-family: var(--font-mono);
  font-size: 0.875em;
  background: var(--color-point-light);
  color: var(--color-point-dark);
  padding: 0.15em 0.4em;
  border-radius: var(--radius-sm);
}

pre {
  font-family: var(--font-mono);
  font-size: 0.9rem;
  line-height: 1.6;
  background: var(--color-surface);
  border: var(--border-width) solid var(--color-border);
  border-radius: var(--radius-lg);
  padding: var(--space-6);
  overflow-x: auto;
}

pre code {
  background: none;
  padding: 0;
  font-size: inherit;
  color: inherit;
}
```

---

## 안티패턴 (Anti-Patterns)

다음은 Warm Humanist 디자인 시스템에서 **절대 하지 말아야 할** 것들입니다.

| 안티패턴 | 이유 | 대안 |
|----------|------|------|
| 순수 흑백(`#000`/`#fff`) 사용 | 시스템의 따뜻한 분위기를 깨뜨림 | 토큰(`--color-text`, `--color-bg`) 사용 |
| 0px border-radius | 친근함 원칙에 위배됨 | 최소 `var(--radius-sm)` (4px) 사용 |
| 강한 그림자 (`blur > 20px`) | 과도한 볼륨감으로 따뜻함을 상쇄 | `var(--shadow-card)` 이하의 미묘한 그림자 |
| 차갑고 밝은 파란색을 강조색으로 | 테라코타 정체성 훼손 | `var(--color-point)` 유지 |
| 자간이 넓은 sans-serif 헤딩 | Noto Serif KR의 따뜻한 캐릭터가 아님 | `var(--font-heading)` (Noto Serif KR) 사용 |
| 딱딱한 균형의 레이아웃 | 유기적 리듬 원칙에 위배 | 비대칭과 여백 활용 |
| 텍스트 대비 3:1 미만 | 접근성 위반 | WCAG AA(4.5:1) 확인 |
| 직접 색상값 하드코딩 | 다크 모드 / 테마 변경 불가 | 항상 CSS 변수 사용 |

---

## 프레임워크 적용 가이드

### Tailwind CSS v4

```css
/* app/globals.css */
@import "tailwindcss";

@theme {
  /* Colors */
  --color-bg:           #faf6f0;
  --color-surface:      #ffffff;
  --color-text:         #2d1f0e;
  --color-text-muted:   #8a6a4a;
  --color-border:       #e8d8c4;
  --color-point:        #c96a2a;
  --color-point-light:  #f5e6d8;
  --color-point-dark:   #a85420;

  /* Typography */
  --font-heading: 'Noto Serif KR', 'Nanum Myeongjo', Georgia, serif;
  --font-body:    'Noto Sans KR', 'Nanum Gothic', system-ui, sans-serif;

  /* Spacing (Tailwind custom scale) */
  --spacing-1:  0.25rem;
  --spacing-2:  0.5rem;
  --spacing-4:  1rem;
  --spacing-6:  1.5rem;
  --spacing-8:  2rem;
  --spacing-12: 3rem;
  --spacing-16: 4rem;
}
```

### Next.js App Router 셋업

```tsx
// app/layout.tsx
import { Noto_Serif_KR, Noto_Sans_KR } from 'next/font/google';

const notoSerifKR = Noto_Serif_KR({
  subsets: ['latin'],
  weight: ['400', '600'],
  variable: '--font-heading',
  display: 'swap',
});

const notoSansKR = Noto_Sans_KR({
  subsets: ['latin'],
  weight: ['400', '600', '700'],
  variable: '--font-body',
  display: 'swap',
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" className={`${lora.variable} ${nunito.variable}`}>
      <head>
        {/* No-flash dark mode script */}
        <script dangerouslySetInnerHTML={{ __html: `
          (function(){
            try {
              var s = localStorage.getItem('theme');
              var p = window.matchMedia('(prefers-color-scheme: dark)').matches;
              if (s === 'dark' || (!s && p)) document.documentElement.classList.add('dark');
            } catch(e){}
          })();
        `}} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

### CSS-in-JS (Styled Components / Emotion)

```tsx
import { createGlobalStyle } from 'styled-components';

export const WarmHumanistTheme = {
  colors: {
    bg:         '#faf6f0',
    surface:    '#ffffff',
    text:       '#2d1f0e',
    textMuted:  '#8a6a4a',
    border:     '#e8d8c4',
    point:      '#c96a2a',
    pointLight: '#f5e6d8',
    pointDark:  '#a85420',
  },
  fonts: {
    heading: "'Noto Serif KR', 'Nanum Myeongjo', Georgia, serif",
    body:    "'Noto Sans KR', 'Nanum Gothic', system-ui, sans-serif",
  },
  radii: {
    sm:   '4px',
    md:   '6px',
    lg:   '12px',
    full: '9999px',
  },
};
```

---

## 체크리스트 (Implementation Checklist)

새 프로젝트에 이 디자인 시스템을 적용할 때:

- [ ] Google Fonts 또는 `next/font` 로 Noto Serif KR + Noto Sans KR 로드
- [ ] CSS 커스텀 프로퍼티(`:root`, `.dark`)를 글로벌 CSS에 추가
- [ ] 다크 모드 no-flash 스크립트를 `<head>` 에 인라인
- [ ] `font-family`, `color`, `background` 를 CSS 변수로 참조
- [ ] 모든 인터랙티브 요소에 `:focus-visible` 스타일 확인
- [ ] 색상 대비 도구로 AA 기준 검증
- [ ] `prefers-reduced-motion` 미디어 쿼리 적용 확인

---

*Warm Humanist Design System — v1.0.0*
*따뜻함, 접근성, 인간성을 중심에 둔 디자인 시스템.*