README 뱃지가 디자인 시스템 밖으로 튀어나올 때
프로젝트에 shadcn/ui를 도입하고 나면 어김없이 발생하는 불쾌한 이음새가 있다. 버튼, 카드, 인풋 모두 같은 디자인 토큰 위에 올라가 있는데, README에 박힌 shields.io 뱃지만큼은 10년 전 감성 그대로다. 폰트도 다르고, 테두리 반경도 다르고, 색상 팔레트도 전혀 관련이 없다. 이 불일치는 단순한 미적 문제가 아니다. 디자인 시스템의 신뢰성은 '예외 없이 일관된 언어'에서 나오는데, 뱃지 하나가 그 일관성을 조용히 갉아먹는다.
shadcn/ui 버튼을 SVG로 굽는 실험—shieldcn
dev.to에 공개된 shieldcn 프로젝트는 이 문제를 정면으로 파고든다. 핵심 아이디어는 단순하지만 기술적으로 흥미롭다. shadcn/ui의 Button 컴포넌트를 Satori로 SVG에 렌더링해서, README에 붙여도 앱의 디자인 시스템과 같은 언어로 읽히도록 만드는 것이다. Inter 폰트, border-radius, padding, 색상 토큰까지—버튼 스펙 그대로를 뱃지에 이식한다.
구현의 진짜 도전은 SVG가 <img> 태그로 삽입될 때 완전히 샌드박스 처리된다는 점이다. CSS 변수도, 외부 스타일시트도, JavaScript도 동작하지 않는다. var(--primary) 같은 shadcn 테마 토큰을 그대로 쓸 수 없다는 뜻이다. 해결책은 렌더링 전에 모든 색상을 리터럴 hex 값으로 확정하는 resolve() 함수를 두고, 렌더러는 그저 받은 hex 값으로 레이아웃을 그리는 역할만 맡기는 것이다. 분기 로직이 렌더러에서 완전히 분리되기 때문에, 새 variant를 추가하려면 토큰 테이블에 한 줄만 더하면 된다. 이것이 바로 디자인 시스템 설계의 본질—변경이 쉬운 구조다.
Satori가 가르쳐주는 컴포넌트 렌더링의 제약
Satori를 실제로 써보면 문서만으로는 파악하기 어려운 quirk들이 있다. opacity CSS 속성을 조용히 무시한다. dangerouslySetInnerHTML이 없어서 SVG 아이콘을 전부 React 엘리먼트 트리로 파싱해야 한다. Next.js Route Handler에서 폰트를 fetch로 불러오면 안 되고 readFileSync로 파일시스템에서 읽어야 한다. 이런 제약들은 단순한 버그 목록이 아니다. 라이브러리의 경계를 정확히 파악해야만 안정적인 렌더링 파이프라인을 설계할 수 있다는 교훈이다. 추상화 뒤에 숨어있는 제약을 빠르게 발견하고 우회책을 만드는 능력—이것이 컴포넌트 전략을 짜는 개발자에게 필요한 핵심 근육이다.
아키텍처 관점에서도 배울 점이 있다. Next.js의 catch-all 라우트 하나(app/[...slug]/route.ts)가 URL 파싱, 데이터 페치, 색상 리졸브, SVG 렌더링, PNG 변환을 모두 처리한다. 프로바이더 함수는 { label, value, color, link } 형태의 동일한 인터페이스를 반환하고, 렌더러는 데이터 출처를 모른다. 25개 이상의 데이터 소스를 지원하면서도 렌더링 코드가 단순하게 유지되는 이유다.
AI 도구로 이런 걸 빠르게 만들 수 있을까—Gemini vs Claude 현실 점검
shieldcn 같은 프로젝트를 혼자 빠르게 프로토타이핑하려면 AI 코딩 도구 선택이 실질적인 변수가 된다. velog에 공개된 Gemini 바이브 코딩 후기는 이 선택의 현실적인 트레이드오프를 잘 보여준다.
저자의 결론은 명확하다. 코딩 성능 자체는 Claude Code(Opus)가 현 시점 최고다. 자연어 추론으로 맥락을 파악하고, 스스로 판단해서 코드를 이어나가는 능력이 다른 모델을 앞선다. 하지만 토큰 비용이 문제다. 긴 세션을 유지하면 비용이 빠르게 쌓인다. 대안으로 선택한 Gemini의 장점은 분명하다—빠른 처리 속도, 멀티모달 입력(디자인 목업 이미지를 바로 넣을 수 있다), 넓은 컨텍스트 윈도우, 그리고 프론트엔드 코딩에서의 실용적인 성능. 단점도 명확하다. 컨벤션 유지가 약하다. 복잡한 멀티스텝 작업에서 흐름이 흔들린다.
두 도구를 엮는 전략—프로토타이핑과 고도화의 분리
이 두 사례를 함께 읽으면 실용적인 워크플로우가 보인다. Gemini로 빠르게 프로토타이핑하고, Claude로 정밀하게 고도화한다. 구체적으로는 이렇다.
초기 컴포넌트 스캐폴딩—토큰 테이블 설계, 라우트 구조, 프로바이더 인터페이스 초안—은 Gemini의 속도와 멀티모달 능력이 빛나는 구간이다. 디자인 목업 이미지를 붙여넣고 "shadcn/ui 토큰 기반으로 이 뱃지를 Satori 렌더러로 구현해줘"라고 지시하면 초안을 빠르게 얻을 수 있다. 컨텍스트 윈도우가 넓기 때문에 관련 파일을 한꺼번에 넣고 전체 구조를 한 번에 짜는 데도 유리하다.
반면 Satori quirk 대응, 색상 리졸브 로직 정밀화, 에러 핸들링, 코드베이스 컨벤션 유지—이런 '디테일 고도화' 작업은 Claude가 훨씬 믿음직하다. 컨벤션 파일(CLAUDE.md)을 잘 구성해두면 복잡한 추론이 필요한 작업도 방향을 잃지 않는다.
디자인 시스템을 '실험 단위'로 보는 관점
shieldcn이 흥미로운 이유는 단지 뱃지 서비스를 만들었기 때문이 아니다. shadcn/ui의 컴포넌트 레지스트리 구조를 그대로 확장해서 자체 레지스트리(shieldcn.dev/r/readme-badge.json)를 제공한다는 점이다. pnpm dlx shadcn@latest add 명령 하나로 뱃지 컴포넌트를 다른 프로젝트에 심을 수 있다. 이것은 shadcn/ui의 설계 철학—컴포넌트를 소유하고, 필요에 맞게 고치고, 팀 레지스트리로 배포한다—을 실서비스 레벨에서 구현한 사례다.
AI 도구가 이 흐름을 가속한다. 컴포넌트 초안을 AI로 생성하고, 실제 사용자 피드백으로 토큰을 조정하고, 레지스트리로 배포하는 사이클이 점점 짧아지고 있다. 디자인 시스템은 한 번 만들어두는 완성품이 아니라, 빠르게 실험하고 검증하는 살아있는 단위가 되어가고 있다.
전망: 컴포넌트 레지스트리 + AI 코딩의 교차점
Gemini의 멀티모달 능력이 고도화되고, Claude의 컨텍스트 추론이 더 정밀해질수록 디자인-개발 경계는 더 빠르게 허물어진다. 단기적으로 주목할 지점은 두 가지다. 첫째, shadcn/ui 레지스트리 생태계가 성숙할수록 'AI로 컴포넌트를 생성하고 레지스트리로 배포하는' 흐름이 표준 워크플로우가 될 가능성이 높다. 둘째, Satori처럼 서버사이드 렌더링 레이어에서 React 컴포넌트를 재활용하는 패턴—이미지 생성, OG 이미지, 뱃지, PDF—이 Next.js Route Handler와 결합해서 더 다양한 서비스로 확장될 것이다.
컨벤션 유지 문제는 AI 도구가 아직 넘지 못한 벽이다. 하지만 역설적으로 이 약점이 디자인 시스템을 코드로 명시화하는 동기가 된다. 토큰 테이블을 명확히 정의하고, 레지스트리 구조를 체계화할수록 AI가 더 일관된 결과를 낸다. 좋은 디자인 시스템 설계가 AI 코딩의 품질을 높이고, AI 코딩이 디자인 시스템 실험을 가속하는 선순환—이것이 지금 이 교차점이 가리키는 방향이다.