---
title: "🎨 260527-수요일_디자인 폴리싱 시스템 + NanumSquare Neo + 목업 방식"
notion_id: "36d22962086881699ab7dd489d56ef1e"
notion_url: "https://app.notion.com/p/36d22962086881699ab7dd489d56ef1e"
category: "workreport"
parent: "Claude Code 작업보고"
updated: "2026-05-28"
priority: "High"
purpose: "UI 전역 폴리싱 대작업 — NanumSquare Neo 폰트·adjustColorForTheme 보색 알고리즘·디자인 토큰/공통 클래스 체계·차트 가독성·목업 catalog 우선 방식"
read_when: ["디자인시스템","UI작업"]
---

## 📌 요약

소량 fix에서 시작하여 UI 전역 폴리싱 대작업으로 확장. 핵심 산출물:

1. **NanumSquare Neo 본문 전역 적용** (`@noonnu/nanum-square-neo-variable` npm 패키지)
2. **`adjustColorForTheme` 자동 보색 매핑 알고리즘** (`src/lib/colorTheme.ts`) — 사용자 지정 색의 theme별 displayColor 자동 계산 (Hue +180° + Lightness clamp)
3. **디자인 토큰 + 공통 컴포넌트 클래스 체계** (`.card` / `.row` / `.btn` / `.btn-outline` / `.btn-destructive` / `.btn--sm` / `.badge`)
4. **라이트 모드 톤 상향** (포인트 티일 자동 적용, 차트 팔레트 차분화, 로고 쉬도우)
5. **코치 브리프 텍스트 가독성** 로고 (´--brief-\*´ 토큰)
6. **대시보드 차트** 높이 2배 + 마커 hover only + 라이트 팔레트
7. **목업 catalog 우선 작업 방식** (효율 검증 데이터 확보)

총 커밋: 약 16건. push: `origin/main` 동기화 완료.

---

## 1. NanumSquare Neo 전역 폰트

### 선정 결과

- npm: `@noonnu/nanum-square-neo-variable@0.1.0` (MIT, 가변 woff2 단일 Ƀ1.7MB)
- 원본: NAVER Corp. 나눔스퀘어 네오, OFL 1.1
- 방식: **자체 호스팅 (npm 패키지)**. 임의 CDN 미사용.
- 적용: `src/main.tsx` 에서 `import '@noonnu/nanum-square-neo-variable/index.css'`. `--font-body` 토큰을 `'NanumSquareNeo-Variable', system-ui, ...` fallback chain 으로 교체.
- 기존 `--font-display`(Bebas Neue) 는 로고·브랜드 디스플레이용으로 유지.
- 라이선스 문서 신설: `THIRD_PARTY_LICENSES.md` — 재새 자산 도입 시 누적 기입.

### 교훈

- `@fontsource/...` 에 NanumSquare Neo 는 **없음** — 대안으로 noonnu 패키지 선택
- Google Fonts 에도 **없음** (네이버 별도 배포)
- 폰트 적용 후 **font-weight 감각 재조정 필수** — 이전 Noto Sans KR 기준에서 400 이던 자리가 NanumSquare Neo 로는 약해보임

---

## 2. adjustColorForTheme 자동 보색 매핑

### 사용자 의도 핵심

> 신규 사용자가 임의 신발·런타입 색을 등록해도 자동으로 라이트/다크 대비색 적용. 디테일 색 규정 하드코딩 X.

### 최종 알고리즘 (`src/lib/colorTheme.ts`)

```typescript
원본 hex → HSL → Hue +180° (보색) → theme 별 lightness clamp

  라이트: L ≤ 0.35 (흰 배경 대비)
  다크:   L ≥ 0.68 (검은 배경 대비)

  무채색(S<0.12) — 안전 톤(#3a3a3a / #d8d8d8)
```

### 교훈 (시도 순서)

5단계 시도 모두 사용자 거절:

1. `textShadow` 4방향 multi outline + glow → 축자막 부자연
2. `명의` 단일 shadow `0 1px 1.5px rgba(0,0,0,0.4)` → 노란/아이보리 여전히 약함
3. 밝은 색 한정 label backing (rgba(0,0,0,0.06)) + box-inset → 배지처럼 어색함
4. row 배경 자체를 어두운 청록 슬레이트(#305769) 으로 → 독립 덩어리감
5. `adjustColorForTheme` HSL Lightness clamp 만 → hue 보존이라 노란 채도가 이전 하니 동일 문제

**해결** = 보색(hue +180°) + lightness clamp. 사용자 명시로 접근 방향 자체 수정 (사용자 원 의도를 내가 하나씩 떨어뜨려서 해석).

### 적용 위치

- `src/pages/Settings.tsx` 신발/런타입 row 텍스트 + 컬러박스
- `src/pages/History.tsx` `shoeColorMap` / `runTypeColorMap` useMemo — 4곣 자동 갱신
- `useTheme` hook — MutationObserver 로 `data-theme` 변경 감지 → 자동 리렌더

---

## 3. 디자인 토큰 + 공통 클래스 체계 (`src/index.css`)

### 토큰 재구조 (기존 이름 유지 → 값만 갱신 → 다른 페이지 자동 반영)

다크 변경:

- `--border2` #333 → **#3a3a3a**
- `--bg4` **#222222** 신규 (hover row)
- `--danger` **#ff6b6b** / `--danger-soft` / `--danger-border` / `--shadow-card{,-hover}` 신규

라이트 변경:

- `--bg` #fafafa → **#f6f7f9** (회청 톤)
- `--bg3` #f1f1f1 → **#f7f8fa** (row 부드러움)
- `--bg4` **#eef0f3** 신규
- `--border` #e5e5e5 → **#e6e8ec**
- `--border2` #d4d4d4 → **#d4d7dc**
- `--text` #181818 → **#14181f**
- `--text2` #4a4a4a → **#4a505a**
- `--text3` #6f6f6f → **#777e89**
- `--danger` **#c8504d** / `--shadow-card` 부드러운 2-layer

공통:

- `--radius` 12 → **14**
- `--radius-sm` 8 → **6**
- `--radius-md` **10** 신규

### 공통 컴포넌트 클래스

- **`.card`** — radius / shadow / padding 24 토큰화
- **`.row` + `.row__left/__chip/__title/__sub/__actions`** — SaaS 리스트 행 (min-h 48, padding 11/14, hover bg4)
- **`.btn`** 기본값 정돈 (font-body 13/700, radius var(--radius-sm))
- **`.btn-outline`** (accent outline + hover bg tint)
- **`.btn-destructive`** (red outline + hover red tint)
- **`.btn--sm`** modifier (11.5/600/28h/r7)
- **`.btn--icon`** (28x28)
- **`.badge / .badge--accent / .badge--muted`**

### 효과

- `Settings.tsx` 신발/런타입 row 의 인라인 style 수십 줄 → className 1줄로 축소
- 다른 페이지의 var(--bg3/--text/--border) 사용처는 날린 토큰 값 갱신으로 자동 반영

---

## 4. 코치 브리프 텍스트 가독성 (`--brief-*` 토큰)

- `--brief-text` `#d8d8d8` (본문) / `#1a1a1a` (라이트)
- `--brief-muted` `#a0a0a0` / `#5a5a5a`
- `--brief-h2` `#5fd9e6` (시안 섹션 헤더)
- `--brief-h3` `#c8f135` (라임 서브 헤더)

적용: `MarkdownBriefRenderer.tsx` h2/h3/p/ul/ol/em + `VisualBriefCards` 4개 카드 헤더/본문/보조.

---

## 5. 그래프 가독성 회복 (`src/lib/chartTheme.ts`)

- 차트 높이 90~110px → **180~220px** (2배)
- 선 차트 마커: `pointRadius: 0` + `pointHoverRadius: 4` (hover 시만 점 등장)
- 라이트 한정 계산 팔레트 — 라임·형광 → 티일 #0a8e9e / 진한 블루 #2563eb / 진한 코랄 #b54a28 (CSS 변수 `--chart-1/2/3`)
- `chartTheme.ts` 헬퍼 — `chartColor(slot)` / `chartBg(slot)` / `lineMarker` spread
- 적용: BodySection / RunningSection / StrengthSection / SummaryBrief (4고·차트 임라인 hex 모두 교체)

---

## 6. 라이트 accent + 사이드바 + 로고

- `--accent` 라이트 한정 교체: 라임 #c8f135 → **진한 티일 #0a8e9e** (라이트 배경에서 자극 ↓)
- `--btn-primary-fg` 토큰화 — 다크 검정 / 라이트 흰색 (티일 배경 대응)
- 사이드바 로고 SVG filter 토큰화 (`--logo-filter`) — 라이트에서 자동으로 진한 티일 변환 + drop-shadow
- 로고 아이콘 크기 34 → 75 → 최종 **52** (compact 브랜드 헤더)
- 사이드바 메뉴 weight 비활성 **700** / 활성 **800** (NanumSquare Neo 대응)

---

## 7. 목업 catalog 우선 작업 방식 (효율 데이터)

### 변경된 작업 방식

기존 = 코드 수정 → 빌드(5s) → push(5s) → CF 배포(~60s) → 사용자 새로고침 → 평가 → 피드백 → 재수정 … = 사이클 ~1.5분/회
변경 = 목업 HTML 작성 → 사용자 더블클릭 → 새로고침(1초) → 토큰만 수정 → 새로고침 … → **확정 후 한 번에 실 코드 적용**

### 실측 데이터 (이번 작업)

- 기존 방식 예상: 4개 페이지 × 5~10회 iteration = 30분~1시간/페이지
- 목업 방식 실제: HTML 30~45분 작성 + 2회 피드백 + 코드 적용 30분 = **총 ~1.5시간**, 사용자 대기 30분 미만
- **사용자 피로도 현저히 ↓** (매 사이클 새로고침 · 평가 주기 반복 없음)

### 산출물

- `docs/260528_design_polish_mockup.html` (라이트 base)
- `docs/260528_design_polish_mockup_dark.html` (다크 default)
- 향후 동일 catalog 갱신으로 추가 시각 보정 명뢹

### 패턴으로 일반화

**시각 요소 보정·디자인 시스템 우선 변경 시에는 목업 catalog 먼저**. 메모리 `feedback-mockup-first` 저장 (이번 세션의 핵심 학습 데이터).

---

## 8. 카프 이동 / 보관

- 팭토핀 작업 재개 시: 동일 구조 (디자인 토큰 + 공통 컴포넌트 클래스 + 목업 catalog) 재사용 권장
- 폰트 = NanumSquare Neo / 디스플레이만 별도 (팭토핀 자체 브랜드 폰트)
- displayColor 보색 매핑은 달록에 특화 — 팭토핀 입력 폼에는 부적합할 수 있음 (색이 의미 상수일 때)
- 그 외 토큰 체계 / 컴포넌트 클래스 / NanumSquare Neo / 목업 catalog 방식 / Deploy Hook 우회는 전부 풌토핀 재사용 가능

---

## 9. 그 외 학습 (별도 메모리 저장)

- **CF Pages 자동 배포 누락 시 Deploy Hook 우회** — webhook 가 닫 회 push 합쳐서 누락시키는 사고 발생함. Hook URL 로 curl POST 으로 강제 트리거 가능. 단 정상 push 직후 hook 자동 호출은 중복 트리거로 큐 적체 유발 — 사고 시에만 호출 (메모리 `reference-cf-pages-redeploy` 이미 저장됨).
- **소량 UI/스타일 수정 = 사용자 명시 위임 시 자동 push** 정책 (`feedback-push-autonomy` 메모리)

---

## 관련 파일

신규:

- `src/lib/colorTheme.ts` — adjustColorForTheme + useTheme
- `src/lib/chartTheme.ts` — chartColor/chartBg/lineMarker
- `THIRD_PARTY_LICENSES.md`
- `docs/260528_design_polish_mockup.html` (라이트)
- `docs/260528_design_polish_mockup_dark.html` (다크)

대폭 수정:

- `src/index.css` — 토큰 재구조 + .row/.btn-\*/.badge 신규
- `src/pages/Settings.tsx` — row/버튼 클래스화 + displayColor 적용
- `src/pages/History.tsx` — shoeColorMap / runTypeColorMap displayColor
- `src/components/SummaryBrief.tsx` — 라임 hex 인라인 → chartColor
- `src/components/MarkdownBriefRenderer.tsx` — brief 토큰
- `src/components/Layout.tsx` — 로고/PACELOG/메뉴 weight
- `src/components/dashboard/{Body,Running,Strength}Section.tsx` — 차트 height/marker/팔레트
- `src/main.tsx` — NanumSquare Neo CSS import

## 커밋 이력 (상위 핵심)

- `4f80930` design polish (토큰 + 공통 클래스)
- `7b76948` NanumSquare Neo 전역 폰트
- `7a529d8` displayColor 보색 해결도즘
- `b1195f3` B안 colorTheme 신설
- `3425967` 대시보드 차트 가독성
- `013aad0` 전역 텍스트 톤 가룡성
- `ae89808` 코치 브리프 텍스트 가독성
- `9edd84e` 로고 + 라임 잔존 + 차트 팔레트

## 관련 페이지

- 작업일지: [📅 2026-05-27 (수) 작업일지](#/doc/devlog-13) §05
- 핸드오프: [📋 26-05-26_1-달록_핸드오프](#/doc/handoff-13) §17
- 메모리: `feedback-mockup-first` (이번 세션에서 신설)

---

*2026-05-28 작성 · Claude Opus 4.7 (1M context)*