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 코딩 에이전트가 곧바로 참고할 수 있는 마크다운 스펙으로 정리해 준다. 색상·간격 같은 "잴 수 있는 값"은 정확하지만, 브랜드 성격 같은 "해석이 필요한 값"은 여전히 키워드 기반 추측이라는 이중적 성격을 정확히 이해하고 쓰는 게 핵심이다.

12직접 해볼 수 있는 실습 과제

아래 명령은 manifest.json이 있는 레포 소스 루트에서 실행한다. Node.js가 필요하며, 예제는 입력 데이터를 메모리에서 만들고 결과를 터미널에 출력한다. 패키지 설치나 원본 파일 수정은 필요 없다.

node --version
node tests/run-tests.mjs

node --input-type=module -e 'import assert from "node:assert/strict";
import { normalizeExtractedStyles } from "./lib/normalize.mjs";

const normalized = normalizeExtractedStyles({
  source: { title: "로컬 실습" },
  sampledElements: 3,
  totalElements: 3,
  colors: ["rgb(17, 24, 39)", "#111827", "rgb(75, 85, 99)"]
    .map(textColor => ({ textColor })),
  spacing: [{
    paddingTop: "16px", paddingRight: "8px",
    paddingBottom: "16px", paddingLeft: "0px"
  }]
});
assert.equal(normalized.colorPalette[0].value, "#111827");
assert.equal(normalized.colorPalette[0].usage, 2);
assert.deepEqual(
  normalized.spacingScale.map(row => row.value),
  ["8px", "16px"]
);
console.table(normalized.colorPalette);
console.table(normalized.spacingScale);'

node --input-type=module -e 'import assert from "node:assert/strict";
import { normalizeExtractedStyles } from "./lib/normalize.mjs";
import { generateDesignMarkdown } from "./lib/generate-design-md.mjs";
import { generateSkillMarkdown } from "./lib/generate-skill-md.mjs";
import { validateMarkdownOutput } from "./lib/validate.mjs";

const normalized = normalizeExtractedStyles({
  source: { title: "로컬 실습" },
  sampledElements: 0,
  totalElements: 0
});
const context = {
  normalized,
  metadata: {
    systemName: "로컬 실습", brand: "실습", scope: "local-lab",
    audience: "학습자", productSurface: "학습용 화면"
  }
};
const design = generateDesignMarkdown(context);
const skill = generateSkillMarkdown(context);
assert.equal(validateMarkdownOutput("design", design).isValid, true);
assert.equal(validateMarkdownOutput("skill", skill).isValid, true);
assert.ok(skill.startsWith("---\n"));
assert.ok(skill.includes("name: design-system-local-lab"));
console.log(design.split("\n").slice(0, 13).join("\n"));
console.log(skill.split("\n").slice(0, 4).join("\n"));
console.log(normalized.diagnostics);'

node --input-type=module -e 'import assert from "node:assert/strict";
import { normalizeExtractedStyles } from "./lib/normalize.mjs";
import { generateDesignMarkdown } from "./lib/generate-design-md.mjs";
import { validateMarkdownOutput } from "./lib/validate.mjs";

const base = generateDesignMarkdown({
  normalized: normalizeExtractedStyles({
    source: { title: "로컬 실습" },
    sampledElements: 0, totalElements: 0
  })
});
const check = text => validateMarkdownOutput("design", text);
const normal = check(base);
const missing = check(base.replace("## Brand\n", ""));
const renamed = check(base.replace("## Brand\n", "## BrandExtra\n"));
const noState = check(base.replaceAll("disabled", ""));

assert.equal(normal.isValid, true);
assert.equal(missing.isValid, false);
assert.equal(renamed.isValid, true);
assert.equal(noState.isValid, true);
assert.ok(noState.warnings.some(text => text.includes("disabled")));
console.table([
  ["정상", normal], ["제목 삭제", missing],
  ["제목 변형", renamed], ["상태 누락", noState]
].map(([name, result]) => ({
  name, isValid: result.isValid,
  errors: result.errors.length, warnings: result.warnings.length
})));'

13관련 기술 심화 학습 로드맵

매주 개념을 읽은 뒤, 해당 코드에서 근거를 찾고 작은 결과물로 정리한다. 앞의 실습 결과를 재사용하되, 브라우저에서 수집한 값과 코드가 덧붙인 해석을 구분하는 습관을 유지한다.

14핵심 키워드 사전