test(visual): 갤러리를 Storybook story로 옮기고 골든 대상을 바꾼다
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).
두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.
위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.
검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
This commit is contained in:
@@ -0,0 +1,442 @@
|
||||
import type { Meta, StoryObj } from "@storybook/react-vite";
|
||||
import { useState, type FormEvent } from "react";
|
||||
|
||||
import { deriveAsyncState } from "../../application/view-models/async-state.ts";
|
||||
import { createFailure } from "../../contracts/errors.ts";
|
||||
import {
|
||||
Alert,
|
||||
AsyncSurface,
|
||||
AuthRequiredSurface,
|
||||
Badge,
|
||||
Button,
|
||||
Card,
|
||||
Checkbox,
|
||||
Dialog,
|
||||
EmptySurface,
|
||||
ForbiddenSurface,
|
||||
LoadingSurface,
|
||||
Menu,
|
||||
NotFoundSurface,
|
||||
PageHeader,
|
||||
ProgressBar,
|
||||
RadioGroup,
|
||||
Select,
|
||||
Switch,
|
||||
Tabs,
|
||||
TerminalErrorSurface,
|
||||
TextArea,
|
||||
TextField,
|
||||
ToastProvider,
|
||||
Tooltip,
|
||||
useToast,
|
||||
} from "./index.ts";
|
||||
|
||||
/**
|
||||
* The design-system gallery and the screen-state gallery. They were the
|
||||
* template's example screens `/examples/ui` and `/examples/states`; the
|
||||
* visual goldens `design-system-gallery-dark` and `state-surfaces-light`
|
||||
* (tests/visual/platform.visual.spec.ts) and the workshop tests
|
||||
* (tests/storybook/galleries.spec.ts) open these stories in the static
|
||||
* Storybook build. The primitives keep their own suites; these stories show
|
||||
* them together, with the tokens they draw with.
|
||||
*/
|
||||
const meta = {
|
||||
title: "Platform/Galleries",
|
||||
parameters: {
|
||||
layout: "fullscreen",
|
||||
// Drawn like a route page: the preview's `main` adds no page of its own.
|
||||
page: true,
|
||||
},
|
||||
} satisfies Meta;
|
||||
|
||||
export default meta;
|
||||
type Story = StoryObj<typeof meta>;
|
||||
|
||||
export const DesignSystem: Story = {
|
||||
render: () => <DesignSystemGallery />,
|
||||
};
|
||||
|
||||
export const ScreenStates: Story = {
|
||||
render: () => <ScreenStateGallery />,
|
||||
};
|
||||
|
||||
const COLOR_TOKENS = Object.freeze([
|
||||
["Surface", "--color-surface"],
|
||||
["Muted surface", "--color-surface-muted"],
|
||||
["Content", "--color-content"],
|
||||
["Muted content", "--color-content-muted"],
|
||||
["Action", "--color-action"],
|
||||
["Danger", "--color-danger"],
|
||||
["Focus", "--color-focus"],
|
||||
]);
|
||||
|
||||
function DesignSystemGallery() {
|
||||
return (
|
||||
<ToastProvider>
|
||||
<UiGalleryContent />
|
||||
</ToastProvider>
|
||||
);
|
||||
}
|
||||
|
||||
function UiGalleryContent() {
|
||||
const toast = useToast();
|
||||
const [projectName, setProjectName] = useState("");
|
||||
const [description, setDescription] = useState("");
|
||||
const [template, setTemplate] = useState("application");
|
||||
const [reviewed, setReviewed] = useState(false);
|
||||
const [notifications, setNotifications] = useState(true);
|
||||
const [density, setDensity] = useState("comfortable");
|
||||
const [fieldTouched, setFieldTouched] = useState(false);
|
||||
const [dialogOpen, setDialogOpen] = useState(false);
|
||||
const [notice, setNotice] = useState(
|
||||
"구성요소를 조작하면 결과가 여기에 표시됩니다.",
|
||||
);
|
||||
const [alertVisible, setAlertVisible] = useState(true);
|
||||
const fieldError =
|
||||
fieldTouched && projectName.trim().length === 0
|
||||
? "프로젝트 이름을 입력해 주세요."
|
||||
: undefined;
|
||||
|
||||
function submitExample(event: FormEvent<HTMLFormElement>): void {
|
||||
event.preventDefault();
|
||||
setFieldTouched(true);
|
||||
if (projectName.trim().length === 0) {
|
||||
setNotice("입력값을 확인해 주세요.");
|
||||
return;
|
||||
}
|
||||
setNotice(`“${projectName.trim()}” 입력을 확인했습니다.`);
|
||||
}
|
||||
|
||||
return (
|
||||
// 08-07. Example copy is Korean in every locale (outside the catalog).
|
||||
<section className="ui-page" lang="ko-KR">
|
||||
<PageHeader
|
||||
title="UI 구성요소"
|
||||
description="제품 도메인과 독립적인 공통 컨트롤, 피드백, 표면과 디자인 토큰을 직접 조작할 수 있습니다."
|
||||
/>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="controls-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="controls-title">버튼과 입력</h2>
|
||||
<p>키보드, 비활성 상태, 오류 설명을 포함한 기본 상호작용입니다.</p>
|
||||
</header>
|
||||
<div className="component-grid component-grid--two">
|
||||
<Card title="버튼" description="의미와 위험도에 따라 변형을 선택합니다.">
|
||||
<div className="button-row">
|
||||
<Button onClick={() => setNotice("기본 작업을 실행했습니다.")}>
|
||||
기본 작업
|
||||
</Button>
|
||||
<Button
|
||||
variant="secondary"
|
||||
onClick={() => setNotice("보조 작업을 실행했습니다.")}
|
||||
>
|
||||
보조 작업
|
||||
</Button>
|
||||
<Button
|
||||
variant="danger"
|
||||
onClick={() => setNotice("위험 작업 예제를 선택했습니다.")}
|
||||
>
|
||||
위험 작업
|
||||
</Button>
|
||||
<Button disabled>사용 불가</Button>
|
||||
</div>
|
||||
</Card>
|
||||
<Card title="입력창" description="레이블과 도움말, 오류가 입력에 연결됩니다.">
|
||||
<form className="example-form" noValidate onSubmit={submitExample}>
|
||||
<TextField
|
||||
label="프로젝트 이름"
|
||||
description="새 도메인을 연결할 때 사용할 중립적인 예제입니다."
|
||||
error={fieldError}
|
||||
value={projectName}
|
||||
required
|
||||
onChange={(event) => setProjectName(event.currentTarget.value)}
|
||||
/>
|
||||
<Button type="submit">입력 확인</Button>
|
||||
</form>
|
||||
</Card>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="form-controls-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="form-controls-title">폼과 선택 컨트롤</h2>
|
||||
<p>native semantics, 설명·오류 연결과 controlled 상태를 제공합니다.</p>
|
||||
</header>
|
||||
<div className="component-grid component-grid--two">
|
||||
<Card title="긴 입력과 선택">
|
||||
<div className="component-stack">
|
||||
<TextArea
|
||||
label="설명"
|
||||
maxLength={120}
|
||||
value={description}
|
||||
onChange={(event) => setDescription(event.currentTarget.value)}
|
||||
/>
|
||||
<Select
|
||||
label="시작 템플릿"
|
||||
options={[
|
||||
{ value: "application", label: "Application" },
|
||||
{ value: "library", label: "Library" },
|
||||
]}
|
||||
value={template}
|
||||
onChange={(event) => setTemplate(event.currentTarget.value)}
|
||||
/>
|
||||
<Checkbox
|
||||
checked={reviewed}
|
||||
label="접근성 계약을 확인했습니다."
|
||||
onChange={(event) => setReviewed(event.currentTarget.checked)}
|
||||
/>
|
||||
</div>
|
||||
</Card>
|
||||
<Card title="단일 선택과 설정">
|
||||
<div className="component-stack">
|
||||
<RadioGroup
|
||||
label="화면 밀도"
|
||||
name="density"
|
||||
onChange={setDensity}
|
||||
options={[
|
||||
{ value: "comfortable", label: "여유롭게" },
|
||||
{ value: "compact", label: "조밀하게" },
|
||||
]}
|
||||
value={density}
|
||||
/>
|
||||
<Switch
|
||||
checked={notifications}
|
||||
description="boolean 설정에만 switch를 사용합니다."
|
||||
label="알림 사용"
|
||||
onChange={setNotifications}
|
||||
/>
|
||||
<ProgressBar label="설정 준비도" max={4} value={3} />
|
||||
</div>
|
||||
</Card>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="feedback-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="feedback-title">피드백과 모달</h2>
|
||||
<p>상태 전달은 색에만 의존하지 않으며, 모든 제어에는 이름이 있습니다.</p>
|
||||
</header>
|
||||
<div className="component-grid component-grid--two">
|
||||
<Card title="알림과 배지" description="짧은 상태와 문맥형 피드백입니다.">
|
||||
<div className="component-stack">
|
||||
{alertVisible ? (
|
||||
<Alert
|
||||
title="설정이 저장되었습니다."
|
||||
variant="success"
|
||||
onDismiss={() => setAlertVisible(false)}
|
||||
>
|
||||
<p>운영 환경에는 실제 저장 포트를 연결하세요.</p>
|
||||
</Alert>
|
||||
) : (
|
||||
<Button
|
||||
variant="secondary"
|
||||
onClick={() => setAlertVisible(true)}
|
||||
>
|
||||
알림 다시 표시
|
||||
</Button>
|
||||
)}
|
||||
<div className="badge-row" aria-label="배지 변형">
|
||||
<Badge>중립</Badge>
|
||||
<Badge variant="info">정보</Badge>
|
||||
<Badge variant="success">준비됨</Badge>
|
||||
<Badge variant="warning">확인 필요</Badge>
|
||||
<Badge variant="danger">실패</Badge>
|
||||
</div>
|
||||
</div>
|
||||
</Card>
|
||||
<Card title="모달" description="배경과 키보드 Esc로 닫고 포커스를 복원합니다.">
|
||||
<div className="button-row">
|
||||
<Button onClick={() => setDialogOpen(true)}>모달 열기</Button>
|
||||
<Menu
|
||||
items={[
|
||||
{
|
||||
id: "inspect",
|
||||
label: "상태 확인",
|
||||
onSelect: () => setNotice("메뉴 작업을 실행했습니다."),
|
||||
},
|
||||
{
|
||||
id: "notify",
|
||||
label: "Toast 표시",
|
||||
onSelect: () =>
|
||||
toast.push({
|
||||
id: "gallery-saved",
|
||||
title: "예제가 저장되었습니다.",
|
||||
tone: "success",
|
||||
}),
|
||||
},
|
||||
]}
|
||||
triggerLabel="작업 메뉴"
|
||||
/>
|
||||
<Tooltip content="이 설명은 필수 정보가 아닙니다.">
|
||||
<Button variant="ghost">도움말</Button>
|
||||
</Tooltip>
|
||||
</div>
|
||||
<Dialog
|
||||
open={dialogOpen}
|
||||
onClose={() => setDialogOpen(false)}
|
||||
title="연동 확인"
|
||||
description="도메인 작업을 실행하기 전 확인 화면의 기본 구조입니다."
|
||||
actions={
|
||||
<>
|
||||
<Button
|
||||
variant="secondary"
|
||||
onClick={() => setDialogOpen(false)}
|
||||
>
|
||||
취소
|
||||
</Button>
|
||||
<Button
|
||||
onClick={() => {
|
||||
setNotice("모달의 확인 작업을 실행했습니다.");
|
||||
setDialogOpen(false);
|
||||
}}
|
||||
>
|
||||
확인
|
||||
</Button>
|
||||
</>
|
||||
}
|
||||
>
|
||||
<p>민감한 값이나 구현 세부정보는 확인 문구에 포함하지 않습니다.</p>
|
||||
</Dialog>
|
||||
</Card>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="navigation-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="navigation-title">탐색 패턴</h2>
|
||||
<p>화살표 키와 명시적인 활성화 정책을 갖는 탭 예제입니다.</p>
|
||||
</header>
|
||||
<Tabs
|
||||
activation="manual"
|
||||
label="디자인 시스템 계층"
|
||||
tabs={[
|
||||
{
|
||||
id: "tokens",
|
||||
label: "토큰",
|
||||
panel: <p>원시 값에서 의미와 컴포넌트 토큰을 파생합니다.</p>,
|
||||
},
|
||||
{
|
||||
id: "primitives",
|
||||
label: "프리미티브",
|
||||
panel: <p>native semantics와 interaction을 닫습니다.</p>,
|
||||
},
|
||||
{
|
||||
id: "patterns",
|
||||
label: "패턴",
|
||||
panel: <p>반복되는 사용자 문제를 조합으로 해결합니다.</p>,
|
||||
},
|
||||
]}
|
||||
/>
|
||||
</section>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="tokens-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="tokens-title">디자인 토큰</h2>
|
||||
<p>구성요소가 사용하는 의미 기반 색상과 형태 토큰입니다.</p>
|
||||
</header>
|
||||
<div className="token-grid">
|
||||
{COLOR_TOKENS.map(([label, token]) => (
|
||||
<article className="token-swatch" key={token}>
|
||||
<span
|
||||
className="token-swatch__color"
|
||||
style={{ backgroundColor: `var(${token})` }}
|
||||
aria-hidden="true"
|
||||
/>
|
||||
<strong>{label}</strong>
|
||||
<code>{token}</code>
|
||||
</article>
|
||||
))}
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<output className="gallery-notice" aria-live="polite">
|
||||
{notice}
|
||||
</output>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
|
||||
function ScreenStateGallery() {
|
||||
const [lastAction, setLastAction] = useState(
|
||||
"상태 화면의 작업을 선택하면 결과가 여기에 표시됩니다.",
|
||||
);
|
||||
const refreshingState = deriveAsyncState({
|
||||
data: ["기존 데이터"],
|
||||
isFetching: true,
|
||||
});
|
||||
|
||||
return (
|
||||
// 08-07. Example copy is Korean in every locale (outside the catalog).
|
||||
<section className="ui-page" lang="ko-KR">
|
||||
<PageHeader
|
||||
title="화면 상태"
|
||||
description="로딩, 빈 화면, 오류, 인증 필요와 권한 없음 상태가 다음 행동까지 일관되게 안내합니다."
|
||||
/>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="async-states-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="async-states-title">비동기 데이터 상태</h2>
|
||||
<p>초기 로딩과 백그라운드 갱신을 구분해 기존 콘텐츠를 보존합니다.</p>
|
||||
</header>
|
||||
<div className="component-grid component-grid--two">
|
||||
<Card title="초기 로딩">
|
||||
<LoadingSurface label="예제 데이터를 불러오는 중" />
|
||||
</Card>
|
||||
<Card title="백그라운드 갱신">
|
||||
<AsyncSurface headingLevel={4} state={refreshingState}>
|
||||
<div className="state-preview-content">기존 콘텐츠는 계속 표시됩니다.</div>
|
||||
</AsyncSurface>
|
||||
</Card>
|
||||
<Card title="빈 화면">
|
||||
<EmptySurface
|
||||
headingLevel={4}
|
||||
title="아직 표시할 항목이 없습니다."
|
||||
description="첫 항목을 추가하거나 필터를 초기화할 수 있습니다."
|
||||
action={
|
||||
<Button onClick={() => setLastAction("빈 화면 작업을 실행했습니다.")}>
|
||||
첫 작업 시작
|
||||
</Button>
|
||||
}
|
||||
/>
|
||||
</Card>
|
||||
<Card title="복구 가능한 오류">
|
||||
<TerminalErrorSurface
|
||||
headingLevel={4}
|
||||
userMessageKey={
|
||||
createFailure("NETWORK_UNREACHABLE", "EXAMPLE", 0)
|
||||
.userMessageKey
|
||||
}
|
||||
action="retry"
|
||||
onAction={() => setLastAction("오류 요청을 다시 시도했습니다.")}
|
||||
/>
|
||||
</Card>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="gallery-section" aria-labelledby="access-states-title">
|
||||
<header className="gallery-section__header">
|
||||
<h2 id="access-states-title">접근과 탐색 상태</h2>
|
||||
<p>인증 여부와 서버 권한 결과를 서로 다른 상태로 전달합니다.</p>
|
||||
</header>
|
||||
<div className="component-grid component-grid--three">
|
||||
<AuthRequiredSurface
|
||||
headingLevel={3}
|
||||
onSignIn={() => setLastAction("로그인 연동 작업을 시작했습니다.")}
|
||||
/>
|
||||
<ForbiddenSurface
|
||||
headingLevel={3}
|
||||
onNavigate={() => setLastAction("접근 가능한 화면으로 이동합니다.")}
|
||||
/>
|
||||
<NotFoundSurface
|
||||
headingLevel={3}
|
||||
onNavigate={() => setLastAction("시작 화면으로 이동합니다.")}
|
||||
/>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<output className="gallery-notice" aria-live="polite">
|
||||
{lastAction}
|
||||
</output>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user