designlang으로 뽑은 디자인 시스템을 그대로 믿으면 안 되는 이유 — 두 사이트 교차 검증으로 노이즈 7종 찾기
2026.07.29
소개
시도하고자 했던 것과 그 이유를 알려주세요.
1주차 실습은 "사이트 주소를 주면 디자인 시스템이 MD로 나온다"는 흐름이었습니다. 실습을 따라가다 결과 파일을 열어 보니 본문 폰트가 Apple Color Emoji로 적혀 있었습니다. 지피터스 사이트가 이모지 폰트로 본문을 쓸 리는 없습니다.
저는 바이오 데이터를 다루는 일을 오래 했습니다. 숫자를 받으면 분모와 집계 정의부터 확인하는 습관이 있는데, 디자인 토큰도 결국 자동 집계된 수치라는 점에서 다르지 않았습니다. 강의에서도 스터디장이 3단계 프롬프트로 "노이즈가 있으면 짚어 줘"를 요청하게 한 이유가 여기 있다고 봤습니다.
그래서 실습을 한 번 더 밀고 나갔습니다. 한 사이트에서 나온 이상값이 그 사이트만의 문제인지, 도구 자체의 문제인지를 가르려면 성격이 다른 두 사이트가 필요합니다. 지피터스(gpters.org)와 Benchling(benchling.com, 바이오텍 R&D 클라우드 플랫폼)을 각각 추출해 같은 항목을 대조했습니다.
목표는 두 가지였습니다. 실습을 완주해 디자인 시스템을 클로드 디자인에 올리는 것, 그리고 올리기 전에 무엇을 손으로 고쳐야 하는지 목록을 만드는 것입니다.
진행 방법
사용 도구: Claude Code (CLI) + designlang v12.21.0 + Node.js v24.12.0
Step 1. 작업 폴더 준비와 Node 확인
강의대로 작업 폴더를 만들고 Claude Code로 열었습니다. Node는 이미 v24.12.0이 있어 설치 단계는 건너뛰었습니다.
Node.js가 설치되어 있는지 확인하고, 없으면 설치해 줘.
Step 2. 두 사이트 추출
designlang은 설치 없이 npx로 바로 돌아갑니다. 헤드리스 브라우저로 실제 렌더된 페이지를 훑어 computed style을 집계하는 방식입니다.
npx -y designlang https://www.gpters.org
npx -y designlang https://www.benchling.com
두 번 모두 산출물이 정상적으로 쌓였습니다. 지피터스 43개, Benchling도 비슷한 규모입니다. DESIGN.md, DTCG 토큰 JSON, Tailwind 설정, CSS 변수, Figma 변수, 모션 프리셋, 사람이 보는 preview.html까지 한 번에 나옵니다.
Step 3. 요약본과 원본을 따로 읽기
여기서 실습과 다르게 간 부분입니다. 모델에게 "노이즈를 짚어 줘"라고 묻기 전에, 같은 실행이 만든 파일끼리 서로 어긋나는 곳을 먼저 찾았습니다. 요약본(DESIGN.md)과 상세본(design-language.md), 원시 토큰(design-tokens.json)이 각각 다른 값을 말하면 그건 사이트 특성이 아니라 도구의 집계 문제입니다.
design-extract-output/ 안의 DESIGN.md와 design-language.md,
design-tokens.json을 서로 대조해 줘.
같은 항목인데 값이 다르거나, 사이트 실제 CSS와 어긋나는 곳만 짚어 줘.
추측 말고 파일에 적힌 값으로만.
Step 4. 결정적 증거를 사이트 CSS에서 확인
폰트 문제는 추출된 CSS 변수 파일에 답이 있었습니다.
grep -n "font-family" design-extract-output/gpters-org-variables.css
--bm-font-family-sans: ui-sans-serif, system-ui, -apple-system,
BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial,
"Noto Sans", sans-serif, "Apple Color Emoji", "Noto Color Emoji",
"Segoe UI Emoji", "Segoe UI Symbol", "Twemoji Mozilla", "Android Emoji";
사이트의 본문 폰트는 ui-sans-serif로 시작하는 시스템 폰트 스택입니다. Apple Color Emoji는 스택 맨 뒤의 이모지 폴백입니다. designlang은 이 스택에서 앞이 아니라 뒤쪽 항목을 집어 "본문 폰트"로 보고했습니다. 사이트 문제가 아니라 파싱 문제입니다.
Benchling에서도 같은 계열의 증상이 나왔습니다. 폰트 목록에 graphik(631회)과 Graphik(248회)이 대소문자만 다른 별개 항목으로 올라와 있습니다. 실제로는 한 폰트인데 둘로 갈려 집계된 것입니다.
Step 5. 클로드 디자인 업로드
정리한 시스템을 클로드 디자인에 올립니다. 클로드 디자인 화면에는 터미널 명령어 안내가 뜨지만, Claude Code 앱에서 말로 요청해도 승인 한 번으로 올라갑니다.
결과와 배운 점
측정 결과 — 확인된 노이즈 7종
# | 항목 | 지피터스 | Benchling | 도구 문제인가 |
|---|---|---|---|---|
1 | 본문 폰트 오인 |
|
| 예 (양쪽 재현) |
2 | 브레이크포인트 직렬화 실패 |
|
| 예 (양쪽 재현) |
3 | radius 라벨 중복 |
|
| 예 (양쪽 재현) |
4 | shadow 라벨 중복 |
|
| 예 (양쪽 재현) |
5 | spacing base와 스케일 불일치 | base 4px인데 스케일에 3·37·336px | base 2px인데 스케일에 1px | 예 (양쪽 재현) |
6 | heading 레벨 오배정 | DESIGN.md는 | — | 예 (같은 실행 내 불일치) |
7 | 실행 종료 시 예외 |
| 동일 메시지 | 예 (양쪽 재현) |
추가로 확인한 것
지피터스 사이트에는 이미 제대로 된 타입 스케일이 CSS 변수로 박혀 있었습니다.
--bm-font-size-h-3xs: 16px; --bm-font-size-h-2xs: 18px;
--bm-font-size-h-xs: 22px; --bm-font-size-h-sm: 24px;
--bm-font-size-h-md: 28px; --bm-font-size-h-lg: 32px;
--bm-font-size-h-xl: 36px; --bm-font-size-h-2xl: 40px;
그런데 DESIGN.md 요약은 그날 그 페이지에 렌더된 네 개(28/24/22/14px)만 h1~h4로 잘라 보고했습니다. 32·36·40px은 사라집니다. 요약본만 보고 시스템을 만들면 큰 제목 쪽 스케일이 통째로 빠집니다.
배운 점
자동 추출은 표본 추출이다. designlang이 보는 것은 "그 순간 그 페이지에 렌더된 요소"뿐입니다. 지피터스 헤딩 스케일 8단계 중 4단계만 잡힌 것이 그 증거입니다. 사이트에 CSS 변수로 시스템이 이미 있으면
variables.css를 먼저 읽는 편이 요약본보다 정확합니다.폴백 스택을 값으로 착각한다. 요즘 사이트는 폰트를 단일 이름이 아니라 긴 스택으로 씁니다. computed style을 그대로 집계하면 스택 뒤쪽 폴백이 최다 사용으로 올라옵니다. 추출된
sans값은 무조건 손으로 확인해야 합니다. 이걸 그대로 클로드 디자인에 올리면 모든 슬라이드가 이모지 폰트를 지정받습니다.한 사이트로는 판단할 수 없었다. 지피터스만 봤다면 "이 사이트 CSS가 지저분한가 보다"로 끝났을 겁니다. 성격이 완전히 다른 Benchling에서 같은 증상이 재현되고 나서야 도구 문제로 확정할 수 있었습니다. 대조군을 하나 더 두는 비용은 명령어 한 줄입니다.
라벨(md/lg/full)은 의미가 아니라 자리표다. 같은
lg에 12px과 15px이 둘 다 붙어 있으면, 그건 시스템이 아니라 관측값 나열입니다. 4단계 프롬프트에서 "노이즈 교정"을 따로 시키는 이유가 여기 있었습니다.
시행착오
실행이 매번 마지막에
The "string" argument must be of type string or an instance of Buffer or ArrayBuffer. Received undefined로 끝나 처음에는 추출이 실패한 줄 알았습니다. 확인해 보니 산출 파일 43개는 이미 다 쓰인 뒤였고, 마지막 단계 하나만 넘어진 것이었습니다. 종료 코드나 마지막 메시지가 아니라 실제 산출물 개수로 확인해야 했습니다.처음에는 모델에게 바로 "노이즈를 짚어 줘"라고 물었는데, 그럴듯한 일반론이 돌아왔습니다. 파일끼리 대조하라고 범위를 좁히고 "파일에 적힌 값으로만"이라고 못 박은 뒤에야 검증 가능한 지적이 나왔습니다.
앞으로의 계획
2주차 과제인 나만의 디자인 시스템을 만들 때, designlang 결과를 초안으로만 쓰고 위 7개 항목을 점검하는 체크리스트를 먼저 통과시킬 계획입니다.
폰트 스택에서 첫 항목을 집는 보정 스크립트를 하나 만들어, 추출 직후 자동으로
sans값을 고치도록 붙여 보려 합니다.학회 발표 슬라이드에 쓸 시스템을 목표로, 그림·표가 많은 과학 자료에 맞는 타입 스케일과 여백 규칙을 따로 정해 볼 생각입니다.
도움 받은 글 (옵션)
참고한 지피터스 글이나 외부 사례를 알려주세요.
23기 클로드 디자인 1주차 강의 (김민철) — 디자인 시스템 추출 5단계 프롬프트와 "별로의 사다리" 디자인 언어 사전
designlang v12.21.0 — https://github.com/Manavarya09/design-extract



