첫 화면은 괜찮은데 다음 화면부터 다른 제품처럼 보인다면
AI 코딩 에이전트로 첫 화면을 만들 때는 꽤 그럴듯합니다. 문제는 설정, 결제, 검색 결과처럼 화면을 늘릴 때 생겨요. 같은 주요 버튼인데 색과 모서리가 달라지고, 로딩·오류 상태가 빠지며, 새 세션에서는 이전에 정한 간격까지 다시 설명해야 합니다.
이때 “토스처럼 깔끔하게” 같은 스타일 지시를 더 길게 쓰는 것만으로는 부족해요. 에이전트가 어떤 값을 왜 골랐는지 남기고, 다음 화면에서도 그 결정을 재사용하게 해야 합니다.
oh-my-design의 흥미로운 지점이 바로 여기에 있습니다. 핵심은 많은 스킬을 설치하는 게 아니라 디자인 철학을 결정 ID, 토큰, 컴포넌트 상태와 렌더링 검토까지 연결하는 것입니다. 그 결과를 DESIGN.md에 남겨 다음 작업의 출발점으로 삼고요.
지금 해볼 것: 화면 하나에 공통 기준 만들기
처음부터 제품 전체를 다시 만들 필요는 없습니다. 기존 동작을 보존해야 하는 화면 하나를 골라 설치, 계약 제안, 승인, 화면 검증까지 한 번 연결해보세요. 아래 절차는 공개 문서를 바탕으로 정리했으며, 편집부가 CLI를 직접 실행해 확인한 결과는 아닙니다.
- 프로젝트 루트에서 설치를 시작합니다.
Node.js 18 이상과 Git 저장소, 설치·인증된 Claude Code·Codex·OpenCode·Cursor 중 하나를 준비하세요.npx oh-my-design-cli@latest를 실행해 기본 프로젝트 설치 범위를 선택합니다. 별도 API 키나 MCP 서버는 핵심 로컬 워크플로우에 필요하지 않습니다. - 에이전트를 완전히 재시작하고 설치 상태를 검사합니다.
Codex에서는 프로젝트를 신뢰해야 프로젝트 로컬 역할이 로드됩니다. 재시작한 뒤 같은 루트에서npx oh-my-design-cli@latest doctor를 실행해 스킬·에이전트·카탈로그·DESIGN.md 관련 누락이 없는지 확인하세요. - 사용자와 보호 조건이 담긴 첫 요청을 입력합니다.
예를 들어 “바쁜 부모가 가족 식단을 기록하는 앱의 프로젝트 소유 DESIGN.md를 제안해 주세요. Toss는 참고 자료로만 사용하고 검증된 사실만 유지하세요. 제품 고유 사실은 결정하기 전에 질문하고, 기존 동작과 로고는 보존하세요. 승인 전에는 DESIGN.md를 채택하지 마세요”라고 요청할 수 있습니다. - 제안 파일을 소유자가 직접 승인합니다.
그래프에 결합된 DESIGN.md를 채택하려면 프로젝트 소유자나 미리 등록된 외부 권한 통제자가 제안된 정확한 바이트를 검토하고 승인해야 합니다. 생성하거나 구현한 에이전트가 스스로 승인할 수는 없습니다. - 경계가 분명한 화면 하나를 개선합니다.
채택된 DESIGN.md를 먼저 읽게 한 뒤 “기존 검색 동작과 로고는 유지하고 검색 결과 화면의 위계와 상태를 개선해 주세요”처럼 요청하세요. 성공 기준은 화면이 화려해지는 것이 아닙니다. 기존 동작이 유지되고, 눈에 보이는 변경과 검증 요약이 나오며, 새 토큰과 상태가 DESIGN.md의 결정에 연결되는지 확인하면 됩니다.
승인 절차의 적용 범위를 구분하세요.
독립형 DESIGN.md를 참고 문서처럼 읽는 데까지 전체 채택 패키지가 필요한 것은 아닙니다. 다만 manifest와 해시로 결합된 그래프가 현재 프로젝트의 권위 있는 기준이라고 주장하려면 소유자 승인과 채택 경계를 지켜야 합니다. Core v2 자체도 현재 초안 상호운용 계약으로 표시돼 있습니다.
93개는 UI 템플릿 수가 아니라 검사할 계약 수예요
oh-my-design의 93개 프리셋 계약은 완성된 화면 93개를 복사해 오는 라이브러리가 아닙니다. 기본 요소, shadcn·Radix 계열 매핑 프리미티브, 커머스·마켓플레이스 같은 화면 장르, 레퍼런스에서 파생한 성향의 네 층으로 구성됩니다. 각 컴포넌트 계약은 구조, 상태 행렬, 접근성 조건과 토큰 슬롯을 정의합니다.
따라서 프로젝트에 93개를 모두 적용할 이유도 없어요. 검색 화면이라면 입력창, 버튼, 결과 목록, 빈 상태, 오류 상태처럼 실제로 사용하는 요소의 계약만 고르면 됩니다. 계약의 가치는 개수가 아니라 적용할 상태와 적용하지 않을 상태의 이유까지 남기는 데 있습니다.
| 작업 장면 | 스타일 지시만 있을 때 | 계약이 연결됐을 때 |
|---|---|---|
| 강조색 추가 | 화면마다 그럴듯한 색을 선택 | 결정 ID를 참조하는 토큰 사용 |
| 입력창 구현 | 기본 상태만 만들기 쉬움 | 포커스·오류·비활성 등 상태 행렬 확인 |
| 두 번째 화면 제작 | 이전 대화의 스타일을 다시 설명 | DESIGN.md와 기존 계약을 먼저 읽음 |
| 디자인 수정 | “더 세련되게” 같은 감상으로 판단 | 결정표와 같은 경로의 렌더링 결과로 비교 |
공식 구조는 철학에서 출발해 결정표, 토큰, 컴포넌트 계약, 레이아웃 문법, 구현, 렌더링 비평, DESIGN.md로 이어집니다. 토큰이나 컴포넌트 값이 자신을 만든 결정표를 참조하지 않거나, 선언한 원칙이 어떤 토큰에도 영향을 주지 않으면 품질 게이트에서 실패로 분류할 수 있습니다.
스킬 숫자가 달라도 유지되는 본체
기존에 알려진 22개 스킬과 19개 역할은 현재 규모가 아닙니다. 최신 공식 Skills 페이지는 27개 제품 스킬과 20개 전문 에이전트를 안내하고, 저장소 README는 채널 전용 항목까지 포함한 전체 번들을 28개 스킬과 20개 역할로 집계합니다.
이 차이는 문서가 서로 다른 범위를 세고 있기 때문에 생깁니다. Cursor 설치 수 역시 README 안의 표기가 일치하지 않아 단일 숫자로 단정하기 어렵습니다. 그래서 도입할 때는 “스킬이 몇 개인가”보다 내 에이전트와 프로젝트에 어떤 파일이 실제로 설치됐는지를 doctor 결과로 확인하는 편이 정확합니다.
스킬은 시스템 생성, 화면 작업, 검토 같은 작업 순서를 맡고, 전문 에이전트는 접근성·콘텐츠처럼 좁은 관점에서 근거를 보탭니다. 프리셋 계약은 구현 결과가 지켜야 할 조건이며, DESIGN.md는 그 조건과 결정 이유를 다음 세션에 전달합니다. 숫자가 바뀌어도 이 역할 구분이 제품의 본체예요.
계약은 취향이 아니라 관찰 가능한 조건이어야 해요
“접근성을 고려한다”는 문장은 좋은 의도지만 통과 여부를 판정하기 어렵습니다. 반면 일반 텍스트 명암비 4.5:1, 텍스트를 200% 확대해도 콘텐츠와 기능이 유지되는지, 키보드 포커스가 보이고 다른 콘텐츠에 완전히 가려지지 않는지는 검사할 수 있습니다. WCAG 2.2는 이런 조건을 구체적으로 정의합니다.
물론 계약에 조건을 적었다고 실제 구현의 WCAG 적합성이 자동으로 증명되는 것은 아닙니다. 로고·큰 글자·비활성 콘텐츠처럼 명암비 기준이 달라지는 예외도 있어요. 그래서 계약은 프로젝트의 선택을 고정하는 문서이면서, 렌더링한 결과를 사람이 검토할 체크리스트여야 합니다.
두 번째 화면에서 효과를 판단하세요.
첫 화면의 미감 대신 다음 화면에서 같은 버튼 토큰이 유지되는지, 로딩·빈 상태·오류 상태가 빠지지 않았는지, DESIGN.md에 없는 값이 임의로 추가됐는지를 비교하세요. 세 항목의 드리프트가 줄어야 계약을 만든 비용이 의미를 갖습니다.
7→3과 47%는 가능성이지 보증이 아닙니다
공식 변경 기록에는 같은 픽스처와 브리프에서 첫 렌더 결함이 7개에서 3개로 줄었고 입력 토큰은 47% 감소했다는 자체 측정이 있습니다. 심각도가 높은 P0·P1 결함은 두 조건 모두 0건이었다고 기록돼 있습니다.
다만 표본 수, 실행 반복 횟수, 사용 모델, 통계적 불확실성과 외부 독립 평가는 공개되지 않았습니다. 모든 프로젝트의 품질이나 비용이 그만큼 개선된다는 근거로 쓰기는 어려워요. 내 프로젝트에서는 첫 렌더의 결함 수보다 상태 누락, 새로 생긴 임의 값, 기존 동작 회귀가 다음 화면에서 줄었는지 확인하는 편이 실용적입니다.
