Omd:reference Capture

omd:reference-capture — Live Reference Capture

선택된 reference brand의 라이브 사이트에서 디자인 컨텍스트를 가져온다. 산출물은 assets/_reference// 디렉토리에 모이고, 사용자의 디자인 작업(omd:apply / omd:harness)에서 컨텍스트로 활용된다.

핵심 원칙 (위반 = regression)

이 스킬은 dev/디자인 reference 캡쳐용이다. brand IP를 사용자 product에 그대로 ship하는 도구가 아니다.

1. Facts vs. Content 구분

• Facts (캡쳐 OK): 컴퓨티드 색상 hex, 폰트 family/weight, spacing, radius, 컴포넌트 구조 — 디자인 시스템 분석은 fair use.
• Brand content (저장만, 사용자 product에 verbatim ship 금지): 로고, 히어로 사진, 마케팅 카피, 슬로건. 다운로드는 reference 확인용으로만.

1. 저작권 표시 의무

• 캡쳐 시작 전 assets/_reference//LICENSE-NOTE.md를 가장 먼저 작성.
• 모든 다운로드 파일은 attribution.md에 source URL + 캡쳐 일자 + 추정 권리자 기록.

1. 사용자 product 생성 시 분리

• omd:apply/omd:harness가 UI를 만들 때, brand의 voice/tone(facts)은 참고하되 literal copy는 새로 작성.
• brand 히어로 사진 / 마케팅 영상은 사용자 product에 직접 embed하지 말고 placeholder + "사용자 자체 자산으로 교체 필요" 주석.

1. robots.txt / TOS 우선

• 다운로드 전 curl -sI /robots.txt로 기본 정책 확인.
• 사이트가 명시적으로 차단하는 경로면 skip하고 사용자에게 알림.

1. scope 한정

• 기본 캡쳐 대상: homepage 1개 + favicon/logo + 컴퓨티드 토큰.
• PDP / checkout / 인증 뒤 페이지는 기본 skip — 사용자가 명시적 요청해야만.
• 비디오 / 대용량 미디어는 기본 skip (URL만 attribution.md에 기록).

트리거

• 명시: "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가 결정되지 않았다면 사용자에게 한 번에 묻기:

를 어떻게 활용할까요?

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. | 캡쳐 + product `로 사용 가능 (banner 의무) | 캡쳐만 (product에 미사용, placeholder 강제) | | screenshots/ | 캡쳐 ✓ | 캡쳐 ✓ | | fonts.json (CDN URLs) | 캡쳐 + 자동 ` 로드 강제 | 캡쳐만 (수동 로드) | | hero illustration assets | (있고 publicly accessible면) URL 기록 + 사용 가능 | URL만 기록 | | attribution.md | 작성 + 사용 표시 | 작성 | | CLONE-MODE.md (project root) | mandatory 작성 | 미작성 | | replace-checklist.md (project root) | mandatory 작성 | 미작성 |

전체 플로우

Phase 1: 입력 검증 — brand id 확정
Phase 2: 라이브 URL 수집 (homepage, logo, docs)
Phase 3: 디렉토리 + LICENSE-NOTE 사전 작성 (CRITICAL — 다운로드보다 먼저)
Phase 4: 토큰 캡쳐 (facts) — playwright computed styles
Phase 5: 시각 reference 캡쳐 (screenshot + 로고)
Phase 6: attribution.md 작성
Phase 7: 사용자 요약 + 다음 단계 안내

Phase 1 — 입력 검증

사용자 요청에서 brand id 추출:

• 명시 brand 이름 (한글/영문) → .claude/data/reference-fingerprints.json items[].id 매칭
• 없으면 사용자에게 묻기: "어느 reference brand 자료를 가져올까요? (예: banksalad, toss, socar)"

id가 카탈로그에 없으면 종료 + "X는 reference 카탈로그에 없어요. omd:init으로 추가 가능합니다."

Phase 2 — 라이브 URL 수집

reference 자료 경로 `` 는 reference DESIGN.md 위치 기준으로 resolve (먼저 존재하는 것 사용 — omd:init Phase 4.1과 동일한 카탈로그 resolution order):

1. .claude/data/references//DESIGN.md (installer가 복사 — npx 설치 기본 경로; 디렉토리에는 DESIGN.md만 보장)
2. node_modules/oh-my-design-cli/web/references//DESIGN.md (로컬 npm 설치 직접 경로 — 디렉토리에 promo.json/research.md 포함)
3. web/references//DESIGN.md (개발 레포)
4. https://oh-my-design.kr//design.md 를 fetch (WebFetch 또는 curl -fsSL) — 1~3 로컬 경로가 전부 없을 때. 200이면 본문이 곧 reference DESIGN.md. 가져온 내용을 .claude/data/references//DESIGN.md로 캐시해 다음부터는 로컬 캐시(경로 1)로 잡히게 한다.

` = resolve된 DESIGN.md가 있는 디렉토리 (tier 4로 fetch한 경우 캐시 후 .claude/data/references//). promo.json/research.md`는 (1)/(4)에 없을 수 있으니, 없으면 (2)/(3)로 폴백하고 그래도 없으면 fingerprints 기반 추론으로 진행.

다음을 순서대로 시도:

1. homepage URL:

• /_promo.json의 logo_url이 brand site면 거기서 도메인 추출
• 없으면 /_research.md에서 Tier 1 source URL grep
• 둘 다 없으면 .claude/data/reference-fingerprints.json의 items[].category_raw 기반으로 추론 — 마지막 수단

1. logo URL (_promo.json 우선):

• _promo.json.logo_url → 그대로 사용
• 없으면 homepage HTML에서 apple-touch-icon / og:image / favicon-256 추출

1. 공식 DS docs URL (있으면):

• /DESIGN.md의 footer 또는 §4 verified 섹션에서 grep

수집한 URL 후보를 사용자에게 보여주고 확인:

다음 자료를 가져오려고 합니다:
  - homepage: https://www.banksalad.com
  - logo: https://blog.banksalad.com/static/img/logo-banksalad.svg
  - 공식 DS: (없음)

저작권 안내: 이 자료는 디자인 reference 용도로만 사용됩니다. 사용자 product에 그대로 ship하지 마세요.

진행하시겠어요? (yes/no/edit-urls)

Phase 3 — 디렉토리 + LICENSE-NOTE 사전 작성 (CRITICAL)

다운로드 시작 전에 다음을 먼저 작성:

mkdir -p "assets/_reference//screenshots"

assets/_reference//LICENSE-NOTE.md:

# License Note —  Reference Capture

This directory contains design-reference materials captured from
****'s public website on **** for the purpose of
informing UI design work in this project.

## What's here is for REFERENCE, not REDISTRIBUTION

- **Design tokens** (colors, fonts, spacing) — `tokens.json`. These
  are facts about the brand's design system and may be used to inform
  your own design.
- **Logo file** — captured for visual recognition during development.
  This is 's trademark. Do not use in your own product, your
  own marketing, or any redistribution. Replace with your own brand
  mark before shipping.
- **Screenshots** — captured for visual reference during development.
  Do not embed in your product, your blog, or social posts beyond
  fair-use commentary.

## What you should NOT do

- Embed `logo.*` or `screenshots/*.png` in your own product UI as if
  they belong to you.
- Copy `tokens.json`'s exact hex values into your own brand without
  shifting them via `delta_set` (see omd:init).
- Copy any marketing text from screenshots into your own product
  verbatim — voice/tone is fact, but specific phrasing is creative work.

## What you SHOULD do

- Use the **design language** (token relationships, component
  patterns, voice register) to inform your project's DESIGN.md.
- Reference the screenshots during design reviews to align with the
  visual target.
- Replace all brand-identifying assets with your own before any
  external sharing.

## Attribution

See `attribution.md` in this directory for source URLs and capture
timestamps.

---

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//fonts.json:

{
  "captured_at": "",
  "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": "",
      "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 `에 fonts.json의 liveobserved: true 항목 htmllink`를 반드시 박는다. 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 ") 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 { 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="/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

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//.live-inspect-proof.json에 저장:

{
  "navigated_at": "",
  "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": ""
}

후속 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가 실제로는 안 돈 것 → liveoverrides 블록을 통째로 삭제하고 사용자에게 "live inspect 결과가 canonical과 동일 — 차이 없거나 inspect 실패. tokens.json#liveoverrides 미사용."이라고 알림. metadata note만 적고 실제 hex override 없는 거짓 live_overrides 금지.

4.2 — token 캡쳐 본문

playwright MCP를 사용해 homepage에 navigate한 뒤 computed styles를 추출. 결과는 assets/_reference//tokens.json:

{
  "captured_at": "",
  "source_url": "https://www.banksalad.com",
  "tokens": {
    "colors": {
      "background": "#ffffff",
      "text_primary": "#2b2b2b",
      "text_body": "#434444",
      "interaction_primary": "#04c584",
      "interaction_hover": "#10df99"
    },
    "typography": {
      "body_font_family": "Pretendard, ...",
      "body_font_weight": "400",
      "heading_font_weight": "700",
      "base_size_px": 16
    },
    "shape": {
      "default_radius_px": 2,
      "card_radius_px": 2,
      "pill_radius_px": 16
    },
    "shadow": {
      "default": "0 2px 5px rgba(0,0,0,0.12)"
    }
  },
  "samples": [
    { "element": "primary button (hero CTA)", "raw_computed_style": { /* getComputedStyle slice */ } },
    { "element": "card", "raw_computed_style": { /* ... */ } }
  ]
}

inspect 패턴: 5-10 elements 샘플링 (body / header nav / hero CTA / card / footer 류 대표 element의 getComputedStyle 추출 — Phase 3.9의 JS 패턴과 동일한 방식). 캡쳐하려는 brand가 카탈로그에 없으면 웹 카탈로그(oh-my-design.kr/design-systems)에서 먼저 찾아보고, 카탈로그에 새 brand를 직접 추가하는 워크플로우(omd-add-reference)는 dev 레포(github.com/kwakseongjae/oh-my-design)에만 존재 — 배포본(npx 설치)에는 포함되지 않는다.

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//structure.json:

{
  "captured_at": "",
  "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": "h

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kwakseongjae](https://github.com/kwakseongjae)
- **Source:** [kwakseongjae/oh-my-design](https://github.com/kwakseongjae/oh-my-design)
- **License:** MIT
- **Homepage:** https://oh-my-design.kr

Install and usage instructions live in the source repository linked above.