bergside/design-md-chrome 딥다이브
— "보이는 대로 뽑아낸다" 웹사이트 → DESIGN.md/SKILL.md 크롬 확장

1프로젝트 한 줄 요약

design-md-chrome은 "웹사이트 → 디자인 토큰 문서" 변환기다. 확장 아이콘을 누르면 지금 활성 탭 페이지의 요소들에서 window.getComputedStyle로 실제 렌더링 값을 긁고, 그 값을 빈도 집계해 font.size.md, color.text.primary, space.3 같은 이름 붙은 토큰으로 정리한 뒤, 정해진 마크다운 템플릿에 끼워 넣는다.

출력은 두 모드다. DESIGN.md는 사람이 참고할 디자인 시스템 문서이고, SKILL.md는 YAML 프런트매터와 TYPEUI_SH_MANAGED_START/END 마커까지 갖춰 Claude Code(.claude/skills) 같은 에이전트가 바로 읽을 수 있게 만든 버전이다. 팝업에는 Copy·Download 외에 Quick install 버튼이 있어, 브라우저의 파일시스템 접근 API로 프로젝트 폴더에 SKILL.md를 곧장 써 넣을 수도 있다.

2왜 지금 뜨는가

2025~2026년 사이 Claude Code의 .claude/skills, Codex의 에이전트 규칙 파일처럼 "AI 코딩 에이전트에게 미리 읽혀 두는 스펙 문서"가 하나의 표준 관행이 됐다. 문제는 이런 문서를 사람이 처음부터 손으로 쓰기가 번거롭다는 것이다. 색상 하나, 여백 값 하나까지 다 사람이 재서 적어야 했다.

① "느낌으로 만들어줘"를 숫자로 바꿔주는 첫 단추

실무에서 흔한 요청은 "이 경쟁사 사이트 톤으로 우리 랜딩페이지 만들어줘"다. 이 확장은 그 사이트를 열어놓고 버튼 한 번으로 색상 hex 값·spacing px 값까지 뽑아주므로, 에이전트가 대략적인 느낌이 아니라 구체적인 숫자를 갖고 시작하게 해준다.

② Bergside(typeui.sh)의 무료 클라이언트 진입점

이 저장소를 만든 Bergside는 typeui.sh라는 "디자인 시스템 스킬 큐레이션" 서비스를 운영한다. README와 팝업 도움말은 계속 typeui.sh/design-md, typeui.sh/design-skills를 참조 링크로 건다. 즉 이 크롬 확장은 무료로 배포해 사용자를 typeui.sh 생태계로 끌어들이는 로컬 도구이기도 하다 — 오픈소스 확장 자체가 회사의 배포 채널인 구조다.

③ 별도 서버·설치 없이 바로 되는 가벼움

package.json조차 없는 순수 바닐라 JS라 npm install도, 빌드도 필요 없다. "압축해제 상태로 로드"만 하면 그대로 동작한다. 이런 제로 디펜던시·제로 빌드 특성이 "가볍게 훑어보고 바로 쓸 수 있는 도구"로 눈에 띄는 이유 중 하나다.

3무엇을 해결하나

문제. AI 코딩 에이전트에게 "이 사이트처럼 만들어줘"라고 말해도, 에이전트는 스크린샷을 보고 색을 추측하거나(부정확), 아예 아무 근거 없이 흔한 값(#111827, 16px 같은 "관용적으로 자주 쓰이는" 숫자)을 골라 쓴다. 결과물은 "비슷하지만 미묘하게 다른" 디자인이 되기 쉽다.

해결. 브라우저는 페이지를 그릴 때 이미 모든 요소의 정확한 색·크기·간격을 계산해 갖고 있다(getComputedStyle). design-md-chrome은 이 값을 그대로 읽어와 빈도순으로 집계하고, color.text.primary, space.3 같은 의미 있는 이름을 붙여 마크다운 표로 정리한다. 에이전트는 이제 "대략 짙은 회색"이 아니라 #111827이라는 정확한 값을 받는다.

4전체 구조

코드는 4개의 층으로 깔끔히 나뉜다. 팝업(사용자 화면), 백그라운드 서비스 워커(조율자), 콘텐츠 스크립트(페이지에 실제로 들어가는 코드), 그리고 lib/ 아래 부작용 없는 순수 함수 4개(정규화·마크다운 생성 2종·검증)다.

이 구조가 주는 교훈은 "브라우저 API를 만지는 코드(주입·메시징)"와 "순수 데이터 변환 코드(lib/)"를 확실히 분리했다는 점이다. lib/ 안 함수들은 전부 입력을 받아 값을 반환할 뿐 chrome.* API를 전혀 부르지 않는다 — 그래서 tests/run-tests.mjs가 크롬 없이 node 하나로 그대로 테스트할 수 있다.

5핵심 설계·동작 원리

설계 패턴 ① — 콘텐츠 스크립트를 "그때그때" 주입한다

보통 확장은 manifest.json의 content_scripts에 페이지를 등록해 놓고 자동 주입시키지만, 이 저장소는 그렇게 하지 않는다. manifest.json에는 content_scripts 항목 자체가 없다. 대신 service-worker.js의 injectExtractor()가 확장 아이콘을 누른 그 순간에만 chrome.scripting.executeScript({ target:{tabId}, files:["content-script.js"] })로 코드를 밀어 넣는다.

content-script.js 맨 위의 if (window.__typeuiStyleExtractorInstalled) return;는 같은 탭에서 여러 번 눌러도 리스너가 중복 등록되지 않게 막는 가드다. "모든 페이지에 항상 살아있는 코드" 대신 "필요할 때만 잠깐 들어갔다 나오는 코드"로 설계해 권한 범위와 성능 부담을 줄인 것이다.

설계 패턴 ② — 우선순위 셀렉터로 "280개 한도" 안에서 훑기

content-script.js의 collectSampledElements(280)는 body → 제목(h1~h6) → p → a → button → 입력 요소 → label → nav/header/footer/main/section/article/aside → 리스트 항목 → 표 → [role='button'] → 클래스에 card/btn이 들어간 요소 → [tabindex] 순서로 셀렉터를 훑으며, isVisible()로 화면에 실제로 보이는 요소만 골라 최대 280개까지 채운다.

요소마다 window.getComputedStyle을 호출해 fontFamily/fontSize/lineHeight/fontWeight, color/backgroundColor/borderColor/outlineColor, 8방향 margin·padding, borderRadius, boxShadow, transitionDuration 등을 그대로 배열에 쌓는다. 동시에 collectSiteSignals()가 메타 태그(description·keywords·og:type)와 제목·내비게이션·CTA 문구, 그리고 document.body.innerText 앞부분 14,000자까지를 함께 담아 반환한다.

설계 패턴 ③ — Map 빈도 집계로 "가장 자주 쓰인 값"을 토큰으로 승격

lib/normalize.mjs의 normalizeExtractedStyles()는 원시 값을 그대로 쓰지 않는다. increment(map, key) 헬퍼로 각 값이 몇 번 등장했는지 Map에 누적하고, topEntries()로 등장 빈도가 높은 순서대로만 골라 SIZE_NAMES = ["xs","sm","md","lg","xl","2xl","3xl","4xl"], RADIUS_NAMES, TEXT_NAMES = ["primary","secondary","tertiary","inverse"] 같은 고정 이름 배열을 순서대로 붙인다. 즉 color.text.primary는 "가장 자주 쓰인 글자색"이라는 뜻이지, 실제 CSS의 --text-primary 변수와는 무관하다.

색상은 toCanonicalColor() → parseRgbLike() → rgbToHex() 경로로 rgb(17, 24, 39) 같은 값을 #111827 형태의 hex로 통일한다. 여백·radius는 parsePx()로, 트랜지션 시간은 parseDuration()으로 150ms/0.15s 표기를 하나의 숫자(ms)로 맞춘다. "많이 쓰인 값일수록 진짜 토큰일 가능성이 높다"는 빈도 = 신뢰도 가정이 이 모듈 전체를 관통한다.

설계 패턴 ④ — 사이트 성격 추론은 100% 규칙 기반 키워드 스코어링

inferSiteProfile()은 documentation/dashboard/marketing/content/ecommerce/webapp 6개 "제품 성격" 후보와 developer/operator/business/consumer/reader/general 6개 "대상 독자" 후보에 각각 점수를 매긴다. 점수 계산은 세 함수뿐이다.

• keywordScore(corpus, keywords, weight, ...) — 제목·메타·헤딩·내비게이션·본문 텍스트를 합친 corpus 문자열에 "dashboard", "pricing", "checkout" 같은 키워드가 몇 번 포함되는지 세어 가중치를 곱한다.
• numericCue(value, threshold, weight, ...) — 폼 개수·표 개수·코드 블록 개수 같은 구조적 수치가 임계값을 넘으면 점수를 더한다.
• pathnameCue(pathname, fragments, ...) — URL 경로에 /docs, /api 같은 조각이 있으면 가산점을 준다.

pickTop()이 가장 높은 점수의 후보를 고르고, confidenceFromScores()가 "점수 ≥ 5이고 2등과 차이 ≥ 1.4면 high, 점수 ≥ 2.4이고 차이 ≥ 0.5면 medium, 아니면 low"라는 하드코딩된 문턱값으로 신뢰도 라벨을 매긴다. 여기엔 임베딩도, 분류 모델도, LLM 호출도 없다 — if/else급 점수표다.

설계 패턴 ⑤ — 저장소 루트의 DESIGN.md 자체가 "생성기의 설계도"

저장소 루트에는 DESIGN.md라는 파일이 하나 더 있는데, 이건 확장이 만들어내는 결과물이 아니라 "SKILL.md를 어떻게 써야 하는지"를 규정한 메타 문서다. 여기 적힌 Mission/Brand/Style Foundations/Accessibility/Writing Tone/Rules: Do/Rules: Don't/Guideline Authoring Workflow/Required Output Structure/Component Rule Expectations/Quality Gates 11개 섹션 이름이, lib/generate-design-md.mjs·lib/generate-skill-md.mjs가 실제로 채워 넣는 섹션과 lib/validate.mjs의 REQUIRED_HEADINGS 배열에 토씨 하나 안 틀리고 그대로 등장한다. 즉 "설계도(DESIGN.md) → 생성 코드 → 검증 코드"가 같은 스펙을 세 번 반복하는 자기참조 구조다.

설계 패턴 ⑥ — 검증은 마크다운을 "파싱"하지 않고 그냥 문자열 검색한다

lib/validate.mjs의 validateMarkdownOutput()은 진짜 마크다운 파서를 쓰지 않는다. markdown.includes("## Mission")처럼 부분 문자열이 포함돼 있는지만 검사한다. REQUIRED_STATES = ["default","hover","focus-visible","active","disabled","loading","error"] 각 단어가 본문 어딘가에 등장하는지, "WCAG 2.2 AA" 문구가 있는지, "must"/"should" 단어가 쓰였는지도 같은 방식으로 확인한다.

6기술 스택·의존성

이 저장소에서 버전의 진실원(source of truth)은 manifest.json의 "version": "0.4.0"이다. 팝업 배지에 보이는 "v0.4.0" 텍스트는 popup/popup.html에 별도로 손으로 박아 넣은 문자열이라, 둘을 늘 맞춰줘야 한다.

7설치·요구사항

8실제 사용 흐름

9함정·오해 방지

10대안 비교

11정리 — 누가 쓰면 좋은가

design-md-chrome은 크지 않은 저장소지만(package.json도 없는 23개 파일) 목적이 뚜렷하다. 임의의 웹사이트에서 실제 CSS 값을 실측해, AI 코딩 에이전트가 곧바로 참고할 수 있는 마크다운 스펙으로 정리해 준다. 색상·간격 같은 "잴 수 있는 값"은 정확하지만, 브랜드 성격 같은 "해석이 필요한 값"은 여전히 키워드 기반 추측이라는 이중적 성격을 정확히 이해하고 쓰는 게 핵심이다.