diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 2d0e8681..b920d0fc 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -86,7 +86,10 @@ const queryClient = createQueryClient();
const preview: Preview = {
decorators: [
- (Story) => (
+ // A page story (`parameters.page`, the galleries) draws its own
+ // `.ui-page`, as a route page does inside the shell's `main`; a component
+ // story gets a padded page around it.
+ (Story, context) => (
@@ -94,9 +97,15 @@ const preview: Preview = {
-
-
-
+ {context.parameters["page"] === true ? (
+
+
+
+ ) : (
+
+
+
+ )}
diff --git a/docs/styling/design-system-platform.md b/docs/styling/design-system-platform.md
index 0618086b..d6eedf68 100644
--- a/docs/styling/design-system-platform.md
+++ b/docs/styling/design-system-platform.md
@@ -38,8 +38,8 @@
- local form facade, field/error summary, dirty navigation dialog
- `src/presentation/templates`
- Standard, Collection, Detail, Form, Status page template
-- `/examples/ui`, `/examples/states`
- - 실행 가능한 primitive와 상태 예제
+- `src/presentation/design-system/galleries.stories.tsx`
+ - 실행 가능한 primitive와 상태 예제(Storybook 갤러리 story)
- component/E2E/axe 테스트
- 필드 설명과 오류 연결
- native dialog 닫기와 trigger focus 복원
@@ -623,8 +623,8 @@ RP-10의 Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어
## 10. Storybook과 시각 검증
-현재 `/examples/ui`는 실행 중인 앱 셸과 primitive 통합을 확인하는 데 유지한다.
-그러나 runtime gallery는 isolated component workshop을 대체하지 않는다.
+디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story다. 앱 셸과 primitive의
+통합은 `/`와 `/examples/platform`을 여는 e2e가 확인한다.
[Storybook 공식 UI 테스트 문서](https://storybook.js.org/docs/writing-tests)는
story를 기반으로 interaction, accessibility, visual test를 구성하는 방법을
@@ -796,8 +796,8 @@ long-content
### Step 9. 통합 예제를 추가한다
-- `/examples/ui`에는 primitive를 추가한다.
-- `/examples/states`에는 새로운 공통 상태를 추가한다.
+- 갤러리 story(`galleries.stories.tsx`)의 `DesignSystem`에는 primitive를 추가한다.
+- 같은 파일의 `ScreenStates`에는 새로운 공통 상태를 추가한다.
- pattern/template은 domain-neutral fixture로 실제 조합을 보여 준다.
- production profile에서 예제 route를 제외할 수 있는 계약을 유지한다.
@@ -919,7 +919,7 @@ component contract에 기록한다. 예를 들어 `Separator`에는 pending/erro
9. locale provider, pseudo-locale, RTL 검증을 추가한다.
10. Storybook, story a11y, interaction test를 추가한다.
11. pinned browser 환경의 visual regression gate를 추가한다.
-12. `/examples/ui`와 `/examples/states`를 통합 smoke gallery로 유지한다.
+12. 디자인 시스템·화면 상태 갤러리를 Storybook story로 유지하고 visual 골든의 대상으로 쓴다.
이 순서는 라이브러리 수를 늘리는 것이 목표가 아니다. 각 단계가 제품 개발자가
중복 구현할 문제를 하나씩 제거하고, 외부 공급자를 교체할 수 있는 로컬 계약과
diff --git a/docs/styling/design-tokens.md b/docs/styling/design-tokens.md
index 1a2d94c5..bd31f947 100644
--- a/docs/styling/design-tokens.md
+++ b/docs/styling/design-tokens.md
@@ -7,7 +7,8 @@ the dark theme, and `component.css` maps roles to per-component values.
`src/presentation/styles/theme.css` only imports the three files and the style
files under `src/presentation/styles/theme/`. Components consume semantic
color, spacing, typography, status, and radius tokens through static classes.
-`/examples/ui` is the executable token and primitive gallery.
+The executable token and primitive gallery is the workshop story
+`src/presentation/design-system/galleries.stories.tsx` (`corepack pnpm storybook`).
## Rules a rebrand must keep
diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md
index e031a932..5cdd8456 100644
--- a/docs/testing/frontend-platform-testing-strategy.md
+++ b/docs/testing/frontend-platform-testing-strategy.md
@@ -808,8 +808,10 @@ production runtime config에 `MOCK_MODE`, `SCENARIO`, fake token 같은 key를
## 12. Storybook 테스트
Storybook은 component를 격리해 state를 열거하고 실제 브라우저 interaction과
-접근성을 검사하는 개발·CI surface다. `/examples/ui`는 앱 통합 smoke로 유지하되
-Storybook을 대신하지 않는다.
+접근성을 검사하는 개발·CI surface다. 디자인 시스템 갤러리와 화면 상태 갤러리도
+story다(`src/presentation/design-system/galleries.stories.tsx`). 갤러리의 브라우저
+상호작용 검사는 `tests/storybook/galleries.spec.ts`가, 앱 셸 안의 통합 확인은
+`/`와 `/examples/platform`을 여는 e2e가 맡는다.
### 12.1 Global decorator
@@ -945,9 +947,10 @@ Playwright `toHaveScreenshot()`을 사용한다.
- `app-shell-wide-light`: `/`, 1440×900, light, 전체 페이지 — wide app shell
- `app-shell-compact-pseudo-drawer`: `/`, 390×844, en-XA, 메뉴 서랍 열림 —
compact app shell, pseudo-locale, 열린 drawer
-- `design-system-gallery-dark`: `/examples/ui`, dark — design-system 갤러리
-- `state-surfaces-light`: `/examples/states` — loading, background refresh,
- empty, error, 401, 403, 404
+- `design-system-gallery-dark`: Storybook 정적 빌드의 갤러리 story
+ `platform-galleries--design-system`, 1280×900, 시스템 dark — design-system 갤러리
+- `state-surfaces-light`: Storybook 정적 빌드의 `platform-galleries--screen-states`,
+ 1280×1100 — loading, background refresh, empty, error, 401, 403, 404
- `platform-overview-light`: `/examples/platform` — 플랫폼 구성 개요
`check-test-evidence`는 기준선 PNG가 4장 이상인지만 본다. 위 목록의 각
@@ -1034,7 +1037,7 @@ TEST_RUN_ID=a playwright test
|---|---|---|
| `TEST_RUN_ID` | 다섯 Playwright 설정, `tests/e2e/preload-use.spec.ts` | `dist`, `artifacts/tests/<이름>/` |
| `RUN_OUTPUT_ROOT` | 빌드 단계 전부(`scripts/build-frontend.ts`가 부르는 것), `vite.config.ts`. 설정이 web server에만 넘긴다. 빌드 뒤 검사(`scripts/generate-supply-chain.ts`, `scripts/check-bundle.ts`)는 `.`이 아니면 멈춘다 | `.` |
-| `TEST_E2E_PORT`, `TEST_VISUAL_PORT`, `TEST_CAPABILITIES_PORT`, `TEST_STORYBOOK_PORT`, `TEST_DEV_PORT` | 각 설정 | 빈 포트 |
+| `TEST_E2E_PORT`, `TEST_VISUAL_PORT`, `TEST_VISUAL_WORKSHOP_PORT`, `TEST_CAPABILITIES_PORT`, `TEST_STORYBOOK_PORT`, `TEST_DEV_PORT` | 각 설정(`TEST_VISUAL_WORKSHOP_PORT`는 visual 설정의 두 번째 서버, 갤러리 골든이 여는 Storybook 정적 빌드) | 빈 포트 |
- run ID는 글자·숫자·`.`·`_`·`-` 64자 이하이고 글자나 숫자로 시작한다.
- 포트 변수를 주면 그 포트를 쓴다. 디버깅할 때 고정하는 용도다.
diff --git a/playwright.storybook.config.ts b/playwright.storybook.config.ts
index a36bfb5f..af4eebe9 100644
--- a/playwright.storybook.config.ts
+++ b/playwright.storybook.config.ts
@@ -4,22 +4,14 @@ import {
reservePort,
TEST_PORT_VARIABLES,
testRunPath,
- testRunRoot,
} from "./scripts/lib/run-isolation.ts";
+import { storybookStaticServer } from "./scripts/lib/storybook-static.ts";
-// 1105/12-04. Under TEST_RUN_ID the workshop is built into the run's own
-// folder (.tmp/runs//artifacts/storybook/static) with build:storybook's
-// two steps and another output folder, and the results and report are the
-// run's own. Unset, the gate's build:storybook writes artifacts/storybook/static.
-// The static server listens on a free port (TEST_STORYBOOK_PORT pins one).
-const staticDirectory = testRunPath("artifacts/storybook/static");
+// 1105/12-04. Under TEST_RUN_ID the workshop build (storybookStaticServer),
+// the results and the report are the run's own. The static server listens on
+// a free port (TEST_STORYBOOK_PORT pins one).
const port = await reservePort(TEST_PORT_VARIABLES.storybook);
const origin = `http://127.0.0.1:${port}`;
-const buildWorkshop =
- testRunRoot() === "."
- ? "corepack pnpm build:storybook"
- : "node scripts/generate-product-feature-index.ts && " +
- `corepack pnpm exec storybook build -o ${staticDirectory}`;
export default defineConfig({
testDir: "./tests/storybook",
@@ -45,8 +37,7 @@ export default defineConfig({
screenshot: "only-on-failure",
},
webServer: {
- command:
- `${buildWorkshop} && node scripts/serve-static.ts ${staticDirectory} ${port}`,
+ command: storybookStaticServer(port).command,
url: origin,
reuseExistingServer: false,
},
diff --git a/playwright.visual.config.ts b/playwright.visual.config.ts
index 977fd864..9330b055 100644
--- a/playwright.visual.config.ts
+++ b/playwright.visual.config.ts
@@ -10,6 +10,7 @@ import {
testRunPath,
testRunRoot,
} from "./scripts/lib/run-isolation.ts";
+import { storybookStaticServer } from "./scripts/lib/storybook-static.ts";
// 1105/12-04. Under TEST_RUN_ID the results, report and build are the run's
// own (.tmp/runs//); the goldens in snapshotDir are shared and only read.
@@ -18,6 +19,11 @@ import {
const dist = testRunPath("dist");
const port = await reservePort(TEST_PORT_VARIABLES.visual);
const origin = `http://127.0.0.1:${port}`;
+// The design-system and screen-state galleries are workshop stories
+// (src/presentation/design-system/galleries.stories.tsx); their goldens open
+// the static workshop, which the second server serves
+// (TEST_VISUAL_WORKSHOP_PORT pins its port).
+const workshopPort = await reservePort(TEST_PORT_VARIABLES.visualWorkshop);
export default defineConfig({
testDir: "./tests/visual",
@@ -62,19 +68,26 @@ export default defineConfig({
},
},
},
- webServer: {
- // The home page and the platform overview print the build and release
- // identity. CI sets VITE_BUILD_ID, VITE_COMMIT_SHA and RELEASE_ID for the
- // whole workflow, so its build drew other text than the goldens and every
- // CI run failed here. The goldens are the template's shape, captured with
- // the local identity.
- // 1103/11-08: CI too, or the build is checked as a release build.
- env: { ...LOCAL_BUILD_IDENTITY, [RUN_OUTPUT_ROOT_VARIABLE]: testRunRoot() },
- command:
- `corepack pnpm build && corepack pnpm preview --host 127.0.0.1 --port ${port} --strictPort --outDir ${dist}`,
- url: origin,
- reuseExistingServer: false,
- },
+ webServer: [
+ {
+ // The home page and the platform overview print the build and release
+ // identity. CI sets VITE_BUILD_ID, VITE_COMMIT_SHA and RELEASE_ID for
+ // the whole workflow, so its build drew other text than the goldens and
+ // every CI run failed here. The goldens are the template's shape,
+ // captured with the local identity.
+ // 1103/11-08: CI too, or the build is checked as a release build.
+ env: { ...LOCAL_BUILD_IDENTITY, [RUN_OUTPUT_ROOT_VARIABLE]: testRunRoot() },
+ command:
+ `corepack pnpm build && corepack pnpm preview --host 127.0.0.1 --port ${port} --strictPort --outDir ${dist}`,
+ url: origin,
+ reuseExistingServer: false,
+ },
+ {
+ command: storybookStaticServer(workshopPort).command,
+ url: `http://127.0.0.1:${workshopPort}`,
+ reuseExistingServer: false,
+ },
+ ],
projects: [
{ name: "visual-fonts", testMatch: /fonts\.setup\.ts$/ },
{ name: "chromium-visual", dependencies: ["visual-fonts"] },
diff --git a/scripts/lib/run-isolation.ts b/scripts/lib/run-isolation.ts
index d51807bd..15cd263c 100644
--- a/scripts/lib/run-isolation.ts
+++ b/scripts/lib/run-isolation.ts
@@ -113,15 +113,33 @@ export function checkoutBuildReadFailure(
/**
* The port variable of each Playwright config's web server. Unset, the config
* picks a free port; set, it uses that one (to pin a port while debugging).
+ * `visualWorkshop` is the visual config's second server, the static workshop
+ * the gallery goldens open.
*/
export const TEST_PORT_VARIABLES = Object.freeze({
e2e: "TEST_E2E_PORT",
visual: "TEST_VISUAL_PORT",
+ visualWorkshop: "TEST_VISUAL_WORKSHOP_PORT",
capabilities: "TEST_CAPABILITIES_PORT",
storybook: "TEST_STORYBOOK_PORT",
dev: "TEST_DEV_PORT",
} as const);
+/**
+ * The origin of a config's second server, for its specs. The runner reserved
+ * the port in `variable` (reservePort) and its workers inherit it.
+ */
+export function reservedOrigin(
+ variable: string,
+ environment: Readonly> = process.env,
+): string {
+ const port = environment[variable];
+ if (port === undefined || port === "") {
+ throw new Error(`${variable} is not set: run this spec through its Playwright config`);
+ }
+ return `http://127.0.0.1:${port}`;
+}
+
/**
* A port nothing listens on now: the one the kernel gives a socket bound to
* port 0, which is closed again. Another process can still take it before the
diff --git a/scripts/lib/storybook-static.ts b/scripts/lib/storybook-static.ts
new file mode 100644
index 00000000..d916d957
--- /dev/null
+++ b/scripts/lib/storybook-static.ts
@@ -0,0 +1,27 @@
+import { testRunPath, testRunRoot } from "./run-isolation.ts";
+
+/**
+ * The static workshop a Playwright config serves: the workshop tests
+ * (playwright.storybook.config.ts) and the gallery goldens
+ * (playwright.visual.config.ts) open the same build.
+ *
+ * 1105/12-04. Under TEST_RUN_ID the workshop is built into the run's own
+ * folder (.tmp/runs//artifacts/storybook/static) with build:storybook's
+ * two steps and another output folder. Unset, the gate's build:storybook
+ * writes artifacts/storybook/static.
+ */
+export function storybookStaticServer(port: number): Readonly<{
+ directory: string;
+ command: string;
+}> {
+ const directory = testRunPath("artifacts/storybook/static");
+ const build =
+ testRunRoot() === "."
+ ? "corepack pnpm build:storybook"
+ : "node scripts/generate-product-feature-index.ts && " +
+ `corepack pnpm exec storybook build -o ${directory}`;
+ return Object.freeze({
+ directory,
+ command: `${build} && node scripts/serve-static.ts ${directory} ${port}`,
+ });
+}
diff --git a/src/presentation/design-system/galleries.stories.tsx b/src/presentation/design-system/galleries.stories.tsx
new file mode 100644
index 00000000..7d9bdde1
--- /dev/null
+++ b/src/presentation/design-system/galleries.stories.tsx
@@ -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;
+
+export const DesignSystem: Story = {
+ render: () => ,
+};
+
+export const ScreenStates: Story = {
+ render: () => ,
+};
+
+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 (
+
+
+
+ );
+}
+
+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): 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).
+
+
+
+
+
+