fix(presentation): 좁은 화면에서 테마 선택과 세션 상태를 메뉴 서랍에 둔다 (08-01)

문제: 폭 48rem 미만(휴대폰, 1280px 창의 약 170% 이상 확대)에서
responsive.css가 머리글의 색상 테마 선택, 세션 상태, 브랜드를
display: none으로 숨긴다. 메뉴 서랍에는 주요 탐색만 있어서 이 기능과
정보를 쓸 곳이 없다. WCAG 2.2 1.4.10(Reflow)의 "기능·정보 손실 없이"
조건을 어긴다.

고른 방법: 머리글은 지금처럼 두고, 서랍에 브랜드 이름(탐색 위)과 색상
테마 선택·세션 상태(탐색 아래)를 넣는다.
- 테마 선택과 세션 상태를 app-shell.tsx 안의 ThemePreferenceSelect,
  SessionStatus로 뽑아 머리글과 서랍이 같은 컴포넌트를 쓴다. 둘 다
  기존 ThemeProvider·SessionProvider를 직접 읽어 따로 든 상태가 없다.
- 서랍 쪽 select id는 mobile-theme-preference로 달리 줘서 id가 겹치지
  않는다. 머리글 #theme-preference는 그대로다(시각 테스트가 쓴다).
- 서랍 쪽은 라벨을 보이게 두고 theme-selector 클래스를 붙이지 않는다.
  그래서 i18n.spec의 "머리글 선택 상자 2개" 검사가 그대로 맞는다.
- 브랜드는 화면을 보고 서랍 위쪽에 링크가 아닌 글자로 넣었다. 서랍에
  "홈" 링크가 이미 있어 링크로 두면 같은 곳으로 가는 Tab 정지가 는다.
- 숨김 규칙(responsive.css)과 머리글(app-shell.tsx)에 서랍이 대신
  보여 준다는 주석을 달았다.

버린 대안:
- 머리글에 테마 아이콘 메뉴 버튼(리뷰 5.3 (C)): 새 컴포넌트가 필요하고
  320px 머리글 공간을 다툰다. 머리글은 단순하게 두기로 정했다.
- 서랍이 열릴 때만 서랍 쪽 컨트롤을 렌더: DOM 중복은 없어지지만 탐색은
  항상, 나머지는 조건부로 그리는 이유가 코드에 드러나지 않는다. 탐색이
  이미 사이드바와 서랍에 두 벌 있는 방식에 맞췄다.
- 서랍 제목을 앱 이름으로 바꾸기: 대화상자 이름 "메뉴"가 바뀌어 기존
  접근성 이름과 테스트가 깨진다.

위험·한계:
- 세션 상태 문구와 테마 select가 DOM에 두 벌 있다. 접근성 트리에는
  한 번만 나온다(좁은 폭은 머리글 쪽이 display: none, 넓은 폭은 닫힌
  dialog). 다만 페이지 전체에서 getByText로 셸 문구를 찾는 테스트는
  strict mode에 걸린다. reference-route.spec의 "인증됨"을 banner로
  좁혔다. 다운스트림 테스트도 같은 수정이 필요할 수 있다.
- 640x400(200% 확대)에서는 테마 선택이 서랍 첫 화면 아래에 있어 서랍을
  스크롤해야 보인다.
- 좁은 화면 서랍 화면이 바뀐다. 시각 골든
  app-shell-compact-pseudo-drawer.png는 이 커밋에서 갱신하지 않았다.
- 초기 JS gzip 203,572 -> 203,648 B(+76 B, 예산 204,800 B). check:bundle은
  pnpm을 불러 돌리지 않았고, 같은 분류(classifyViteJavascript)와
  gzipSync로 직접 쟀다.
- 실제 기기 터치, 스크린 리더 발표는 확인하지 않았다.

검증:
- RED: tests/e2e/responsive.spec.ts 새 테스트(320·375·640px)가 수정 전
  chromium·firefox·webkit 9/9 실패. getByRole('dialog', { name: '메뉴' })
  .getByRole('combobox', { name: '색상 테마' }): element(s) not found.
- GREEN: 같은 테스트 9/9 통과. 마지막 탐색 링크에서 Tab으로 테마 선택에
  닿고, dark·light 선택에 html[data-theme]이 바뀐다. 서랍에 "로그인 전"과
  브랜드가 보인다.
- 회귀 e2e: responsive·i18n·theme·accessibility·app-shell·reference-route
  (세 엔진) + compact-smoke(chromium-compact) 85/85 통과. app-shell.spec의
  Esc 닫기·포커스 복원·서랍 링크 뒤 h1 포커스 포함. 수정 전에는
  reference-route가 세 엔진에서 strict mode로 실패하는 것을 확인했다.
- 열린 서랍 axe(375px, light·dark, 세 엔진) 위반 0(일회성, 커밋 안 함).
- node scripts/run-vitest.ts run tests/component: 211/211 통과.
- tsc(app·test·node) 0, eslint(바꾼 tsx·spec) 0, check-design-system
  PASS, check-architecture(pnpm 대신 exec 전용 shim) PASS.
- Playwright는 webServer만 `npx vite preview`로 바꾼 임시 설정으로
  돌렸다(빌드는 node scripts/build-frontend.ts).

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-01
This commit is contained in:
DongHyeonka
2026-11-01 20:32:47 +09:00
parent 4b646f687f
commit d2a882fde6
5 changed files with 99 additions and 19 deletions
+45 -18
View File
@@ -38,7 +38,6 @@ export function AppShell() {
const location = useLocation();
const { sessionState } = useSession();
const sessionAction = useSessionAction();
const { preference, setPreference } = useTheme();
const { locale, setLocale, message } = useLocale();
const [navigationOpen, setNavigationOpen] = useState(false);
const navigationTriggerRef = useRef<HTMLButtonElement | null>(null);
@@ -75,21 +74,10 @@ export function AppShell() {
<NavLink className="app-shell__brand" to={routePath("APP_HOME")}>
{message("common.appName")}
</NavLink>
{/* Below 48rem `responsive.css` hides the brand, the theme selector
and the session status here; the menu drawer shows them (08-01). */}
<div className="app-shell__session">
<Select
className="theme-selector"
id="theme-preference"
label={message("shell.theme")}
options={[
{ value: "system", label: message("shell.theme.system") },
{ value: "light", label: message("shell.theme.light") },
{ value: "dark", label: message("shell.theme.dark") },
]}
value={preference}
onChange={(event) =>
setPreference(normalizeColorSchemePreference(event.currentTarget.value))
}
/>
<ThemePreferenceSelect className="theme-selector" id="theme-preference" />
<Select
className="locale-selector"
id="locale-preference"
@@ -105,9 +93,7 @@ export function AppShell() {
setLocale(normalizeLocale(event.currentTarget.value))
}
/>
<span className="session-status" data-state={sessionState}>
{message(SESSION_MESSAGE_KEYS[sessionState])}
</span>
<SessionStatus />
{integrationAvailable ? (
<Button
disabled={sessionAction.pending}
@@ -147,12 +133,17 @@ export function AppShell() {
returnFocusRef={navigationTriggerRef}
title={message("shell.menu")}
>
<p className="app-shell__drawer-brand">{message("common.appName")}</p>
{/* Close before the route commits: while the modal is open the page
is inert and the new route cannot take focus. */}
<PrimaryNavigation
id="mobile-primary-navigation"
onNavigate={() => setNavigationOpen(false)}
/>
<div className="app-shell__drawer-preferences">
<ThemePreferenceSelect id="mobile-theme-preference" />
<SessionStatus />
</div>
</Drawer>
<main className="app-shell__content" id="main-content" tabIndex={-1}>
<Outlet />
@@ -161,6 +152,42 @@ export function AppShell() {
);
}
// Drawn in the header and in the menu drawer. Both copies read the same
// provider, so neither keeps its own state; only the element id differs.
function ThemePreferenceSelect({
id,
className,
}: Readonly<{ id: string; className?: string }>) {
const { preference, setPreference } = useTheme();
const { message } = useLocale();
return (
<Select
className={className}
id={id}
label={message("shell.theme")}
options={[
{ value: "system", label: message("shell.theme.system") },
{ value: "light", label: message("shell.theme.light") },
{ value: "dark", label: message("shell.theme.dark") },
]}
value={preference}
onChange={(event) =>
setPreference(normalizeColorSchemePreference(event.currentTarget.value))
}
/>
);
}
function SessionStatus() {
const { sessionState } = useSession();
const { message } = useLocale();
return (
<span className="session-status" data-state={sessionState}>
{message(SESSION_MESSAGE_KEYS[sessionState])}
</span>
);
}
function PrimaryNavigation({
id,
onNavigate,
@@ -41,6 +41,8 @@
cursor: pointer;
}
/* 08-01. Hidden only in the header: the menu drawer (`app-shell.tsx`)
shows the session status, the theme selector and the brand instead. */
.app-shell__session .session-status {
display: none;
}
+14
View File
@@ -66,6 +66,20 @@
white-space: nowrap;
}
/* 08-01. The narrow header drops these; the menu drawer carries them. */
.app-shell__drawer-brand {
margin: 0 0 0.75rem;
font-weight: 800;
}
.app-shell__drawer-preferences {
display: grid;
gap: 0.75rem;
margin-top: 1rem;
padding-top: 1rem;
border-top: 1px solid var(--color-border);
}
.app-shell__menu-button {
display: none;
align-items: center;
+2 -1
View File
@@ -28,7 +28,8 @@ test("opens the protected integration route through the local demo seam", async
await expect(
page.getByRole("heading", { name: protectedRoute.title }),
).toBeVisible();
await expect(page.getByText("인증됨")).toBeVisible();
// The closed menu drawer holds a second copy of the status (08-01).
await expect(page.getByRole("banner").getByText("인증됨")).toBeVisible();
// The mocked row went through the production codec, mapper and query cache.
await expect(page.getByText("Browser reference")).toBeVisible();
});
+36
View File
@@ -19,6 +19,42 @@ test("reflows the UI gallery at the 320px minimum without horizontal overflow",
expect(viewport.scrollWidth).toBeLessThanOrEqual(viewport.clientWidth);
});
// 08-01. Below 48rem the header hides the theme selector, the session status
// and the brand. WCAG 1.4.10 allows moving them, not dropping them: the menu
// drawer carries them. 640px is a 1280px window at 200% zoom.
for (const width of [320, 375, 640]) {
test(`keeps the theme selector and session status in the menu drawer at ${width}px`, async ({
page,
}) => {
await page.setViewportSize({ width, height: 720 });
await page.goto("/");
await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
await page.getByRole("button", { name: "메뉴", exact: true }).click();
const drawer = page.getByRole("dialog", { name: "메뉴" });
await expect(drawer).toBeVisible();
const theme = drawer.getByRole("combobox", { name: "색상 테마" });
await expect(theme).toBeVisible();
// Keyboard reach: the selector follows the last navigation link.
await drawer
.getByRole("navigation", { name: "주요 탐색" })
.getByRole("link")
.last()
.focus();
await page.keyboard.press("Tab");
await expect(theme).toBeFocused();
await theme.selectOption("dark");
await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
await theme.selectOption("light");
await expect(page.locator("html")).toHaveAttribute("data-theme", "light");
await expect(drawer.getByText("로그인 전", { exact: true })).toBeVisible();
await expect(
drawer.getByText("Frontend Skeleton", { exact: true }),
).toBeVisible();
});
}
test("keeps desktop navigation and two-column examples at wide viewports", async ({
page,
}) => {