Files
clean-architecture-frontend…/docs
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
..

docs

저장소의 문서는 이 폴더 아래에 있다(루트 README.md, CHANGELOG.md 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.

  • 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
  • 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.

규칙의 정본은 design-docs 저장소의 conventions/docs-system.md다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다. 파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.

문서와 코드가 다르면 코드가 맞다.

1. 문서 지도

  • 표의 첫 칸이 폴더다(docs/ 기준 경로).
  • 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
  • 문서 검사의 map이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).

처음 읽을 문서

문서 정하는 것
../AGENTS.md 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 scripts/verify.sh
work/, work/reference/ 작업 매뉴얼: 맡은 일마다의 playbook과 기준(완료 기준은 work/improve.md 5절)
README.md 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
manual/ 새 기능을 더하는 순서와 판단 기준, create:feature(manual/reference/)
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

매뉴얼

일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.

폴더 무엇
work/ 작업 매뉴얼: 새 기능, 리뷰·수정·리팩터링, 조사·설계, 문서, 운영, 일 나누기의 playbook. work/reference/에 게이트·구조·테스트·리뷰 기준과 결정 색인, work/evidence.md에 매뉴얼 규칙의 근거 기록
manual/ 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. manual/reference/에 명령 인자, 전역 ID, 패턴, 오류 메시지
ledger/ 작업 예측·실측 장부(ledger/estimates.jsonl, 형식은 ledger/README.md)

현재 계약

지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.

폴더 무엇
architecture/ 계층과 import 규칙(architecture/layers.md), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(architecture/scale-architecture.md, 코드 주석의 scale-architecture.md §N이 가리킨다), 짝 백엔드 계약(architecture/backend-api-and-server-state-contract.md 4.1·6·6.1절이 실행 규칙. 기준 커밋은 config/contracts/backend-contract-pin.json), 2026-07-18 도식 리뷰 기록의 사본(architecture/review-evidence.md, architecture/review-ledger.json)
contracts/ 계약 호환 규칙(읽는 쪽을 먼저 배포한다)
security/ 브라우저 보안 경계와 공급망
styling/ 디자인 토큰
accessibility/ 수동 접근성 검토 체크리스트와 라우트별 검토 기록(accessibility/route-reviews/)
testing/ 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선

운영

폴더 무엇
operations/ CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(operations/adapter-remediation-ledger.md)
runbooks/ 오류 code별 장애 대응 runbook(FE-RB-00N). 등록은 config/runbooks/runbooks.json

결정 기록

폴더 무엇
adr/ 결정 기록(VD). 번호는 옮기기 전과 같다(VD-NN-<주제>.md). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다

설계와 기록

설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.

폴더 무엇
design/ 설계서. YYYY-MM-DD-<주제>-design.md. 2026-11-08에 옛 superpowers 폴더의 specs와 architecture/의 목표 설계를 옮겼다
history/plans/ 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(SPEC.md)과 작업 목록도 여기 있다
history/evidence/ 작업 단계의 증거·체크포인트
reviews/ 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다
  • 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
  • history/와 reviews/는 복사한 프로젝트가 지워도 된다(루트 README.md 「복사한 뒤 지워도 되는 것」). 예외는 reviews/adapters/다: reviews/adapters/INVENTORY.md는 check:adapter-inventory(FE-GATE-010)가 src/adapters와 대조하는 살아 있는 목록이다.
  • design/과 adr/은 코드 주석이 근거로 가리키므로 지우지 않는다.

폴더 밖 문서

문서 무엇
../README.md 루트 README. 6절의 필수 절을 가진다
../CHANGELOG.md 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다
../AGENTS.md 규칙의 정본과 지도. src/ 계층 폴더마다 지역 규칙 AGENTS.md가 있다
루트 CLAUDE.md AGENTS.md를 가져오고 Claude Code 전용 줄만 둔다. 경로별 규칙·스킬·서브에이전트는 .claude/
vision.md, problem-statement.md 비전과 문제 정의. 소유자가 채우는 양식이다
루트 PRODUCT.md 디자인 도구가 읽는 제품 맥락
../src/adapters/browser-transfer/image-cdn/README.md Image CDN adapter의 모듈 README

게이트가 읽는 파일

지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
라우트별 수동 접근성 기록(accessibility/route-reviews/<ROUTE_ID>.md) verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)
architecture/backend-api-and-server-state-contract.md 6.1절 표 tests/unit/backend-contract-pin-document.test.ts (FE-GATE-005)
architecture/starter-experience.md의 기능 폴더 밖 파일 표, manual/03-outside-feature-folder.md A절 tests/unit/feature-tracked-files.test.ts (FE-GATE-005)
manual/의 표시한 코드 블록과 manual/04-paired-backend-session.md 3.2절 tests/unit/manual-code-blocks.test.ts, tests/unit/manual-paired-backend-settings.test.ts (FE-GATE-005)

2. 문서 수명과 언어

수명 문서 위치 언어 고치는 법
살아 있음 README, AGENTS.md(루트와 src/ 계층 폴더), CLAUDE.md, .claude/의 규칙·스킬, 매뉴얼(work/, manual/), 장부(ledger/), vision.md·problem-statement.md, 현재 계약(architecture/, contracts/, security/, styling/, accessibility/, testing/), 운영(operations/, runbooks/), reviews/adapters/INVENTORY.md, 모듈 README, CHANGELOG.md 제자리 한국어 코드와 같은 변경에서 고친다(4절)
결정 결정 기록(VD) adr/ 한국어 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다
기록 설계서, 계획서, 증거, 리뷰 design/, history/, reviews/ 머리 블록은 한국어, 본문은 쓴 때의 원문 머리 블록의 칸만 고친다
  • 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
  • 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
  • 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
  • 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
  • 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
  • accessibility/route-reviews/의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(scripts/lib/manual-a11y-evidence.ts). 문서 검사가 보지 않는다.

3. 기록 문서의 머리 블록

design/, history/, adr/의 .md 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
  • 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: design/ 설계서, history/plans/ 계획서, history/evidence/ 증거. 결정 기록(adr/)의 둘째 줄은 > **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.

  • 상태는 종류마다 고정 어휘다.

    종류 상태
    설계서 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함
    결정 기록 제안 · 채택 · 채택(보완) · 폐기 · 대체됨
    계획서 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함
    증거 보관
  • 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.

  • 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.

  • 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).

  • 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.

  • .md가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.

  • 리뷰(reviews/)는 아직 머리 블록을 요구하지 않는다.

4. 문서와 코드를 같은 변경에서 고친다

  • 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: git grep -n '<바꾼 이름>' -- '*.md'.
  • 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 CHANGELOG.md에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 > 이력 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
  • 숫자·버전을 복사하지 않는다. 프레임워크 버전은 package.json과 .nvmrc, 게이트 목록은 config/ci/gates.json, recipe 목록은 config/recipes/frontend-capability-recipes.json, adapter 파일 목록은 reviews/adapters/INVENTORY.md를 가리킨다.
  • 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs conventions/docs-system.md 6.1절이고, 문서 검사의 readme가 그 목록(scripts/lib/docs-system.ts의 README_SECTIONS)을 본다.

5. 문서 검사

verify:documentation(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.

  • pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 tests/unit/documentation-readiness.test.ts가 이 repo를 그대로 두고 verify:documentation을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(config/ci/gates.json의 documentation_gate).
검사 보는 것
language 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정)
head 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지
document references 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다
number 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, CHANGELOG.md는 보지 않는다
map 이 README의 1절 지도가 docs/ 아래 모든 폴더를 덮는가(표 첫 칸의 폴더/). 파일 없이 폴더만 가진 묶음 폴더(history/)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다
readme 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 ## 절을 정해진 순서로 가지는가
style 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, > 이력 블록은 보지 않는다
  • 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 src/ 폴더 설명(architecture/layers.md 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
  • 규칙과 판정의 정본은 scripts/lib/docs-system.ts(검사 여섯)와 scripts/verify-documentation-readiness.ts(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 check-docs.py)를 같은 이름·문턱으로 옮긴 것이다.
  • 검사 자신의 시험: tests/unit/docs-system.test.ts, tests/unit/documentation-readiness.test.ts.
  • 예외 목록 scripts/docs-system-exceptions.txt는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 scripts/lib/docs-system.ts의 FROZEN에 지문이 있어야 하는데, FROZEN이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
  • 복사한 프로젝트가 지운 기록(history/, reviews/)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
  • 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.