Open DesignMD: AI 코딩 에이전트를 위한 무료 Google 사양 DESIGN.md 파일 생성

만약 여러분이 Cursor나 Claude에게 UI 컴포넌트를 만들어 달라고 요청했다가, 2012년의 Bootstrap 기본값처럼 보이는 결과물을 받은 적이 있다면 그 고통을 잘 알 것입니다. AI가 기능적으로는 올바른 코드를 생성했지만, 스타일링은 일반적이고 일관성이 없으며 여러분이 의도했던 세련된 모습과는 거리가 멀었습니다.

해결책은 존재합니다. 여러분의 정확한 색상, 글꼴, 간격 및 레이아웃 규칙을 정의하는 DESIGN.md 파일을 AI에게 제공하는 것입니다. 하지만 최근까지도 어떤 웹사이트에서든 이러한 사양을 추출하는 가장 좋은 도구는 Context.dev에 의존해 왔으며, 이는 최근 무료 티어 접근을 구독 장벽 뒤로 제한한 유료 API였습니다.

Open DesignMD가 이 문제를 해결합니다. 이것은 오픈 소스 대안을 사용하여 동일한 작업을 수행하는 무료 셀프 호스팅 (self-hosted) 포크(fork)입니다. 마크다운 (markdown) 추출을 위한 Jina Reader, 스크린샷을 위한 Microlink, 그리고 Vercel AI SDK를 통한 멀티 프로바이더 LLM 지원을 사용합니다. 구독도 필요 없고, 추출 레이어를 위한 API 키도 필요하지 않습니다.

이 포크가 존재하는 이유

Context.dev의 원본 designmd.supply는 라이브 웹사이트 텔레메트리 (telemetry)를 마크다운 기반 디자인 시스템으로 컴파일하는 개념을 개척했습니다. 그것은 훌륭했고 무료였습니다. 그러다 Context.dev가 유료 전용 모델로 전환하면서, 추출 파이프라인이 로컬 배포 시 502 에러를 반환하기 시작했습니다.

훌륭한 도구가 유료 장벽 뒤에서 사라지는 것을 지켜보는 대신, Open DesignMD는 이 개념을 계속 유지하기 위해 만들어졌습니다. 우리는 모든 독점 엔드포인트를 무료의 고품질 대안으로 교체했습니다:

Context.dev API → HTML-to-markdown 변환을 위한 Jina Reader (r.jina.ai)
Context.dev 스크린샷 → 풀 HD 캡처를 위한 Microlink API
Context.dev LLM → OpenRouter, Ollama, Google, Anthropic 또는 표준 OpenAI

결과적으로: 완전히 무료 API와 여러분 자신의 LLM 크레딧(또는 Ollama를 통한 비용 제로의 로컬 모델)으로 실행되는 도구가 탄생했습니다.

내부 기술 스택

Open DesignMD는 Tailwind CSS v4와 함께 Next.js 16을 기반으로 구축되었습니다. 이 스택은 이전 프레임워크들이 어려워했을 기능들을 가능하게 하기 때문에 중요합니다.

Next.js 16 + Turbopack

이 앱은 빠른 개발 빌드를 위해 Turbopack과 함께 Next.js 16의 App Router를 사용합니다. API 라우트 핸들러는 app/api/design-md/route.ts에 위치하며 전체 추출 파이프라인 (extraction pipeline)을 조율합니다.

Jina Reader: 무료 HTML-to-Markdown

여기에 핵심적인 통찰이 있습니다. 웹페이지를 깔끔한 마크다운 (Markdown)으로 변환하기 위해 독점적인 API를 사용할 필요가 없습니다. Jina Reader가 이를 무료로 수행합니다. 어떤 URL이든 https://r.jina.ai/{url}로 보내면 LLM 친화적인 깔끔한 마크다운을 돌려받을 수 있습니다.

대상 URL (Target URL)
    │
    ├──► [Jina Reader] ──────► 깔끔한 마크다운 (Clean Markdown)
...

무료 티어에서는 API 키 없이 분당 20회의 요청을 제공하며, 무료 키를 사용하면 분당 500회(RPM)까지 가능합니다. 소수의 사이트에서 디자인 사양을 추출하기에는 충분하고도 남는 수준입니다.

멀티 프로바이더 LLM 지원 (Multi-Provider LLM Support)

Vercel AI SDK를 사용하면 거의 모든 LLM 프로바이더 (provider)를 연결할 수 있습니다. Open DesignMD는 다음을 지원합니다:

OpenRouter (DeepSeek-V3, Llama 3, Mixtral—종종 무료이거나 백만 토큰당 몇 센트 수준)
Ollama (완전 오프라인, 비용 제로)
Google Gemini (무료 티어 사용 가능)
Anthropic Claude
표준 OpenAI

설정은 .env 파일에 위치합니다:

AI_PROVIDER=openrouter
AI_MODEL=deepseek/deepseek-chat
OPENROUTER_API_KEY=your_key_here

또는 로컬 추론 (local inference)의 경우:

AI_PROVIDER=ollama
AI_MODEL=llama3
OLLAMA_BASE_URL=http://localhost:11434

.chat() 수정 사항: Vercel AI SDK 5+의 중단된 변경 사항(Breaking Change) 해결하기

커스텀 게이트웨이 (gateway)나 대체 프로바이더를 사용하면서 Vercel AI SDK 5+ 버전을 사용 중이라면 주의해야 할 함정이 있습니다. 최신 SDK 버전은 기본적으로 OpenAI의 /v1/responses 엔드포인트로 POST 요청을 보냅니다. 만약 FreeLLMAPI, LiteLLM, 또는 OpenRouter를 통해 라우팅하고 있다면, 해당 게이트웨이들은 전통적인 /v1/chat/completions 엔드포인트만 지원하기 때문에 404 Not Found 오류가 발생합니다.

해결 방법은 생각보다 매우 간단합니다. 기본 createOpenAI 클라이언트를 직접 사용하는 대신, .chat(modelName) 메서드를 호출하면 됩니다:

import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
...

해당 .chat() 호출은 SDK가 전통적인 completions 엔드포인트를 사용하도록 강제합니다. 이 호출이 없다면, OpenAI가 아닌 다른 게이트웨이는 조용히 실패하거나 모호한 404 오류를 발생시킬 것입니다.

시작하기: 원클릭 설정

Open DesignMD는 Windows 환경에서 마찰 없는(zero-friction) 로컬 설정을 위해 설계되었습니다. 전체 과정은 약 2분 정도 소요됩니다.

저장소(repository)를 클론(Clone)하거나 다운로드하세요:

   git clone https://github.com/Yp-pro/open-designmd.git

install.bat를 더블 클릭하세요. 이 과정은 휴대용(portable) Node.js v20 런타임을 다운로드하고, 사용자의 글로벌 Node 설치 환경을 건드리지 않고 의존성(dependencies)을 설치합니다. nvm, npm install -g, 또는 PATH 수정이 전혀 필요 없습니다.
designmd-portable/app/.env 파일에서 LLM 제공자(provider)를 설정하세요 (위의 예시 참조). OpenRouter를 사용하는 경우, 해당 대시보드에서 무료 API 키를 받으세요. Ollama를 사용하는 경우, Ollama를 설치하고 모델을 풀(pull)하기만 하면 됩니다.
run.bat를 더블 클릭하세요. 앱이 http://localhost:3000에서 시작되며 브라우저가 자동으로 열립니다.
인터페이스에 URL을 붙여넣고, 추출(extract)을 클릭한 뒤 DESIGN.md를 다운로드하세요. 추출에는 사이트의 복잡도에 따라 10~30초가 소요됩니다.

캐시된 데이터를 삭제하려면, 로컬 Turso 캐시를 즉시 삭제하는 clear-cache.bat 유틸리티가 있습니다. 이는 사이트가 디자인을 업데이트한 후 다시 추출하고 싶을 때 유용합니다.

생성된 DESIGN.md 사용하기

DESIGN.md 파일이 준비되면, 프로젝트 루트(또는 AI 에이전트가 컨텍스트를 읽어오는 위치)에 넣으세요. 핵심은 AI가 컴포넌트를 생성하기 전에 해당 파일을 컨텍스트(context)로 접근할 수 있도록 하는 것입니다.

다음은 Cursor 또는 Claude에서 잘 작동하는 프롬프트(prompt) 템플릿입니다:

프로젝트 루트에 있는 DESIGN.md 파일을 읽으세요. 
명세서(spec)에 정의된 색상(colors), 타이포그래피(typography), 간격(spacing), 그림자(shadows), 테두리 반경(border-radius) 등의 디자인 토큰(design tokens)을 정확히 사용하여 가격 카드(pricing card) 컴포넌트를 만드세요.
...

AI는 디자인 토큰(design tokens)을 참조하여 일반적인 Bootstrap 기본값이 아닌, 원본 웹사이트의 시각적 언어(visual language)와 일치하는 컴포넌트를 생성합니다. 저는 이를 Cursor의 인라인 완성(inline completion)과 Claude의 아티팩트 모드(artifact mode)로 테스트해 보았으며, 두 방식 모두 놀라울 정도로 일관된 결과를 만들어냈습니다.

이 방식이 강력한 이유는 구체성(specificity)에 있습니다. AI에게 "현대적인 느낌으로 만들어줘"라고 말하는 대신, 정확한 헥사 값(hex values), 글꼴 두께(font weights), 간격 스케일(spacing scales)을 제공하는 것입니다. 그 결과, 목표로 하는 디자인과 실제로 일치하는 코드가 생성됩니다.

다음은 생성된 DESIGN.md에 포함될 수 있는 내용의 간략한 예시입니다:

# 디자인 시스템 사양 (Design System Specification)

## 색상 (Colors)
...

솔직한 트레이드오프 (The Honest Trade-off)

Open DesignMD가 완벽한 것은 아닙니다. 기존의 Context.dev API는 원본 CSS 스타일시트(stylesheets)를 분석하여 모든 커스텀 속성(custom property), 모든 미디어 쿼리 중단점(media query breakpoint), 모든 애니메이션 타이밍 함수(animation timing function)와 같은 정확한 변수를 추출했습니다. 반면 우리의 방식은 Jina Reader의 마크다운(markdown) 출력을 사용한 다음, LLM(대규모 언어 모델)이 구조적 콘텐츠로부터 디자인 토큰을 추론하고 재구성하도록 요청합니다.

이 방식은 색상 팔레트(color palettes), 타이포그래피 스케일(typography scales), 간격 패턴(spacing patterns), 레이아웃 구조(layout structures) 등 95%의 사용 사례에서 정확하게 작동하며 깔끔하게 추출됩니다. 하지만 원본 스타일시트 변수를 그대로 캡처하지는 못합니다. 만약 사이트가 --color-primary: #2563EB;와 같은 CSS 커스텀 속성을 컴포넌트 범위 스타일(component-scoped styles) 내에 깊게 중첩하여 사용하는 경우, LLM이 값은 정확하게 추론할 수 있지만 원래의 변수 이름은 보존하지 못할 수 있습니다.

대부분의 AI 코딩 워크플로(workflows)에서 이 차이는 무시할 수 있는 수준입니다. Cursor가 버튼 컴포넌트를 생성할 때, 기본 색상이 --color-primary에서 왔는지 아니면 #2563EB로 추론되었는지는 중요하지 않습니다. 단지 헥사 값이 필요할 뿐입니다. LLM이 추론한 토큰은 컴포넌트가 원본과 시각적으로 일치하게 렌더링될 만큼 충분히 정확합니다.

이러한 트레이드오프(trade-off)는 충분한 가치가 있습니다. 유료 API 의존성 대신, 여러 제공자(multi-provider)를 유연하게 선택할 수 있는 완전히 무료인 셀프 호스팅(self-hosted) 도구를 얻을 수 있기 때문입니다. 만약 픽셀 단위로 완벽한 CSS 변수 추출이 필요하다면, 기존의 Context.dev API(현재 유료) 구독이 가치가 있을 수 있습니다. 하지만 그 외의 모든 경우에는 이 도구가 효과적입니다.

제공 기능

비용 제로 (Zero cost): Jina Reader와 Microlink을 사용한 추출
멀티 프로바이더 LLM (Multi-provider LLM) 지원 (OpenRouter, Ollama, Gemini, Claude, OpenAI)
휴대 가능한 Windows 설정: 로컬 Node.js 런타임 포함
세밀한 캐시 제어: clear-cache.bat를 통한 관리
스크린샷 타이밍 최적화: React/애니메이션을 위해 최적화됨 (하이드레이션(hydration)을 위한 3초 대기)

직접 사용해보기

저장소는 GitHub에서 확인할 수 있습니다: Yp-pro/open-designmd

만약 이 포크(fork) 버전이 여러분의 작업 흐름에서 시간을 절약해주거나 유료 구독을 대체할 수 있다면, 저장소에 스타(star)를 눌러주시면 감사하겠습니다. 또한, 원본 컨셉이 가치 있다고 느끼신다면 업스트림(upstream)인 designmd.supply에도 스타를 눌러주세요. 그들의 선구적인 작업이 있었기에 이것이 가능했습니다.

피드백, 이슈 또는 기능 요청이 있으신가요? GitHub에 이슈를 오픈하거나 아래에 댓글을 남겨주세요. 이 도구는 활발히 유지 관리되고 있으며, 저는 실제 사용 사례에 관심이 많습니다. 어떤 사이트에서 디자인 토큰(design tokens)을 추출하고 계신가요? 어떤 LLM 제공자를 사용 중이신가요? 피드백이 많을수록 도구는 더욱 발전합니다.

테스트 과정에서 발견한 한 가지 사항은, 이 도구가 Stripe, Linear, Vercel의 마케팅 페이지와 같이 디자인 요소가 풍부한 사이트에서 특히 잘 작동한다는 점입니다. 이러한 사이트들은 Jina Reader가 아름답게 파싱할 수 있는 깔끔하고 잘 구조화된 HTML을 가지고 있으며, 결과물로 나오는 디자인 토큰도 놀라울 정도로 정확합니다. 자바스크립트 렌더링이 과도하거나 캔버스(canvas) 기반 레이아웃을 사용하는 사이트는 다루기 더 까다롭지만, 여전히 사용 가능한 결과를 만들어냅니다.

Next.js 16, Tailwind CSS v4, Vercel AI SDK, Jina Reader, 그리고 Microlink으로 제작되었습니다.