AI에게 “토스처럼 깔끔하게”라고 말하면 첫 화면은 그럴듯해도, 두 번째 화면부터 버튼·간격·상태가 흔들리기 쉬워요. oh-my-design-cli가 흥미로운 이유는 디자인을 더 잘 생성한다고 약속해서가 아니라, 에이전트가 임의로 결정할 공간을 계약과 검증 단계로 줄인다는 데 있습니다.
22개 스킬의 본체는 ‘디자인 결정의 추적성’이에요
현재 공개 저장소 기준 oh-my-design-cli에는 22개 제품 스킬, 19개 전문 역할, 93개 프리셋 계약, 440개 이상의 품질 등급 레퍼런스가 들어 있습니다. Claude Code·Codex·OpenCode에는 전체 역할 묶음을 설치하고, Cursor에는 호환 가능한 21개 스킬을 설치하는 식으로 채널별 구성은 조금 달라요.
숫자만 보면 거대한 프롬프트 모음처럼 보이지만 구조는 다릅니다. 핵심 흐름은 철학 → 결정표 → 토큰 → 컴포넌트 계약 → 레이아웃 문법 → 구현 → 렌더링 검토예요. 예를 들어 “강조색은 주요 행동과 포커스 링에만 쓴다”는 원칙에 결정 ID를 붙이고, 실제 색상 토큰이 그 ID를 다시 참조하게 합니다. 근거 없는 색상값이 생기면 단순 취향 차이가 아니라 검증 실패로 다루는 방식이죠.
여기서 93개는 완성된 UI 컴포넌트를 복사해 오는 숫자가 아니라, 컴포넌트와 화면을 만들 때 지켜야 할 프리셋 계약의 수입니다. 기본 요소, shadcn/Radix 계열 프리미티브, 커머스·마켓플레이스 같은 화면 장르, 레퍼런스에서 파생한 성향으로 나뉩니다. 구조는 기존 컴포넌트 라이브러리에서 가져오더라도 색·간격·상태 같은 값은 프로젝트 결정표에서 채우도록 요구해요.
실무에서 중요한 구분
스킬은 “어떤 일을 어떤 순서로 할지”를 맡고, 전문 역할은 조사·접근성·카피처럼 좁은 관점의 근거를 제공합니다. 프리셋 계약은 구현 결과가 지켜야 할 조건이고, DESIGN.md는 그 조건이 왜 생겼는지 다음 세션까지 남기는 인수인계서에 가깝습니다.
프롬프트보다 계약이 강한 이유
프롬프트는 한 번의 결과를 유도하지만 계약은 다음 화면에서도 같은 결정을 재사용하게 합니다. 공식 워크플로우도 새 디자인 시스템 만들기, 새 화면 출시, 기존 화면 개선, 사용자의 취향 교정 기록을 서로 다른 작업으로 구분해요. “대시보드를 예쁘게”가 아니라 “동작은 보존하고 위계·밀도·모션·접근성을 점검한 뒤 영향이 큰 문제를 수정하라”처럼 목표와 보호 조건을 함께 전달하도록 권합니다.
| 구분 | 스타일 프롬프트 중심 | 계약 중심 워크플로우 |
|---|---|---|
| 색상·간격 | 모델이 화면마다 그럴듯한 값을 선택 | 결정 ID와 연결된 토큰을 재사용 |
| 컴포넌트 상태 | 기본 상태만 만들고 오류·로딩을 누락하기 쉬움 | 상태 행렬과 적용하지 않는 상태의 이유까지 기록 |
| 수정 기준 | “좀 더 세련되게” 같은 주관적 피드백 | 원칙·계약·동일 경로의 렌더링 증거로 판단 |
| 다음 세션 | 대화가 바뀌면 설명을 다시 전달 | 저장소의 DESIGN.md와 시스템 파일을 다시 읽음 |
| 모르는 값 | 평균적인 기본값으로 빈칸을 채움 | 미확정 값은 생략하고 중요한 결정만 질문 |
DESIGN.md Core v2는 이를 일곱 영역으로 정리합니다. 경험, 기반, 타이포그래피와 에셋, 컴포넌트와 상태, 레이아웃과 플랫폼, 콘텐츠와 로케일, 거버넌스예요. 특히 확인되지 않은 값을 그럴듯한 기본값으로 채우지 말고 비워 두도록 규정합니다. 디자인 문서를 “무드보드 설명서”가 아니라 사람과 에이전트가 함께 읽는 실행 계약으로 만든 셈이에요.
토큰을 도구 간에 교환할 수 있는 형태로 구조화한다는 방향은 oh-my-design만의 발상도 아닙니다. Design Tokens Community Group의 포맷 명세 역시 디자인 토큰을 여러 도구가 주고받을 수 있는 표준 파일 형식으로 표현해 통합 비용을 낮추는 것을 목표로 해요. oh-my-design은 여기에 값의 출처와 결정 이유, 컴포넌트 상태, 검증 절차를 더한 접근으로 볼 수 있습니다.
93개 계약이 있어도 품질이 자동 보장되지는 않아요
계약의 수보다 중요한 건 프로젝트에 맞는 계약을 골라 실제 화면에서 검사했는지입니다. 공식 안티 슬롭 문서도 둥근 카드나 보라색 포인트 하나를 문제라고 판정하지 않아요. 사용자·과업·기존 동작·DESIGN.md를 먼저 읽고, 맥락 없는 패턴이 여러 번 반복되며 위계나 신뢰를 해치는지 확인하라고 설명합니다.
접근성도 같은 원리예요. “접근성을 고려한다”는 문장만으로는 검사할 수 없지만, 일반 텍스트 명암비 4.5:1이나 키보드 포커스의 가시성처럼 관찰 가능한 조건은 테스트할 수 있습니다. WCAG 2.2는 텍스트 명암비뿐 아니라 포커스가 가려지지 않아야 한다는 기준도 포함합니다. 따라서 계약은 취향을 절대화하는 규칙이 아니라, 측정할 수 있는 품질과 프로젝트 고유의 선택을 구분하는 장치여야 해요.
벤치마크 숫자는 가설로 보세요.
프로젝트 변경 기록에는 동일한 픽스처와 브리프에서 첫 렌더 결함이 7개에서 3개로 줄고 입력 토큰이 47% 감소했다는 자체 측정이 있습니다. 다만 외부 독립 평가나 다양한 프로젝트 표본은 공개되지 않았어요. 도입 판단은 이 숫자보다 여러분 화면의 상태 누락, 접근성 오류, 디자인 드리프트가 실제로 줄었는지로 내려야 합니다.
국내 실사용 소개에서도 반복해서 등장하는 문제는 “첫 화면의 미감”보다 페이지가 늘어날수록 버튼 형태와 색상값이 달라지는 일관성 붕괴입니다. DESIGN.md를 프로젝트의 공통 기준으로 둔다는 접근은 이 문제와 잘 맞지만, “일관성 100%” 같은 표현은 검증된 보장으로 받아들이면 안 됩니다.
내 프로젝트에서 작게 검증하는 4단계
- 실제 프로젝트 루트에 설치하고 상태를 확인하세요.
npx oh-my-design-cli@latest를 실행한 뒤 에이전트를 재시작하고,npx oh-my-design-cli@latest doctor로 스킬·역할·카탈로그와 DESIGN.md 상태를 확인합니다. 공식 문서는 Node.js 18 이상을 최소 조건으로 안내해요. - 브랜드 이름보다 제품 과업을 먼저 적으세요.
“토스 스타일”에서 끝내지 말고 “바쁜 부모가 가족 식단을 빠르게 기록하는 앱, 기록 완료가 주 행동, 기존 로고와 데이터 흐름 보존”처럼 사용자·주 행동·보호할 동작을 명시하세요. 확인되지 않은 제품 사실은 쓰기 전에 질문하도록 요청합니다. - 화면 하나와 상태 네 종류로 시험하세요.
홈 전체를 갈아엎기보다 검색 결과나 결제 완료처럼 경계가 분명한 화면을 고릅니다. 기본·로딩·빈 상태·오류 상태를 만들고, 기존 컴포넌트 재사용 여부와 키보드 이동·명암비·모바일 리플로를 확인하세요. - 결과가 아니라 드리프트를 비교하세요.
두 번째 화면을 추가한 뒤 같은 토큰과 버튼 상태가 유지되는지 봅니다. DESIGN.md에 없는 값이 새로 생겼는지, 수정 이유가 결정 ID로 추적되는지, 같은 경로를 다시 렌더링했을 때 회귀가 없는지를 기록하세요. 이 세 항목이 줄지 않으면 스킬 수가 많아도 도입 효과는 낮습니다.
