---
title: "📓 작업일지 — raw color 토큰 가드 신설(count-ratchet 방식) (U4)"
category: "worklog"
parent: "Claude Code 작업일지"
updated: "2026-07-03"
priority: "Low"
purpose: "토큰맵 v0 후속 라운드 U4 항목 — px 토큰 가드(spacingTokenGuard)의 색상판 colorTokenGuard.test.ts 신설. CSS/tsx의 raw #hex·rgba를 검출하되, line/fingerprint 스냅샷 대신 count-ratchet(부채 개수 상한)으로 정상 편집·클린업은 통과시키고 신규 raw 추가만 막는 방식으로 설계한 기록."
read_when: ["colorTokenGuard.test.ts", "count-ratchet 가드 설계", "raw color allowlist", "css138 tsx25 부채상한"]
document_type: "개발일지"
source_status: "generated"
knowledge_group: "03_history"
work_timestamp: "20260703_140053"
source_of_truth: "https://dallog-tools.hansbridge.co.kr/knowledge/"
context: "달록 본레포(ccy-hansbridge/dallog), 커밋 534f15a(2026-07-03). 토큰맵 v0 후속 라운드 U4."
---

# 작업일지 — raw color 토큰 가드 신설(count-ratchet 방식) (U4)

## 1. 무엇을 했나

- `src/styles/colorTokenGuard.test.ts` 신규 작성 — 기존 px 가드(`spacingTokenGuard`)의 색상판에 해당.
- 검출 대상: 실제 CSS 속성 값과 tsx 인라인 스타일의 `#hex`/`rgba(...)`. `--*` 토큰 정의부 자체는 SKIP. `transparent`, alpha 0 sentinel 값은 예외 처리.
- allowlist는 값 기반(라인 번호 무관)으로 관리 — 소셜 로그인 브랜드로고(Brand/Login/SocialAuth), Settings의 `PRESET_COLORS`, Univer 팔레트(`PAL`), `chartTheme`의 cssVar 폴백값, `colorTheme`, `index.css`의 소셜버튼·아바타 브랜드색 등은 raw여도 정당한 예외로 취급.
- 검증 방식은 **count-ratchet**: 부채 목록(`debt.length`) 길이가 상한(CSS 138·tsx 25)을 넘으면 FAIL, 넘지 않으면 통과. 신규 raw color 추가는 상한 초과로 즉시 잡히지만, 정리(개수 감소)나 단순 라인 시프트는 그대로 통과.
  - Codex 초안이 제안했던 line/fingerprint 스냅샷 방식은 정상적인 편집이나 클린업까지 실패로 잡아버리는 문제가 있어, count-ratchet으로 교정.
- 잔여 부채(admin 운영 격리 영역·SVG fallback·`#5f5f5f`·CoachNotes 팔레트·`color-mix` 피연산자 등)는 unresolved로 남기고, 가드 상한을 점진적으로 낮춰가는 트랙으로 관리.
- 비-vacuous 검증(임시로 raw color를 주입해 실제 FAIL이 뜨는지 확인) 통과. `npm test` 123건 GREEN.

## 2. 주요 변경 파일

| 파일 | 내용 |
|---|---|
| `src/styles/colorTokenGuard.test.ts` | 신규 파일(164줄) — CSS/tsx raw color count-ratchet 가드 |

## 3. 관련 커밋

- `534f15a` test(guard): raw color 토큰 가드 신설 — count-ratchet (U4) (2026-07-03)

## 4. 남은 이슈

커밋 메시지 기준 unresolved로 남은 잔여 부채: admin 운영 격리 영역, SVG fallback, `#5f5f5f`, CoachNotes 팔레트, `color-mix` 피연산자 — 가드 상한을 점진적으로 낮춰가는 방식으로 후속 처리 예정(별도 완료 시점 언급 없음).