oh-my-design, CJK 화면을 위한 AI 디자인 시스템의 등장
똑같은 프롬프트로 화면을 만들어도 페이지마다 버튼 곡률과 여백이 제각각 깨지는 현상, 과연 프롬프트 엔지니어링 부족 때문일까요?
이 아티클의 핵심 내용 요약과 글로벌 검색·AI 엔진을 위한 테이크어웨이입니다.
✦ KR 주제: oh-my-design의 CJK 특화 디자인 시스템 아키텍처
✦ KR 핵심 요약: oh-my-design은 AI 코딩 에이전트가 겪는 UI 파편화와 CJK 폰트 처리 한계를 해결하기 위해 등장한 오픈소스 프레임워크입니다. 토스, 카카오뱅크, 라인 등 500개 이상의 실제 기업 디자인 시스템을 단일 진실 공급원(DESIGN.md)으로 변환하여, 로컬 환경에서 추가 API 호출 없이 Claude Code, Cursor 등의 에이전트에 주입합니다.
🌐 Global Takeaway: oh-my-design addresses AI-generated UI inconsistency and typography constraints in CJK environments by injecting verified company design systems into coding agents. Utilizing a local-first DESIGN.md specification with zero API calls, it provides Claude Code and Cursor with production-grade UI consistency based on top East Asian tech products.
아래 비교와 계층도는 범용 UI 스킬 대비 oh-my-design의 구조적 차이와 내부 작동 계층을 보여줍니다.
- 영문 베이스 폰트·행간 기본값
- 화면마다 달라지는 파편화 코드
- 외부 API 호출 및 토큰 소모
- 서구권 SaaS 룩앤필 위주 복제
- 한중일(CJK) 맞춤 타이포·자간·행간
- DESIGN.md 단일 진실 공급원
- 로컬 로직 기반 Zero API Calls
- 토스·라인 등 500+ 실무 레퍼런스
1. 프론트엔드 AI 에이전트가 직면한 디자인 슬롭의 한계
대규모 언어 모델(LLM) 기반의 코딩 에이전트가 소프트웨어 개발의 주류 도구로 자리 잡으면서, 프로토타입 제작과 프론트엔드 컴포넌트 작성 속도는 비약적으로 빨라졌습니다. Claude Code, Cursor, Codex, OpenCode와 같은 도구는 요구사항 몇 줄만으로 복잡한 레이아웃을 작성해 냅니다. 그러나 프로젝트의 규모가 단일 페이지를 넘어 멀티 뷰 라우팅과 수십 개의 재사용 컴포넌트로 확장되는 순간, 치명적인 문제점이 드러납니다. 바로 에이전트가 페이지마다 제각각 다른 디자인 언어를 구사하는 '디자인 슬롭(AI Slop)' 현상입니다.
동일한 프로젝트 내부임에도 불구하고 로그인 화면에서는 모서리 곡률이 16px인 버튼이 생성되고, 대시보드 화면에서는 각진 4px 모서리의 버튼이 생성됩니다. 기본 텍스트 색상 역시 #111827, #1f2937, #333333 등으로 매번 달라지며, 타이포그래피의 계층 구조와 여백 체계(Spacing Scale)가 무너집니다. 이는 모델이 컴포넌트를 생성할 때 전체 프로젝트의 전역 컨텍스트를 지속적으로 유지하지 못하고, 학습 데이터의 통계적 평균치에 의존하여 무작위 서구권 템플릿의 조각들을 조합하기 때문에 발생합니다.
더 심각한 장벽은 동아시아 언어권(CJK, 한국어·중국어·일본어) 프로덕트 환경에서 나타납니다. 대부분의 글로벌 프론트엔드 프롬프트나 UI 생성 라이브러리는 영어 알파벳의 시각적 비중과 렌더링 특성에 최적화되어 있습니다. 알파벳에 맞춰진 빡빡한 행간(leading-tight)과 자간 설정은 한글이나 한자를 적용했을 때 글자 상하단이 잘리거나 시각적 밀도가 뭉개지는 문제를 야기합니다. 글로벌 커뮤니티에서 유행한 UI UX Pro Max, Taste skill v2, Emil Kowalski 스타일의 스킬들이 서구권 감성의 영문 랜딩 페이지에서는 미려하게 작동할지 몰라도, CJK 환경의 밀도 높은 핀테크나 커머스 대시보드에서는 타이포그래피의 파탄으로 귀결되곤 했습니다.
1-1. 기존 UI 보조 스킬과 CJK 프로덕트의 간극
기존에 공개된 AI UI 스킬들은 주로 추상적인 디자인 미학(Aesthetics)이나 일반적인 클린 코드 지침을 에이전트 시스템 프롬프트에 주입하는 방식을 취했습니다. 이 방식은 개별 컴포넌트의 단편적인 시각적 완성도는 높여줄 수 있으나, 프로덕션 레벨에서 요구하는 엄격한 토큰 규칙을 강제하지 못합니다.
| 비교 항목 | 서구권 중심 범용 디자인 스킬 | CJK 실무 프로덕트 요구사항 |
|---|---|---|
| 타이포그래피 기준 | 라틴 알파벳(Latin) 기준 행간·자간 | 글리프 구조가 복잡한 CJK 문자 맞춤 행간·줄바꿈 |
| 텍스트 줄바꿈 규칙 | 공백 중심 word-break: normal |
음절 보존 및 가독성을 위한 word-break: keep-all |
| 컬러 및 컴포넌트 토큰 | 무작위 Tailwind 클래스 난립 | 토스(TDS) 등 검증된 디자인 토큰 체계 |
| 일관성 유지 방식 | 프롬프트 미사여구 의존 | DESIGN.md 단일 진실 공급원(SSOT) 참조 |
결국 프론트엔드 엔지니어들은 에이전트가 쏟아낸 코드를 다시 손으로 열어 폰트 크기, 행간, 여백, 토큰 변수를 일일이 수정하는 이중고를 겪어야 했습니다. 이러한 구조적 문제를 해결하기 위해 등장한 프로젝트가 바로 오픈소스 oh-my-design입니다.
2. oh-my-design: CJK 화면을 위한 단일 진실 공급원 체계
개발자 곽성재(kwakseongjae)가 공개한 oh-my-design은 "Give your AI coding agent a design system(당신의 AI 코딩 에이전트에 디자인 시스템을 부여하라)"이라는 간결한 철학 아래 개발되었습니다. 이 프로젝트의 핵심 목표는 프롬프트 엔지니어링의 수사학적 지시에 의존하는 대신, 검증된 실제 기업의 디자인 시스템을 파일 규격으로 변환하여 AI 코딩 에이전트의 작업 환경에 이식하는 것입니다.
공식 서비스 랜딩 페이지(oh-my-design.kr)에 따르면, 이 프로젝트는 한국의 토스(Toss), 카카오뱅크(KakaoBank), 당근(Karrot), 뱅크샐러드(Banksalad), 컬리(Kurly), 크림(KREAM), 채널톡(Channel Talk), 업비트(Upbit), 쏘카(SOCAR), 야놀자(Yanolja), 클래스101(Class101)은 물론 대만의 104인력은행(104人力銀行), 일본의 프리(freee), 라인(LINE)에 이르기까지 500개 이상의 실제 기업 화면에서 추출·검증된 DESIGN.md 레퍼런스를 보유하고 있습니다.
"좋은 oh-my-design 데모는 스킬 이름을 훑어보는 시간이 아니에요. 눈에 보이는 문제 하나로 시작해 제품이 기대고 있는 동작은 그대로 지키고, 실제 라우트에서 누구나 확인할 수 있는 근거를 보여 주며 끝나요." — oh-my-design 공식 문서
oh-my-design은 이러한 기업들의 시각적 토큰과 컴포넌트 패턴을 DESIGN.md라는 단일 진실 공급원(Single Source of Truth, SSOT) 포맷으로 정형화합니다. 에이전트는 무작위로 스타일을 생성하는 대신, 이 레퍼런스 파일을 읽어 들여 지정된 토큰 값과 컴포넌트 사양을 엄격하게 준수하며 코드를 작성합니다.
2-1. 단일 규격 DESIGN.md의 구조적 설계
DESIGN.md는 프로젝트 루트에 위치하여 에이전트가 코드를 작성하거나 리팩터링할 때 최우선으로 참조하는 설계 문서입니다. 이 파일은 단순한 텍스트 가이드가 아니라 기계와 인간 모두가 즉각 파싱할 수 있는 표준 명세로 구성됩니다.
- 컬러 시스템(Color Tokens): 배경(
colors.canvas), 본문 텍스트(colors.body,colors.foreground), 보조 텍스트(colors.muted), 서피스 레이어(colors.surface) 등 위계별 색상 16진수 값 명시. - 타이포그래피 스케일(Typography): 폰트 크기, 폰트 두께, 상대 행간 비율(예:
14 / 400 / 1.5,36 / 700 / 1.5)을 정확히 수치화하여 모호성을 배제. - 컴포넌트 명세(Component Specs): 버튼, 입력창, 카드 등 핵심 요소의 배경색, 텍스트 색상, 높이, 내부 여백(패딩), 모서리 곡률(
border-radius)의 절대 규칙 지정. - 인터랙션 및 브랜드 보이스: 마우스 호버, 비활성화(Disabled), 포커스 상태의 시각적 변화 규칙과 제품 페르소나 정의.
이러한 구조적 토큰을 통해 코딩 에이전트는 "현대적이고 깔끔한 토스 스타일로 만들어줘"라는 모호한 자연어를 해석할 필요 없이, colors.canvas #ffffff, components.tds-button.radius 16px와 같은 물리적 상수를 그대로 코드에 바인딩하게 됩니다.
3. CJK 타이포그래피 특화와 /hangul 스킬의 디테일
동아시아 문자권 프로덕트에서 완성도를 결정짓는 가장 핵심적인 요소는 타이포그래피와 UX 라이팅의 정밀성입니다. 한글은 영문 라틴 알파벳과 달리 초성, 중성, 종성이 결합된 사각형 박스 형태의 음절 글리프 구조를 갖습니다. 이로 인해 영문 서체 기준으로 설정된 행간을 그대로 적용할 경우 줄 간격이 지나치게 좁아져 가독성이 급격히 저하됩니다.
oh-my-design의 생태계에서 핵심 차별점으로 주목받는 것은 바로 /hangul 스킬과 CJK 특화 CSS 처리 엔진입니다. 이는 서구권 중심의 프론트엔드 생성 도구들이 간과해 온 동아시아 특유의 프론트엔드 이슈를 해결하기 위한 구체적인 CSS 규칙과 라이팅 원칙을 내장하고 있습니다.
첫째, 단어 단위 줄바꿈과 음절 처리의 자동화입니다. 웹 브라우저의 기본 영문 줄바꿈 정책(word-break: normal)은 한글 문장에서 단어 중간에 어색하게 줄이 바뀌어 조사나 단어의 일부가 다음 줄로 넘어가는 문제를 일으킵니다. /hangul 스킬은 CJK 텍스트 컨테이너에 word-break: keep-all 및 overflow-wrap: break-word를 필수적으로 적용하여 단어의 의미 단위를 유지합니다. 또한 제목 및 주요 안내 문구에는 text-wrap: balance 또는 text-wrap: pretty 속성을 부여하여 뷰포트 너비 변화에 따른 텍스트 균형을 보정합니다.
둘째, 시각적 계층에 맞춘 자간(Letter-spacing)과 행간(Line-height) 보정입니다. 한글 폰트는 글자 크기가 커질수록 글자 사이의 여백이 시각적으로 벌어져 보이는 특성이 있습니다. 따라서 큰 제목(Heading) 영역에서는 미세한 음수 자간(letter-spacing: -0.02em 내외)을 주입하고, 본문 텍스트에서는 판독성을 높이기 위해 최소 1.5배 이상의 행간을 확보하도록 설계됩니다.
셋째, 실무 수준의 UX 라이팅과 다국어 폰트 스택 폴백(Fallback) 지정입니다. 버튼 레이블이나 알림 메시지에서 어색한 번역투 표현("성공적으로 완료되었습니다")을 배제하고, 국내 핀테크·커머스 실무에서 표준으로 자리 잡은 간결하고 명확한 어조("송금했어요", "확인")를 생성 단계에서 에이전트에 지시합니다. 시스템 폰트 스택 역시 Pretendard, SUIT, Apple SD Gothic Neo, Noto Sans CJK 등 현업에서 널리 검증된 CJK 폰트 패밀리를 우선 배치하도록 규칙화되어 있습니다.
4. 로컬 오프라인(Zero API Calls) 기반 아키텍처와 도구 연동
많은 개발자가 AI 에이전트 확장 도구를 도입할 때 가장 우려하는 지점은 추가적인 API 비용 발생, 외부 서버로의 소스 코드 유출 위험, 그리고 네트워크 레이턴시입니다. oh-my-design은 이러한 문제를 원천 차단하기 위해 철저한 로컬 우선(Local-First), 오프라인(Zero API Calls) 아키텍처를 채택했습니다.
oh-my-design은 별도의 외부 LLM 엔드포인트를 호출하지 않으며, 자체 클라우드 서버로 프로젝트 데이터를 전송하지 않습니다. CLI 도구인 oh-my-design-cli를 통해 프로젝트 내부에 정적 파일과 스킬 스크립트를 한 번 다운로드하면, 이후의 모든 추론과 컴포넌트 합성은 사용자가 실행 중인 AI 코딩 에이전트(Claude Code, Cursor 등) 내부 컨텍스트에서 순수 로컬로 완결됩니다.
4-1. 번들 스킬과 전문 서브 에이전트 체계
공식 문서에 명시된 바에 따르면, oh-my-design-cli는 단순한 템플릿 복사기를 넘어 프로젝트 내에 32개의 전체 번들 스킬과 20개의 전문 서브 에이전트를 함께 배치합니다. 사용자가 일일이 스킬의 내부 함수명을 외워 호출할 필요 없이, 자연어로 작업을 요청하면 에이전트가 작업의 성격에 맞는 하위 스킬을 스스로 판단하여 오케스트레이션합니다.
대표적인 내부 스킬인 omd-apply는 사용자가 특정 기업 레퍼런스를 지정했을 때 로컬 디렉터리(.claude/data/references/...)에 저장된 해당 기업의 DESIGN.md를 1초 이내에 읽어 들여 작업 컨텍스트에 마운트합니다. 예를 들어 랜딩 페이지에 소개된 실제 실행 로그를 살펴보면, Linear 스타일의 이슈 카드를 생성하는 작업에서 다음과 같은 단계적 실행이 확인됩니다.
- 1단계 (Thought): 요구사항 분석 및 적용할 디자인 시스템 파악 (약 1.0초)
- 2단계 (Skill
omd-apply): 내부 스킬 로드 및 환경 검증 (약 0.5초) - 3단계 (Read DESIGN.md):
.claude/data/references/linear.app/DESIGN.md파싱 (약 0.7초) - 4단계 (Write Component): 토큰 값이 반영된
IssueCard.tsx작성 (약 1.6초)
이 모든 과정이 외부 네트워크 왕복 없이 단 3.9초 만에 로컬에서 완료됩니다. 이처럼 가벼운 실행 구조 덕분에 네트워크 연결이 제한된 엔터프라이즈 사내 인프라나 보안 규제가 엄격한 금융권 프론트엔드 프로젝트에서도 보안 감사 저촉 없이 도입할 수 있습니다.
5. 실전 설치 및 oh-my-design-cli 적용 워크플로우
oh-my-design을 프로젝트에 도입하는 절차는 매우 직관적입니다. 별도의 글로벌 설치나 복잡한 환경 설정 없이 Node.js 런타임 환경에서 npx 명령어를 통해 최신 CLI를 단일 명령으로 실행할 수 있습니다.
프로젝트 루트 디렉터리에서 터미널을 열고 다음 명령어를 실행합니다.
npx oh-my-design-cli@latest
이 명령을 실행하면 CLI는 현재 작업 디렉터리를 스캔하여 설치되어 있는 AI 코딩 에이전트 환경(Claude Code 설정 폴더, Cursor 설정 파일, Codex, OpenCode 환경 등)을 자동으로 감지합니다. 이후 에이전트가 즉각 호출할 수 있는 스킬 인터페이스와 500개 이상의 품질 검증 기업 DESIGN.md 레퍼런스 데이터베이스를 프로젝트 로컬 경로에 구성합니다.
설치가 완료된 후 코딩 에이전트 세션(예: Claude Code 또는 Cursor Composer)에서 다음과 같이 직관적인 자연어 프롬프트를 입력하여 작업을 시작할 수 있습니다.
- 특정 기업 디자인 시스템 채택: "토스 스타일의 디자인 시스템을 프로젝트의 기본 규격으로 설정해 줘."
- 규격화된 컴포넌트 생성: "Linear 스타일의 이슈 트래커 카드를 TypeScript와 Tailwind CSS로 작성해 줘."
- 한글 타이포그래피 정밀 보정: "작성된 랜딩 페이지 본문의 타이포그래피를 /hangul 스킬 규칙에 맞춰 줄바꿈과 자간을 최적화해 줘."
에이전트는 백그라운드에서 omd-apply 스킬을 기동하여 로컬에 저장된 web/references/toss/DESIGN.md의 colors.canvas #ffffff, typography.h1 36 / 700 / 1.5, components.tds-button.radius 16px 등의 수치를 읽어 들인 후, 이 토큰 체계를 엄격히 준수한 컴포넌트 코드를 생성합니다.
6. 도입 시 고려할 기술적 제약과 운영 주의사항
oh-my-design이 제공하는 강력한 일관성에도 불구하고, 실제 프로덕션 환경에 적용할 때는 몇 가지 기술적 제약과 거버넌스 측면의 주의사항을 충분히 고려해야 합니다.
첫째, 기업 브랜드 아이덴티티의 모방과 저작권 리스크입니다. oh-my-design이 제공하는 수백 개의 DESIGN.md는 토스, 카카오뱅크, 라인 등 유수 기업들의 공개된 웹 인터페이스를 정밀 분석하여 토큰화한 레퍼런스 자료입니다. 개발 초기 프로토타이핑이나 내부 관리자 대시보드 구축 시에는 이러한 레퍼런스를 그대로 차용하여 극단적인 생산성을 얻을 수 있지만, 상용 대고객(B2C) 프로덕트를 출시할 때 특정 기업의 고유한 시각적 브랜딩(예: 토스 특유의 컴포넌트 형태나 색채 조합)을 그대로 복제하는 것은 브랜드 표절 논란을 불러올 수 있습니다. 따라서 실무 프로덕트에서는 레퍼런스 DESIGN.md를 베이스라인으로 삼되, 자사의 고유한 브랜드 컬러와 토큰으로 커스터마이징하여 단일 진실 공급원을 재정의하는 작업이 필수적입니다.
둘째, 레퍼런스 수치 표기에 대한 출처별 편차와 데이터 검증입니다. 수집된 소스 및 공개 문서에 따르면, 프로젝트 내의 디자인 레퍼런스 개수는 블로그 문서의 440개 이상, Threads 게시글의 521개, 공식 GitHub 저장소의 500+ 개, 공식 웹사이트의 597개 등 기록된 시점에 따라 수치적 차이가 존재합니다. 이는 프로젝트가 오픈소스로 활발히 업데이트되면서 지속적으로 레퍼런스가 추가되고 있음을 나타냅니다. 엔지니어링 팀은 프로젝트 도입 시 공식 저장소(github.com/kwakseongjae/oh-my-design)의 최신 릴리스 노트를 확인하고, 사용할 레퍼런스 토큰이 현재 타깃 프레임워크(Tailwind CSS v3 vs v4, CSS Modules 등)와 정확히 호환되는지 점검해야 합니다.
셋째, 프로젝트 규모에 따른 컨텍스트 윈도우 관리입니다. DESIGN.md 파일 자체는 경량화된 마크다운 구조로 설계되어 있으나, 수많은 컴포넌트 명세가 하나의 파일에 과도하게 축적될 경우 에이전트의 프롬프트 컨텍스트를 불필요하게 점유할 수 있습니다. 프로젝트가 거대해질수록 공통 토큰(색상, 타이포그래피)과 개별 도메인별 컴포넌트 토큰을 모듈화하여 관리하는 파이프라인 정비가 병행되어야 합니다.
7. 결론: AI 코딩 에이전트 시대를 지탱하는 디자인 엔지니어링
AI 코딩 에이전트의 발전은 단순히 코드를 생성하는 단계를 넘어, 생성된 결과물이 프로덕션 수준의 품질과 일관성을 유지할 수 있는가라는 시스템 엔지니어링의 영역으로 진화하고 있습니다. 프롬프트에 아무리 화려한 수식어를 덧붙여도 단일 진실 공급원(SSOT)이라는 명확한 구조적 규격이 부재하다면, AI가 생성하는 UI는 파편화된 코드의 집합체로 전락할 수밖에 없습니다.
oh-my-design은 이러한 프론트엔드 AI 파이프라인의 병목을 실무 기업들의 검증된 디자인 토큰과 경량 CLI 아키텍처로 정면 돌파한 프로젝트입니다. 특히 서구권 중심의 UI 생성 도구들이 해결하지 못했던 CJK 문자권의 타이포그래피 디테일과 UX 라이팅 규칙을 /hangul과 같은 전용 스킬셋으로 포섭해 낸 점은 동아시아 프론트엔드 생태계에 시사하는 바가 큽니다.
일관되지 않은 버튼과 폰트 크기 때문에 에이전트와의 프롬프트 씨름에 피로감을 느끼고 있는 개발자라면, npx oh-my-design-cli@latest 한 줄로 프로젝트에 명확한 디자인 규격을 부여해 보길 권합니다. AI 에이전트가 올바른 궤도 안에서 일관되고 견고한 컴포넌트를 조립해 나가는 진정한 프론트엔드 생산성 혁신을 경험할 수 있을 것입니다.
자주 묻는 질문
Q. oh-my-design을 사용하면 별도의 AI API 비용이 추가로 발생하나요?
A. 발생하지 않습니다. oh-my-design은 외부 LLM API를 자체 호출하지 않는 'Zero API Calls' 로컬 아키텍처로 작동합니다. CLI를 통해 레퍼런스 데이터와 스킬 스크립트를 로컬에 설치한 뒤, 현재 사용 중인 코딩 에이전트(Claude Code, Cursor 등) 내부 컨텍스트에서 오프라인으로 실행됩니다.
Q. 기존에 사용하던 Tailwind CSS 프로젝트에도 바로 도입할 수 있나요?
A. 네, 가능합니다. 프로젝트 루트에 설치되는 DESIGN.md의 토큰 체계는 Tailwind CSS의 테마 설정이나 CSS 변수와 자연스럽게 매핑될 수 있도록 설계되었습니다. 에이전트에 지시하여 DESIGN.md에 정의된 토큰을 tailwind.config 파일에 연동하도록 요청할 수도 있습니다.
Q. CJK 특화 기능인 /hangul 스킬은 어떤 역할을 수행하나요?
A. 라틴 알파벳과 글리프 구조가 다른 한글의 가독성을 보장하기 위해 단어 단위 줄바꿈(word-break: keep-all), 큰 글꼴 음수 자간, 본문 행간 확보(1.5 이상) 등의 CSS 규칙을 에이전트가 자동 적용하도록 강제합니다. 또한 자연스러운 한국어 UX 라이팅 스타일을 컴포넌트 텍스트에 반영합니다.



댓글 0개