- 상태: In sync (2026-09-26)
- 상위:
SYSTEM.md· 문서 우선순위:sot-priority.md
토큰·컴포넌트·패턴·문구를 바꾸는 일은 한 화면이 아니라 앱 전체에 번진다. 아래 순서를 지키면 "왜 이렇게 됐지?"를 나중에 다시 묻지 않아도 된다.
| 바꾸는 것 | 흐름 | 예 |
|---|---|---|
| 새 토큰(색·크기·모션), 토큰 값 변경 | 제안부터 | 새 상태색, 글자 크기 추가 |
새 ui/ 컴포넌트, 기존 컴포넌트의 variant·size 추가 |
제안부터 | EmptyState, Button size="lg" |
| 새 패턴 또는 패턴 결정 트리 변경 | 제안부터 | 확인 단계 추가 기준 변경 |
| 기존 규칙대로 화면 만들기·고치기 | PR 체크리스트만 | 새 모달에 StateMessage 쓰기 |
| 문구 한두 줄 | PR 체크리스트만 | 오류 문구 다듬기 |
- 제안 — GitHub 이슈 "시스템 변경" 템플릿(라벨
system-change). 무엇이 필요한지, 기존 것으로 왜 안 되는지, 대안. - 결정 — 이슈에서 한 명 이상 동의. 급하면 PR 리뷰에서 함께 해도 된다. 결정과 이유는 해당 문서의 결정 기록 절에 날짜와 함께 남긴다(Phase A~F 방식).
- 문서 먼저 — 코드보다 문서를 먼저 고친다: 토큰 →
docs/foundations.md, 컴포넌트 → JSDoc +Name.meta.ts, 패턴 →docs/patterns/*.md, 문구 →docs/copy.md. - 코드 —
main.css·컴포넌트·화면을 맞춘다. 새ui/컴포넌트는 스토리를 함께. - 검증 — PR 에서 CI(검수 5종)가 돈다. 화면이 바뀌면 전/후 스크린샷, 스토리는 Storybook Accessibility 패널에서 위반 0.
yarn tokens:check 가 CI 에서 매 PR 마다 돈다 — 토큰 밖 클래스·대비·모션, 컴포넌트 meta 누락, 패턴 위반(confirm/alert·손 스피너·라벨 바꿔치기·하드코딩 색), 문구(습니다체·...·폐기 용어). 생성 파일(docs/registry.md, docs/tokens/contrast-matrix.md)이 커밋본과 다르면 CI 가 실패한다 — 로컬에서 yarn tokens:check 후 함께 커밋한다.