release: v0.11.0

packages/skill/references/tokens.md

@@ -17,7 +17,7 @@
 | Perfect Fourth | 1.333 | 또렷한 위계 | 랜딩 페이지, 제품 소개 |
 | Golden | 1.618 | 극적 | 포트폴리오, 에디토리얼. 중간 단계가 비어 본문이 외로워진다 |
 
-**한 페이지에 비율은 하나다.** 헤드라인만 다른 비율을 쓰고 싶으면 그건 비율이 아니라 **디스플레이 사이즈를 따로 정의**하는 것이다.
+본문 scale은 하나의 비율에서 시작하면 관리하기 쉽다. display가 다른 비율이나 별도 크기를 요구할 수 있으므로, 토큰 이름·역할·대표 폭에서의 위계 검증을 함께 기록한다.
 
 ### 실제 값으로 적는다
 
@@ -34,12 +34,12 @@
 }
 ```
 
-### 반응형은 clamp 로, 미디어쿼리로 하지 마라
+### 유동 크기와 구조 전환을 구분한다
 
 ```css
 --step-4: clamp(2.25rem, 1.5rem + 3.75vw, 3.157rem);
 ```
-`clamp(최소, 기준+vw, 최대)`. 최소값은 **모바일에서 읽히는 크기**, 최대값은 데스크톱 기준. 중간이 매끄럽게 이어져 중간 뷰포트에서 깨지지 않는다.
+`clamp(최소, 기준+vw, 최대)`는 연속적으로 변해야 하는 값에 유용하다. 최소·최대는 대표 콘텐츠로 확인한다. grid 열, 내비, 작업대처럼 구조가 바뀌는 지점에는 미디어쿼리나 container query를 쓰고, 임의 기기 폭이 아니라 실제 실패 지점에서 정한다.
 
 ### 함께 정해야 하는 것
 
@@ -48,9 +48,9 @@
 | `--leading-tight` | 1.1~1.2 — 디스플레이/헤드라인 |
 | `--leading-normal` | 1.5~1.6 — 본문 (라틴) / **1.6~1.8 (한글)** |
 | `--measure` | 한 줄 길이. 라틴 60~75자, **한글 25~40자** |
-| 자간 | 큰 글자에만 음수(`-0.02em` 정도). **한글에는 음수 자간 금지** |
+| 자간 | 큰 라틴 디스플레이에서만 작은 음수 자간을 후보로 두고 실제 렌더로 확인. 한글은 글꼴·크기·문맥별로 시험하며, 음수값을 기본 처방이나 절대 금지로 두지 않는다 |
 
-**폰트는 최대 2종**(+ 코드용 모노 1). 세 번째 텍스트 폰트를 넣고 싶다면 위계를 웨이트로 못 만들고 있다는 신호다.
+폰트 수는 전송량·언어 범위·위계·라이선스를 함께 보고 예산으로 정한다. 두 텍스트 패밀리와 필요 시 모노는 흔한 시작점이지만, 세 번째 패밀리가 무조건 실패라는 뜻은 아니다.
 
 > **어떤 폰트를 어떻게 고르고 싣는지는 `typography.md` 가 정본이다.** 여기서는 스케일 값만 정한다.
 > 로딩 전략, 폴백 메트릭 보정, OpenType 기능, 한글 서브셋, 라이선스 확인이 그 문서에 있다.
@@ -70,16 +70,16 @@
   --ink:            /* 본문 텍스트 */
   --ink-muted:      /* 보조 텍스트 — 대비 4.5:1 유지 */
   --line:           /* 경계선 */
-  --accent:         /* 강조 — 페이지당 하나 */
+  --accent:         /* 강조 역할이 필요할 때의 기본 토큰 */
   --accent-ink:     /* 강조 위에 올라가는 글자색 */
 }
 ```
 
 ### 규칙
 
-1. **강조색은 하나다.** 두 개가 필요하다고 느끼면 위계 설계가 실패한 것이다. 예외: 상태색(성공/경고/오류)은 강조색이 아니라 기능색이다
+1. 강조 역할은 한 색에서 시작해 경쟁 여부를 검증한다. 여러 강조 역할이 필요할 수 있으며, 그때는 행동·상태·정보 목적을 역할 토큰으로 구분한다. 수만으로 위계 실패를 판정하지 않는다
 2. **채도가 높은 색은 면적을 좁게.** 넓은 면적에 쓰면 눈이 피로하고 싸구려로 보인다
-3. **중성색도 색이다.** 순수 회색(`#808080`) 대신 강조색 쪽으로 약간 기운 중성색을 쓰면 화면 전체가 하나로 묶인다
+3. **중성색도 색이다.** 순수 회색과 색조를 띤 중성색을 모두 후보로 두고, 표면·브랜드·상태색과의 관계를 비교한다
 4. **대비를 측정해라.** 본문 4.5:1, 큰 글자 3:1. 눈으로 판단하지 마라
 
 ### 다크 모드
@@ -88,9 +88,9 @@
 
 다크를 기본으로 하려면 **근거를 한 줄로 대라.** 정당화되는 이유의 목록은 `presets/dark-instrument.md` 에 있다(야간 운영 환경, 밝은 데이터 시각화의 대비, 제품 자체가 어두움). 댈 수 없으면 라이트로 간다.
 
-어느 쪽을 기본으로 하든 **두 테마를 동등하게 정의한다.** 다크만 만들고 라이트를 빼는 것은 사용자 선택권을 뺏는 것이다.
+라이트/다크 모두를 지원하기로 한 제품은 역할 토큰을 각각 정의하고 실제 상태를 검증한다. 제품이 한 테마만 제공할 수는 있지만, 사용자 환경·브리프·운영 맥락과 접근성 영향을 명시한다.
 
-지원할 때는 색을 뒤집는 게 아니라 **역할별로 다시 정의**한다. 다크에서 순수 검정(`#000`)은 대비가 너무 세서 눈이 아프고, 순수 흰색 텍스트도 마찬가지다.
+지원할 때는 색을 뒤집는 게 아니라 **역할별로 다시 정의**한다. 순수 검정·흰색과 근접한 색은 제품·디스플레이·주변광에 따라 읽기 경험이 다르므로, 대비·눈부심·브랜드 표면을 실제 기기에서 확인한다.
 
 ```css
 :root { --surface: #fbfaf8; --ink: #1a1917; }
@@ -123,10 +123,10 @@
 ### 여백이 위계를 만든다
 
 - 관련 있는 것끼리는 **가깝게**, 다른 그룹과는 **확실히 멀게**. 애매한 중간 간격이 가장 나쁘다
-- 섹션 간격은 **본문 간격의 4배 이상**. 좁으면 페이지가 뭉개진다
+- 섹션·그룹·요소 간 간격 차이가 관계를 읽히게 하는지 실제 화면에서 본다. 4배 같은 고정 비율은 시작 가설일 뿐, 콘텐츠와 폭에 따라 조절한다.
 - 요소를 정렬할 때 **간격이 아니라 정렬선**을 먼저 맞춰라
 
-### h1 이 h2 보다 한 단계만 크면 위계가 아니다
+### 제목 역할이 실제로 구분되는지 확인한다
 
 히어로 제목을 줄이다가 실측에서 이렇게 됐다.
 
@@ -142,10 +142,9 @@
 배경 그래픽과 싸워서 줄였는데, 줄이다가 h2 와 붙는 데까지 왔다.
 **한 극단에서 도망치다 반대쪽 극단에 도착한 것이다.**
 
-기준: **넓은 화면에서 히어로 h1 은 섹션 h2 의 2 배 안팎.** 그 아래면 위계가 없고,
-그 위는 배경·여백과 싸우기 시작한다.
+넓은 화면에서 히어로와 섹션 제목이 같은 위계로 읽히지 않는지 비교한다. 2배 안팎은 한 프로젝트의 관찰값일 뿐 기준선이 아니다. 문구 길이, 구도, 여백, 브랜드 타입에 따라 같은 크기 차도 다르게 보인다.
 
-### clamp 의 하한은 h2 를 기준으로 정한다
+### clamp 값을 역할 관계와 함께 확인한다
 
 여기서 한 번 더 틀렸다. 데스크톱만 보고 고쳤더니 이렇게 됐다.
 
@@ -162,7 +161,7 @@
 **h1 만 `vw` 에 비례해 줄고 h2 는 고정이라, 좁아질수록 둘이 만난다.**
 데스크톱에서 고친 위계가 모바일에서 그대로 사라진다.
 
-하한을 h2 의 1.4 배 이상으로 잡으면 전 구간이 유지된다.
+모바일에서 h1과 h2가 거의 같은 크기로 수렴하지 않는지 확인한다. 아래 값은 해당 조합의 예시이며 모든 제목에 적용하는 비율 규칙이 아니다.
 
 ```css
 /* 하한 3rem = 48px = h2(33.2px)의 1.45 배 */
@@ -174,7 +173,7 @@
 | 비율 | 1.45 | 1.45 | 1.63 | 1.87 | 2.12 |
 
 좁은 화면에서 2 배를 고집할 필요는 없다 — 폭이 좁으면 큰 글자가 줄만 늘린다.
-**1.4 배가 하한, 2 배 안팎이 상한**이고 그 사이를 `vw` 가 잇는다.
+최소·중간·최대 폭에서 제목 역할이 구분되는지 확인하고, 필요한 경우 h1과 h2를 함께 유동화하거나 문구·레이아웃을 조정한다.
 
 > 확인법: 한 화면 폭에서만 재지 마라. `clamp` 를 쓴 값은 **최소 폭·중간 폭·최대 폭
 > 세 곳에서 계산해 보고**, 같이 변하지 않는 값(고정 스케일의 h2 등)과의 비율을 봐라.
@@ -291,12 +290,12 @@ h3 + *,
 ### 버튼처럼 생긴 것은 전부 같은 치수를 쓴다
 
 ```css
---control-h:     2.75rem;   /* 44px — 터치 타깃 */
+--control-h:     2.75rem;   /* 프로젝트의 편안한 기본 높이 예시 */
 --control-h-sm:  2.25rem;   /* 36px — 헤더 등 조밀한 자리 */
 --control-pad-x: var(--space-3);
 ```
 
-컴포넌트마다 높이와 패딩을 다시 정하면 그때부터 SSOT 가 아니다.
+같은 역할의 컴포넌트는 치수 토큰을 공유한다. 다른 밀도나 위험도는 별도 역할 토큰으로 설명한다. WCAG 2.2 AA의 포인터 target 최소 기준은 예외를 포함해 24×24 CSS px이며, 44px는 많은 터치 UI에서 쓰는 편안한 시작값이지 보편 적합성 수치는 아니다 (`evidence-ledger.md`의 `WCAG-TARGET`).
 실측 사례: 같은 페이지의 두 버튼이 높이 36 vs 44, 패딩 16 vs 8, 테두리 1px vs 0,
 웨이트 400 vs 500 이었다. 규칙이 없으니 전부 달랐다.
 반대로 R1 의 두 버튼은 `h36 · pad-x10 · r4 · w400 · 14px` 로 **픽셀 단위까지 같았다.**
@@ -314,7 +313,7 @@ h3 + *,
 
 ### 큰 간격은 화면에 반응해야 한다
 
-작은 값(4~24px)은 고정, 큰 값만 `clamp()`.
+작은 값은 고정값부터, 큰 공간은 `clamp()`부터 검토할 수 있다. 어느 쪽이든 콘텐츠·확대·컨테이너 조건에서 관계가 유지되는지 확인한다.
 
 ```css
 --space-6: clamp(2.5rem, 1.6rem + 2.6vw, 4rem);
@@ -339,16 +338,16 @@ h3 + *,
 | WebGL/3D 추가분 | +200KB | +600KB | 측정 |
 | 총 전송량 (첫 화면) | 1MB | 2MB | 측정 |
 | 첫 인터랙션 (모바일 4G) | 3초 | 5초 | 측정 |
-| LCP | 2.5초 | 3.5초 | 측정 |
-| CLS | 0.1 | 0.1 | 측정 |
-| 폰트 **패밀리** | 2개 이하 | 3개 | 개수 확인 |
+| LCP | field p75 2.5초 이하를 목표로 검토 | 브리프에 명시 | RUM/CrUX 또는 local proxy 표기 |
+| CLS | field p75 0.1 이하를 목표로 검토 | 브리프에 명시 | RUM/CrUX 또는 local proxy 표기 |
+| 폰트 **패밀리** | 프로젝트별 전송량·언어 범위 예산 | 브리프에 명시 | 실제 요청·전송량 확인 |
 | 폰트 전송량(첫 화면) | 100KB | 200KB | 측정 |
-| 애니메이션 속성 | transform/opacity 만 | 동일 (타협 없음) | grep |
+| 애니메이션 속성 | compositing 친화 속성을 우선 검토 | 브리프에 명시 | 성능·reduced-motion·상태 피드백 확인 |
 
 예산을 올렸다면 **올렸다는 사실과 이유를 명시**해라. 조용히 넘기는 것이 가장 나쁘다.
 
 > **폰트는 파일 개수가 아니라 패밀리 수와 전송량으로 센다.** 한글 웹폰트를 유니코드 범위별로
-> 수십 개 파일로 쪼개는 것은 **올바른 최적화**다(Pretendard `dynamic-subset` 은 14개 이상).
+> 수십 개 파일로 쪼개는 방식은 실제 사용 문자 범위·캐시·전송 waterfall에 따라 유효할 수 있다. 파일 개수 자체로 최적화를 판정하지 않는다.
 > 브라우저는 페이지에 실제로 쓰인 글자 범위만 받는다. 파일 개수를 줄이라고 요구하면
 > 한글 프로젝트를 단일 대용량 파일이라는 잘못된 방향으로 몬다.
 
@@ -372,8 +371,7 @@ new PerformanceObserver((l) => {
 </script>
 ```
 
-**프로덕션 빌드에 돌려라.** 개발 서버는 번들이 다르고 HMR 스크립트가 섞여 값이 의미 없다.
-Lighthouse 를 쓸 수 있으면 그쪽이 더 정확하다 — 단 모바일 프로파일로.
+프로덕션 빌드에서 재는 편이 개발 서버보다 배포 조건에 가깝다. 다만 PerformanceObserver·Lighthouse 한 번은 **lab proxy**다. CWV의 적합성 주장은 실제 사용자의 field data에서 모바일·데스크톱별 75th percentile로 판단한다. local 값은 회귀 탐지에 쓰고 field 수치와 혼동하지 않는다 (`evidence-ledger.md`의 `CWV`, `CWV-METHOD`).
 
 ### 예산을 지키는 기본 수단