GitHub 일간 트렌딩 1위인데, 한국어로 쓰면 디자인 규칙이 깨집니다. 별 2,855개 (2026-08-13 08:47 UTC 기준) 2위 저장소의 12.6배 Claude Code에 붙이는 다이어그램 스킬이에요. 직접 뜯어봤더니 한국어 사용자만 걸리는 함정이 하나 있었어요. 1/ 먼저 정체부터요. diagram-design. 구조도, 흐름도, 시퀀스 같은 다이어그램 27종을 그려주는 Agent Skill이에요. “우리 사이트 색이랑 폰트로 맞춰줘” 이게 되는 게 핵심이에요. 홈페이지 주소를 주면 색 팔레트와 폰트를 뽑아서 스타일 토큰에 넣어줘요. 산출물은 HTML 파일 하나. 더블클릭하면 브라우저에서 바로 열려요. 2/ 그런데 한국어에서 문제가 생겨요. 기본 폰트가 딱 3종이에요. Geist, Instrument Serif, Geist Mono. Google Fonts에서 이 3종의 문자 범위를 직접 조회해봤어요. 한글 영역(U+AC00) 결과는 셋 다 0건. 대조군으로 넣은 Noto Sans KR은 정상 검출됐고요. 즉 한글 라벨은 시스템 기본 폰트로 대체 렌더돼요. “폰트 3종 고정"이라는 디자인 규율이 한글 구간에서만 풀리는 셈이에요. 3/ 보는 사람 컴퓨터마다 달라진다는 뜻이기도 해요. macOS면 애플 SD 산돌고딕 Windows면 맑은 고딕 같은 다이어그램인데 화면마다 인상이 달라집니다. 대응은 어렵지 않아요. 스타일 가이드 파일의 폰트 토큰을 Pretendard나 Noto Sans KR로 바꾸고, 템플릿의 Google Fonts 링크도 같이 교체하면 돼요. 브랜드 자동 온보딩만으로는 안 바뀌어요. 기본 템플릿 값은 그대로거든요. 4/ 숫자 하나도 짚고 갈게요. 저장소 한 줄 소개에는 29종이라고 적혀 있어요. README와 SKILL.md는 27종. 실제 타입 정의 파일을 세어봐도 27개. 라이브 갤러리 항목은 35개예요. 정식 27종에 변형 8개가 섞인 숫자고요. “그래서 몇 개예요?” 27종이 정답이에요. 소개문 숫자만 보고 인용하면 그대로 오류가 됩니다. 5/ “그럼 Mermaid는 버리는 건가요?” 아니요. 오히려 반대예요. import-mermaid 명령으로 기존 Mermaid를 읽어서 다시 그려줘요. draw.io 파일도 마찬가지고요. Mermaid는 배포력이 강점이에요. GitHub나 Notion에서 별도 설정 없이 그려지니까요. 대신 자동 배치를 손으로 통제하기 어렵죠. 영국 정부 디지털서비스도 도입 문서에 그 한계를 적어뒀어요. 쌓아둔 Mermaid 자산은 그대로 두고, 결과물만 다시 뽑는 방향이에요. 6/ “Claude Code 전용이죠?” 아니요. Claude Code, Codex, Pi가 같은 스킬 파일을 공유해요. 쓰는 에이전트가 달라도 결과물은 같습니다. 7/ AI가 만든 티가 안 나는 이유가 따로 있어요. 강조색은 하나. 그림자 금지. 테두리는 1px, 모서리 반경은 최대 10px. 모든 좌표와 간격은 4의 배수. README 표현이 재밌어요. 다이어그램이 AI가 만든 것처럼 느껴지지 않게 해주는 게 바로 이 규칙이라고 못을 박아뒀어요. 노드가 9개를 넘으면 사실 다이어그램 두 개라는 말도 함께 적혀 있고요. 8/ 검증 장치는 꽤 진지한 편이에요. 라벨이 다른 노드 배경에 잘리는지 기하학적으로 검사해요. 접근성 이름 없는 SVG나 실행 속성이 든 파일은 거부하고요. CI는 리눅스, 윈도우, macOS 세 곳에서 돌아가요. 다만 라벨 “내용"이 사실인지는 보지 않아요. 독자 설정을 실무자에서 임원으로 올리면 표현이 의도적으로 단순해지거든요. 대외 문서라면 다이어그램 글자도 팩트체크 대상으로 보는 게 맞아요. 9/ 실무에서는 이 순서가 편해요. 먼저 스타일 가이드의 폰트 토큰을 한글 폰트로 교체. 그다음 브랜드 온보딩으로 색 맞추기. 쌓여 있던 Mermaid는 import로 한 번에 다시 뽑기. PNG로 내보내려면 Playwright와 Chromium 설치가 따로 필요해요. HTML 그대로 쓰면 설치 없이 바로 보입니다. 트렌딩 1위에 오른 건 2026-08-12부터예요. 깊은 기술 토론은 아직 붙지 않은 단계고, 급등 당일 올라온 버그 리포트는 그날 대부분 수정됐어요.

GitHub 트렌딩 상위에 오른 diagram-design 은 AI 에이전트에 다이어그램 생성 기능을 붙여주는 스킬입니다. Claude Code 나 Codex 같은 에이전트에서 명령 한 줄로 HTML 형태의 다이어그램을 생성합니다. 웹사이트 주소를 전달해 색상과 폰트를 자동으로 추출하는 브랜딩 기능이 눈에 띕니다.

한글 라벨 렌더링 문제와 해결 방법

기본 제공 폰트 3종이 한글 글자 집합을 포함하지 않아 시스템 기본 폰트로 대체 렌더링됩니다. Geist, Instrument Serif, Geist Mono는 한글 영역(U+AC00) 대응 글자가 0건입니다. 이로 인해 macOS에서는 애플 SD 산돌고딕으로 나타나고 Windows 환경에서는 맑은 고딕으로 바뀝니다.

스타일 가이드 파일의 폰트 토큰을 Pretendard 나 Noto Sans KR 로 수정하면 한글 렌더링 문제를 깔끔하게 해결할 수 있습니다. 이때 템플릿 파일 내 Google Fonts 불러오기 링크도 함께 교체해야 합니다. 브랜드 온보딩 명령만 실행해서는 기본 템플릿 설정까지 바뀌지 않으므로 수동 보정이 필요합니다.

27종 유형 지원과 기존 Mermaid 자산 재활용

공식 지원 다이어그램 유형은 27종이며 기존 Mermaid 문법을 읽어 재구성하는 명령을 지원합니다. 저장소 한 줄 소개에는 29종으로 표기되어 있으나 타입 정의와 문서 기준은 27종입니다. 라이브 갤러리의 35개 항목은 기본 27종에 변형 디자인 8개를 더한 수치입니다.

import-mermaid 명령을 실행하면 기존 Mermaid 자산을 가공해 HTML 파일로 다시 그려줍니다. Mermaid는 GitHub 나 Notion 환경에서 바로 렌더링되지만 레이아웃 통제가 어렵습니다. 이 스킬은 강조색 하나만 사용하고 그림자를 금지하며 노드가 9개를 넘으면 다이어그램을 나누는 디자인 규율을 적용합니다.

실무 도입 순서와 검증 장치

스타일 가이드의 폰트 설정을 먼저 변경한 후 브랜드 온보딩을 진행하는 순서가 효율적입니다. PNG 이미지로 내보내는 작업에는 Playwright 와 Chromium 설치가 필요하지만, HTML 파일 형태 그대로 브라우저에서 열면 추가 설치 없이 바로 확인할 수 있습니다.

스킬 파일 자체는 Claude Code 와 Codex 및 Pi 에서 함께 공유하여 사용합니다. 라벨이 노드 배경에 가려지는지 기하학적으로 검사하고 실행 속성이 포함된 안전하지 않은 SVG 파일은 거부합니다. 다만 라벨에 적힌 텍스트의 사실 여부까지 검증해주지는 않으므로 작성자의 직접 확인이 필요합니다.

디자인 규칙이 정돈된 다이어그램 스킬은 기술 문서 작성 수고를 대폭 덜어줍니다. 한글 폰트 토큰만 보정하면 실무 환경에서 활용도 높은 도구가 됩니다.

요약

  • diagram-design의 기본 폰트는 한글 글꼴을 포함하지 않으므로 스타일 토큰과 Google Fonts 링크에서 한국어 폰트(Pretendard, Noto Sans KR 등)로 교체해야 합니다.
  • 소개문 표시 수치와 달리 실제 지원 다이어그램은 27종이며, import-mermaid 명령으로 기존 Mermaid 코드를 고품질 HTML 다이어그램으로 재구성할 수 있습니다.
  • 단일 강조색, 그림자 금지, 4px 그리드 정렬 및 기하학적 겹침 검사 규율을 통해 AI 생성 특유의 어색한 디자인을 방지합니다.