oh-my-design-cli 1.3.0 → 1.3.9

package/skills/omd-reference-capture/SKILL.md

@@ -37,6 +37,49 @@ description: "선택된 reference brand의 라이브 사이트에서 디자인
 - 명시: "X 에셋 가져와줘", "X 사이트 패칭해줘", "X 라이브 스타일 추출", "X reference 캡쳐"
 - 묵시: omd:harness 안에서 reference 선정 후, 또는 사용자가 "X처럼 만들어줘" 요청 시 omd:init 후속 작업으로 자동 제안
 
+## Phase 0 — (v1.3.3 폐기) Mode 선택
+
+이전 버전(v1.3.2)은 `clone` vs `inspired` 두 mode를 제공했으나 v1.3.3에서 폐기. 시각적 동일성은 brand creative work을 사용자 product에 reproduce해야 가능하고 그건 IP 영역. 단일 mode 흐름으로 통일 — brand 토큰·구조·voice는 가져오되, brand 자체 자산(mascot·로고·마케팅 사진)은 reference로만 보존하고 사용자 product에는 자체 자산 자리(`[YOUR LOGO]` placeholder 등)를 둠. 결과물의 시각 polish는 무료 라이선스 자산 라이브러리(Open Peeps / Lucide / Heroicons 등 CC0/MIT/SIL OFL)로 채움 — 자세한 카탈로그는 `skills/omd-harness/SKILL.md` Step 4 master prompt rule 6 참조.
+
+다음 모든 Phase는 단일 흐름. (구버전 Phase 0 - clone/inspired ask 제거됨.)
+
+## (legacy reference) — 이전 mode 선택 텍스트 (참고용, 동작 안 함)
+
+reference-capture가 어디까지 가져올지는 사용자 의도에 따라 두 갈래. 호출 진입 시점에 mode가 결정되지 않았다면 사용자에게 한 번에 묻기:
+
+```
+<id>를 어떻게 활용할까요?
+
+1. clone — 거의 똑같이 시작. 실제 로고·일러스트·폰트 받아와서 dev scaffold 구성.
+   landing이 라이브 사이트와 시각적으로 매우 비슷하게 시작됩니다.
+   ⚠ 자동으로 CLONE-MODE.md 배너 + replace-checklist.md가 생성되고,
+     "사용자 product에 ship 전에 brand 자산을 자체 자산으로 교체 필요"라고 표시됩니다.
+
+2. inspired — 톤·체계만 가져옴. [YOUR LOGO] placeholder, 일러스트는 generic placeholder.
+   브랜드의 voice·원칙·팔레트 철학만 적용. 바로 ship 가능한 상태로 산출.
+
+답: clone / inspired (기본값: inspired)
+```
+
+이 선택은 `.omd/init-context.json`의 `mode` 필드에 저장되어 후속 omd:init / omd:harness / omd:apply가 일관되게 사용한다.
+
+이미 omd:harness Step 3.7에서 mode를 묻고 진입했으면 Phase 0 skip.
+
+### Mode별 동작 요약
+
+| 단계 | clone | inspired |
+|---|---|---|
+| LICENSE-NOTE.md | 작성 ✓ | 작성 ✓ |
+| tokens.json (atomic facts) | 캡쳐 ✓ | 캡쳐 ✓ |
+| structure.json (composition facts) | 캡쳐 ✓ | 캡쳐 ✓ |
+| logo.<ext> | 캡쳐 + product `<img>`로 사용 가능 (banner 의무) | 캡쳐만 (product에 미사용, placeholder 강제) |
+| screenshots/ | 캡쳐 ✓ | 캡쳐 ✓ |
+| fonts.json (CDN URLs) | 캡쳐 + 자동 `<link>` 로드 강제 | 캡쳐만 (수동 로드) |
+| hero illustration assets | (있고 publicly accessible면) URL 기록 + 사용 가능 | URL만 기록 |
+| attribution.md | 작성 + 사용 표시 | 작성 |
+| **CLONE-MODE.md (project root)** | **mandatory 작성** | 미작성 |
+| **replace-checklist.md (project root)** | **mandatory 작성** | 미작성 |
+
 ## 전체 플로우
 
 ```
@@ -145,8 +188,156 @@ This note is generated by `omd:reference-capture`. Do not edit by hand
 — rerun the skill to refresh.
 ```
 
+## Phase 3.5 — Font 캡쳐 (fonts.json, 라이브 폰트가 실제 로드되도록)
+
+캡쳐된 brand가 web font(Pretendard / BM JUA / Inter / Noto Sans KR 등 시스템 기본이 아닌 폰트)를 쓰면, 토큰만 잡아도 생성기가 폰트를 **로드 안 하면** 결과가 시스템 fallback으로 바뀐다 (가장 흔한 증상: macOS 시스템 폰트가 둥글둥글하게 렌더되는 mismatch).
+
+`assets/_reference/<id>/fonts.json`:
+
+```json
+{
+  "captured_at": "<ISO-8601>",
+  "fonts": [
+    {
+      "family": "Pretendard",
+      "license": "SIL OFL 1.1 (open-source, free for commercial use)",
+      "cdn_url": "https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/static/pretendard.css",
+      "html_link": "<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/static/pretendard.css\" />",
+      "live_observed": true,
+      "role": "body + heading"
+    },
+    {
+      "family": "Apple SD Gothic Neo",
+      "license": "system (macOS/iOS)",
+      "cdn_url": null,
+      "html_link": null,
+      "live_observed": false,
+      "role": "system fallback"
+    }
+  ]
+}
+```
+
+### 3.5.1 추출 절차
+
+1. live homepage의 computed style에서 `body` / `h1-h3` / 주요 buttons의 `font-family` 첫 항목 추출 (fallback chain 무시, 첫 토큰만)
+2. 추출된 family를 known-font registry에 매칭:
+
+| 추출된 family | license | CDN URL |
+|---|---|---|
+| `Pretendard` | SIL OFL 1.1 | `https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/static/pretendard.css` |
+| `Pretendard Variable` | SIL OFL 1.1 | `https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/variable/pretendardvariable.css` |
+| `Noto Sans KR` | SIL OFL 1.1 | `https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700;900&display=swap` |
+| `Inter` | SIL OFL 1.1 | `https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap` |
+| `Wanted Sans` | SIL OFL 1.1 | `https://cdn.jsdelivr.net/gh/wanteddev/wanted-sans@latest/packages/wanted-sans/fonts/webfonts/static/complete/WantedSans.css` |
+| `BM JUA` (배민 주아체) | 배달의민족 폰트 라이선스 (개인·기업 무료, **재배포·판매 금지**) | (CDN 미공식 — `html_link: null` 처리, 사용자에게 "BM JUA는 라이브에서 관측 안 됨; 로컬 fallback" 알림) |
+| `Apple SD Gothic Neo`, `Malgun Gothic`, `system-ui`, `-apple-system` | system | `html_link: null` |
+
+registry에 없는 family는 `html_link: null` + `notes`에 "CDN 미확인, 수동 로드 필요" 기록.
+
+### 3.5.2 BM JUA 같은 misapplication 가드
+
+canonical DESIGN.md가 "BM JUA를 landing/promo accent로"라고 적어뒀더라도, **라이브 inspect에서 실제 BM JUA 사용이 관측 안 되면** `live_observed: false`로 기록하고 후속 generator가 적용 안 하도록 신호. omd:init Phase 5B의 priority rule이 `live_overrides` 우선 처리.
+
+### 3.5.3 Clone mode 강제 로드
+
+mode=clone이면 omd:init/omd:harness가 생성 HTML `<head>`에 fonts.json의 `live_observed: true` 항목 `html_link`를 **반드시** 박는다. mode=inspired면 폰트 로드는 사용자 선택.
+
+## Phase 3.9 — Browser harness 자동 선택 (v1.3.6 신설)
+
+라이브 캡쳐 도구는 두 가지 옵션. 환경 detect 후 빠른 쪽 사용:
+
+### Fast-path: browser-harness (있으면 우선)
+
+`shutil.which("browser-harness")` 또는 `command -v browser-harness`로 detect. 있고 `browser-harness --doctor` 가 `[ok ] chrome running` 띄우면 fast-path:
+
+- **장점**: heredoc 단일 호출 + Chrome remote-debugging CDP 직접 → playwright MCP 대비 3-5x 빠름 (실측 3.5s/페이지). sub-agent의 "did live inspect" 거짓 보고 불가능 (heredoc 실행 자체가 evidence).
+- **prerequisite**: Python 3.11+, uv 또는 pip, Chrome with `--remote-debugging-port=9222` 또는 `chrome://inspect#remote-debugging` 활성.
+- **호출 패턴**:
+  ```bash
+  BU_CDP_URL="http://localhost:9222" browser-harness <<'PY'
+  new_tab("https://<brand-domain>")
+  wait_for_load()
+  import time; time.sleep(1.5)  # SPA hydration
+  result = js("""
+  (() => {
+    const body = getComputedStyle(document.body);
+    const ctas = [...document.querySelectorAll('button, a[role="button"], [class*="button"]')]
+      .filter(el => {
+        const r = el.getBoundingClientRect();
+        return r.height >= 32 && r.height <= 80 && r.top < 1200;
+      })
+      .slice(0, 8).map(el => {
+        const cs = getComputedStyle(el);
+        return { bg: cs.backgroundColor, color: cs.color, radius: cs.borderRadius,
+                 padding: cs.padding, fontWeight: cs.fontWeight, h: Math.round(el.getBoundingClientRect().height) };
+      });
+    return JSON.stringify({
+      bodyFont: body.fontFamily.split(',')[0].replace(/['"]/g,'').trim(),
+      ctas, scrollH: document.documentElement.scrollHeight
+    });
+  })()
+  """)
+  print(result)
+  capture_screenshot(path="<assets_dir>/screenshots/hero-desktop.png", full=False)
+  PY
+  ```
+- 결과를 `tokens.json#live_overrides` + `.live-inspect-proof.json` raw_samples에 그대로 박음.
+
+### Fallback: playwright MCP (default)
+
+browser-harness 미설치면 `mcp__playwright__browser_navigate` + `browser_evaluate` + `browser_take_screenshot` 사용 (이전 버전 동작 그대로).
+
+### 자동 선택 logic
+
+```bash
+if command -v browser-harness >/dev/null && browser-harness --doctor 2>&1 | grep -q "ok.*chrome running"; then
+  echo "MODE=harness"
+else
+  echo "MODE=playwright"
+fi
+```
+
+### 사용자 안내 (선택)
+
+skill 진입 시 사용자에게 한 줄로 알림:
+> "browser-harness 감지됨 — fast-path 사용 (3.5s/page)" 또는 "playwright MCP 사용 — browser-harness 설치하면 3x 빠름: github.com/browser-use/browser-harness"
+
+이 안내는 informational only, 사용자 action 요구 X.
+
 ## Phase 4 — 토큰 캡쳐 (facts)
 
+**Proof gate (위반 = regression)**: 이 Phase는 실제 playwright navigate + computed style 추출이 일어났음을 후속 generator에게 증명하는 artifact를 남겨야 함. 이전 버전(v1.3.3)에서 sub-agent가 "라이브 inspect 했다"고 보고하지만 실제로는 canonical 값만 복사하는 결함이 관측됨. proof gate가 이를 차단:
+
+### 4.0 — `.live-inspect-proof.json` 작성 (REQUIRED, 이 파일 없으면 후속 generator는 live_overrides 무시)
+
+playwright `browser_navigate` 직후 `browser_evaluate`로 raw computed style 5개 이상 추출하고 결과를 `assets/_reference/<id>/.live-inspect-proof.json`에 저장:
+
+```json
+{
+  "navigated_at": "<ISO-8601 with seconds>",
+  "source_url": "https://www.banksalad.com",
+  "viewport": "1280x800",
+  "tool_used": "playwright_mcp_browser_evaluate",
+  "raw_samples": [
+    { "element_selector": "body", "font-family": "Pretendard, ...", "color": "rgb(0, 0, 0)", "background": "rgba(0, 0, 0, 0)" },
+    { "element_selector": "header nav a:first-child", "font-size": "14px", "font-weight": "500" },
+    { "element_selector": "button:contains('앱 다운로드')", "background-color": "rgb(19, 189, 126)", "border-radius": "41px" },
+    { "element_selector": ".hero-section section", "background-color": "rgba(0, 0, 0, 0)" },
+    { "element_selector": "footer", "background-color": "rgb(255, 255, 255)" }
+  ],
+  "playwright_response_hash": "<5+ char of returned evaluate result>"
+}
+```
+
+후속 generator (omd:init / omd:harness)는 이 파일이 **존재하고 raw_samples 길이 ≥5** 이어야만 `tokens.json#live_overrides`를 신뢰. 파일 없거나 비어있으면 canonical만 사용.
+
+### 4.1 — drift detection (proof와 tokens.json#live_overrides 일관성)
+
+tokens.json의 `live_overrides` 값이 캡쳐된 canonical 값과 **byte-for-byte 동일**하면 live inspect가 실제로는 안 돈 것 → live_overrides 블록을 통째로 삭제하고 사용자에게 "live inspect 결과가 canonical과 동일 — 차이 없거나 inspect 실패. tokens.json#live_overrides 미사용."이라고 알림. metadata note만 적고 실제 hex override 없는 거짓 live_overrides 금지.
+
+### 4.2 — token 캡쳐 본문
+
 playwright MCP를 사용해 homepage에 navigate한 뒤 computed styles를 추출. 결과는 `assets/_reference/<id>/tokens.json`:
 
 ```json
@@ -185,6 +376,113 @@ playwright MCP를 사용해 homepage에 navigate한 뒤 computed styles를 추
 
 inspect 패턴은 `.claude/skills/omd-add-reference/SKILL.md`의 "apple.com 류 라이브 inspect 패턴"과 동일. 5-10 elements 샘플링.
 
+## Phase 4.5 — 구조 cue 캡쳐 (structure.json)
+
+Tokens는 색·radius·font 같은 원자 값이고, **structure**는 페이지가 어떻게 짜였는지의 관측 가능한 facts다. 토큰만 보면 같은 brand도 surface마다 다른 결과물이 나오는 mismatch가 생긴다 (예: app surface의 2px-radius advisor 톤 vs marketing landing의 41px-pill 일러스트 톤). structure.json은 후속 생성기가 **실제 라이브 사이트의 composition idiom**을 따라가도록 한다.
+
+### 4.5.1 추출 항목 (facts only — 저작권 영역 0)
+
+`assets/_reference/<id>/structure.json`:
+
+```json
+{
+  "captured_at": "<ISO-8601>",
+  "source_url": "https://www.banksalad.com",
+  "viewport": "1280x800",
+  "hero": {
+    "type": "illustration | photo | video | data-card | text-only | mixed",
+    "has_carousel": false,
+    "carousel_dot_count": 0,
+    "primary_visual_position": "right | left | center | full-width | background",
+    "background_ornament": "none | gradient-blob | geometric | radial-tint | photo-bleed",
+    "approx_height_vh": 75
+  },
+  "cta": {
+    "dominant_shape": "pill | rectangular | ghost-only | text-link",
+    "primary_radius_px_observed": 41,
+    "secondary_style": "ghost-outline | underline | none",
+    "vertical_stack": true
+  },
+  "nav": {
+    "structure": "horizontal-categories | mega-menu | hamburger-mobile | single-row-utility | top-tabs",
+    "approx_item_count": 11,
+    "has_search": false,
+    "has_locale_switch": false
+  },
+  "page": {
+    "viewport_heights": 3.9,
+    "section_count_observed": 8,
+    "predominant_alignment": "center | left | grid-asymmetric",
+    "image_density": "high | medium | low | none"
+  },
+  "section_rhythm": [
+    "hero",
+    "social-proof",
+    "feature-grid",
+    "testimonial",
+    "footer"
+  ],
+  "notes": [
+    "라이브 hero는 carousel — 3-5 슬라이드로 product 카테고리 순환",
+    "section_rhythm은 위에서 아래로 관측 순서"
+  ]
+}
+```
+
+### 4.5.2 추출 방법
+
+playwright로 homepage navigate 후 다음 JS 실행 (facts derivation only):
+
+```js
+() => {
+  // hero 탐색 — 보통 첫 800px 이내 viewport에서 가장 큰 visual element
+  const heroCandidates = [...document.querySelectorAll('section, header + div, [class*="hero" i], [class*="Hero"]')]
+    .filter(el => {
+      const r = el.getBoundingClientRect();
+      return r.top < 200 && r.height > 300 && r.width > 800;
+    });
+  const heroEl = heroCandidates[0];
+
+  // type 판정
+  const heroImgCount = heroEl ? heroEl.querySelectorAll('img, svg, picture').length : 0;
+  const heroVideoCount = heroEl ? heroEl.querySelectorAll('video').length : 0;
+  const heroHasCarouselDots = heroEl ? !!heroEl.querySelector('[class*="dot" i], [class*="pagination" i], [class*="indicator" i]') : false;
+
+  // CTA 탐색 — viewport 위 절반의 button/cta
+  const ctas = [...document.querySelectorAll('button, a[role="button"], [class*="button" i] a')]
+    .filter(el => el.getBoundingClientRect().top < 800)
+    .map(el => {
+      const cs = getComputedStyle(el);
+      return { radius: cs.borderRadius, bg: cs.backgroundColor };
+    });
+  const dominantRadii = ctas.map(c => parseInt(c.radius)).filter(n => !isNaN(n));
+  const maxRadius = Math.max(...dominantRadii, 0);
+
+  // nav
+  const navEl = document.querySelector('header nav, [role="navigation"]');
+  const navItemCount = navEl ? navEl.querySelectorAll('a, button').length : 0;
+
+  return {
+    hero_img_count: heroImgCount,
+    hero_video_count: heroVideoCount,
+    hero_has_carousel_dots: heroHasCarouselDots,
+    cta_max_radius_observed: maxRadius,
+    cta_sample_count: ctas.length,
+    nav_item_count: navItemCount,
+    total_scroll_height_px: document.documentElement.scrollHeight,
+    viewport_height_px: window.innerHeight,
+  };
+}
+```
+
+위 raw 측정값을 structure.json schema의 enum 값으로 매핑 (예: `hero_img_count >= 1 && hero_video_count === 0` → `hero.type: "illustration"`, `cta_max_radius_observed >= 40` → `cta.dominant_shape: "pill"`).
+
+### 4.5.3 IP 가드레일 재확인
+
+structure.json에는 텍스트·이미지·copy·brand statement 일체 X. 오로지 **structural facts** (개수, radius, viewport-relative position). 저작권 영역 아님.
+
+`notes` 필드의 자유 텍스트는 **본인 관찰**만 — 사이트의 마케팅 카피 인용 금지.
+
 ## Phase 5 — 시각 reference 캡쳐
 
 ### 5.1 로고 다운로드
@@ -229,6 +527,7 @@ Captured: **<ISO-8601>** via `omd:reference-capture`
 | File | Source URL | Captured | Notes |
 |---|---|---|---|
 | `tokens.json` | `<homepage_url>` | <date> | Computed styles via playwright, factual analysis |
+| `structure.json` | `<homepage_url>` | <date> | Observable composition facts (hero type, CTA shape, nav structure, page rhythm) |
 | `logo.<ext>` | `<logo_url>` | <date> | Brand trademark — do not redistribute |
 | `screenshots/hero-desktop.png` | `<homepage_url>` (1280×800) | <date> | Reference for design alignment |
 | `screenshots/hero-mobile.png` | `<homepage_url>` (375×812) | <date> | Reference for design alignment |
@@ -250,6 +549,103 @@ directory). Captured tokens reflect the live site at capture time and
 may drift as the brand evolves.
 ```
 
+## Phase 6.5 — Clone mode 전용 산출 (mode=clone일 때만)
+
+### 6.5.1 `CLONE-MODE.md` (project root, mandatory)
+
+clone mode 진입 시점에 프로젝트 루트(`./CLONE-MODE.md`)에 **다른 산출보다 먼저** 작성:
+
+```markdown
+# ⚠ CLONE MODE — Reference Scaffold
+
+This project was scaffolded in **clone mode** from the **<id>** reference
+on **<ISO-date>**. The scaffold deliberately resembles <id>'s live
+public surface to help you start fast.
+
+## What this means
+
+- **Brand assets in this project are NOT yours.** The header logo, web
+  fonts, illustration patterns, and visual rhythm currently match
+  <id>'s public brand. They are placeholders/references, not part of
+  your product's identity.
+- **You MUST replace them before shipping.** See `replace-checklist.md`
+  for the exact list of files and lines to swap.
+- **Marketing copy** in this scaffold was generated fresh in the brand's
+  voice register — it is not copied verbatim from the live site. Edit
+  freely for your product's narrative.
+
+## Why clone mode exists
+
+Designers and engineers commonly evaluate "what would an X-styled UI
+look like for my product" by starting from a close visual reference.
+clone mode automates that scaffold step. It is **not** a license to
+ship the reference brand's identity as your own.
+
+## To switch back to inspired mode
+
+Re-run with `mode=inspired` — all brand-identifying assets revert to
+`[YOUR LOGO]` placeholders and generic illustration silhouettes, ready
+to ship with your own brand.
+
+---
+
+Generated by `omd:reference-capture`. Do not delete this banner until
+`replace-checklist.md` is fully resolved.
+```
+
+### 6.5.2 `replace-checklist.md` (project root, mandatory)
+
+clone mode가 만든 모든 brand-identifying 자산의 정확한 swap 지점 enumeration:
+
+```markdown
+# Replace Checklist — pre-ship swap list
+
+Before shipping, resolve every item below. Each item points to a
+brand-cloned asset that must be replaced with your own product's
+equivalent.
+
+## Logo
+
+- [ ] `assets/_reference/<id>/logo.<ext>` — replace `<img src="assets/_reference/<id>/logo.<ext>">` references
+      in `landing.html` (line <N>), `app/layout.tsx` (line <N>), etc.
+      Suggested replacement: `assets/brand/logo.<ext>` (your own).
+
+## Web fonts
+
+- [ ] `<link rel="stylesheet" href="<CDN URL>">` in `landing.html` head
+      — keep if you use the same font (Pretendard is open-source);
+      remove if you switch to a different typeface.
+
+## Hero illustration / imagery
+
+- [ ] `landing.html` lines <N-M> — placeholder illustration matching
+      <id>'s visual idiom. Replace with your own illustration / photo.
+
+## Marketing copy
+
+- (none — all copy was written fresh in the brand voice register;
+  edit for your product's specific narrative as needed)
+
+## Color tokens
+
+- [ ] Live brand colors (e.g. `#13bd7e` for banksalad) are used as
+      `--brand-primary`. Adjust if your brand uses a different hue.
+
+## Final pre-ship check
+
+```bash
+# Should return no matches before shipping:
+grep -rn "_reference/<id>" .
+```
+
+## When this checklist is complete
+
+Delete this file and `CLONE-MODE.md` from the project root. The
+scaffold is now your product.
+```
+
+이 두 파일은 generator가 clone mode를 인지하는 마커이기도 함. 사용자가 의도적으로 삭제해야 inspired mode로 전환.
+
 ## Phase 7 — 사용자 요약
 
 prose로:
@@ -295,7 +691,8 @@ UI 생성 시 logo 사용 규칙 (omd:apply / omd:harness 둘 다 적용):
 assets/_reference/<id>/
 ├── LICENSE-NOTE.md       (사전 작성)
 ├── attribution.md        (마지막 작성)
-├── tokens.json           (facts)
+├── tokens.json           (facts — atomic values)
+├── structure.json        (facts — composition cues for surface idiom)
 ├── logo.<svg|png|ico>    (brand mark — reference only)
 └── screenshots/
     ├── hero-desktop.png  (1280×800, above fold)