Wireloom

UI 와이어프레임 (wireframes)을 위한 Markdown 확장 도구. 몇 줄의 들여쓰기된 텍스트로 화면을 설명하세요. 채팅, 문서, PR 코멘트, 이슈 등 Markdown이 지원되는 곳이라면 어디에서나 렌더링되는 깔끔한 SVG 목업 (mockup)을 얻을 수 있습니다.

Wireloom은 사용자 인터페이스 와이어프레임 (wireframes)을 스케치하기 위한 작은 텍스트 기반 언어입니다. 어떤 Markdown 문서 내의 코드 블록 (fenced code block) 안에 들여쓰기된 일반 텍스트로 레이아웃을 작성하면, Wireloom은 이를 GitHub, Obsidian, Notion, 정적 사이트 생성기 (static site generators) 또는 Markdown에서 SVG를 지원하는 모든 도구에서 인라인으로 렌더링되는 SVG 다이어그램으로 변환합니다.

왜 텍스트 우선 와이어프레임인가

전통적인 와이어프레임 도구들 (Balsamiq, Figma, Whimsical)은 사람이 클릭하고 드래그하도록 설계되었습니다. 이들은 사람이 작성자라고 가정합니다. 하지만 AI 에이전트 (AI agent)가 작성자일 때

v0.50: 모바일 네비게이션 프리미티브 (mobile navigation primitives). 이번 릴리스에는 모바일 목업 (mobile mockups)에 지속적으로 필요한 도형들이 추가되었습니다: spacer + row justify= (행을 쌓지 않고 행의 양 끝에 아이템을 고정), leading:/trailing: 슬롯이 있는 navbar (목록/상세 흐름을 위한 상단 크롬 밴드), tabbar/tabitem (하단 기본 네비게이션), backbutton (경로가 그려진 셰브론 (chevron) + 부모 레이블), header large: (iOS 스타일의 대형 타이틀 밴드), sheet (position=bottom|center를 사용하는 모달 및 바텀 시트 (bottom-sheet) 오버레이), segmented/segment (둥근 필 모양의 콘텐츠 필터), 그리고

선택적 배지 (badge)가 포함된 섹션, 우측 정렬된 kv 레이블/값 (label/value) 행을 추가할 수 있습니다. 그 위에 tabs, slot, combo, slider, image, 그리고 icon 프리미티브 (primitives)를 더하면 전체 애플리케이션 화면을 스케치할 수 있습니다:

해당 렌더링의 소스는 examples/11-colonial-charter.wireloom에 있으며, 이는 v0.2의 충실도 (fidelity)를 테스트하기 위해 사용된 실제 게임 UI 스트레스 테스트 사례입니다.

주석 (Annotations) (v0.4.1)

동일한 소스 내에서 목업 (mockup) 옆에 사용자 매뉴얼 스타일의 콜아웃 (callouts)을 추가할 수 있습니다:

window "Sign in":
  header:
    text "Welcome back" bold size=large id="welcome"
...

와이어프레임과 그 주석은 하나의 파일에 존재하며 하나의 SVG로 렌더링됩니다. 별도의 주석 레이어(annotation layer)나 두 번째 도구가 필요하지 않습니다.

모바일 네비게이션 (Mobile navigation) (v0.50)

크롬 (chrome, UI 프레임)을 흉내 내는 대신 실제 프리미티브를 사용하여 전화번호부 목록/상세 페이지 쌍을 스케치해 보세요:

window "Notes":
  header large:
    text "Notes"
...

window:
  navbar:
    leading:
...

행 (row) 내부의 spacer는 행을 쌓지 않고도 형제 요소들을 양 끝으로 고정하며, row justify=between|around|end는 이에 대응하는 선언적 (declarative) 방식입니다. sheet (하단 또는 중앙)는 스크림 (scrim) + 그랩버 (grabber) + 선택적 타이틀과 함께 하단 콘텐츠 위에 모달 오버레이 (modal overlay)를 그립니다. segmented/segment는 상호 배타적인 콘텐츠 필터를 위한 둥근 필 (pill) 모양의 컨트롤입니다. v0.50의 전체 워크스루 (walkthrough)는 AGENTS.md를 참조하세요.

AI 에이전트와 함께 Wireloom 사용하기

Wireloom은 LLM 에이전트가 작성하도록 설계되었습니다. Claude, Codex, Cursor 또는 기타 코딩 에이전트를 사용 중이라면, 모든 프리미티브, 속성 (attribute), 구문 오류 레시피 (parse-error recipe)가 포함된 독립적인 입문서인 AGENTS.md의 문법 참조를 제공하세요. 에이전트가 해당 파일을 참조하도록 지정하면, 자연어 프롬프트로부터 단 한 번에 정확한 Wireloom 소스를 작성할 수 있습니다.

특히 Claude Code 사용자들을 위해, .claude/skills/wireloom.md는 이미 만들어진 스킬(skill)을 제공합니다. 이 파일을 프로젝트의 .claude/skills/ 디렉토리에 복사하면, 사용자가 와이어프레임(wireframe)을 요청할 때 Claude가 자동으로 이를 활성화합니다.

만약 당신이 이 저장소(repo)를 읽고 있는 에이전트(agent)라면: Wireloom 소스를 작성하기 전에 여기서 멈추고 AGENTS.md를 먼저 읽으십시오. 이 문서는 당신을 위해 작성되었습니다.

설치 (Install)

npm install wireloom

pnpm add wireloom 또는 yarn add wireloom으로도 동일하게 작동합니다. 런타임 의존성(runtime dependencies)이 전혀 없으며, 완전한 TypeScript 타입을 지원하는 ESM/CJS 이중 모드로 제공됩니다. 마이너 업데이트(minor bumps)를 원하지 않는다면 정확한 버전을 고정하거나 틸드(~0.4.0) 범위를 사용하십시오. 1.0 미만의 마이너 릴리스는 소스 수준의 호환성을 유지하는 것을 목표로 하지만, Theme 인터페이스나 AST 형태에 파괴적 변경(breaking changes)을 도입할 수 있습니다.

출력물은 독립적인 SVG 문자열입니다. <script> 태그나 외부 참조가 없으며, 모든 텍스트와 속성 값은 HTML 이스케이프(HTML-escaped) 처리됩니다. innerHTML / dangerouslySetInnerHTML을 통해 안전하게 주입할 수 있습니다.

사용법 (Usage)

다른 텍스트-투-다이어그램(text-to-diagram) 라이브러리와 동일한 형태의 네 가지 공개 호출(public calls)을 제공합니다:

import wireloom from 'wireloom';

// 선택 사항: 시작 시점에 전역 테마(global theme)를 한 번 설정합니다.
...

렌더링 없이 파싱(Parse)할 수 있어, 에디터 및 툴링(tooling)에 유용합니다:

const doc = wireloom.parse(source); // 타입이 지정된 AST

AST를 다시 정형화된 소스(canonical source)로 직렬화(Serialize)할 수 있습니다. 포맷터(formatters) 및 구조적 차이(structural diffs) 확인에 유용합니다:

const canonical = wireloom.serialize(doc);

전역 설정(global config)을 건드리지 않고 렌더링마다 테마를 전환할 수 있습니다:

const { svg } = await wireloom.render('id', source, { theme: 'dark' });

소스 위치 정보와 함께 파싱 에러를 포착할 수 있습니다:

import { WireloomError } from 'wireloom';

try {
...

Markdown 렌더러 내부에서 사용하기

짧은 버전 — 사용 중인 파이프라인(pipeline)에서 wireloom 코드 블록 언어에 wireloom.render를 후킹(hook)하십시오:

// react-markdown
<ReactMarkdown
  components={{
...

remark/rehype, markdown-it, react-markdown, 그리고 일반적인 서버 사이드 렌더링 (SSR)을 위한 전체 레시피 — 에러 표면 (error-surface) 패턴, 테마 선택, SSR 참고 사항, 번들 크기 (bundle-size) 상세 정보 포함 — 는 INTEGRATION.md에 있습니다.

왜 그냥 [다른 것]을 사용하지 않나요?

• ASCII art는 읽을 수는 있지만 시각적으로 렌더링되지 않으며 스타일을 적용할 수 없습니다.
• **플로우차트 DSL (Flowchart DSLs)**은 UI 레이아웃 — 행 (rows), 열 (columns), 패널 (panels), 폼 필드 (form fields) — 를 표현할 수 없습니다.
• **와이어프레임 도구 (Wireframing tools)**는 텍스트가 아닌 이미지를 생성합니다. 이들은 Markdown 내에 존재하지 않으며, git에서 차이점 (diff)을 비교할 수 없고, 도구를 변경할 때 깨지게 됩니다.

Wireloom은 텍스트 우선 (text-first), SVG 출력 (SVG-output), Markdown 네이티브 (Markdown-native) 방식입니다.

설계 원칙 (Design principles)

• 텍스트 입력, SVG 출력 (Text in, SVG out). 하나의 핵심 호출: render(id, source) → { svg }.
• Markdown + SVG가 작동하는 곳이라면 어디서든 작동합니다. 렌더링된 출력물을 위해 JavaScript 런타임 (runtime)이 필요하지 않습니다.
• 읽기 쉬운 소스 (Readable source). .wireloom 파일을 눈을 가늘게 뜨고 보더라도 레이아웃을 확인할 수 있어야 합니다.
• 작은 코어 (Small core). 적은 수의 기본 요소 (primitives)로 구성되며, 잘 조합됩니다. 기능 비대화 (feature creep)를 지양합니다.
• 공개 패키지 (Public package). MIT 라이선스입니다. 의존성으로 사용될 수 있도록 구축되었습니다.

기본 요소 세트 (Primitive set)

그룹별 개요 (v0.50 추가 사항은 인라인으로 표시됨):

• 구조적 컨테이너 (Structural containers): window, header, footer, panel, section, tabs, row, col, list, slot, grid, resourcebar, stats, navbar (v0.50), tabbar (v0.50), sheet (v0.50), segmented (v0.50)
• 대화형 리프 (Interactive leaves): button, input, combo, slider, tab, item, tabitem (v0.50), backbutton (v0.50), segment (v0.50)
• 콘텐츠 리프 (Content leaves): text, kv, image, icon, divider, cell, resource, stat, progress, chart, spacer (v0.50)
• 폼 + 위젯 기본 요소 (Form + widget primitives) (v0.4.5): checkbox, radio, toggle, tree/node, menubar/menu/menuitem/separator, breadcrumb/crumb, chip, avatar, spinner, status

text 및 kv 값에 대한 스타일 속성(Styling attributes): bold / italic / muted 플래그, weight=light|regular|semibold|bold, size=small|regular|large. 탭(tabs), 섹션(sections), 버튼(buttons)에 적용되는 badge="…". 행(rows)에 적용되는 align=left|center|right. 열(columns)에 적용되는 fill.

v0.4 추가 사항: 슬롯(slots) 및 셀(cells)에 적용되는 통합된 state= 열거형 (enum) (locked/available/active/purchased/maxed/growing/ripe/withering/cashed), 슬롯/섹션/셀/버튼/아이콘에 적용되는 의미론적(semantic) accent= 색상 (research/military/industry/wealth/approval/warning/danger/success), 슬롯의 선택적 footer: 자식 요소, 그리고 명명된 아이콘 라이브러리 (credits, research, military, industry, lock, check, star, gear 등 포함 — 알 수 없는 이름은 상자 안의 글자 플레이스홀더(placeholder)로 대체됨).

v0.4.1 추가 사항: 모든 프리미티브(primitive)에 적용되는 범용 id="…" 속성, 그리고 최상위 노드인 annotation — id가 태그된 요소로 지시선(leader line)을 연결하여 캔버스 여백에 표시되는 사용자 매뉴얼 스타일의 레이블입니다. 본문 텍스트는 \n 줄바꿈을 지원하며, target="<id>" 및 position=left|right|top|bottom 설정이 필수입니다. 주석(Annotations)은 window의 자식이 아닌 형제(siblings) 요소입니다.

v0.50 추가 사항: **row justify=start|between|around|end**는 주축(main axis)을 따라 자식 요소들을 배치합니다. spacer 리프(leaf) 노드는 행 내부의 남는 공간을 채우며