From 48b2e50d46e0ef43758e5626bf737b2ddbb88a88 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:41:15 +0900 Subject: [PATCH] =?UTF-8?q?docs(manual):=20loadingSurface=EA=B0=80=20?= =?UTF-8?q?=EB=A1=9C=EB=94=A9=20=EB=AA=A8=EC=96=91=EC=9D=B4=20=EC=95=84?= =?UTF-8?q?=EB=8B=88=EB=9D=BC=20=EC=9D=B4=EB=A6=84=ED=91=9C=EB=9D=BC?= =?UTF-8?q?=EA=B3=A0=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 라우트 계약의 `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 --- .claude/skills/fe-ux/SKILL.md | 4 ++-- docs/manual/01-add-a-feature.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/fe-ux/SKILL.md b/.claude/skills/fe-ux/SKILL.md index afa7fc08..b94a0fdb 100644 --- a/.claude/skills/fe-ux/SKILL.md +++ b/.claude/skills/fe-ux/SKILL.md @@ -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절 문구 diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 07093512..4ed75fe3 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -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`이면 메뉴에 나오지 않는다.