Flowy, AI-네이티브 다이어그램 스킬은(는) 무엇을 하나요?
Flowy는 자체 완결형 HTML 파일을 생성하여 대화형 SVG 다이어그램을 렌더링합니다. 각 파일은 CSS, JavaScript, 다이어그램 데이터를 내장하며, 의존성이 전혀 없어 더블 클릭만으로 모든 브라우저에서 열 수 있습니다.
파일 위치
- 다이어그램:
docs/diagrams/*.html(예:docs/diagrams/upload-flow.html). 폴더는 첫 사용 시 생성하며, 없을 수도 있습니다. 프로젝트에 이미 다이어그램을 보관하는 다른 위치가 있다면 해당 프로젝트의 규칙을 따르세요. - HTML 템플릿:
${CLAUDE_SKILL_DIR}/references/html-template.html, 표준 렌더러이며, 이 스킬이 제공하는 유일한 참조 파일입니다. 이 경로는 플러그인, 개인 또는 프로젝트로 설치된 위치에 관계없이 이 스킬의 자체 폴더로 해석되므로 현재 프로젝트에 의존하지 않습니다.
스키마 파일, 예제 폴더, 비주얼 편집기는 의도적으로 없습니다. 이전 버전의 이 스킬은 flowy/schema.ts, flowy/examples/, flowy/editor.html 및 디스크의 Flowy 소스 저장소를 가리켰습니다. 이들은 모두 존재하지 않으며, 경로가 오래되어 따라가면 시간만 낭비했습니다. 위의 HTML 템플릿이 구조의 진실 공급원(source of truth)입니다. 다이어그램을 작성하기 전에 반드시 읽어보세요.
사전 점검
Flowy 다이어그램을 생성하거나 편집하기 전에:
${CLAUDE_SKILL_DIR}/references/html-template.html을 읽어 최신 렌더러 코드를 확인하세요.docs/diagrams/에 있는 기존 다이어그램을 나열하여 이름 충돌을 방지하세요.- 기존 다이어그램을 업데이트하는 경우 먼저 읽고
DIAGRAM객체를 추출하세요.
스키마
모든 다이어그램은 세 가지 필드를 가진 JavaScript 객체입니다:
{
meta: { title, description, type, tags[], created, updated },
nodes: [...],
edges: [...]
}
meta
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| title | string | 예 | 사람이 읽을 수 있는 제목 |
| description | string | 아니요 | 다이어그램이 보여주는 내용 |
| type | string | 예 | "flowchart" 또는 "ui-mockup" |
| tags | string[] | 아니요 | 조직화를 위한 태그 |
| created | string | 아니요 | ISO 날짜 (YYYY-MM-DD) |
| updated | string | 아니요 | ISO 날짜, 생성/업데이트 시 오늘 날짜로 설정 |
nodes
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| id | string | 예 | 고유, snake_case (예: "step1_upload") |
| type | string | 예 | "box", "circle", "diamond", "note", "group" |
| label | string | 예 | 도형에 표시되는 주요 텍스트 |
| sublabel | string | 아니요 | 호버 툴팁에 표시되는 보조 텍스트 |
| position | { x, y } | 예 | 픽셀 단위의 왼쪽 상단 모서리 |
| size | { width, height } | 예 | 픽셀 단위의 크기 |
| style | object | 아니요 | 아래 노드 스타일 필드 참조 |
| group | string | 아니요 | 부모 그룹 노드의 id (시각적 그룹화 전용) |
노드 스타일 필드: fill, stroke, strokeWidth, color (텍스트), fontSize, borderRadius, opacity
edges
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| id | string | 예 | 고유 (예: "e_upload_to_extract") |
| source | string | 예 | 소스 노드 id |
| target | string | 예 | 타겟 노드 id |
| label | string | 아니요 | 화살표 위 텍스트 (예: "yes", "error") |
| sourceHandle | string | 아니요 | "top", "right", "bottom" (기본값), "left" |
| targetHandle | string | 아니요 | "top" (기본값), "right", "bottom", "left" |
| style | object | 아니요 | 아래 엣지 스타일 필드 참조 |
엣지 스타일 필드: stroke, strokeWidth, strokeDasharray, markerEnd
노드 렌더링 규칙
| 타입 | SVG 요소 | 설명 |
|---|---|---|
| box | <rect> | borderRadius의 rx/ry를 통한 둥근 모서리. 기본값: 8px |
| circle | <ellipse> | cx = x + width/2, cy = y + height/2, rx = width/2, ry = height/2 |
| diamond | <polygon> | 4개 점: 상단-중앙, 오른쪽-중앙, 하단-중앙, 왼쪽-중앙 |
| note | <path> | 오른쪽 상단 구석이 접힌 사각형. 접힘 크기: 12px |
| group | <rect> | 점선 테두리 (stroke-dasharray: 6,3). 다른 모든 노드 뒤에 렌더링. 레이블은 왼쪽 상단. 낮은 불투명도 |
엣지 렌더링 규칙
- 소스 포인트 계산: 소스 노드의 지정된 핸들 측면 중앙 (기본값: 하단)
- 타겟 포인트 계산: 타겟 노드의 지정된 핸들 측면 중앙 (기본값: 상단)
- 핸들 방향으로 50px 오프셋된 제어점으로 3차 베지어 곡선(
C명령) 그리기 - SVG
<marker>정의를 사용하여 화살촉 추가 strokeDasharray가 설정된 경우 점선으로 렌더링label이 있으면 베지어 곡선의 중점에 작은 흰색 배경 사각형과 함께 렌더링
레이아웃 규칙
흐름 방향
- 플로우차트: 위에서 아래로 (기본값)
- UI 목업: 그룹 컨테이너 내에서 위에서 아래로, 주석은 오른쪽
간격
- 노드 중심 간 최소 70px 세로 간격
- 평행 노드 간 최소 60px 가로 간격
- 그룹 패딩: 그룹 경계 내부 40px
결정 다이아몬드
- 왼쪽 분기 = 기본 / 예 경로
- 오른쪽 분기 = 보조 / 아니오 / 오류 경로
오류/경고 노트
- 메인 흐름의 오른쪽에 배치
- 빨간색 점선 엣지로 연결 (
strokeDasharray: "6,3", stroke:#991b1b)
표준 크기
| 타입 | 너비 | 높이 |
|---|---|---|
| box | 200 | 50 |
| circle | 90 | 40 |
| diamond | 120 | 60 |
| note | 180 | 44 |
색상 팔레트
| 용도 | 채우기 | 테두리 | 텍스트 |
|---|---|---|---|
| 일반 액션 | #ffffff | #2d6a4f | #1f2937 |
| 주요 액션 | #d1fae5 | #065f46 | #065f46 |
| 결정 | #fef3c7 | #92400e | #1f2937 |
| 오류 | #fee2e2 | #991b1b | #991b1b |
| 시작/종료 | #40916c | #2d6a4f | #ffffff |
| 그룹 | #f5f5f2 | #e6e4df | #374151 |
| 정보/보조 | #dbeafe | #1e40af | #1e40af |
| 기본 엣지 | , | #6b7280 | , |
HTML 파일 구조
모든 Flowy HTML 파일은 다음 구조를 따릅니다. 완전한 작동 코드는 HTML 템플릿 참조 파일을 읽으세요.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{diagram title}</title>
<style>
/* 모든 CSS 인라인, 툴바, 캔버스, 툴팁, 선택 하이라이트 */
</style>
</head>
<body>
<div id="toolbar">
<!-- [Fit] [-] 100% [+] Title badge [Download JSON] -->
</div>
<div id="canvas-wrap">
<svg id="canvas">
<defs><!-- 화살촉 마커 --></defs>
<g id="diagram-root"></g>
</svg>
</div>
<div id="tooltip"></div>
<script>
const DIAGRAM = { meta: {...}, nodes: [...], edges: [...] };
// 렌더링 + 상호작용 코드
</script>
</body>
</html>
툴바
- 상단에 고정, 높이 48px, 흰색 배경, 하단 테두리
- 왼쪽: 화면에 맞춤 버튼, 축소, 확대 %, 확대
- 중앙: 다이어그램 제목 (굵게) + 타입 배지 (회색 알약)
- 오른쪽: JSON 다운로드 버튼 (파란색)
상호작용 (모두 바닐라 JS)
- 확대/축소: 마우스 휠로 SVG viewBox 크기 조절. 범위: 0.2배 ~ 5배. 커서 위치를 중심으로 확대/축소.
- 이동: 빈 캔버스를 클릭-드래그하여 viewBox 이동.
- 호버: 노드 위에 마우스를 올리면 커서 근처에
sublabel이 툴팁으로 표시됨. - 클릭: 노드를 클릭하면 노드가 파란색 테두리로 강조되고 연결된 모든 엣지가 강조됨. 빈 공간을 클릭하면 선택 해제.
- 화면에 맞춤: 버튼이 모든 노드의 경계 상자를 계산하고 60px 패딩으로 viewBox를 설정.
- JSON 다운로드:
DIAGRAM객체를 포맷된 JSON으로 직렬화하고 파일 다운로드를 트리거.
새 다이어그램 만들기
사용자가 새 플로우차트 또는 UI 목업을 요청하면:
- 템플릿 읽기: HTML 템플릿 참조 파일을 읽어 최신 렌더러 코드를 확인
- 요청 분석: 노드(단계, 결정, 오류)와 엣지(연결) 식별
- 위치 지정: 레이아웃 규칙을 사용하여 위치 할당 (위-아래 그리드, 표준 간격)
- 색상 적용: 색상 팔레트를 사용하여 색상 적용 (시작/종료 = 초록, 결정 = 호박색, 오류 = 빨강 등)
- 완전한 HTML 파일 생성: 템플릿 구조를 복사하고
DIAGRAM객체를 새 데이터로 교체 - 저장:
docs/diagrams/{kebab-case-name}.html에 저장 - 사용자에게 알림: "브라우저에서
docs/diagrams/{name}.html을 열어 다이어그램을 확인하세요."라고 말하기
파일 이름 규칙
- 위치:
docs/diagrams/{name}.html - 형식:
kebab-case.html(예:docs/diagrams/upload-flow.html,docs/diagrams/checkout-screen.html) meta.updated를 오늘의 ISO 날짜로 설정
기존 다이어그램 업데이트
사용자가 다이어그램 수정을 요청하면:
- 읽기: 기존 HTML 파일 읽기
- 추출:
<script>블록에서DIAGRAM객체 추출 - 수정: 요청에 따라 노드/엣지 수정
- 업데이트:
meta.updated를 오늘 날짜로 업데이트 - 재생성: 업데이트된 데이터로 완전한 HTML 파일 재생성 (최신 렌더러를 위해 템플릿 다시 읽기)
- 저장: 동일한 경로에 저장
다이어그램 읽기
다이어그램을 분석하거나 설명하라는 요청을 받으면:
- HTML 파일 읽기
const DIAGRAM = { ... };블록 찾기- 타입과 레이블별로 노드 나열
- 엣지를 추적하여 자연어로 흐름 설명
- 결정 지점과 해당 분기 강조
예제
"로그인 흐름에 대한 플로우차트를 만들어줘"
액션: docs/diagrams/login-flow.html을 다음으로 생성:
start(원, 초록) →enter_credentials(상자) →validate(다이아몬드, 호박색)validate→ 예/왼쪽 →dashboard(원, 초록)validate→ 아니오/오른쪽 →show_error(노트, 빨강) → 점선 화살표로enter_credentials로 돌아감
"설정 목업에 다크 모드 토글을 추가해줘"
액션: docs/diagrams/settings-screen.html 읽기, DIAGRAM 추출, 테마 섹션 뒤에 레이블이 "Dark Mode"인 새 상자 노드 "section_dark_mode" 추가, meta.updated 업데이트, HTML 재생성.
"업로드 흐름의 3단계에 오류 처리를 추가해줘"
액션: HTML 읽기, 노드 배열에서 3단계 찾기, 오른쪽에 오류 노트 노드 추가, 3단계에서 오류 노트로 빨간 점선 엣지 추가, 재생성.
중요한 제약 사항
- 의존성 제로: npm, CDN 링크, 외부 스크립트/스타일 없음
- 오프라인 작동: 인터넷 접속 없이 렌더링 가능해야 함
- 단일 파일: 각 다이어그램은 하나의
.html파일 - 브라우저 네이티브: 표준 HTML5, CSS3, SVG 및 바닐라 ES6+ JavaScript만 사용
- LLM 친화적: DIAGRAM JSON은 압축되지 않은 깔끔한 형식이어야 함
자체 유지 관리
다이어그램을 만드는 과정에서 유용한 패턴, 새로운 레이아웃 트릭, 특정 목적에 잘 맞는 색상, 렌더링 개선 사항을 발견하면 이 스킬 파일을 업데이트하여 포함시키세요. 스킬을 정확하고 실행 가능하게 유지하세요.