`, so a line-scoped match never sees both. The comment alternation matches `DISCLAIMER_FIRST_CHILD` in `src/lib/preview-validator.ts`: a comment between `` and the strip is still a strip-first document, and flagging it here would send Stage 9a back to fix markup that 9a2 already passed.
**These sentinels are deliberately stricter than the validator on one axis: quoting.** `preview-validator.ts` accepts `class='catalog-disclaimer'` because it also validates hand-edited and pre-existing files. Stage 10 re-checks *pipeline output*, where `.claude/agents/preview-html-author.md` prescribes the strip **byte for byte** with double quotes — so `-F` on the verbatim form is the point, not an oversight. A single-quoted strip reaching here means the author deviated from a verbatim instruction, which is worth a Stage 9a round. Do not "fix" this by loosening it to match the validator.
The two phrase sentinels are literal (`-F`) for the same reason: the non-affiliation sentence is shared verbatim with `src/components/site/footer.tsx` and pinned by `src/lib/license-notice-consistency.test.ts`.
If any `DISCLAIMER_*` sentinel prints, do not proceed to Stage 11. Re-run Stage 9a with a blocking prior-preview issue quoting the verbatim strip from `.claude/agents/preview-html-author.md` and stating it must be the first child of `` — in the shared markup, not inside a theme variant.
### Preview token alias registration
The moment the previews land in `public/`, the OKLCH drift gate starts expecting this slug to be accounted for. Run it:
```bash
cd "${repo_root}" && pnpm test src/lib/oklch-drift-corpus.test.ts
```
That gate compares each preview's `--custom-property: oklch(…)` declarations against the `name: oklch(…)` definitions in `services/{slug}.md`, by **exact name**. Previews almost always namespace their variables (`--tds-blue-500` for md `blue-500`), so each slug declares a rewrite rule in `PREVIEW_TOKEN_ALIASES` (`src/lib/oklch-drift.ts`). Without one, every declaration in this preview is unreachable and the gate silently checks nothing for the new entry — which is what the corpus test refuses to let happen.
**Stage 9a2's `oklch coverage` metric does not cover this.** It searches the HTML for the design.md's OKLCH *values* as substrings; it never looks at custom-property *names*, and `src/lib/preview-validator.ts` does not consult the drift gate at all. A fully namespaced preview can score 100% coverage at 9a2 and still match zero declarations here.
Three rule shapes are in use, all measured against real entries:
| md name | preview name | rule |
|---|---|---|
| `blue-500` | `--tds-blue-500` | `["", "tds-"]` — prepend |
| `ldsg-color-linegreen` | `--ldsg-linegreen` | `["ldsg-color-", "ldsg-"]` — replace |
| `gray0` | `--g-gray-0` | `[["gray", "g-gray-"], ["", "g-"]]` — one family differs from the rest |
Rules are tried in order, first match wins, and an empty `from` matches anything so it belongs last.
If the test fails with `these slugs have no entry in MATCH_FLOOR`, add the rule, then record the count the failure message prints into `MATCH_FLOOR` (`src/lib/oklch-drift-corpus.test.ts`) — that table is a per-slug floor, so it also has to be raised deliberately rather than guessed. Recording a bare `0` is refused: only `bezier` is entitled to it, because its preview is hex rather than OKLCH and no naming rule can reach it.
Both files are outside this skill's write scope, so this does not route back to Stage 9a — a human operator running the skill by hand makes these two edits directly. Skipping them does not corrupt the entry; it leaves the drift gate blind to it, and CI fails on the pull request rather than here.
### Token coverage row
The same moment creates a row this entry owes to `src/lib/token-coverage.test.ts`. Run it:
```bash
cd "${repo_root}" && pnpm test src/lib/token-coverage.test.ts
```
That file pins, per entry, how many `name: oklch(…)` definitions each token gate can see — exact in both directions, because a count that rises can mean a reader widened, not that tokens were added. A new entry fails it with `these entries have no row in TOKEN_COVERAGE`, and the message prints the row itself: paste that line into `TOKEN_COVERAGE` at its sorted position, then read it. `drift: 0` is refused (the drift gate would have no md-side name to compare for the whole entry — fix the frontmatter token map instead), while `annotated: 0` can be right (an entry that comments its colours in prose with no hex, as baemin and toss do). Nothing else in the repo prints these numbers, so do not guess them. A row per entry is what lets two catalogue pull requests be open at once without the second one failing on the first one's merge (#324).
This file is outside the skill's write scope too: the operator makes the edit by hand, next to the `MATCH_FLOOR` row above.
## Stage 11 — Build OG image
```bash
cd "${repo_root}" && pnpm build:og
```
After the command:
**If exit non-zero**: capture stderr. Likely cause is frontmatter that `buildDoc` in `src/lib/content-parser.ts` rejects after slipping past the 6a2 gate (e.g. a hand edit at the Stage 7 checkpoint): a `last_updated` / `created_at` that is not a real `YYYY-MM-DD` date, or an `estimated_tokens` that is not a number. An off-enum category does not fail `build:og` (`buildDoc` falls back to `etc`); once the draft is past 6a2, only `pnpm validate:catalog` catches it, so run it before finishing. Surface stderr via text. Offer via `AskUserQuestion`: "frontmatter 직접 수정 후 재시도" (open `${repo_root}/services/{slug}.md` for editing; on user confirmation that they've edited, re-run `pnpm build:og` and re-validate — loop up to 3 retries), "취소 (파일 유지)" (partial state is acceptable since the index works without an OG image — the route falls back per `build-og.ts`). Do NOT auto-rollback the placed .md. After 3 failed retries, fall through to "취소" with a diagnostic message.
**If exit zero**: validate the OG output (catches the corrupt-PNG silent failure mode that happens on satori panic):
```bash
[ -s "${repo_root}/public/og/{slug}.png" ] || echo "OG_EMPTY"
file "${repo_root}/public/og/{slug}.png" | grep -q PNG || echo "OG_NOT_PNG"
```
If either check prints its sentinel, treat as the same error path as a non-zero exit (surface, ask the user, do not auto-rollback).
## Stage 12 — Verification (preview MCP)
Start the dev server and confirm the new entry renders correctly. This is the strongest end-to-end check.
1. **Port preflight**: `Bash`: `lsof -i :3000 -t 2>/dev/null`. If the output is non-empty, port 3000 is already in use (the user has a dev server running). `AskUserQuestion`: "포트 3000이 사용 중입니다 — (a) 기존 서버 종료 후 재시작 / (b) 검증 단계 건너뛰기 / (c) 취소". On "건너뛰기", skip to Stage 13 with a `verification_skipped: port_collision` flag in the report.
2. `Bash` (run_in_background): `cd "${repo_root}" && pnpm dev` — runs on port 3000.
3. **Server readiness poll**: `Bash`: `for i in $(seq 1 30); do curl -sf http://localhost:3000 -o /dev/null && echo READY && break; sleep 0.5; done`. The dev server takes a few seconds to bind; without this poll, `preview_start` may hit a connection refused before Vite is up. If the loop completes without printing `READY`, fall through to the `curl` fallback at the end of this stage.
4. `mcp__Claude_Preview__preview_start` with URL `http://localhost:3000/services/{slug}`.
5. `mcp__Claude_Preview__preview_eval`: `document.title` — should contain `{brand_name}` and `ko/design.md`. Then confirm the **token-card section** loaded from the Stage 8 sidecar: `preview_eval`: `document.querySelector('[aria-label="Design tokens"]')?.querySelector('p')?.textContent ?? 'MISSING'` — should return the count badge (`{N} Colors · {N} Type · …`). `MISSING` means `services/{slug}.tokens.json` is absent or failed `coerceServiceTokens`; verify it exists and is valid JSON before continuing.
6. `preview_eval` against the iframe: confirm `document.querySelector('iframe')?.src` contains `/preview/{slug}/preview.html`, and that the iframe document's `data-theme` matches the route default (`src/routes/services/$slug.tsx:97`) — one file serves both themes now.
7. `preview_screenshot` once on the default tab.
8. `preview_eval`: navigate to `?tab=md` and confirm DESIGN.md tab renders the syntax-highlighted markdown.
9. `preview_screenshot` once on the `?tab=md` view.
10. **Agent endpoint check**: `Bash`: `curl -sf -o /dev/null -w "%{http_code} %{content_type}\n" http://localhost:3000/services/{slug}/llms.txt` — expect `200 text/plain; charset=utf-8`. This raw-markdown sibling route reads from `services/{slug}.md` directly, so a failure here means either the file wasn't placed correctly or the project's `/services/$slug/llms.txt` route regressed. Surface non-200 output to the user before stopping the server.
11. **Responsive sweep (mobile / tablet / desktop)** — confirm the preview demo doesn't break at narrow widths (the regression class hotfixed in PR #77). Load each demo **top-level**, not through the width-constrained detail-page iframe. Sweep **both themes** of the one file: load it, then run the probe once with `data-theme="light"` and once with `"dark"`. They share layout, but PR #77's lesson is that a fix can miss one theme, and the two scopes can still size text differently. `preview_eval`: `window.location.href = "http://localhost:3000/preview/{slug}/preview.html"`, and set the theme with `document.documentElement.setAttribute('data-theme', '{theme}')` before each probe, then at **375 (mobile) / 768 (tablet) / 976 (detail-page embed width — the historical blind spot where multi-column cells are tightest, see PR #150) / 1440 (desktop)** × 900 run `mcp__Claude_Preview__preview_resize` to `{width} × 900` followed by `preview_eval` of the overflow probe:
```js
(() => {
const d = document.documentElement;
const vw = d.clientWidth;
const overflowPx = d.scrollWidth - vw;
const broken = overflowPx > 1;
// Collect culprits only when the document actually overflows, AND skip any element
// inside an overflow-x: hidden/auto/scroll ancestor: an intentional horizontally-
// scrollable row (chip row, carousel) reports right > vw without extending the
// document, so it is not the break even when another element broke the page.
const culprits = !broken ? [] : Array.from(document.querySelectorAll('body *'))
.filter(el => {
const r = el.getBoundingClientRect();
if (r.right <= vw + 1 && r.left >= -1) return false;
for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
const ox = getComputedStyle(p).overflowX;
if (ox === 'hidden' || ox === 'auto' || ox === 'scroll') return false;
}
return true;
})
.slice(0, 6)
.map(el => {
// getAttribute('class') works for SVG too (el.className is an SVGAnimatedString there).
const cls = (el.getAttribute('class') || '').trim();
return el.tagName.toLowerCase() + (cls ? '.' + cls.split(/\s+/).slice(0, 2).join('.') : '');
});
return { viewport: vw, scrollWidth: d.scrollWidth, overflowPx, broken, culprits };
})()
```
`broken = overflowPx > 1` (1px tolerance) means a horizontal scrollbar — a broken responsive layout. The check keys on the **document** `scrollWidth`, so an element inside an intentional horizontally-scrollable row (a chip row, a carousel) does not trip it. `culprits` (collected only when `broken`, and excluding any element nested in an `overflow-x` scroll/clip ancestor) lists the genuinely page-extending elements (e.g. `.comp-card`, `.ftile`) so the fix can be targeted. Collect every `broken` result as `breaks[] = {file, width, overflowPx, culprits}`.
**Auto-fix loop** (≤ 2 attempts) when `breaks` is non-empty — reuses the Stage 9a dispatch and the Stage 10 copy, so there is no new mechanism:
1. Write a synthetic review at `{cache_dir}/preview-review-resp-{attempt}.json` whose `issues[]` carries one `severity: "block"` entry per break: `{"severity":"block","section":"responsive — {theme} @{width}px","fix":"Horizontal overflow {overflowPx}px at {width}px. Offending: {culprits}. Repair per the author's Responsive & mobile-overflow guard — the usual root cause is a bare 1fr grid track flooring at its content min-content, so switch content tracks to minmax(0, 1fr), add a mobile grid-collapse @media rule, and put min-width: 0 on items wrapping fixed-width children. A layout fix belongs in the shared rules, not duplicated per theme scope."}`.
2. Dispatch `preview-html-author` exactly as in **Stage 9a**, with `prior_review_path` = that JSON. The author rewrites `{cache_dir}/preview.html`.
3. Re-copy staging → public with the **Stage 10** `cp` commands (the Stage 10 logo deterministic check still applies).
4. `preview_eval`: `window.location.reload()` (the `/preview/*` `no-cache` header serves the fresh file), then re-run the sweep.
Stop when `breaks` is empty or after 2 attempts.
**Result**: if `breaks` is empty → `responsive_result = ok` (record the attempt count). If still non-empty after 2 attempts → `preview_screenshot` at the narrowest failing width for evidence and set `responsive_result = warn` with the residual `breaks`. Non-blocking either way (consistent with the non-blocking preview loop). The OG image is derived from design.md, so re-fixed previews do **not** trigger an OG rebuild. (The port-collision path never reaches this step — it returns to Stage 13 at step 1 — so handling for that case lives in the Stage 13 report, not here.)
12. **Stop the dev server**: `Bash`: `kill $(lsof -t -i:3000) 2>/dev/null || true`. Killing by port is portable across macOS/Linux and avoids accidentally killing other `pnpm` processes the user might be running. The `|| true` keeps the skill from aborting if the process already exited.
If preview MCP tools are unavailable, fall back to `Bash`: `curl -sf http://localhost:3000/services/{slug} | grep -q '
` on the HTML page.
- Final review scores: design `{score}/10`, preview `{score}/10`.
- Screenshots taken during verification (paths or inline).
- Responsive verification (Stage 12 sweep) — pick the line by state:
- `responsive_result = ok` → `반응형: ✅ 375/768/976/1440 가로 오버플로 없음 (자동수정 {attempts}회)`
- `responsive_result = warn` → `반응형: ⚠️ 잔여 오버플로 — {file} @{width}px {overflowPx}px, 요소 {culprits} (스크린샷 {path}, 자동수정 2회 후 잔존)`
- skipped — set when `verification_skipped: port_collision` (step 1 returned early, so `responsive_result` was never assigned) **or** `responsive_result = skipped` (preview MCP unavailable) → `반응형: ⏭ 검증 건너뜀 (포트 충돌 / preview MCP 없음)`
- Leftover TODOs:
- If the logo values are empty: "Logo asset: `public/logos/{slug}.svg|png|webp|avif` 가 아직 없습니다. 직접 추가한 뒤 frontmatter `logo: https://getdesign.kr/logos/{slug}.{ext}` (절대 URL, 외부 복사 대비) 를 채우고 preview HTML에는 `![](\"/logos/{slug}.{ext}\")
` (site-relative, iframe 전용) 형식으로 렌더링하세요."
- Any preview review warnings if iteration 3 didn't reach 8.
`AskUserQuestion`: "캐시 정리할까요?"
- "지금 삭제" → `rm -rf .claude/cache/design-md/{slug}/`
- "보관 (디버깅용)" → leave intact.
## Edge cases
- **WebFetch blocked / paywalled** — research-collector halts with INSUFFICIENT_SOURCES, skill body re-prompts user (Stage 5).
- **Docs-site crawl yields 0 pages / fails** — Stage 4b surfaces the failure via `AskUserQuestion`; research proceeds from `source_urls` alone with `crawl_corpus_path = "none"`.
- **Reviewer never reaches 8 in 3 iterations** — checkpoint shows the failing draft and verdict; user decides via AskUserQuestion.
- **Responsive overflow persists after 2 auto-fix attempts (Stage 12 step 11)** — surface it as a ⚠️ in the Stage 13 report (residual `breaks` + screenshot) and finish anyway. Non-blocking, consistent with the preview loop; the placed design.md and OG image are unaffected.
- **User aborts at checkpoint** — leave cache intact, print resume path. Do not delete partial work.
- **`pnpm build:og` fails** — Stage 11's error path. Do not auto-rollback the placed .md.
- **Subagent missing expected output file** — retry once. Second failure aborts with diagnostic.
- **Pretendard CDN dependency** — tokens.css imports Pretendard from jsDelivr. Online-only assumption; flag in the final report.
- **Preview HTML / logo cache policy** — `/preview/*` and `/logos/*` are served with `Cache-Control: no-cache` by `previewCacheHeadersPlugin` in `vite.config.ts` (both `vite dev` and `vite preview`). This prevents browsers heuristic-caching iframe HTML and logo files after entry edits — the cache trap that previously required users to hard-refresh after every preview/logo change. Per-entry HTML does NOT need its own `` (unreliable across browsers anyway); the server-level header is the source of truth. Production cache headers are handled by the host (Vercel defaults).
## What this skill must NOT do
- Edit any file outside of `services/`, `public/preview/`, `public/logos/{slug}.{svg,png,webp,avif}` for user-supplied logo assets, and `.claude/cache/design-md/{slug}/`.
- Skip the user checkpoint. Even if the design review passes 10/10 on iteration 1, show the draft to the user before writing to `services/`.
- Run subagents in parallel within a stage. The design-md author and reviewer are explicitly sequential because the reviewer needs the author's output. Same for preview HTML.
- Use `npm` instead of `pnpm` for any script invocation. The project uses `pnpm` (memorized preference).
- Write outside `cache_dir` from any subagent. Subagents have constrained tool access for this reason; respect that.
## Why this design
- **Five specialized subagents (vs. one general agent looping)**: author and reviewer are intentionally separated to avoid self-grading bias. Same model in both roles with different prompts produces noticeably stricter reviews. All five agent definitions pin `model: inherit` (the documented default, stated explicitly) so the whole pipeline follows the session model — no stage silently runs on a different tier when the operator switches models.
- **Machine gates before reviewer dispatches (6a2/9a2)**: every mechanically checkable rule lives in `pnpm validate:draft` / `pnpm validate:previews`, so reviewer quality degrades gracefully with model capability — a weaker reviewer model still receives deterministic findings instead of being trusted to "grep mentally".
- **Single user checkpoint at design.md**: in this pipeline the preview is built *from* the approved design.md, so the design.md is upstream of everything after the checkpoint. Locking it after one approval gate gives the user maximum control with minimum interruption. This ordering describes what this pipeline produces, not every entry: when an entry's design.md and preview were both transcribed from a Claude Design handoff bundle, the bundle is upstream of both, and the design.md's silence is not evidence against the preview (`.claude/skills/preview-prose-audit/SKILL.md`).
- **Stitch v0.1 standard sections**: every catalog entry follows the Stitch v0.1 structure (English headings, OKLCH tokens, citation hygiene). The early `_demo-*.md` fixtures that used Korean editorial headings have been removed; if older entries surface in git history they are superseded.
- **OKLCH everywhere, never hex**: downstream LLMs (which are the primary audience for design.md) reason about lightness/chroma/hue components more reliably than hex codes.
- **File-presence state encoding**: simpler than a state.json for v1; resumable because the cache dir's contents fully describe pipeline progress.