# pjy.pizza — Pizza Editorial 디자인 시스템

`pjy.pizza`의 모든 페이지(메인, 글, 자료, 스타일가이드)가 공유하는 단일 디자인 시스템입니다.
"피자집처럼 보이지 않으면서 오븐/크림/토마토/올리브 무드만 은은하게" 가져가는, 읽기 좋은 에디토리얼 톤을 목표로 합니다.

- **단일 소스 CSS**: [`/assets/pjy-theme.css`](./pjy-theme.css)
- **라이브 예시**: <http://pjy.pizza/styleguide> (모든 토큰·컴포넌트가 실제로 렌더된 페이지)
- **이 문서**: <http://pjy.pizza/assets/DESIGN-SYSTEM.md>

---

## 1. 쓰는 법

새 페이지를 만들 때는 이 한 줄만 넣으면 테마가 적용됩니다.

```html
<link rel="stylesheet" href="/assets/pjy-theme.css" />
```

그다음은 아래 컴포넌트 클래스를 조합합니다. 색·폰트·간격을 새로 정의하지 말고 **토큰(CSS 변수)** 을 쓰세요.

```html
<header>
  <div class="wrap topbar">
    <a class="wordmark" href="/"><span class="mark"></span><span>pjy.pizza</span></a>
    <nav><a href="/">홈</a><a href="/styleguide" class="nav-pill">styleguide</a></nav>
  </div>
</header>

<div class="wrap wrap--narrow">
  <p class="kicker">section label</p>
  <article class="pz-article pz-prose"> … 본문 … </article>
</div>

<footer>
  <div class="wrap footer-grid">
    <div><strong>pjy.pizza</strong><span>한 줄 설명</span></div>
    <div class="footer-links"><a href="/">홈</a></div>
  </div>
</footer>
```

> 글/문서형 페이지는 본문을 `<article class="pz-article pz-prose">`로 감싸면 `h2/h3/p/ul/li/a/code`가 자동으로 스타일됩니다. 별도 클래스가 필요 없습니다.

---

## 2. 디자인 토큰 (`:root`)

CSS 변수로 정의되어 있습니다. **페이지에서 값을 새로 정의하지 말고 변수만 참조**하세요. 톤을 바꾸려면 `pjy-theme.css`의 `:root` 한 곳만 고치면 전체에 반영됩니다.

### 색

| 토큰 | 값 | 용도 |
|---|---|---|
| `--cream` | `#f8f0df` | 기본 배경(구운 종이) |
| `--cream-2` | `#fff9ec` | 카드/표면 |
| `--dough` | `#ead8b9` | 보조 표면, 코드 배경 |
| `--crust` | `#d8b57d` | 크러스트 브라운(마크, 강조 숫자) |
| `--tomato` | `#bb4d32` | **메인 액센트**(링크, 라벨, 버튼) |
| `--tomato-2` | `#d96a45` | 밝은 액센트(hover) |
| `--olive` | `#737a45` | 보조 액센트 |
| `--ink` | `#211a15` | 본문 글자 |
| `--soft-ink` | `#5f554b` | 보조 글자 |
| `--muted` | `#958779` | 메타/흐린 글자 |
| `--line` | `#dfcdb0` | 경계선 |
| `--dark` | `#231b16` | 다크 패널 배경 |
| `--dark-soft` | `#3b2c23` | 다크 패널 경계 |

의미 별칭: `--bg`, `--surface`, `--surface-2`, `--accent`(=tomato), `--accent-2`(=olive).

### 타이포그래피

| 토큰 | 용도 |
|---|---|
| `--serif` (Georgia) | **헤드라인** — 에디토리얼 느낌의 큰 제목 |
| `--sans` | 본문 |
| `--mono` | 라벨·kicker·메타·코드 |

원칙: **제목은 serif, 본문은 sans, 작은 라벨은 mono.** 한글 헤드라인은 `letter-spacing` 음수(`-.05em~-.07em`)로 조여서 밀도를 줍니다.

### 반경 · 그림자 · 간격

- 반경: `--r-sm 14` · `--r-md 22` · `--r-lg 28` · `--r-xl 38` · `--r-pill 999`
- 그림자: `--paper-shadow`(종이 패널), `--soft-shadow`(카드)
- 간격 스케일: `--space-1 … --space-6` (8 / 14 / 22 / 34 / 56 / 86px)

---

## 3. 레이아웃

| 클래스 | 설명 |
|---|---|
| `.wrap` | 페이지 폭 컨테이너 (max 1180px) |
| `.wrap--narrow` | 글 읽기용 좁은 폭 (max 900px) |
| `header` + `.topbar` + `.wordmark` + `.mark` + `nav` + `.nav-pill` | 상단 마스트헤드. `.mark`는 피자 한 조각 + 페퍼로니/올리브 점 |
| `footer` + `.footer-grid` + `.footer-links` | 하단 |

---

## 4. 컴포넌트 (`.pz-*`)

모든 재사용 컴포넌트는 `pz-` 접두사를 씁니다(페이지 고유 클래스와 충돌 방지).

| 클래스 | 용도 |
|---|---|
| `.pz-article` | 글 본문을 감싸는 크림 종이 패널 |
| `.pz-prose` | 내부 `h2/h3/h4/p/ul/li/a/code` 자동 스타일 |
| `.pz-lead` | 도입부 큰 문장 |
| `.kicker` / `.pz-eyebrow` | 섹션 위 작은 mono 라벨 |
| `.pz-callout` + `--accent` / `--note` / `--warn` | 강조 박스(슬로건 / 참고 / 경고) |
| `.pz-stat-grid` + `.pz-stat` | 다크 통계/원칙 카드 4열 |
| `.pz-panel-dark` | 다크 패널(소개 등) |
| `.pz-grid-2` / `.pz-grid-3` | 2열 / 3열 그리드 |
| `.pz-card` | 일반 카드 |
| `.pz-principle` | 좌측 그라데이션 바가 있는 원칙 카드 |
| `.pz-steps` + `.pz-step` | 번호가 매겨진 단계 |
| `.pz-plain-box` | 단순 설명 박스 |
| `.pz-table` | 표 |
| `.pz-mermaid` | Mermaid 다이어그램 래퍼 |
| `.pz-figure-grid` + `.pz-figure` | 스크린샷 갤러리 |
| `.pz-agent` | 접이식 코드/브리프 블록(다크 `pre`) |
| `.pz-tech-grid` + `.pz-tech` | 링크/레퍼런스 카드 |
| `.pz-toc` | 목차 |
| `.pz-btn` + `--ghost` | 버튼 |

### Mermaid 테마

Mermaid를 쓰는 페이지는 `mermaid.initialize`에 따뜻한 팔레트를 넣습니다(다크 노드 + 크림 글자):

```js
themeVariables: {
  primaryColor: '#231b16', primaryTextColor: '#fbeede', primaryBorderColor: '#3b2c23',
  lineColor: '#b0875a', secondaryColor: '#ead8b9', tertiaryColor: '#f8f0df',
  fontFamily: 'ui-sans-serif, system-ui, "Noto Sans KR", sans-serif'
}
```

---

## 5. 서빙 구조 (운영 메모)

- **메인/자료/글/스타일가이드**: `pjy-pizza-static/server.py`(포트 5555, NPM 프록시 뒤). `/assets/*`는 `_serve_static`이 `ROOT/assets`에서만 서빙(경로 탈출 차단). `/styleguide`는 `styleguide.html`.
- **내부 미러(글)**: `192.168.1.200:8731`은 `observable-surface-blog/`를 `python -m http.server`로 서빙. 글은 두 위치에 동일 파일로 둡니다.
- **CSS는 두 곳에 복사본 유지**: `pjy-pizza-static/assets/pjy-theme.css`(정식) + `observable-surface-blog/assets/pjy-theme.css`(8731 미러). 글이 절대경로 `/assets/pjy-theme.css`로 링크하므로 각 서버 루트에 파일이 있어야 합니다.

### 무언가 바꾼 뒤 동기화

```bash
# 테마/글 수정 후 두 서버 동기화
cp pjy-pizza-static/assets/pjy-theme.css observable-surface-blog/assets/pjy-theme.css
cp observable-surface-blog/index.html    pjy-pizza-static/writing/observable-surface/index.html
systemctl --user restart observable-surface-blog.service   # 8731
# server.py 자체를 고쳤다면 pjy.pizza 서버 프로세스도 재시작
```

---

## 6. 원칙 한 줄 정리

1. 색/폰트/간격은 **토큰만** 쓴다. 하드코딩 금지.
2. 제목은 serif, 본문은 sans, 라벨은 mono.
3. 피자는 **은은하게** — 마크와 색감으로만. 대놓고 피자 일러스트/이모지 금지.
4. 새 컴포넌트는 `pz-` 접두사로 추가하고 이 문서와 `/styleguide`에 반영한다.
5. 한 곳(`pjy-theme.css`)을 고치면 전체가 바뀌도록 유지한다.