docs(manual): loadingSurface가 로딩 모양이 아니라 이름표라고 적는다

라우트 계약의 `loadingSurface`는 로딩 표면의 `data-surface` 속성에만 쓰인다
(`src/presentation/routes/app-router.tsx` `RouteLoadingSurface`). 모든
라우트가 같은 `LoadingSurface`(skeleton 블록 하나)를 그린다. 그런데 매뉴얼은
이 값을 "로딩 화면 이름"으로 정하라고만 하고, fe-ux 스킬은 "loading surface가
실제 내용 모양(collection·detail·form)을 따른다"를 확인 항목으로 둔다. 기능
작성자는 효과 없는 값을 정하고, 리뷰어는 없는 약속을 본다.

고른 방법: 결정 R9-D5(2026-11-12, 총괄: 계약은 그대로, 문장을 동작에 맞춘다)대로
매뉴얼 1단계의 `loadingSurface` 설명과 fe-ux 확인 항목을 실제 동작(이름표,
모양은 고르지 않음, 내용 모양 skeleton이 필요하면 페이지가 그린다)으로
고친다. 버린 대안: `loadingSurface`를 닫힌 union(`collection`·`detail`·`form`)
으로 바꾸고 모양을 고르게 하기(라우트 계약·생성 출력·FE-REG-ROUTE 기준선을
바꾸는 계약 변경이다).

검증: RED 없음 — 문서를 동작에 맞춘 것이다. 이름표 동작은
`tests/component/route-status-surfaces.test.tsx` 첫 사례가 이미 고정한다
(`.route-loading[data-surface="fixture-page"]`). 노트북 `scripts/verify.sh
docs`, desktop `verify:documentation`(PR 본문).

Refs: 1112/04-04
This commit is contained in:
DongHyeonka
2026-11-13 18:45:16 +09:00
parent aa4bddac36
commit 48b2e50d46
2 changed files with 3 additions and 3 deletions
+2 -2
View File
@@ -48,8 +48,8 @@ paths:
상태
- [ ] 로딩·빈·오류·배경 갱신은 `AsyncSurface`, 로그인 필요·권한 없음·없음·점검은 `StatusPage`와 상태 화면이다. — `src/presentation/components/async-surface.tsx`, `src/presentation/components/state-surfaces.tsx`
- [ ] loading surface가 실제 내용 모양(collection·detail·form)을 따른다. reduced-motion에서 skeleton 움직임을 줄인다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.1절
- [ ] 예상 못 한 오류는 안전한 일반 문구 + 지원 참조(build id와 incident id)다. — 같은 문서 6.2절
- [ ] 라우트 로딩은 모든 라우트가 같은 `LoadingSurface`다. 라우트 계약의 `loadingSurface`는 그 표면의 이름표(`data-surface`)일 뿐 모양을 고르지 않는다(소유자 결정 2026-11-12). 데이터를 받는 동안 내용 모양을 따르는 skeleton이 필요하면 그 페이지가 그린다. reduced-motion에서 skeleton 움직임을 줄인다. — `src/presentation/routes/app-router.tsx` `RouteLoadingSurface`, `docs/manual/01-add-a-feature.md`
- [ ] 예상 못 한 오류는 안전한 일반 문구 + 지원 참조(build id와 incident id)다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.2절
문구
+1 -1
View File
@@ -436,7 +436,7 @@ projectRequest: (input) => Object.freeze({
① **정할 것**
- `access`: `public`(로그인 없이) 또는 `session-required`(로그인 필요).
- `loadingSurface`: 로딩 화면 이름. 케밥 표기.
- `loadingSurface`: 라우트 청크를 받는 동안 보이는 로딩 표면의 이름. 케밥 표기. 화면에는 `data-surface` 속성으로만 붙는다. 진단과 시험이 어느 라우트의 로딩인지 찾는 이름표이고, 로딩 모양은 고르지 않는다. 모든 라우트가 같은 `LoadingSurface`를 그린다(`src/presentation/routes/app-router.tsx`).
- `errorSurface`: `route-boundary`, `feature-boundary`, `not-found` 중 하나. 생성된 판은 `feature-boundary`다.
- `chunkId`: 지연 로드 청크 이름. 전역에서 유일해야 한다.
- `navigationOrder`: 메뉴 순서. `null`이면 메뉴에 나오지 않는다.