From f846f51020f3e629363f791167d30811ddadfa3d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 30 Aug 2026 12:02:00 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20=ED=99=94=EB=A9=B4=20=EA=B2=80=ED=86=A0?= =?UTF-8?q?=EC=9A=A9=20=EC=B4=AC=EC=98=81=20=EC=8A=A4=ED=81=AC=EB=A6=BD?= =?UTF-8?q?=ED=8A=B8=EB=A5=BC=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 손으로 찍으면 두 가지를 반드시 놓친다. 뷰포트: 브라우저 세션이 리셋되면 창은 기본 크기(약 877px)로 돌아간다. 이 사이트의 분기는 1179/1050/900/767 이라 877px 는 900 아래로 떨어져 헤더가 접힌 좁은 화면이 나온다 — 방문자 대부분이 보지 않는 배치를 놓고 디자인을 논하게 된다. 축소: 전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 줄어든다. 실제로 1425x4466 이 638x2000 으로 들어와 17px 글자가 7~8px 이 되었다. 덩어리는 보이지만 정작 타이포는 못 본다. 그래서 폭 세 개를 고정으로 돌고 화면 높이만큼 잘라 찍는다. 잊을 자리를 없앤다. 눈은 어디가 이상한지까지만 알려 주므로 폭마다 측정도 함께 남긴다 — 이번에 고친 결함(목록 항목 간격 0px, 한 줄 53자)은 전부 측정에서 나왔다. 목록 판정에서 gapPx 만 보면 여백이 항목 안(padding)에 있는 경우를 구분이 없는 것으로 잘못 읽는다. 실제로 그렇게 읽어서 「판단 기준」을 결함으로 지목했었다. separatedByPadding 을 따로 남겨 같은 오독을 막는다. networkidle 은 기다리지 않는다 — 이 앱은 유휴 상태에서도 요청을 보내 그 순간이 오지 않는다. 본문 제목이 그려질 때까지 기다린다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ --- .gitignore | 2 + package.json | 1 + scripts/capture-public-screens.ts | 206 ++++++++++++++++++++++++++++++ 3 files changed, 209 insertions(+) create mode 100644 scripts/capture-public-screens.ts diff --git a/.gitignore b/.gitignore index 538c7cf..950df5f 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,8 @@ artifacts/**/*.xml artifacts/**/*.txt artifacts/**/*.sarif artifacts/tests/e2e/ +# 디자인 검토용 촬영본. 매번 다시 찍는 것이라 저장소에 남길 이유가 없다. +artifacts/design-review/ artifacts/tests/browser-capabilities/ artifacts/storybook/ artifacts/tests/storybook/ diff --git a/package.json b/package.json index caf51b7..5d13b60 100644 --- a/package.json +++ b/package.json @@ -86,6 +86,7 @@ "generate:artifact-schemas": "node scripts/generate-artifact-schemas.ts", "check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check", "generate:tech-log-contract": "node scripts/generate-tech-log-contract.ts", + "capture:screens": "node scripts/capture-public-screens.ts", "check:tech-log-contract": "node scripts/generate-tech-log-contract.ts --check", "generate:dev-release-manifest": "node scripts/check-dev-release-manifest.ts --write", "check:dev-release-manifest": "node scripts/check-dev-release-manifest.ts", diff --git a/scripts/capture-public-screens.ts b/scripts/capture-public-screens.ts new file mode 100644 index 0000000..02fa349 --- /dev/null +++ b/scripts/capture-public-screens.ts @@ -0,0 +1,206 @@ +import { mkdir, writeFile } from "node:fs/promises"; +import path from "node:path"; +import process from "node:process"; + +import { chromium, type Page } from "@playwright/test"; + +/** + * 화면을 사람 눈으로 보기 위한 촬영기. 디자인을 검토할 때 쓴다. + * + *

손으로 찍으면 두 가지를 반드시 놓친다. 첫째, 뷰포트다. 브라우저 세션이 리셋되면 창은 + * 기본 크기(약 877px)로 돌아가는데 그 폭은 이 사이트의 900px 분기 아래라 헤더가 접힌 좁은 + * 화면이 나온다 — 방문자 대부분이 보지 않는 배치를 보면서 검토하게 된다. 둘째, 전체 페이지를 + * 한 장으로 찍으면 세로로 긴 문서가 통째로 축소되어 17px 글자가 7~8px 로 뭉갠다. 덩어리는 + * 보이지만 정작 타이포는 못 본다. + * + *

그래서 폭을 고정 목록으로 돌고, 화면 높이만큼씩 잘라 찍는다. 잊을 자리를 없앤다. + * + *

눈으로 본 인상은 어디가 이상한지까지만 알려 준다. 얼마나 잘못됐는지는 값이 말해야 하므로 + * 매 폭마다 측정도 함께 남긴다 — 실제로 고친 결함(목록 항목 간격 0px, 한 줄 53자)은 전부 + * 이 측정에서 나왔다. + */ + +/** 이 사이트의 반응형 분기는 1179 / 1050 / 900 / 767 이다. 그 위·사이·아래를 하나씩 본다. */ +const WIDTHS = [1440, 900, 390] as const; + +const VIEWPORT_HEIGHT = 900; + +/** 한 폭당 이만큼까지만 자른다. 문서가 길어도 검토는 앞쪽에서 대부분 끝난다. */ +const MAX_SLICES = 6; + +const OUTPUT_DIRECTORY = "artifacts/design-review"; + +type Measurement = { + readonly width: number; + readonly layoutWidth: number; + readonly scrollbarWidth: number; + readonly horizontalOverflow: boolean; + readonly overflowingElements: readonly string[]; + readonly text: readonly TextMeasurement[]; + readonly lists: readonly ListMeasurement[]; +}; + +type TextMeasurement = { + readonly selector: string; + readonly fontSize: string; + readonly lineHeight: string; + readonly widthPx: number; + /** 한글 기준 한 줄 글자 수. 25~40 이 편한 범위이고 그보다 길면 줄을 놓치기 쉽다. */ + readonly charactersPerLine: number; +}; + +type ListMeasurement = { + readonly section: string; + readonly items: number; + readonly marker: string; + /** 항목 사이 실제 간격. 0 이면서 마커도 없으면 여러 줄 항목이 한 덩어리로 보인다. */ + readonly gapPx: number | null; + readonly separatedByPadding: boolean; +}; + +function slugOf(url: string): string { + const { pathname } = new URL(url); + const cleaned = pathname.replace(/^\/+|\/+$/gu, "").replace(/[^a-zA-Z0-9-]+/gu, "-"); + return cleaned || "home"; +} + +async function measure(page: Page, width: number): Promise { + return page.evaluate((viewportWidth: number) => { + const root = document.documentElement; + const layoutWidth = root.clientWidth; + + const text = ["main p", "main li", "h1"].flatMap((selector) => { + const element = document.querySelector(selector); + if (!element) return []; + const style = getComputedStyle(element); + const box = element.getBoundingClientRect(); + const fontSize = Number.parseFloat(style.fontSize); + return [ + { + selector, + fontSize: style.fontSize, + lineHeight: style.lineHeight, + widthPx: Math.round(box.width), + charactersPerLine: fontSize > 0 ? Math.round(box.width / fontSize) : 0, + }, + ]; + }); + + const lists = [...document.querySelectorAll("main ul, main ol")].map((list) => { + const items = [...list.children]; + const first = items[0]; + const second = items[1]; + const itemStyle = first ? getComputedStyle(first) : null; + const gapPx = + first && second + ? Math.round( + second.getBoundingClientRect().top - first.getBoundingClientRect().bottom, + ) + : null; + return { + section: + list.closest("section")?.querySelector("h2")?.textContent?.trim().slice(0, 16) ?? + String(list.className).slice(0, 24) ?? + "(이름 없음)", + items: items.length, + marker: getComputedStyle(list).listStyleType, + gapPx, + /* 여백이 항목 안(padding)에 있으면 박스 사이는 0으로 나온다 — 그것도 구분이다. */ + separatedByPadding: itemStyle + ? Number.parseFloat(itemStyle.paddingTop) > 0 || + Number.parseFloat(itemStyle.borderBottomWidth) > 0 + : false, + }; + }); + + return { + width: viewportWidth, + layoutWidth, + scrollbarWidth: window.innerWidth - layoutWidth, + horizontalOverflow: root.scrollWidth > layoutWidth, + overflowingElements: [...document.querySelectorAll("body *")] + .filter((element) => { + const box = element.getBoundingClientRect(); + return box.width > 0 && box.right > layoutWidth + 1; + }) + .slice(0, 5) + .map((element) => `${element.tagName}.${String(element.className).slice(0, 24)}`), + text, + lists, + }; + }, width); +} + +async function capture(page: Page, url: string, width: number): Promise { + await page.setViewportSize({ width, height: VIEWPORT_HEIGHT }); + /* + `networkidle` 은 오지 않는다 — 이 앱은 유휴 상태에서도 요청을 계속 보낸다. 기다려야 하는 + 것은 네트워크가 조용해지는 순간이 아니라 본문이 그려진 순간이므로 제목이 나올 때까지 기다린다. + */ + await page.goto(url, { waitUntil: "domcontentloaded" }); + await page.waitForSelector("main h1", { timeout: 15_000 }); + + const slug = slugOf(url); + const pageHeight = await page.evaluate(() => document.documentElement.scrollHeight); + const slices = Math.min(Math.ceil(pageHeight / VIEWPORT_HEIGHT), MAX_SLICES); + + for (let index = 0; index < slices; index += 1) { + await page.evaluate((top: number) => window.scrollTo(0, top), index * VIEWPORT_HEIGHT); + // 스크롤에 붙은 전환이 끝나기를 기다린다. 반쯤 그려진 화면을 남기면 검토가 그것을 지적한다. + await page.waitForTimeout(250); + await page.screenshot({ + path: path.join(OUTPUT_DIRECTORY, `${slug}-${width}-${index + 1}.png`), + scale: "css", + }); + } + + await page.evaluate(() => window.scrollTo(0, 0)); + return measure(page, width); +} + +async function main(): Promise { + const urls = process.argv.slice(2); + if (urls.length === 0) { + process.stderr.write( + "사용법: node scripts/capture-public-screens.ts [URL...]\n" + + `폭 ${WIDTHS.join(" / ")} 로 각각 찍고 ${OUTPUT_DIRECTORY}/ 에 남긴다.\n`, + ); + process.exitCode = 1; + return; + } + + await mkdir(OUTPUT_DIRECTORY, { recursive: true }); + const browser = await chromium.launch(); + const report: Record = {}; + + try { + const page = await browser.newPage(); + for (const url of urls) { + const measurements: Measurement[] = []; + for (const width of WIDTHS) { + const measurement = await capture(page, url, width); + measurements.push(measurement); + const body = measurement.text.find((entry) => entry.selector === "main p"); + const worstList = measurement.lists.find( + (list) => list.gapPx === 0 && list.marker === "none" && !list.separatedByPadding, + ); + process.stdout.write( + `${url} ${width}px → 레이아웃 ${measurement.layoutWidth}px` + + (body ? `, 본문 ${body.charactersPerLine}자/줄` : "") + + (measurement.horizontalOverflow ? ", 가로 넘침 있음" : "") + + (worstList ? `, 구분 없는 목록: ${worstList.section}` : "") + + "\n", + ); + } + report[url] = measurements; + } + } finally { + await browser.close(); + } + + const reportPath = path.join(OUTPUT_DIRECTORY, "measurements.json"); + await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8"); + process.stdout.write(`\n측정값: ${reportPath}\n스크린샷: ${OUTPUT_DIRECTORY}/\n`); +} + +await main();