에디토리얼 다이어그램 27종을 뽑는 스킬lint-skin.py · 제작 Cathryn Lavery · TrendShift Daily #13)
diagram-design을 한 문장으로 줄이면, 27종의 다이어그램 각각에 대한 레이아웃 규칙을 파일로 따로 떼어 두고, 그림을 그리기 직전에 딱 필요한 한 타입의 명세만 읽어들여, 강한 디자인 제약(강조 1색·초점 1~2곳·4px 격자·그림자 금지) 아래에서 JS 없는 단일 HTML 파일을 뽑아내는 시스템이다.
보통 AI에게 "아키텍처 다이어그램 그려줘"라고 하면, 둥근 모서리 상자 몇 개에 파랑·보라 그라데이션을 칠한, 어디서 본 듯한 그림이 나온다. diagram-design은 그 "AI가 그린 티"를 만드는 요소들(그림자, 무지개 색, 대각선 화살표, 과한 강조)을 명시적으로 안티패턴 목록으로 금지하고, 대신 잡지 편집 디자인(editorial design)의 절제된 규칙을 따르게 만든다.
일반 AI 그림 도구가 '아무 폰트나 쓸 수 있는 워드'라면, diagram-design은 '사보 편집 디자이너의 스타일 가이드'다. 워드는 뭐든 되지만 그래서 촌스러워지기 쉽다. 편집 가이드는 "본문은 이 서체, 강조는 딱 한 색, 여백은 이만큼"을 정해 놓아 누가 만들어도 톤이 흐트러지지 않는다.
이 스킬은 그 가이드를 사람이 지키는 게 아니라 AI가 지키도록 문서로 못 박아 두었다. "삭제가 최고의 품질 향상"이라는 철학, 노드 9개·화살표 12개라는 복잡도 상한, 출력 직전 통과해야 하는 체크리스트가 전부 스킬 파일 안에 들어 있다.
SKILL.md에 언제·어떻게 이 기능을 쓸지 적어 두면, 에이전트가 관련 요청을 받을 때 그 지침을 읽고 그대로 수행한다. diagram-design은 이 스킬 형식으로 배포된다.2026년 현재 TrendShift 일간 트렌드의 상위 토픽은 #AI agent, #AI skills, #AI coding assistant 순이다. 즉 "AI 코딩 에이전트에 꽂아 쓰는 스킬"이라는 카테고리 자체가 지금 가장 뜨거운 흐름이고, diagram-design은 그중에서도 '결과물의 미감'이라는 빈틈을 정확히 찌른 스킬이다. 코드를 짜주는 에이전트는 많아졌지만, 그 에이전트가 뽑는 도식은 여전히 조잡했다.
| 비교 축 | Mermaid / 일반 AI 도식 | diagram-design |
|---|---|---|
| 미적 품질 | 기본 테마 그대로 — "생성한 티" | 편집 디자인 규칙을 강제 — 안티슬롭 |
| 브랜드 적용 | 수동 CSS 오버라이드 | URL 하나로 색·폰트 자동 추출(60초) |
| 산출물 | 런타임 렌더러(mermaid.js) 필요 | JS 없는 단일 HTML — 브라우저면 끝 |
| 타입 범위 | flowchart·sequence 등 10여 종 | 27종(간트·레이더·메달리온·DP보안행렬 등) |
| 품질 보증 | 없음 | 린터 lint-skin.py + 출력 전 체크리스트 |
① "AI 슬롭"에 대한 피로. README의 문제의식이 정확히 대중의 불만이다 — "다이어그램이 필요할 때마다 Claude에게 물으면 사이트와 전혀 안 어울리는 둥근 상자 그림이 나와서, Figma로 30분 싸우거나 그냥 다이어그램을 포기했다." 이 공감대가 확산의 1차 동력이다.
② 60초 브랜딩. 스킬에 자기 웹사이트 URL을 주면 배경·본문·강조색과 서체를 뽑아 style-guide.md를 새로 써준다. 그 뒤로 생성되는 모든 다이어그램이 자동으로 그 브랜드를 입는다. "설정 없이 바로 내 톤"이라는 경험이 강력하다.
③ 듀얼 플랫폼. .claude-plugin과 .codex-plugin을 모두 담아, Claude Code 사용자와 OpenAI Codex 사용자 양쪽이 같은 스킬을 설치할 수 있다. 특정 도구에 묶이지 않는 점이 채택 장벽을 낮춘다.
mermaid.js가 실시간 렌더링해주는 인기 도구. 편하지만 결과물이 다 비슷하게 생겨서, 이 스킬은 스스로를 "No Mermaid-slop(머메이드 특유의 조잡함 없음)"이라고 홍보한다. 산출물이 JS 의존 없는 정적 HTML이라는 점도 대비된다.이 저장소는 실행되는 애플리케이션이 아니라 AI에게 주입하는 지침 묶음이다. 그래서 기술 스택도 "서버/DB"가 아니라 두뇌(마크다운 명세) · 산출물(HTML+SVG) · 공장 도구(파이썬 유틸)의 세 층으로 읽어야 한다.
| 구성 | 내용 |
|---|---|
| SKILL.md | 485줄. 철학·타입 선택표·안티패턴·디자인 시스템·SVG 프리미티브·복잡도 상한·출력 전 체크리스트. 항상 로드되는 "색인" |
| references/type-*.md | 27개. 타입별 레이아웃 규칙·안티패턴·예시. 그 타입을 고를 때만 로드 |
| style-guide.md | 색·폰트의 단일 진실원(single source of truth). 시맨틱 역할(paper/ink/accent…)로만 표기 |
| onboarding.md | URL·스킬·폴더에서 브랜드 토큰을 뽑아 style-guide를 다시 쓰는 절차 |
| primitive-*.md | 아이콘·주석 콜아웃·손그림(sketchy)·터미널 창 등 선택적 부품 |
| 기술 | 역할 |
|---|---|
| 단일 HTML | 모든 다이어그램은 자기완결 .html 한 개. 외부 이미지·JS 없음 |
| 인라인 SVG | 도형·화살표·텍스트를 SVG로 직접 그림. <path> 직교 엘보, <marker> 화살촉 |
| 임베드 CSS | 레이아웃·색은 <style>에 인라인. 유일한 외부 의존은 Google Fonts |
| 서체 3종 | Instrument Serif(제목·이탤릭 콜아웃), Geist(노드 이름), Geist Mono(포트·URL 등 기술 라벨) |
| 스크립트 | 역할 |
|---|---|
| build-icons.py | 588줄. Tabler·Simple Icons·Devicon·log-z에서 SVG를 받아 24×24 currentColor로 정규화 → 아이콘 카탈로그·갤러리 생성. stdlib(urllib/re/pathlib)만 사용 |
| lint-skin.py | 268줄. 생성된 HTML의 모든 색·폰트가 style-guide 팔레트 안인지 검사. 순수 검정·<script>·외부 에셋 차단 |
| fix-mojibake.py | cp1252 오해석으로 깨진 UTF-8(모지바케)를 원문자로 복원하는 정리 유틸 |
| Playwright(선택) | PNG 익스포트 시에만 필요. HTML을 크로미엄으로 렌더 후 SVG 영역만 2배율·투명 배경으로 캡처 |
.claude-plugin/(plugin.json + marketplace.json)과 .codex-plugin/(plugin.json + interface 메타데이터, brandColor #b5523a)을 함께 담아 Claude Code와 OpenAI Codex 양쪽에서 설치된다. commands/export-diagram.md는 /diagram-design:export 슬래시 명령을 정의한다.
이 스킬의 설계 핵심은 SKILL.md 하나만 항상 읽고, 27개 타입 명세와 프리미티브는 그 타입을 실제로 고른 순간에만 읽어들이는 '점진적 공개' 구조다. 덕분에 타입이 27개든 100개든 AI가 매번 짊어지는 문맥(context)은 "코어 + 지금 그릴 타입 하나"로 항상 가볍게 유지된다.
모든 색·폰트는 오직 style-guide.md 한 파일에만 산다. 27개 타입 명세는 #eb6c36 같은 hex를 절대 쓰지 않고 시맨틱 역할 이름(accent, ink, muted)으로만 참조한다. 그래서 브랜드를 바꿔도 타입 로직은 한 글자도 안 건드린다.
연극 대본과 조명의 관계다. 대본(타입 명세)은 "여기서 주인공에게 스포트라이트"라고만 적는다. 그 스포트라이트가 무슨 색인지는 조명 콘솔(style-guide.md) 한 곳에서 정한다. 무대 분위기를 통째로 바꾸고 싶으면 콘솔 색만 갈면 되고, 대본은 그대로다.
AI의 "잘 지켰겠지"에 기대지 않는다. lint-skin.py가 생성된 HTML을 정규식으로 훑어, 등장하는 모든 #hex·rgba()가 style-guide 팔레트에서 파생된 값인지 확인하고, 순수 검정(#000000)·<script> 태그·외부 에셋(Google Fonts <link> 제외)·허용 외 서체를 전부 걸러낸다. 2.0 이전 예시들은 lint-skin-baseline.txt로 면제 처리한다.
SKILL.md는 "협상 불가(non-negotiable)"라고 못 박은 커넥터 규칙 5개를 둔다. AI 도식이 조잡해 보이는 결정적 원인이 선이기 때문이다.
| # | 규칙 |
|---|---|
| 1 | 축이 다른 노드는 대각선 금지 — 반드시 r=8 둥근 직각 엘보 |
| 2 | 화살표 라벨은 선 위 6~10px 띄우고, 뒤에 불투명 마스크 사각형 |
| 3 | 선끼리 겹침 금지 — 교차는 브리지/홉(반원 점프)으로 |
| 4 | 한 변에서 여러 선이 나가면 부착점을 12px 이상 벌려 부채꼴로 |
| 5 | 목적지가 아닌 상자 뒤로 선을 통과 금지(불가피하면 점선 + 라벨은 보이는 끝단) |
구조의 핵심은 명세(skills/…/references)와 산출 예시(skills/…/assets)와 빌드 도구(scripts)의 분리다. 새 다이어그램 타입을 추가하려면 type-<이름>.md 한 개를 넣고 SKILL.md 선택표에 한 줄만 잇는다 — 나머지는 아무것도 안 바뀐다. 확장에 강한 이 개방-폐쇄 구조가 "27종"이라는 규모를 감당하는 비결이다.
가장 값진 학습은 주관적인 "예쁨"을 검증 가능한 규칙으로 번역하는 방식이다. "좋아 보이게"가 아니라 "강조는 2개 이하", "좌표는 4의 배수", "그림자 금지", "서체 3종"처럼 셀 수 있는 제약으로 바꿔 놓았다. 디자인 감각이 없어도 규칙만 지키면 톤이 유지된다.
SKILL.md의 §9 체크리스트를 본떠, 내가 자주 만드는 산출물(슬라이드·리드미·대시보드)에 대해 "출력 전 통과 규칙" 10개를 셀 수 있는 형태로 적어 본다. 주관적 항목("깔끔하게")을 객관적 항목("여백 24px 이상")으로 바꾸는 연습.
모든 좌표·크기·간격이 4의 배수라는 단순 규칙이 "AI가 뽑은 티"를 없애는 핵심이라고 명시한다. 여기에 타입별 상한(노드 9·화살표 12·강조 2·ER 엔터티 8·간트 태스크 12…)을 둬서, 넘치면 "쪼개서 개요+상세 두 장으로"라고 지시한다. 제약이 품질을 만든다는 사고를 코드가 아닌 규칙으로 배울 수 있다.
값이 아닌 역할로 색을 부르는 시맨틱 토큰, 그리고 웹사이트/스킬/폴더에서 토큰을 자동 추출해 매핑하는 온보딩 로직(이름 휴리스틱: bg/surface→paper, accent/brand/primary→accent 등)은 그대로 다른 테마 시스템에 이식할 수 있는 패턴이다.
둥근 직각 엘보 경로(M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 …), 교차 브리지 아크(a 8,8 0 0,1 16,0), 화살표 라벨 마스크까지 — 라이브러리 없이 SVG <path>로 깔끔한 다이어그램을 그리는 구체적 공식을 배운다.
build-icons.py는 외부 패키지 0개(urllib·re·pathlib)로 5개 아이콘 소스를 받아 정규화하고, lint-skin.py는 정규식만으로 디자인 규칙을 강제한다. "무거운 프레임워크 없이도 견고한 자동화가 가능하다"는 좋은 본보기.
| 상황 | 필요한 것 |
|---|---|
| 스킬 사용(다이어그램 생성) | Claude Code 또는 OpenAI Codex 클라이언트. 스킬 폴더를 ~/.claude/skills/ 또는 ~/.codex/skills/에 설치 |
| 결과물 보기 | 모던 브라우저만 있으면 됨. 인터넷은 Google Fonts 로드에만 사용(오프라인이면 서체만 대체됨) |
| PNG 익스포트(선택) | Python + Playwright + Chromium(pip install playwright && playwright install chromium). 스킬은 자동 설치하지 않고 안내만 함 |
| SVG 익스포트(선택) | 추가 의존 없음 — <svg> 블록을 추출하고 폰트 @import만 주입 |
| 아이콘 재생성(기여자) | Python 3(stdlib만) — python scripts/build-icons.py. 생성물은 커밋되어 있어 일반 사용자는 실행 불필요 |
서버·DB·GPU 요구사항이 없다. 대신 AI 코딩 에이전트라는 실행 환경을 전제로 한다. Claude Code/Codex 없이 이 폴더만 클론하면 "예쁜 예시 HTML 모음 + 규칙 문서"일 뿐, 자동 생성 기능은 에이전트가 SKILL.md를 읽어야 작동한다.
레포를 클론해 skills/diagram-design을 ~/.claude/skills/(또는 ~/.codex/skills/)에 복사한다. Claude Code에서 "내 웹앱 아키텍처 다이어그램 만들어줘"라고 요청하고, 나온 .html을 브라우저로 연다. 안티패턴(그림자·둥근 상자·무지개색)이 정말 안 나오는지 눈으로 확인.
"이 스킬을 내 사이트 https://내도메인에 온보딩해줘"라고 요청한다. 색·폰트가 추출되어 style-guide.md가 바뀌는 diff를 확인하고 승인한 뒤, 같은 다이어그램을 다시 생성해 기본 스킨 버전과 나란히 비교한다. 시맨틱 토큰이 어떻게 한 번에 톤을 바꾸는지 체감.
일부러 순수 검정·외부 이미지·JetBrains Mono·대각선 화살표를 넣은 HTML을 손으로 만든 뒤 python3 scripts/lint-skin.py 내파일.html을 돌려 본다. 어떤 규칙이 어떻게 정규식으로 잡히는지 lint-skin.py 소스와 대조하며 읽는다.
예: "칸반 보드" 타입을 만든다고 하고 references/type-kanban.md에 레이아웃 규칙·안티패턴·복잡도 상한을 적고, SKILL.md의 선택표에 한 줄을 잇는다. template.html을 복사해 예시 3변형을 만들고 lint-skin.py를 통과시킨다. 개방-폐쇄 구조를 실제로 확장해 보는 과제.
build-icons.py의 ICONS 매니페스트에 새 아이콘을 추가해 재빌드하거나, export.md의 Playwright 렌더 절차를 떼어 내 자신의 "HTML→PNG 캡처" CLI 도구로 재구성한다. stdlib 기반 자동화를 자기 프로젝트로 옮겨 보는 응용.
| 주차 | 주제 | 배우는 것 |
|---|---|---|
| 1주차 | 디자인 시스템 기초 | 시맨틱 토큰, 타이포 위계(serif/sans/mono 3종 분업), 4px 스페이싱 시스템, WCAG AA 대비 검사 |
| 2주차 | SVG 손코딩 | viewBox 좌표계, <path> 직교 라우팅, <marker> 화살촉, 텍스트 마스킹, 아크(a) 명령 |
| 3주차 | 에이전트 스킬 저작 | SKILL.md 구조, 점진적 공개 설계, 슬래시 명령, plugin.json 매니페스트(Claude Code·Codex) |
| 4주차 | 자동화 · 품질 | 정규식 기반 린팅, Playwright 헤드리스 렌더, stdlib(urllib/re/pathlib) 파이프라인 설계 |
먼저 왜 예뻐 보이는지(1주)를 규칙으로 이해하고, 그 규칙을 SVG로 직접 그리는 손기술(2주)을 익힌 다음, 그것을 AI가 대신 지키게 만드는 스킬 저작(3주)으로 올라가고, 마지막에 사람 없이 검증·출력하는 자동화(4주)로 닫는다. "감각 → 손 → 위임 → 자동화"의 상승 곡선.
| 키워드 | 한 줄 정의 |
|---|---|
| Editorial design | 잡지·신문의 절제된 편집 미학. 강조 1색, 넉넉한 여백, 명확한 위계를 지향 |
| AI slop | 디자인 결정 없이 대량 생성되어 "기계가 뽑은 티"가 나는 산출물 |
| Progressive disclosure | 필요한 순간에 필요한 만큼만 정보를 로드하는 설계(코어 + 고른 타입 1개) |
| Semantic token | 색을 값이 아니라 역할(accent, ink)로 부르는 방식 → 스킨 교체 가능 |
| Single source of truth | 색·폰트가 오직 style-guide.md 한 곳에만 존재 |
| Complexity budget | 타입별 노드·화살표·강조 개수 상한. 넘으면 두 장으로 분할 |
| Orthogonal connector | 대각선 대신 둥근 직각(r=8)으로만 꺾는 연결선 |
| Bridge / hop | 선이 교차할 때 덜 중요한 선에 반원 점프를 넣어 겹침을 피하는 기법 |
| Taste gate | 출력 직전 통과해야 하는 체크리스트(삭제 테스트·강조 수·격자 등) |
| Onboarding(skin) | URL·스킬·폴더에서 브랜드 토큰을 추출해 style-guide를 재작성하는 60초 절차 |
| currentColor | 아이콘 SVG가 부모의 글자색을 상속하게 하는 값 → 스킨에 자동으로 물듦 |
| 분류 | 링크 |
|---|---|
| GitHub 저장소 | github.com/cathrynlavery/diagram-design (MIT, v2.0) |
| 제작자 | Cathryn Lavery — littlemight.com(블로그·뉴스레터), BestSelf.co 창업자, X @cathrynlavery |
| 핵심 파일 | skills/diagram-design/SKILL.md — 철학·규칙의 정본(485줄) |
| 스킨 정의 | references/style-guide.md · 브랜딩은 references/onboarding.md |
| 서체 | Instrument Serif · Geist · Geist Mono (Google Fonts) |
| 아이콘 출처 | Tabler Icons(MIT) · Simple Icons(CC0) · Devicon(MIT) · log-z/logos(MIT) |
| 익스포트 | Playwright(PNG 렌더) — references/export.md 절차 참고 |
| 비교 도구 | Mermaid(mermaid.js) — 텍스트 기반 다이어그램, 런타임 렌더 방식 |