fix(design-system): 스타일·토큰·story·검사를 토큰 계약에 맞춘다 #56

Merged
donghyeon.kang merged 9 commits from donghyeon.kang/fix/r9-design-tokens-stories AGit into main 2026-11-13 19:13:51 +00:00
9 Commits
Author SHA1 Message Date
DongHyeonka 91b3aaac46 test(visual): 시각 골든의 색 허용치를 0.05로 좁힌다
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m14s
frontend-quality-gates / merge / tests (pull_request) Successful in 16m3s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m32s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
시각 골든은 `maxDiffPixels: 50`만 정하고 색 허용치(threshold)를 두지 않아
Playwright 기본값 0.2를 쓴다. 0.2는 pixelmatch YIQ 거리로 1408.6까지 같은
색으로 본다. 밝은 `--color-danger-surface`의 색상각 25 → 145(분홍 → 초록,
거리 154.5)와 어두운 `--color-danger` 한 단계(거리 1260.1)가 옛 골든과 새
골든을 모두 통과했다. 그래서 위험 표면이 초록빛으로 바뀌어도 골든이 통과한다.
CHANGELOG 알려진 제한으로만 적혀 있었다.

고른 방법: 결정(2026-11-12, 총괄: 흔들림 없는 값을 재서 낮춘다)대로 0.05(거리
88.0)를 쓴다. 기준을 올리는 쪽이다. `playwright.visual.config.ts`는 지금
w2-fe-2가 브라우저 실행 설정을 고치는 중이라 이번에 건드리지 않고, 시각
spec이 모든 screenshot에 `GOLDEN`(threshold 0.05)을 넘긴다. 새 screenshot이
빠뜨리지 않도록 `tests/unit/visual-golden-threshold.test.ts`가 대조한다. 버린
대안: 0.1(거리 352.2라 첫 변이가 다시 통과한다).

위험·한계: 글꼴·래스터 설정을 고정한 깨끗한 빌드는 0 px 차이라는 기존 주장에
기댄다. desktop에서 변이 없이 세 번, 변이로 한 번 돌려 PR 본문에 적는다.
설정 기본값은 0.2 그대로라 다른 Playwright 설정의 screenshot은 이 값을 받지
않는다(지금 다른 곳에는 screenshot이 없다).

검증: 실험 X-02(변이 `--color-danger-surface` 색상각 145에서 0.2는 통과,
0.05는 `state-surfaces-light` 실패, 변이 없이 세 번 통과)는 desktop에서
돌려 PR 본문에 적는다.

Refs: 1112/04-11
2026-11-13 23:27:47 +09:00
DongHyeonka 27da6d8d53 docs(styling): 토큰 문서가 primitive 목록을 손으로 들지 않고 배럴과 story를 가리킨다
`docs/styling/design-tokens.md` 「들어 있는 primitive」가 Button·TextField·
Card·Alert/Badge·Dialog·상태 surface 여섯만 적는다. 실제 배럴에는 primitive
25개, pattern 5개, 페이지 템플릿, 폼 구성요소가 있고, 문서는 스스로 "지금
구현된 primitive 기준선을 적는다"고 한다. fe-a11y 스킬이 이 절을 근거로 든다.

고른 방법: 손 목록을 지우고 정본(배럴 `index.ts`)과 상태를 여는 곳(갤러리·
카탈로그 story), 대조 시험을 가리킨다. 목록이 들고 있던 약속(색에만 기대지
않음, tooltip에만 두지 않음, overlay의 Escape·focus 복원)은 문장으로 남긴다.
fe-a11y 스킬이 이 절을 인용하므로 절 제목은 그대로 둔다.

검증: 노트북 `scripts/verify.sh docs`, desktop `verify:documentation`(PR
본문).

Refs: 1112/04-16
2026-11-13 23:27:47 +09:00
DongHyeonka 2f3ebba46b test(storybook): 배럴의 모든 화면 컴포넌트에 story를 두고 저장 상태를 골든에 넣는다
디자인 시스템 배럴(`src/presentation/design-system/index.ts`)의 값 export
가운데 화면 컴포넌트 37개에 story가 없다: SearchField·ConfirmationDialog·
Drawer·Popover·Breadcrumbs·Pagination·LinkButton·Separator·IconButton 같은
primitive, DataTable 등 pattern 다섯, 페이지 템플릿 다섯, 폼 구성요소, 아이콘
아홉. 결과를 모르는 저장(확인·같은 요청 다시 보내기), 충돌, 오래된 데이터,
저장 중은 갤러리와 골든에 없다. 그래서 파생 서비스가 쓸 컴포넌트의 상태를 볼
곳이 없고, 그 배치 회귀를 골든이 잡지 못한다.

고른 방법:
- `catalog.stories.tsx`에 묶음 story 열을 더한다(겹치는 화면, 탐색과 입력,
  아이콘, 화면 패턴, 페이지 템플릿 다섯을 하나씩, 저장 결과). 템플릿 story는
  각자 자기 h1을 그린다.
- ScreenStates 갤러리에 저장 상태 절을 더한다: 결과를 모르는 저장(다시 보내기
  가능), 충돌, 오래된 데이터, 저장 중, 입력과 무관한 저장 실패
  (FormFailureStatus), 입력 오류 요약. `state-surfaces-light` 골든이 이 절을
  담는다.
- `tests/unit/design-system-story-coverage.test.ts`가 배럴의 값 export마다
  story에서 `<Name`으로 그려지는지 대조한다. 그리지 않는 것(Portal·FocusRing·
  VisuallyHidden, 토큰 상수, hook)은 이유와 함께 목록에 둔다.
- 새 story 열은 `tests/storybook/galleries.spec.ts`의 axe 검사(light·dark)에
  더했고, 겹치는 화면 셋(확인 대화 상자, 서랍, 팝오버)은 연 상태로도 본다.
  대조 시험이 catalog story마다 그 목록에 있는지 본다.
- 갤러리에 넣으면서 드러난 둘을 고쳤다. 저장 상태 안내의 문장과 버튼이 붙어
  있었다(`.async-surface__status`: 한 줄로 감싸고 간격, 지원 참조는 아랫줄).
  `FormFailureStatus`가 제목 단계를 받지 못해 카드 안에서 h2로 그려졌다
  (`headingLevel`, 추가만, 다른 상태 표면과 같은 08-05 계약).
- 버린 대안: 컴포넌트마다 variant 행렬 story를 한 번에 쓰기(이번 범위는 "모든
  화면 컴포넌트에 story 하나 이상"이고, 행렬은 컴포넌트를 고칠 때 더한다).
  StatusPage를 갤러리에 넣기(자기 h1을 그려 갤러리의 h1과 겹친다. 자기
  story로 뒀다).

위험·한계: 갤러리 골든이 바뀐다(이 커밋에서 다시 찍는다). theme·locale
toolbar는 아직 없다. story axe가 20번 늘어 FE-GATE-008이 조금 길어진다.

검증: 대조 시험(고치기 전 story 파일에서 37개 누락으로 실패), story 빌드
(FE-GATE-011), story axe와 시각 골든(FE-GATE-008)은 desktop에서 돌려 PR
본문에 적는다.

Refs: 1112/04-10
2026-11-13 23:27:47 +09:00
DongHyeonka d5083f862d fix(home): 홈이 StandardPage와 LinkButton을 쓴다
홈(`src/presentation/pages/home-page.tsx`)이 페이지 템플릿 대신 자기
`section.ui-page`와 `PageHeader`를 쓰고, 시작 링크를
`<Link className="ui-button …">`으로 `LinkButton`을 손으로 다시 만든다.
`PRODUCT.md`는 홈이 파생 서비스에 남는다고 적는다. 그래서 그대로 복제되고
개발자가 따라 하는 예가 된다. `LinkButton`의 variant·size가 바뀌면 홈만
어긋난다.

고른 방법: `StandardPage`(heading 슬롯에 eyebrow·제목·설명)와
`LinkButton variant="primary"/"secondary"`로 바꾼다. 준비 목록, 런타임 요약,
시작 링크는 템플릿의 본문 자리에 `home-page__sections`(블록 사이 `--space-6`)로
묶어 둔다. 템플릿 본문 자리에는 간격이 없어, 묶지 않으면 런타임 요약이 카드에
붙는다(첫 골든에서 보고 고쳤다). component 시험이 홈의 링크가
standard 템플릿 안의 `ui-button ui-button--primary`인지 본다.

위험·한계: 머리말과 본문 사이는 템플릿 간격(`--space-5`)이라 홈의 세로 간격이
조금 바뀐다. 시각 골든은 이 커밋에서 다시 찍고 이유를
PR 본문에 적는다.

홈이 템플릿과 `LinkButton`을 쓰면서 번들러가 청크 둘을 합쳤다. 초기 JS는
파일 17 → 15개, gzip 194,397 → 194,143 B, Service Worker precache 자산은
24 → 22개다. `config/scale/feature-shape-ceilings.json`은 측정 스크립트
(`node scripts/scale/measure-feature-shape-growth.ts --initial-baseline
--write`, desktop)가 쓴 그대로다.

검증: `tests/component/starter-pages.test.tsx`와 시각 골든은 desktop에서
돌린다(PR 본문).

Refs: 1112/04-06
2026-11-13 23:27:47 +09:00
DongHyeonka f948aa67c3 docs(design-system): 스킬과 토큰 문서의 색 혼합·아이콘 토큰 문장을 규칙에 맞춘다
fe-design-system 스킬의 기준 문장 두 곳이 실제 규칙·토큰과 다르다.
`color-mix()`는 `in oklab`만 쓴다고 적었지만 규칙(UI-02)은 색상각 공간만
거절하고, 코드는 반투명 가림막을 브라우저가 겹쳐 그린 색과 맞추려고
`in srgb`를 일부러 쓴다. `docs/styling/design-tokens.md` UI-02도 같은
문장이었다. 그리고 아이콘 토큰을 `--icon-size-*`라고 적었지만 실제 이름은
`--size-icon-*`·`--icon-stroke-default`다. 스킬을 따르는 리뷰어가 srgb를
oklab으로 "고치면" 스크롤바 자리 색 맞춤이 깨지고, 없는 토큰을 새로 만든다.

고른 방법: 두 문서의 문장을 규칙과 토큰 이름에 맞춘다. 그리고
`scripts/tests/test_claude_setup.py`에 "스킬이 백틱으로 적은 토큰 이름(토큰
이름공간만, 별표는 아무 이름)은 토큰 파일이 정의한다" 시험을 더한다. 버린
대안: 문서만 고치기(같은 어긋남이 다시 생겨도 아무도 모른다).

검증: 노트북 `python3 -m unittest scripts.tests.test_claude_setup`. 고치기 전
스킬에서 새 시험이 `--icon-size-*`로 실패했고, 고친 뒤 전부 통과한다.

Refs: 1112/04-15
2026-11-13 23:27:47 +09:00
DongHyeonka 5fa4ebe189 fix(design-system): 디자인 검사가 기능 CSS·gradient·인라인 style의 날 값을 잡는다
`check:design-system`이 잡지 못하는 길이 다섯 남았다(1101/12-03, 지금 위반
없음). gradient의 색상각 보간(`linear-gradient(in oklch, …)`)은 UI-02가
`color-mix`만 봐서 지난다. TSX 인라인 `color-mix`도 그렇다. 기능 폴더의 CSS는
아예 읽지 않는다. style sheet에서 `:root`로 토큰을 다시 정의해도, focus ring을
`outline-offset: 0`으로 그려 UI-01의 대비 계산 밖으로 내보내도 지난다. 그리고
primitive의 `className`·`style`이 범위 없이 열려 있어 화면이 primitive 위에
`style={{ color: "red", padding: 13 }}`을 얹어도 막는 것이 없다(04-14).

고른 방법: UI-02 정규식이 gradient의 색 공간까지 보고 TS·TSX 소스에도 돈다.
토큰 파일 밖 CSS는 `src/` 아래 전부를 읽고, 날 색·토큰 재정의·offset 0
focus ring을 거절한다. 04-14는 결정(2026-11-12, 총괄: 공개 props는 두고
검사를 더한다)대로 TSX `style={{ … }}`의 손 색(키워드·`var()` 말고)과 손
간격·글자·반경·층·그림자 값을 거절한다. `className`·`style`의 범위(배치용)를
`docs/styling/design-tokens.md`에 적고, fe-design-system 스킬의 「검사가 안
보는 것」 문장을 새 범위에 맞췄다. 거절 fixture `raw-inline-style.tsx`를
더했다. 버린 대안: primitive 공개 props에서 `style`을 빼기(배럴 표면 BREAKING).

위험·한계: 다운스트림이 기능 CSS나 인라인 style에 날 값을 두었으면 다음
동기화에서 그 줄이 이름과 함께 실패한다. 문자열로 조립한 class와 Tailwind
임의 값은 여전히 보지 않는다.

검증: 규칙 단위 시험, check-design-system 연결 시험(기능 폴더 probe CSS),
`check:design-system:fixture`(FE-GATE-029)는 desktop에서 돌려 PR 본문에 적는다.

Refs: 1101/12-03, 1112/04-14
2026-11-13 23:27:47 +09:00
DongHyeonka 838ed410f7 fix(styles): 스타일이 간격·글자·층·그림자 토큰을 읽고 검사가 날 값을 거절한다
셸·페이지 템플릿·카드 CSS가 간격·글자·반경·층·그림자 토큰을 건너뛰고 날
값을 쓴다(`src/presentation/styles/theme/*.css`에서 규칙에 걸리는 선언
118개). `shell.css`·`pages.css`·`templates.css`는 `var(--space-*)`를 한
번도 쓰지 않았고, z-index 100·30·10, 카드·헤더의 손 그림자, `999px`,
`min-height: 2.75rem`이 토큰과 같은 값을 다시 적었다. 필수 semantic 토큰
가운데 `--layer-navigation`·`--layer-modal`·`--opacity-scrim`·
`--opacity-skeleton`·`--elevation-panel`·`--color-disabled-content`·
`--color-action-pressed`를 읽는 스타일이 없었다. 그래서 파생 서비스가
밀도·층·그림자를 토큰으로 바꿔도 화면이 그대로다. 그리고 component.css의
가림막 토큰 셋이 `REQUIRED_COMPONENT_TOKENS`에 없어 UI-03 밖이었다(04-12).

고른 방법:
- 날 값을 토큰으로 바꾼다. 맞는 단계가 없는 간격은 가까운 `--space-*`로
  반올림했다(0.15~0.35rem → 1, 0.4~0.55 → 2, 0.65~0.85 → 3, 0.9 → 4).
  큰 값 3.5rem·4rem은 `--space-14`·`--space-16`을 더했다. 글자 크기도
  가까운 단계(0.8 → xs, 0.8125~0.9 → sm, 1.05 → md, 1.1 → lg, 1.35 → xl),
  굵기 600·650 → semibold, 700·750·800 → bold, 줄 높이 1.5~1.6 → normal,
  1.65·1.7 → relaxed. 페이지 h1은 semantic `--font-size-heading-1`·
  `--line-height-heading-1`(새 primitive 단계 3xl·4xl·compact)을 읽는다.
- 층: skip link는 `--layer-navigation`, sticky 헤더와 sticky 폼 버튼은
  `--layer-sticky`. 그림자: 카드·패널·갤러리 안내는 `--elevation-panel`,
  헤더는 새 `--elevation-sticky`(`--shadow-sticky`). `.ui-panel`의 Tailwind
  `shadow-sm`도 `--elevation-panel`로 바꿔 카드와 같은 높이가 됐다. dialog는
  `--radius-modal`, 가림막 비율은 `--opacity-scrim`을 읽고
  `--dialog-backdrop-weight`는 지웠다.
- 읽는 곳이 없던 semantic 토큰: skeleton 깜박임이 `--opacity-skeleton`,
  꺼진 입력이 `--color-disabled-content`·`--color-disabled-surface`, 누른
  primary 버튼이 새 component 토큰 `--button-primary-pressed`
  (`--color-action-pressed`)를 읽는다. `--layer-modal`은 native `<dialog>`가
  top layer에 열려 z-index가 닿지 않으므로 이유와 함께
  `SEMANTIC_TOKENS_WITHOUT_TEMPLATE_READER`에 둔다.
- `check:design-system`에 셋을 더한다. UI-06: styles 아래 간격·글자·반경·
  z-index·그림자의 날 값을 줄 번호와 함께 거절한다. UI-03을 필수 semantic
  토큰으로 넓힌다. component.css `@theme`의 토큰이 모두 계약에 있어야 한다.
  계약에 `--button-primary-pressed`, `--dialog-backdrop`,
  `--dialog-backdrop-on-surface`를 더했다.
- 버린 대안: 맞는 단계가 없는 값마다 primitive 단계를 더하기(단계가 두 배로
  늘어 scale이 무의미해진다). `--layer-modal`을 dialog에 z-index로 읽히기
  (top layer에서는 효과가 없는 가짜 읽기다).

위험·한계: 반올림과 패널 그림자 때문에 화면이 조금 바뀐다(간격 최대
0.15rem, 굵기 800 → 750, 패널 그림자 크기). 시각 골든은 이 커밋에서 다시
찍고 차이를 PR 본문에 적는다. 다운스트림이 styles에 날 값을 더해 두었으면
UI-06이 그 줄을 알린다. 너비·높이·위치(top 등)와 opacity는 UI-06 밖이다.

검증: 규칙 단위 시험과 check-design-system 연결 시험, 새 검사기로 고치기
전 CSS를 돌린 결과(RED), 시각 골든은 desktop에서 돌려 PR 본문에 적는다.

Refs: 1112/04-08, 1112/04-12
2026-11-13 23:27:47 +09:00
DongHyeonka b384d29ca5 refactor(tokens): semantic 색을 모두 팔레트에서 읽고 검사가 날 색을 거절한다
`semantic.css`가 팔레트를 거치지 않은 날 `oklch()` 36개를 정의한다(밝은
테마의 focus와 info·success·warning·danger 세 쌍 13개, 어두운 테마 23개).
`PRODUCT.md`와 `docs/styling/design-tokens.md`는 토큰이 primitive →
semantic → component로 파생되고 팔레트는 `primitive.css`에 있다고 적는다.
그래서 팔레트만 바꿔 리브랜드하면 status 색, focus, 어두운 테마 대부분이
그대로다.

고른 방법: 36개 값을 그대로 `primitive.css` 팔레트로 옮기고 semantic은
`var()`로 읽는다. 색상 이름 무리(slate·night·blue·sky·green·amber·red)마다
밝기 순서로 단계 이름을 붙였다. 값은 바꾸지 않아 화면은 같다. 그리고
`check:design-system`에 UI-07을 더한다: semantic 선언값이 날 색(#hex,
oklch·oklab·lch·lab·rgb·hsl·hwb·color 함수)이면 실패하고, 토큰과 위치를
말한다. 버린 대안: 문서에 "semantic은 역할 전용 값을 가질 수 있다"와 예외
목록을 적는 것(리브랜드 약속이 그대로 깨진다).

위험·한계: 다운스트림이 `semantic.css`에 날 색을 더해 두었으면 다음
동기화에서 UI-07이 그 줄을 이름과 함께 알린다. 팔레트로 옮기면 된다.
UI-01 대비 계산은 var 사슬을 따라가므로 그대로 돈다.

검증: 규칙 단위 시험(거절 다섯·통과 셋·저장소 파일)과 check-design-system
연결 시험의 RED·GREEN, 시각 골든 불변은 desktop에서 돌려 PR 본문에 적는다.

Refs: 1112/04-13
2026-11-13 23:27:47 +09:00
DongHyeonka 009a29918e style(shell): 지운 compact 사이드바의 CSS를 지운다
compact 내비게이션은 2026-11 셸 개편 뒤 Drawer다(`app-shell.tsx`). 그런데
`responsive.css`에 옛 고정 사이드바 배치, `[data-open="true"]`, 가림막
`.app-shell__scrim`(날 z-index 50·40, 가림막 35%)이 남았고 `pages.css`에도
scrim 규칙이 있었다. `data-open`을 세우거나 `app-shell__scrim`을 쓰는
TS·TSX는 0곳이다. 리브랜드할 때 가림막 정의가 둘로 보인다(dialog 55% 토큰,
죽은 35% 날 값).

고른 방법: 죽은 규칙을 지우고 compact의 `.app-shell__sidebar
{ display: none }`만 남긴다. 화면에 닿던 선언은 그것 하나였다.

검증: compact 시각 골든이 바뀌지 않는지 desktop test:visual로 본다(PR 본문).

Refs: 1112/04-17
2026-11-13 23:27:47 +09:00