Communitygithub.com

Isometric SVG 애니메이션

빌드 스크립트로 생성된 애니메이션 SVG 등각 투영 아키텍처 다이어그램입니다. 시스템, 파이프라인 또는 아키텍처 다이어그램의 등각 투영(2.5D) 버전, 웹사이트용 애니메이션 SVG 흐름 일러스트레이션, 또는 이런 방식으로 만들어진 다이어그램 수정이 필요할 때 사용합니다.

Isometric SVG 애니메이션란 무엇인가요?

이 스킬은 단일 Node.js 빌드 스크립트(`node build.mjs`)를 실행하여 등각 투영(isometric, 2.5D) 아키텍처 다이어그램을 완전히 자동화된 방식으로 생성합니다. 스크립트는 모든 도형을 **평면 단위(plan units)** 로 배치하고, 이를 등각 투영으로 변환한 후, CSS 키프레임을 포함한 자체 완결형 SVG 파일(`diagram.svg`)과 미리보기 HTML(`preview.html`)을 출력합니다. 모든 것은 코드로 제어되며, 수동 드로잉 없이 코드 수정과 재빌드로 변경됩니다. 이 스킬은 Claude Code와 같은 AI 코딩 에이전트 환경에서 사용하며, 콘텐츠, 기하학, 텍스트, 레이아웃, 선, 톤(상태), 모션, 렌더링 비용 등 8가지 원칙을 따릅니다. 주된 장점은 반복 리뷰 주기에서 사용자 피드백을 한 번에 하나씩 적용하고, 변경 전에 현재 빌드를 `versions/` 폴더에 복사하며, 상태 기반 톤(tone)과 기하학 기반 시간 계산을 통해 자연스러운 애니메이션을 구현한다는 점입니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/413ZERO/isometric-svg-animation/tree/HEAD

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Isometric SVG 애니메이션은(는) 무엇을 하나요?

하나의 스크립트(node build.mjs)가 모든 도형을 평면 단위로 배치하고, 등각 투영(isometric)으로 변환한 후, 자체 완결형 diagram.svg(CSS 키프레임 내장, 일반 <img>로 재생 가능)와 preview.html(동일한 SVG를 인라인으로 포함하고 창 크기에 맞게 조정)을 생성합니다. 수동으로 그리는 작업은 없습니다: 모든 수정은 코드 변경 및 재빌드를 통해 이루어집니다.

스크립트를 작성하기 전에 references/generator.md를 읽으십시오: 그 섹션들과 투영(projection), 카드, 지면 텍스트, 경로, 키프레임, 플랫폼 및 어셈블리를 위한 핵심 코드를 확인하십시오.

단계

  1. 스토리(Story). 시스템 자체 문서를 읽고, 다이어그램의 스토리를 한 줄로 작성하십시오: 무엇이 들어오고, 무엇이 처리하며, 무엇이 작업을 구동하고, 무엇이 나오는지. 흐름은 왼쪽 아래에서 오른쪽 위로 읽힙니다. 각 단계가 한두 단어로 이름 지을 수 있는 노드가 되고 사용자가 그 흐름에 동의하면 완료됩니다.
  2. 브리프(Brief). 느낌(선 굵기, 밀도, 플랫폼 스타일)에 대한 참조 이미지 하나를 얻습니다. 사용자가 없는 경우 references/examples.md의 다이어그램을 보여주고 선택하게 합니다. 테마, 종횡비(1.6:1은 브라우저 창 하나에 맞음), SVG가 위치할 곳을 결정합니다. 네 가지가 모두 스크립트의 헤더 주석에 포함되면 완료됩니다.
  3. 정적 빌드(Static build). 플랫폼, 노드, 경로, 레이블: 아직 모션 없음. 빌드 감사(audit)가 중첩이나 좁은 코너가 없다고 출력하고, 사용자가 레이아웃 스크린샷을 승인하면 완료됩니다.
  4. 모션(Motion). 루프를 추가합니다. 하나의 루프가 스토리를 순서대로 한 번 재생하고, 축소된 모션(reduced motion)에서는 완료된 상태를 보여주면 완료됩니다.
  5. 내보내기(Export). 아래 내보내기 섹션을 참조하십시오.

각 리뷰 라운드: 사용자의 노트를 하나씩 가져와, 변경 전에 질문에 답하고, 큰 변경 전에 현재 빌드를 versions/에 복사한 후 스크린샷으로 응답합니다. 사용자가 이름이나 아이콘을 선택할 때는 옵션을 나란히 렌더링합니다.

원칙

콘텐츠

  • 하나의 흐름에 적은 세부 사항. 각 노드는 실제로 수행하는 작업에 따라 이름이 지정됩니다. 이름이 이의가 있을 때는 정확한 이름과 이유를 말한 후 사용자가 선택하게 합니다.
  • 모든 레이블은 낯선 사람도 독립적으로 읽을 수 있어야 합니다. 설명이 필요한 레이블은 다시 쓰거나 제거됩니다.
  • 정말로 더미(예: 보고서의 페이지)인 것에만 접시 스택(stack of plates)을 사용합니다. 다른 모든 노드는 단일 카드(single card)입니다.
  • 정직한 사이드 경로(단계를 건너뛰는 입력)는 공간이 들더라도 그려집니다.
  • 외부 시스템은 내부 시스템과 동일한 채우기(fill)로 플랫폼 위에 놓입니다. 점선(dashed edge)만으로 외부임을 표시합니다.
  • 느슨한 입력(loose inputs)은 플랫폼 없이 지면 위에 평평하게 놓입니다.

기하학(Geometry)

  • 평면 단위가 모든 곳에 사용됩니다: a는 흐름 방향(화면 위-오른쪽), b는 횡방향(화면 아래-오른쪽), z는 위쪽. 위치, 크기, 간격 및 경로는 평면 단위입니다. 화면 픽셀은 투영 내부에만 존재합니다.
  • 카드는 윗면(top face) + 측면 띠(side band, 위쪽과 아래쪽 외곽선의 껍질)이며 외곽 윤곽에 하나의 선(stroke)이 있고, 윗면과 두께가 만나는 부분에는 선이 없습니다. 플랫폼은 대신 윗면에 선을 긋습니다(그 면이 그리드 위에 있기 때문에).
  • 모든 카드와 모듈 알약(pill)은 하나의 두께를 가집니다. 이름 알약(name pill)은 두께 없이 평평하게 놓입니다.
  • 레이어로 칠합니다(지면, 플랫폼, 와이어, 객체, 레이블). 각 레이어 내에서는 깊이 순서로 정렬합니다.

텍스트

  • 모든 레이블은 기준선이 a를 따라 지면 평면에 놓입니다. 글리프는 빌드 시간에 경로로 변환되어(outlined to paths), SVG가 <img>로 어디서나 동일하게 렌더링되며 폰트를 로드하지 않습니다.
  • 크기는 하나의 작은 테이블(알약, 레이블, 작은, 캡션, 제목)에서 가져옵니다. 플랫폼 제목은 간격이 있는 모노스페이스 대문자(spaced monospace capitals)로 표시됩니다.

레이아웃

  • 2단위의 지면 그리드(ground grid). 플랫폼 가장자리는 바깥쪽으로 그리드 선에 맞춰집니다. 플랫폼 간 간격과 행 간 간격은 전체 셀(whole cell)입니다. 공유 트렁크 라인(shared trunk line)은 간격의 중앙에 있는 그리드 선을 따라 실행됩니다.
  • 플랫폼은 스스로 크기를 조정합니다: 모든 노드와 레이블은 자체 플랫폼에 자신의 풋프린트(footprint)를 등록하고, 플랫폼은 그 박스에 균일한 패딩을 더한 후 그리드에 맞춰집니다. 행에 있는 플랫폼은 마주보는 가장자리를 공유합니다.
  • 플랫폼 제목은 왼쪽 가장자리에서 앞쪽 가장자리까지의 거리만큼 떨어져(자본의 하단에서 측정) 왼쪽 정렬로 콘텐츠와 함께 위치합니다.
  • 그리드는 프레임의 모든 가장자리를 넘어 확장되며 프레임의 종횡비를 가진 타원을 통해 페이드 아웃되어, 그림에 딱딱한 가장자리가 없습니다. 배경은 투명합니다.
  • 모든 빌드는 감사(audit) 를 출력합니다: 각 플랫폼의 네 여백, 플랫폼 간 간격, 레이블×레이블 및 레이블×카드 중첩, 반경에 비해 너무 좁은 코너. 무엇이든 보여주기 전에 읽으십시오.

선(Line)

  • 모든 연결은 하나의 연속적인 경로입니다: 직각(orthogonal)이며, 고정된 반경의 1/4 회전 코너를 가지므로 경로를 공유하는 구간은 정확히 공유되고 분기는 접선(tangent)을 따라 트렁크를 떠납니다. 경로를 먼저 그리고 노드를 그 위에 배치합니다. 결과물에 끊긴 부분, 포크, 또는 간격이 없어야 합니다.
  • 선 종류는 패턴으로 구분됩니다: 실선(solid)은 흐름, 점선(dashed)은 외부 경로, 둥근 점(round dots)은 읽기 전용 액세스입니다.

톤(Tone)

  • 톤은 상태입니다. 중성색(Neutrals)만 사용합니다(R = G = B). 밝은 색 = 아직 도달하지 않음, 한 단계 더 어두운 색 = 입력이 준비됨, 가장 어두운 색 = 이번 실행에서 완료됨. 아이콘과 윤곽선도 같은 규칙을 따르므로 "왜 이게 더 어둡지?"라는 질문에 대한 답은 상태입니다. 가장 어두운 잉크는 중간 어두운 회색(mid-dark grey)입니다. 순수한 검은색과 단단한 어두운 블록은 사용하지 않습니다.
  • 선은 매우 밝게 시작하고 빛이 그 선을 따라 흐른 후에만 어두워집니다.
  • 색상은 현재 작업 중을 의미합니다: 카드는 흰색을 유지하면서 브랜드 그라디언트가 약간 아래에서 비쳐 보이고 주변에 희미한 빛(glow)이 있습니다. 빛은 흐름을 따라 전체 그림에 걸쳐 있는 하나의 그라디언트에서 색상을 가져옵니다.
  • 한 단계(예: 입력이 집계되는 중)에 대한 악센트는 조명 중에만 표시되고, 그 후에는 원래의 회색으로 돌아갑니다.

모션(Motion)

  • SVG 애니메이션: SVG 내부의 CSS 키프레임, 스크립트 없음, <img>로 재생. 요청 시에만 렌더링된 비디오.
  • 기본 스타일(resting style)은 완료된 실행입니다. 키프레임은 각 루프를 완료되지 않은 실행에서 시작합니다. 따라서 축소된 모션과 정적 내보내기는 완료된 다이어그램을 보여줍니다.
  • 시간은 기하학에서 비롯됩니다. 빛은 일정한 화면 속도(약 400 px/s)로 이동합니다. 각 도착은 시작 + 경로 길이 ÷ 속도이며, 다음 이벤트는 해당 도착에 일시 정지를 더한 값입니다. 노드를 이동하면 타임라인이 따라옵니다. 키프레임을 작성하기 전에 전체 타임라인과 루프 길이를 계산하십시오.
  • 하나의 루프는 스토리를 한 번 알려줍니다: 입력이 들어오고, 드라이버가 위에서 아래로 실행되고, 조각이 모이고 출력이 조립되며, 내보내기, 대기, 지우기, 반복. 따라갈 수 있을 만큼 느림(약 20초).
  • 빛은 더 부드럽고 넓은 후광(halo)을 가진 짧은 대시(dash)로 경로를 따라 이동합니다. 루프가 지워질 때까지 더 어두운 흔적이 그 뒤에 남습니다. 작업 중인 노드는 몇 픽셀 올라가고, 빛나며, 그라디언트 면을 번쩍입니다.

렌더링 비용

<img>로 재생 시 모든 실행 중인 애니메이션은 브라우저가 매 프레임마다 전체 그림을 다시 래스터화(rasterize)하도록 만듭니다.

  • 마스크, 필터 및 그룹은 작게 유지합니다: 그리드는 자체 선 그라디언트(stroke gradient)를 통해 페이드 아웃되고, 마스크는 드러내는 경로를 감쌉니다.
  • 보이지 않는 것은 visibility: hidden으로 설정합니다(불투명도 0 및 경로에서 벗어난 대시는 여전히 그려집니다).
  • 동일한 키프레임은 한 번만 작성됩니다.

내보내기(Export)

  • 정적 PNG: 축소된 모션을 에뮬레이션한 상태에서 SVG 문서 자체를 열고 스크린샷을 찍습니다. <img> 내부에서는 에뮬레이션이 SVG에 도달하지 못하며, 대신 루프의 첫 번째 프레임을 캡처합니다.
  • 미리보기는 사용자가 SVG를 배치할 때까지 사용자 사이트 외부, 로컬로 제공되는 독립 페이지에 있습니다.

관련 스킬