디자인 시스템 배럴(`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
화면 문구 셋이 어긋난다.
- 상태 화면 문구가 템플릿 개발자용이다(04-01). 생성 기능은 모두
`session-required`라 로그인 전 최종 사용자에게 "이 화면은 인증 연동 지점을
확인하기 위한 보호 라우트입니다."가 보인다. 끈 기능 화면은 "코드에는
포함되어 있으며 운영자가 다시 켤 수 있습니다.", 연동 실패 화면은 "외부 인증
소유자가 연결되면…"이다.
- 숫자를 locale formatter 없이 그린다(04-03). 생성 목록이 "총 12345개 항목"을
그리고, TextArea는 en에서 남은 1자도 "1 characters remaining"이다.
- ko·en 뜻이 다르다(04-07). en `form.conflict`에 "최신 상태를 확인해 주세요"가
없고, en 문서 제목 "Page not found"와 h1 "Page not found."가 다르다.
ErrorSummary가 번역 문장 사이에 JSX 글자 ": "를 넣는다.
고른 방법: 세 설명을 사용자 말("이 화면을 보려면 로그인해 주세요." 등)로 바꾸고
운영 설명은 뺐다. 생성 목록은 `useLocale().number(total)`을 넘긴다. TextArea는
`plural`로 `form.remaining.one`(en 단수)과 `form.remaining`을 고른다. en 충돌
문구에 행동을 더하고 not-found 제목을 h1과 같게 했다. 오류 요약 항목은
`form.errorSummary.item` "{label}: {message}"로 잇는다. 연동 실패 화면의 제목
"로그인 연동이 필요합니다."는 짝 백엔드 매뉴얼이 그 글자로 가리켜 그대로 뒀다.
검증 V4가 반박한 부분(세 화면에 행동 버튼이 없다, ProgressBar `%`)은 고치지
않았다: 셸 탐색이 늘 있고, `%`는 ko·en 결과가 같다.
위험·한계: 다운스트림이 이 키의 옛 문장을 시험으로 고정했으면 문장을 바꾼다.
이미 생성한 기능의 목록 페이지는 `count: query.data.total`을 그대로 갖는다.
`number(query.data.total)`로 바꾸면 된다(생성 명령의 새 출력과 같다).
검증: `tests/unit/i18n-contract.test.ts`(개발자 낱말, not-found 제목, 항목
문장), `tests/component/design-system-a11y.test.tsx`(en 단수·복수),
`tests/unit/create-feature.test.ts`(생성 목록의 `number(`)가 고치기 전에
실패하고 고친 뒤 통과한다. 생성 기능 시험의 total 12345 → "총 12,345개 항목"은
FE-GATE-005가 돌린다(desktop, PR 본문).
Refs: 1112/04-01, 1112/04-03, 1112/04-07
앞 커밋(1112/01-01) 뒤 확인 리뷰가 완료 기준의 남은 셋과 결함 둘을 찾았다.
- 생성 작성 페이지에 마운트 표시(useRef)와 저장 뒤 이동이 남았다. 저장이
끝나면 페이지가 폼보다 먼저, 폼이 pending인 동안 상세로 옮겼다. 다시
마운트한 폼에서 재전송이 성공하면 사용자가 돌아와 입력한, 보낸 적 없는
값을 이탈 확인 없이 버렸다(1112/01-02 영향).
- 폼이 재전송 결과로 결과 불명을 다시 판정했다(resendLeftUnknown).
코디네이터와 401에서 갈린다. 코디네이터는 결과 불명을 쥐고 폼은 다시
로그인으로 가는데, FormSaveFeedback이 결과 불명을 먼저 그려 다시 로그인
안내를 가렸다(D-2 위반).
- 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 생성 페이지 시험에만
있었다.
고른 방법: useAppForm에 onSaved를 더한다(추가만). 폼이 결과를 보이고
pending을 끈 뒤, 마운트된 동안만 부른다. confirmUnknownEffect(then)도
마운트된 동안만 then을 부른다. resendUnknownEffect의 then 인자와
FormSaveFeedback의 onResent는 지운다(앞 커밋에서 생겨 아직 내보낸 적이
없다). 재전송 뒤 결과 불명인지는 코디네이터의 새 holdsUnknownEffect로
묻는다. mutation 없이 쓰는 폼(이미 생성한 페이지)은 물을 곳이 없어 같은
거절 표(isRefusedOnEveryAttempt)로 본다. FormSaveFeedback은 다시 로그인
실패를 결과 불명보다 먼저 그린다. 생성 페이지는 mutation.submit을 그대로
넘기고 onSaved와 onConfirmed에서 옮기기만 한다. VD-04 머리 칸에 넣었던
문장은 보완 절로 옮긴다(머리 칸의 백틱 낱말을 문서 검사가 경로로 본다).
페이지가 FormSaveFeedback을 늘 넘기므로, 할 말이 없는 피드백 칸은 자리를
차지하지 않는다(templates.css, 빈 칸이 그리드 간격을 한 줄 더했다).
위험·한계: 저장 뒤 이동이 폼이 결과를 그린 뒤로 한 번 늦어진다. 다시
마운트한 폼에 보내지 않은 값이 있으면 이동이 이탈 확인을 띄운다(의도).
검증: form-foundation 새 시험 일곱과 create-feature 생성 페이지 시험
(RED·GREEN, 막기·다른 저장·충돌 안내 변이 셋), 생성 기능 e2e의 피드백 칸 간격 시험은 desktop에서 돌려 PR
본문에 적는다.
Refs: 1112/01-01, 1112/01-02, 1105/08-02, 1105/08-04, 1106/08-02, 1112/04-02
결과 불명 상태를 코디네이터(useApplicationMutation)와 폼(useAppForm)이
따로 갖고, 둘을 맞추는 규칙은 생성 작성 페이지의 사본에 있다: 결과 불명·
다른 저장 중 새 저장 막기, 「변경됨으로 확인」 뒤 settleApplied, 같은 키
재전송, 다른 저장이 도는 동안의 표시. 그래서 플랫폼에서 고친 것(1105/08-02,
1105/08-04, 1106/08-02)이 이미 생성한 기능에 들어가지 않는다(1112/01-01).
같은 구조에서 셋이 더 나온다.
- 재전송이 쓰기 전에 거절되거나(429·503) 선언한 409가 나면 "입력 내용을
확인해 주세요." 요약 아래 나온다(1112/04-02).
- 폼 밖에서 부른 같은 입력이 NOT_APPLIED로 끝나면 훅은 결과 불명인데 폼은
다시 시도를 보인다(1106/03-01 ②).
- 필드 이름이 붙은 결과 불명(VALIDATION_REJECTED + MAYBE_APPLIED)이 필드
오류와 결과 불명 화면을 함께 띄운다(1101/03-04).
고른 방법(R9-D1, 권하는 안으로 정함(2026-11-12, 총괄)): useAppForm에 선택
옵션 mutation을 더한다(추가만). 주면 폼이 saveBlocked로 새 저장을 막고
confirmUnknownEffect·resendUnknownEffect를 내주며, 입력 오류가 아닌 저장
안내를 notice로 둔다. 새 FormSaveFeedback이 결과 불명 → 저장 실패 → 충돌 →
다른 저장 순으로 피드백을 그리고, AsyncSurface의 새 notice 칸에 재전송 거절
안내를 보인다. 결과 불명을 코디네이터 상태로 먼저 보므로 ②도 같은 화면이
된다. 폼은 MAYBE_APPLIED를 입력 오류보다 먼저 본다. 생성 작성 페이지는 이
둘을 쓰고 자기 사본을 지운다. mutation을 주지 않은 폼은 전과 같다. 버린
대안: 판정 hook을 따로 두고 폼은 그대로(사본이 하나 더 생긴다).
위험·한계: 이미 생성한 기능은 바뀌지 않는다. CHANGELOG에 생성 페이지를
옮기는 방법을 적는다. 다시 마운트한 폼이 mutation 없이 쓰이면 ②는 그대로다.
VD-04 결정 5의 범위(선언하지 않은 409만)는 머리 블록에 적었다(1103/03-01 (3)).
검증: tests/component/form-foundation.test.tsx의 새 시험 넷(막기, 확인,
재전송 거절 표면, 결과 불명 우선)과 create-feature.test.ts의 생성 페이지
시험이 고치기 전 코드에서 실패하고 고친 뒤 통과한다. 생성 페이지는
FE-GATE-020 scaffold 드릴과 FE-GATE-008 e2e가 돈다(PR 본문).
Refs: 1112/01-01, 1112/04-02, 1106/03-01, 1101/03-04, 1103/03-01
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.
고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.
위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).
검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
reference-page 3. 예: "Unable to find an element with the text: 지원
참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
59 files 336 tests 통과. e2e reference-save·reference-form·
reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
check-i18n, check-design-system 통과.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.
고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.
위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).
검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
[ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
eslint 통과. e2e accessibility·typography·reference-form·reference-save
chromium 27/27.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
Save failures outside sign-in, permission and retry still went into
ErrorSummary under "review the entered information". They now reach
FormFailureStatus with their own copy and action; the unused copy is gone.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every non-input save failure became "unavailable" under the "review the entered
information" summary, with no sign-in button. useAppForm now reports
reauth-required, forbidden and retry-later with the failure, and
FormFailureStatus shows each one's copy and action outside ErrorSummary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>