brandmd: 웹사이트 디자인 시스템을 LLM용 DESIGN.md로 추출하여 AI 코딩 에이전트의 브랜드 컨텍스트 제공

Claude Code, Cursor, Gemini CLI, Google Stitch가 사용자의 UI를 추측하지 못하게 하세요. brandmd는 어떤 웹사이트의 디자인 시스템이라도 LLM이 읽을 수 있는 DESIGN.md로 추출합니다.

AI 코딩 에이전트(AI coding agents)는 사용자의 색상, 글꼴, 간격, 컴포넌트 및 레이아웃 규칙을 모를 때 일반적인 화면을 생성합니다. 명령어 하나를 실행하고 프로젝트 루트(project root)에 DESIGN.md를 넣으면, 에이전트가 코드를 작성하기 전에 브랜드 컨텍스트(brand context)를 갖게 됩니다. 기본 추출은 API 키 없이 로컬에서 실행됩니다.

npx brandmd https://stripe.com -o DESIGN.md

여러 URL을 전달하여 페이지 전반의 브랜드 토큰(brand tokens)을 병합할 수 있습니다: npx brandmd https://site.com https://site.com/pricing https://site.com/docs -o DESIGN.md

사용 중인 스택이 읽을 수 있는 모든 형식으로 출력합니다:

(기본값): Claude Code, Cursor, Gemini CLI, Codex, Stitch용 DESIGN.md

--json: 스크립트, MCP 서버 및 에이전트 툴체인(agent toolchains)을 위한 가공되지 않은 추출 토큰

--css: 어떤 프로젝트에도 바로 적용 가능한 CSS 사용자 정의 속성(CSS custom properties)

--tailwind: Tailwind v4 @theme 블록

--html: 시각적이고 공유 가능한 브랜드 가이드

다음과 결합하여 사용하세요:

--agent: .cursor/rules/brand.mdc 및 .claude/skills/brand-style/SKILL.md도 함께 작성하여 Claude Code와 Cursor가 브랜드 컨텍스트를 자동으로 인식하도록 합니다. 수동 설정이 필요 없습니다. 생성된 SKILL.md는 Anthropic Claude Code Skills, google/skills, vercel-labs/agent-skills와 동일한 설치 가능한 스킬(installable-skills) 컨벤션을 따릅니다.

--dark: 다크 모드 토큰도 함께 추출합니다.

--vision: 스크린샷에서 일러스트레이션 스타일, 사진 분위기, 카피라이팅 보이스 및 마이크로카피 패턴을 추가합니다. GEMINI_API_KEY가 필요합니다 (aistudio.google.com/apikey에서 무료로 발급 가능).

Claude Code, Cursor 규칙, Gemini CLI, Codex, Google Stitch, MCP 서버 및 마크다운을 읽는 모든 코딩 에이전트의 브랜드 컨텍스트로 작동합니다.

실제 사례: Stripe · Linear · GitHub · Vercel · Notion · Cursor · Anthropic · Figma · Supabase · Raycast · 갤러리에 20개 이상 더 있음

## 2. Color Palette & Roles
- **--color-accents-1** (`#FAFAFA`): Page background
- **--color-blue-600** (`#0075DE`): Accent background
...

brandmd는 Claude Code, Cursor, Gemini CLI, Codex, 그리고 Google Stitch에 실제 디자인 컨텍스트 (design context)를 제공하기 위한 도구입니다. 이 도구는 실제 웹사이트의 색상 (colors), 타이포그래피 (typography), 간격 (spacing), 그림자 (shadows), 컴포넌트 패턴 (component patterns), 그리고 레이아웃 규칙 (layout rules)을 추출하여 DESIGN.md 파일로 만듭니다.

이를 통해 AI 코딩 에이전트 (AI coding agents)가 일반적인 화면이 아닌, 브랜드 정체성이 반영된 UI를 구축할 수 있게 합니다.

brandmd를 직접 실행하지 않고도 이미 만들어진 브랜드 기술 (brand skills)을 사용하고 싶다면, 다음 명령어로 yuvrajangadsingh/brand-skills를 직접 설치하세요:

npx skills add yuvrajangadsingh/brand-skills

이 명령은 5가지 brandmd 생성 기술 (Tailwind CSS, shadcn/ui, Vercel, Mintlify, Anthropic)을 프로젝트의 에이전트 기술 (agent skills) 폴더에 설치합니다. 각 기술은 references/DESIGN.md가 포함된 독립적인 구조로 되어 있습니다. 커뮤니티 예시들은 공개된 마케팅 사이트에서 생성된 것이며, 언급된 브랜드들과 공식적으로 제휴된 것은 아닙니다.

릴리스 노트 (Release notes)

v0.9: --agent 플래그를 사용하면 DESIGN.md와 함께 Cursor 규칙 (Cursor rule) 및 Claude Code 기술 (Claude Code skill)을 작성합니다. CI (지속적 통합)가 npm Trusted Publishing으로 전환되었습니다.

v0.8: 디스플레이 (display), 헤딩 (heading), 본문 (body), 그리고 글로벌 텍스트 역할 전반에 걸쳐 기본 글꼴 (primary font) 감지 정확도가 향상되었습니다.

v0.7: Cloudflare로 보호되는 사이트의 경우, JS 챌린지 (JS challenge)를 위해 최대 20초까지 대기하여 처리할 수 있도록 개선되었습니다.

v0.6: 선택 사항인 --vision 플래그를 추가하면 일러스트레이션 스타일 (illustration style), 사진 분위기 (photography mood), 카피라이팅 어조 (copywriting voice), 그리고 마이크로카피 (microcopy) 노트를 추가합니다. 무료 Gemini API 키가 필요합니다.

전체 이력은 CHANGELOG.md를 참조하세요.

주요 딥 링크 (Flagship deep links) (DESIGN.md):

• Stitch
• Stripe
• Linear
• GitHub
• Vercel
• Notion
• Cursor
• Anthropic
• Figma
• Supabase
• Raycast
• OpenAI
• Tailwind CSS

기타 출력 형식:

Google Stitch는 LLM이 읽을 수 있는 형식으로 디자인 시스템을 인코딩하는 마크다운 (markdown) 파일인 DESIGN.md를 도입했습니다. 문제는 아무도 이를 처음부터 직접 작성하고 싶어 하지 않으며, Stitch는 웹 UI를 통해서만 이를 생성한다는 점입니다.

brandmd는 이를 터미널 (terminal)에서 수행합니다. 어떤 URL이든 지정하기만 하면 DESIGN.md를 돌려받을 수 있습니다. 이를 프로젝트 루트 (project root)에 넣으면 AI 도구들이 브랜드 정체성이 반영된 UI를 생성하기 시작합니다.

# 직접 실행 (설치 불필요)
npx brandmd https://linear.app
# 전역 설치
...

# DESIGN.md (기본값)
brandmd https://stripe.com
brandmd https://stripe.com -o DESIGN.md
...

5개의 섹션으로 구성된 Google Stitch의 DESIGN.md 사양을 따릅니다. 프로젝트 루트(root)에 저장하면 AI 코딩 에이전트가 이를 사용하여 브랜드 정체성에 맞는 UI를 생성할 수 있습니다.

:root {
--color-accents-1: #FAFAFA;
--color-blue-600: #0075DE;
...

@import "tailwindcss";
@theme {
--color-primary: #0075DE;
...

컬러 스와치(color swatches), 폰트 견본(font specimens), 간격 시각화(spacing visualization) 및 그림자 예시가 포함된 독립적인 다크 테마 HTML 페이지입니다. 브라우저에서 열거나 이해관계자(stakeholders)와 공유할 수 있습니다.

프로그래밍 방식의 사용을 위한 가공되지 않은 추출 토큰(Raw extracted tokens)입니다.

여러 URL을 전달하면 서로 다른 페이지의 토큰을 하나의 DESIGN.md로 병합합니다. 각 페이지는 정규화(normalized)되어 내용이 긴 페이지가 전체를 압도하지 않도록 합니다.

brandmd https://stripe.com https://stripe.com/pricing https://stripe.com/docs

실패한 페이지는 경고와 함께 건너뜁니다. 도메인이 섞여 있는 경우 경고가 표시됩니다.

다크 테마 토큰을 별도의 섹션으로 추출합니다:

brandmd https://github.com --dark

DESIGN.md에 다크 컬러 팔레트가 포함된 "Dark Theme Overrides" 섹션을 추가합니다. Playwright를 통해 prefers-color-scheme: dark를 사용하므로, 사용자가 다크 모드에서 실제로 보는 내용을 캡처합니다. 이는 DESIGN.md 출력에만 영향을 미칩니다 (--css, --tailwind, --html 옵션에서는 무시됨).

• CSS 사용자 정의 속성 (CSS custom properties): :root 및 @media 규칙에서 추출 (사용 가능한 경우 실제 변수 이름 사용)

• 색상 (Colors): 의미론적 역할(semantic roles) 부여 (배경, 텍스트, 강조, 테두리)

• 타이포그래피 (Typography): 역할 인지형 기본(Primary) 탐지 (display > heading > body), 역할별 폰트 세부 분석, 그리고 "탐지된 모든 폰트" 전체 빈도 목록 제공. 기본(Primary) 선택 시 고정폭(monospace), 기본 대체(default fallbacks) 폰트 및 아이콘 폰트는 제외함.

• 간격 스케일 (Spacing scale) 및 기본 그리드 단위

• 테두리 반경 (Border radii) 및 그림자 스타일

• 컴포넌트 패턴 (Component patterns): (버튼, 카드, 입력창)

• 헤드리스 브라우저(Playwright)에서 각 페이지를 렌더링합니다.

• 지연 로딩(lazy-loaded)되는 콘텐츠를 트리거하기 위해 스크롤합니다.

• 쿠키 배너 및 오버레이를 닫습니다.

• :root에서 CSS 사용자 정의 속성을 추출합니다 (@media 규칙까지 재귀적으로 탐색)

rules) - 모든 가시적 요소로부터 계산된 스타일 (computed styles)을 추출합니다.

• 유사한 색상을 클러스터링하고, 간격 스케일 (spacing scale)을 식별합니다.
• 페이지 전반에 걸쳐 토큰을 병합합니다 (페이지별로 정규화됨).
• 선택한 형식으로 출력합니다.

LLM 호출 없음, API 키 필요 없음, 완전히 로컬 머신에서 실행됩니다.

brandmd는 Claude Code, Cursor, VS Code/Copilot, Codex, Gemini CLI를 포함한 30개 이상의 플랫폼에서 작동하는 에이전트 스킬 (Agent Skill)로 제공됩니다.

npx skills add yuvrajangadsingh/brandmd

그 다음 에이전트에게 다음과 같이 말하세요: "https://linear.app 에서 디자인 시스템을 추출해줘"

brandmd가 시간을 절약해 주었다면, 저장소(repo)에 별(star)을 눌러주는 것을 고려해 보세요.