디자인팀 × 프론트팀 — 첫 팀 크로스 하네스, 금성과 화성을 잇다
1편은 문서의 정원을, 3편은 기획의 정원을 다뤘습니다. 이번엔 제 차례입니다 — 디자인팀과 프론트엔드팀. 따로 일하던 두 팀이 하나의 하네스 위에서 만난 이야기를, 그 일을 직접 한 제가 적습니다.
저는 블룸AI 디자인팀의 제나입니다. 사내에 「AI가 이해하는 디자인 시스템 구축기」라는 1인칭 기록을 남겼는데, 이 글은 그 기록을 블룸AI 하네스 시리즈 에 맞춰 제가 다시 정리한 네 번째 편입니다. 3편이 기획 단계의 언어와 경계를 다뤘다면, 이번 편은 그 언어가 화면(UI)으로 번역되는 계층 — 디자인과 프론트엔드 — 으로 내려옵니다.
제가 이 글에서 말을 걸고 싶은 분은 기획의 의도를 가장 먼저 받아 해석해야 하는 사람들입니다 — UI/UX(User Interface · User Experience, 사용자 인터페이스 · 사용자 경험) 디자이너 · 프론트엔드 개발자 · 디자인 리드, 그리고 AI(Artificial Intelligence, 인공지능) 코딩 도구를 제품에 붙이려다 "생각보다 안 되는데…" 를 겪어 본 모든 분입니다.
솔직히 처음엔 제가 그냥 디자인 규칙서 하나를 만들었다고 생각했습니다. 그런데 이 시리즈를 읽고 나서야 깨달았습니다 — 제가 만든 것이 사실은 디자인팀과 프론트팀이 함께 쓰는 첫 번째 하네스였다는 걸요. 그래서 이 글에서는 제 여정을 그대로 들려드리되, 곳곳에서 하네스의 눈으로 다시 보면 그게 무엇이었는지 를 제가 직접 짚어 보겠습니다.
1. 금성에서 온 디자이너, 화성에서 온 개발자 — 그리고 끼어든 제3의 외계인
제 이야기는 한 장면에서 출발합니다.
저는 디자이너입니다. 그래서 화면을 볼 때 가장 먼저 의도와 위계를 봅니다. 같은 회색이라도 "위에 뭐가 얹히느냐"에 따라 다른 회색이어야 한다고 생각합니다. 한 화면에 버튼이 세 개라면 그중 하나만 주인공이어야 한다고 믿습니다.
제 옆에는 늘 개발자가 있습니다. 같은 화면을 보지만, 개발자가 보는 것은 값과 클래스입니다. 제가 "여기 카드는 플랫로 가고, 배경은 bg-subtle이 자연스럽겠어요. radius는 안쪽이 바깥보다 작아야 해요" 라고 말하면, 개발자는 이렇게 되묻습니다.
"네, 그런데
bg-subtle이 정확히 몇 번째 gray인가요? radius 규칙은 어디에 적혀 있죠?"
둘 다 틀리지 않았습니다. 다만 같은 언어를 쓰지 않았을 뿐입니다. 저는 의도의 언어를, 개발자는 값의 언어를 씁니다. 같은 화면을 가리키며 서로 다른 문장을 말합니다.
그리고 어느 순간부터, 이 대화에 세 번째 존재가 끼어들었습니다 — AI입니다. AI는 저보다 빠르고 개발자보다 부지런하지만, 두 사람의 어휘를 둘 다 어설프게 흉내 냅니다. 결과는 예상대로였습니다. 매번 비슷해 보이지만, 매번 미묘하게 어긋난 UI.
| 화자 | 같은 화면에서 보는 것 | 쓰는 언어 |
|---|---|---|
| 🎨 디자이너 (금성) | 의도 · 위계 | "플랫 카드, bg-subtle" |
| ⚙️ 개발자 (화성) | 값 · 클래스 | "몇 번째 gray? 규칙은 어디?" |
| 🤖 AI (제3의 외계인) | 웹의 평균값 | "비슷하지만 매번 다름" |
여기서 저는 한 가지를 깨달았습니다.
문제는 디자이너와 개발자의 사이가 아니었습니다. 세 사람(디자이너·개발자·AI)이 공유할 "공용 언어"가 없다는 것이 문제였습니다.
나중에 이 시리즈의 3편을 읽고서야, 제 진단이 에반스의 유비쿼터스 언어(Ubiquitous Language) — 같은 단어로 같은 개념을 칭하는 공통 어휘 — 와 정확히 같은 뼈대였다는 걸 알았습니다 (3편 §4.3 참고). 3편이 기획자와 개발자 사이의 언어를 다뤘다면, 제 자리는 디자이너와 개발자, 그리고 AI 사이의 언어였습니다. 계층만 바뀌었을 뿐, 문제의 형태는 똑같았습니다.
2. 문제는 사람이 아니라 기준의 부재
기준이 없을 때 어떤 일이 벌어지는지, 저는 오래 겪었습니다.
- 저는 매번 같은 설명을 반복했습니다 — "이 카드는 강조, 저 카드는 플랫이에요."
- 개발자는 매번 되물었습니다 — "저번 화면과 다르다고요? 어떻게 다른가요?"
- AI는 매번 그럴듯하게 다른 화면을 만들었습니다.
같은 요청 "카드 UI 만들어줘" 가 어떤 날은 rounded-lg + shadow 로, 어떤 날은 rounded-md + border 로, 또 어떤 날은 rounded-[12px] + bg-gray-50 으로 나왔습니다. 진짜 문제는 "가이드 문서가 없어서" 가 아니었습니다.
진짜 문제는, 판단 주체가 매번 달라진다는 점이었습니다. 어떤 날은 제가, 어떤 날은 PM이, 어떤 날은 AI가 그 자리에서 결정합니다. 결정의 근거는 그날의 분위기와, 옆 화면의 기억과, 가장 최근에 본 피그마 파일입니다.
그래서 저는 문제를 두 개의 질문으로 쪼갰습니다.
| 질문 | 무엇인가 | 기존 디자인 시스템 문서 | AI에게 주는 효과 |
|---|---|---|---|
| ① 무엇을 쓸 수 있는가 | 재료 목록 (토큰, 컴포넌트, variant) | ✅ 대부분 담고 있음 | 재료만 주면 매번 다른 요리를 함 |
| ② 언제 무엇을 우선하는가 | 판단 기준 (결정 트리, 금지 규칙, 예외) | ❌ 대부분 비어 있음 | 이게 없어서 환각이 발생 |
기존의 디자인 시스템 문서는 대부분 ①번까지만 담고 있었습니다. 피그마 변수 테이블, 스토리북 컴포넌트 목록, 토큰 JSON. 그런데 AI에게 재료만 건네주면, AI는 매번 다른 요리를 합니다. ②번이 없기 때문입니다.
사람들 사이에서도 이건 갈등의 원인이지만, AI가 끼어드는 순간 갈등은 배율로 증폭됩니다. 하루에 수십 개의 화면을 만드는 AI가, 매 화면마다 자기 나름의 판단을 내리기 때문입니다.
이 시리즈의 1편을 읽은 분이라면 익숙한 그림자가 보일 겁니다. 1편의 정원에서 knowledge(햇빛) 가 비어 있으면 "무엇이 올바른지 판단하는 기준" 이 없어 꽃이 잘못된 방향으로 자란다고 했습니다 (1편 참고). 제 ②번 — 판단 기준 — 이 바로 그 햇빛이었습니다. 디자인 계층에도 햇빛이 필요했던 것이죠. 물론 이 비유는 한참 뒤에야 손에 잡혔습니다. 그때의 저는 그저 "왜 매번 다르지" 가 답답했을 뿐입니다.
3. 잠깐의 우회 — "목업은 정말 느릴까?"
해결책으로 가기 전에, 저는 한 번 옆길로 샜습니다. 혹시 Shape Up의 Breadboarding 과 Fat Marker Sketch 를 들어 본 적 있으신가요?
"목업은 느리다" 는 말은 꽤 자주 들립니다. 디자이너가 목업을 만드는 데 이틀이 걸리고, 그 사이 개발은 기다리고, 기획은 다시 수정되고, 목업도 다시 그려야 하고… 이 루프가 답답했던 Basecamp 팀은 와이어프레임조차 만들지 않는 방법을 고안했습니다 (Basecamp, Shape Up — Find the Elements).
| 기법 | 무엇인가 | 의도 |
|---|---|---|
| Breadboarding | 화면 요소만 글자로 나열 — 장소(Places)·행동 가능 요소(Affordances)·연결선 세 가지만 그린다 | 시각 디자인을 생략하고 구조만 합의 |
| Fat Marker Sketch | 두꺼운 매직펜으로만 그려 세부를 물리적으로 불가능하게 만든 초저해상도 스케치 | 2D 배치만 다루고, 해석의 여지를 남김 |
저는 이 접근에 반은 동의하고, 반은 동의하지 않습니다.
- 동의하는 쪽: Breadboarding은 의사소통 도구로서 강력합니다. 와이어프레임보다 단순하고, 가장 필수적인 요소만 다룹니다. 서로의 머릿속을 동기화하는 데 좋습니다.
- 동의하지 않는 쪽: 현실에서 "완벽한 자율권 이양" 은 잘 작동하지 않았습니다. 디자인과 개발은 계속 조율이 필요하고, Breadboarding이 화면 요소를 확정해 버리는 순간 디자인은 경직됩니다. 정해진 부품으로 조립되는 SaaS(Software as a Service, 서비스형 소프트웨어)엔 괜찮지만, 디자인이 곧 기획인 제품(게임, 감성 앱, AI 어시스턴트)엔 맞지 않았습니다.
그런데 AI가 등장하면서 이 논쟁이 달라졌습니다
Shape Up이 Breadboarding을 고안한 이유는 "목업이 느리니까" 였습니다. 그런데 지금은, AI가 목업 수준의 화면을 초 단위로 만들어 냅니다. "피그마 → 개발 → 검증" 에 사흘이 걸리던 루프가, AI 코딩 도구에서는 대화 한 번입니다.
그렇다면 초저해상도 표현 단계는 건너뛰어도 될까요? 저는 직접 해봤습니다. Figma Make, Cursor, Claude Code, Codex, Gemini — 도구를 바꿔 가며 "머릿속 화면"을 곧바로 뽑아내려 했습니다. 결과는 이상했습니다.
속도는 100배 빨라졌는데, 결과물은 매번 달랐습니다. Breadboarding이 해결해 주던 "해석의 여지를 남기되 요소를 공유한다"는 장점이 사라진 것입니다. AI는 해석의 여지를 새 요소를 창작할 기회로 받아들였습니다.
여기서 저는 결정적인 방향 전환을 했습니다.
목업이 느려서가 아니라, 모두가 같은 규칙을 보고 있어야 자율권이 작동하는구나. 그 규칙이 사람끼리도, 사람과 AI 사이에도, AI와 AI 사이에도 같아야 하는구나.
그래서 저는 "Breadboarding을 AI 입력 포맷으로 만들기" 가 아니라, "AI가 읽을 수 있는 디자인 규칙 체계를 만들기" 로 방향을 잡았습니다. 속도는 AI가 담당하고, 판단의 일관성은 사람이 미리 규정해 두는 방식입니다.
이 문장을 — 나중에 배운 — 하네스의 언어로 옮기면 이렇게 됩니다. 물길(engine)은 AI에게 맡기되, 햇빛(knowledge)은 사람이 채운다.
4. 세계는 이미 같은 고민을 하고 있었다
바깥을 살펴보니, 같은 고민을 하는 사람이 이미 전 세계에 많았습니다.
4-1. "문제는 Cursor가 아니라, 당신의 디자인 토큰"
Sachin Patel은 2026년 1월에 이렇게 썼습니다.
"Cursor가 엉망인 UI 코드를 뱉는다고? Cursor가 문제가 아니다. 문제는 당신의 디자인 토큰이다. 모든 색은 환각이고, 모든 간격은 지어낸 값이다." — Sachin Patel, Cursor Isn't the Problem. Your Design Tokens Are (Medium, 2026-01)
저도 같은 것을 느꼈습니다. color-primary-500, blue-500, brand/primary, #3B82F6 — 같은 색을 가리키는 네 가지 이름. 이 중 무엇을 써야 할지 AI는 매번 주사위를 굴립니다. Patel의 핵심 처방은 프론트엔드 CSS 변수를 디자인 토큰과 1:1로 정렬하는 것이었습니다 — 저는 여기서 이미 디자인과 프론트의 경계가 만나야 한다는 신호를 봤습니다.
4-2. "디자인 시스템은 이제 AI가 참조하는 데이터셋이다"
디자인 시스템의 독자가 바뀌고 있다는 통찰도 도처에 있었습니다. Romina Kavcic와 Into Design Systems 진영은 이를 에이전틱 디자인 시스템(agentic design system) 이라 부릅니다 — AI 에이전트가 자율적으로 읽고, 추론하고, 빌드할 수 있는 인프라. 디자인 시스템을 피그마 라이브러리보다 CI/CD 파이프라인이나 데이터베이스에 가깝게 다루자는 것입니다 (Into Design Systems, Agentic Design Systems).
디자이너는 이미 머릿속에 시스템을 넣고 있습니다. 그런데 진짜 독자는 AI고, AI가 읽을 수 있는 형태로 다시 정리해야 했습니다.
4-3. Spec · 닫힌 토큰 레이어 · 자동 감사
Hardik Pandya는 AI 친화 디자인 시스템을 세 층으로 정리했습니다 (Hardik Pandya, Expose Your Design System to LLMs).
| 층 | 역할 | 하네스 대응 |
|---|---|---|
| Spec 파일 | LLM이 읽을 사람 언어의 규칙서 | 햇빛 (knowledge) |
| 닫힌 토큰 레이어 | AI가 값을 지어내지 못하도록 고정한 토큰 집합 | 햇빛의 가장 단단한 핵 |
| 자동 감사 | 규칙을 어긴 코드를 CI(Continuous Integration, 지속적 통합)에서 걸러내는 린터 | 물길 (engine) — 검수 단계 |
제가 보기에 가장 중요한 단어는 "닫힌(closed)" 이었습니다.
AI에게 "색을 자유롭게 골라봐" 라고 하면 반드시 새로운 색을 만듭니다. "이 37개 토큰 중에서만 골라" 라고 하면, 그제야 일관된 선택을 시작합니다. 선택지를 늘리는 게 아니라 줄이는 것이 AI를 길들이는 기본기였습니다.
이건 3편에서 본 데밍·에반스 현자의 사상과도 통합니다. 자유도를 좁히는 것이 일관성을 만든다 — 닫힌 토큰 레이어는 디자인 계층의 경계된 컨텍스트인 셈입니다.
4-4. 큰 시스템들도 같은 방향으로 움직였다
- IBM Carbon은 2025년 "Carbon for AI" 가이드라인을 별도 섹션으로 분리했습니다 (Carbon Design System — Carbon for AI).
- Oleksandra Huba는 "Dear LLM, here's how my design system works" 에서, AI가 신뢰할 수 있는 코드를 만들려면 디자인 시스템이 자기 의도를 스스로 설명할 수 있어야 한다고 정리했습니다 (UX Collective, 2025-11).
공통점은 하나였습니다 — AI가 시스템을 해석하는 비용을 낮추는 방향. 흐름은 분명했습니다. "예쁜 피그마 파일" 에서 "기계가 읽을 수 있는 규칙 체계" 로.
5. 규칙서는 사실 하네스였다 — Deskit UI 제작 AI 규칙서
외부 사례는 방향만 보여 줬을 뿐, 블룸 제품에 그대로 붙일 답은 없었습니다. 블룸에는 블룸만의 제약과, Sort UI 라는 자신만의 디자인 언어가 있었기 때문입니다. 그렇게 만든 것이 Deskit UI 제작 AI 규칙서입니다.
여기서 저는 시점을 한 번 비틀어 보겠습니다. 저는 그냥 디자인 규칙서를 만들었다고 생각했는데, 나중에 하네스의 눈으로 다시 보니 제가 만든 건 디자인 계층의 하네스였습니다. 1편의 정원과 한 줄씩 대응시켜 보면 이렇습니다.
| 하네스 3층 | 1편 문서 정원 | 나의 디자인 하네스 (Deskit UI 규칙서) |
|---|---|---|
| ☀️ 햇빛 (knowledge) | doc-clarity-principles 등 | §0~§8 규칙서 — 닫힌 토큰, 결정 트리, 금지 패턴 |
| 🌱 영양분 (agents) | doc-reviewer·style-enforcer 등 검수자 | AI(실행자) + §6 금지 패턴 / §7 체크리스트(검수자) |
| 💧 물길 (engine) | full-review·publication-pipeline | 판단 순서 고정(8단계 결정 트리) + 자동/질문 분기 |
제 규칙서는 9개 섹션으로 구성됩니다.
| 섹션 | 내용 |
|---|---|
| §0 목적·전제·우선순위 | AI가 매 결정마다 가장 먼저 확인할 판단 순서 |
| §1 절대 규칙 | 컴포넌트·색상·타이포·radius·Primary의 바꿀 수 없는 제약 |
| §2 UI 제작 결정 트리 | 배경색/텍스트색/보더/radius/카드/중첩/리스트 판단 순서 |
| §3 영역별 규칙 | 레이아웃·타이포·간격·인터랙션·모달·툴팁의 실행 규정 |
| §4 허용되는 예외 | 하드코딩이 허용되는 유일한 "단일 진실 원본" |
| §5 사용자에게 물어야 하는 경우 | AI 임의 판단 금지, 사람에게 물어볼 기준 |
| §6 금지 패턴 | AI가 웹 관습으로 만들어 내는 잘못된 스타일 차단 |
| §7 빠른 체크리스트 | 작업 직후 스스로 검증 |
| §8 UI 케이스 레퍼런스 | 리스트·설정·대시보드·빈 상태·모달의 실전 샘플 갤러리 |
규칙서의 목표는 처음부터 분명했습니다 — 100%가 아닙니다.
Human Designer의 70% 수준을 AI가 신속하게 만들어 냅니다. 나머지 30%는 사람이 튜닝합니다.
AI를 신격화하지도, 배제하지도 않는 실용적 합의입니다. 100%를 추구하면 규칙이 무한히 복잡해지고, 결국 사람도 AI도 그 규칙을 못 지킵니다. 이 70/30 선은 뒤에서 두 팀의 분업을 가르는 기준선이 됩니다.
5-1. 제가 특히 공들인 다섯 가지 원칙
규칙서의 정수는 다섯 원칙에 있습니다. 이 원칙들은 그대로 하네스의 검수 규칙으로 읽힙니다.
원칙 1 — 판단 순서를 고정한다 (물길)
AI가 매 결정마다 네 단계를 순서대로 밟게 만들었습니다.
- DS(Design System, 디자인 시스템) 컴포넌트 사용 가능 여부 — 이미 있으면 쓴다
- 색상은 "영역 판단" 이 먼저 — 앱 레이아웃 영역인지, 일반 surface인지 분류
- 기존 파일·주변 코드 패턴 유지 — 튀지 않는 것이 기본
- 특수 케이스에 한해 하드코딩 허용 — 허용 목록은 §4가 유일한 출처
배경색 하나를 정하는 데에도 8단계 결정 트리를 뒀습니다 — bg-app-* → bg-default → bg-subtle → bg-muted → bg-overlay → bg-inverted → bg-state-disabled → 예외. AI는 위에서부터 내려가다 조건이 맞으면 멈춥니다.
판단의 자유도를 줄이는 것 — 이것이 제가 가장 힘을 준 설계였습니다. 같은 프롬프트를 두 번 줬을 때 같은 결과가 나오는 것, 그게 일관성입니다.
원칙 2 — 금지 패턴을 명시한다 (검수자)
AI는 Tailwind 예제를 정말 많이 학습했습니다. 그래서 가만히 두면 이런 한 줄을 툭 내놓습니다.
className="bg-gray-100 text-sm rounded-md transition-all"
눈으로 보면 멀쩡합니다. 그런데 이 한 줄은 블룸 디자인 시스템의 네 규칙을 동시에 위반합니다.
| 위반 조각 | 왜 금지인가 |
|---|---|
bg-gray-100 | 회색 하드코딩 금지 — 회색은 언제나 DS 토큰 |
text-sm | size-* 만 사용 |
transition-all | 변경되는 속성만 명시 |
rounded-md | 토큰화된 radius가 아니면 의심 대상 |
제가 금지 패턴 섹션을 길게 쓴 데는 이유가 있습니다.
허용 규칙은 선택지입니다. AI는 선택지 사이에서 방황합니다. 금지 규칙은 탈락 조건입니다. AI의 후보 풀을 즉시 잘라냅니다.
훈련 데이터에 bg-gray-100 이 수만 번 등장했어도, "금지" 라고 명시해 두면 AI는 그것만은 피합니다. 금지 규칙은 생성 마지막 단계에서 작동하는, 가장 강한 필터입니다. — 나중에 보니 이것이 정확히 하네스의 검수자(agents) 가 하는 일이었습니다. style-enforcer가 표기를, terminology-keeper가 용어를 탈락 조건으로 거르듯, 제 §6 금지 패턴이 잘못된 스타일을 탈락시킵니다.
원칙 3 — 중첩 컨테이너의 위계를 지킨다
카드 안에 카드를 넣을 때, 안쪽이 바깥보다 시각적으로 튀면 위계가 역전됩니다. 저는 이를 구분 강도의 순서로 명문화했습니다.
없음 <
bg차이 <border<shadow
그리고 절대 규칙 하나 — 바깥이 안쪽보다 같거나 강한 구분 스타일을 가져야 한다.
| 판정 | 바깥 | 안쪽 | 결과 |
|---|---|---|---|
| ✅ | shadow-card | border-default | 정상 — 바깥이 더 강함 |
| ✅ | border-default | border-default | 동일 — 허용 |
| ❌ | bg-subtle | shadow-card | 위계 역전 |
여기에 radius 위계도 붙였습니다 — 안쪽 R값은 반드시 바깥 R값보다 작아야 한다. 제가 배운 요령 하나를 공유합니다.
"중첩하지 마" 라고 말하면 AI는 중첩이 필요한 상황에서 얼어붙습니다. 대신 "이런 중첩은 되고, 저런 중첩은 안 된다" 고 양수/음수 예시를 쌍으로 주면 AI가 그 사이의 판단 공간을 알아서 찾아냅니다.
원칙 4 — Primary 색상은 "희소 자원"이다
AI가 두 번째로 많이 깨뜨리는 규칙은 Primary 남용입니다. "이 버튼 중요해 보이게" 라고 하면 AI는 무조건 primary를 씁니다. 그래서 한 화면에 primary 버튼이 다섯 개씩 등장합니다. 다섯 개가 다 primary면, 결국 하나도 primary가 아닙니다.
저는 이를 희소 자원 원칙으로 풀었습니다.
- 1개 컨테이너(카드/패널/섹션)당 primary 요소는 최대 1개
- 반복 구조(리스트 행, 카드 그리드, 테이블 셀)에는 primary를 기본 적용하지 않는다
- 같은 중요도의 액션이 여러 개면 secondary나 soft를 쓴다
이것은 단순 금지가 아니라 경제학적 모델입니다. Primary는 무한 자원이 아니라, 한 컨테이너당 하나씩 할당되는 희소 자원. AI가 이 개념을 받아들이면, 화면 전체의 정보 위계가 자동으로 정돈됩니다.
원칙 5 — 자동 판단하되, 모호할 때만 사람에게 묻는다
실전에서 가장 까다로운 원칙입니다. "모르면 물어봐" 를 잘못 가르치면 AI는 매번 묻습니다. "절대 묻지 마" 라고 하면 확신 없는 답을 자신 있게 내놓습니다. 저는 이 비대칭을 두 리스트로 나눴습니다.
| 🤔 물어볼 수 있는 것 (양쪽 다 정답일 때) | 🙅 절대 묻지 말 것 (기본값 사용) |
|---|---|
| 카드 유형(강조 vs 플랫) | 일반 텍스트 크기 |
| Drawer·특수 팝업의 노출 위치·방향 | 일반 radius 값 |
| Gap/Gapless 리스트 (밀도 의도가 양쪽 다 자연스러울 때) | hover/transition 방식 |
| 상태색이 장식인지 의미 전달인지 애매할 때 | 툴팁 기본 placement/delay |
핵심 통찰: 묻는 비용과 묻지 않는 비용은 비대칭입니다. 사람의 의도가 필요한 것만 묻고, 규칙서에 답이 있는 것은 묻지 않습니다. AI가 "과하게 묻거나 못 묻는" 양극단 실패를, 문서가 대신 방지합니다.
3편을 떠올리면 이 원칙은 sage-evans의 "기획자가 스키마·API를 지시하지 않는다 — 그 아래층은 위임" 과 데밍의 "없는 것은 없다고 명시" 가 디자인 계층에서 재현된 것입니다. 모호함을 추정으로 메우지 않는다.
5-2. AI가 자주 하는 실수 — 나의 "실전 지도"
규칙서를 만들며 제가 얻은 가장 값진 것은, AI가 어디서 어떻게 실수하는지의 지도였습니다.
| # | 실수 | 원인 |
|---|---|---|
| 1 | 회색 환각 (bg-gray-50, text-gray-600) | Tailwind 문서에서 가장 자주 본 패턴 |
| 2 | Tailwind 폰트 사이즈 (text-sm) | DS가 size-* 로 재정의한 걸 모름 |
| 3 | 임의 radius (rounded-[12px]) | 디자이너의 "12px"를 그대로 받아들임 |
| 4 | transition-all 남용 | 웹 관습에 가장 가까운 방식 |
| 5 | DS 컴포넌트 래핑 | "약간만 다르게" 요청의 과잉 해석 |
| 6 | 아이콘 버튼 40×40 누락 | 히트 영역 접근성 규칙 미학습 |
| 7 | Primary 남발 | "중요함"을 "primary"로 단순 매핑 |
| 8 | 리스트 혼용 (gap + border-b) | Gap/Gapless 개념 구분 부재 |
제 금지 패턴은 학술적 리스트가 아니라, AI가 실제로 하는 실수의 지도입니다. 지도가 상세할수록 방어가 강해집니다.
그리고 한 가지 메타 관찰을 더 보탰습니다 — 이 규칙서는 Claude, Gemini, Codex 세 AI 모두에게 통과시켜야 의미가 있다. 이 통찰은 §9에서 다시 다루겠습니다.
6. 다리 — Storybook이라는 단일 진실 원본
여기까지가 저 혼자의 이야기였습니다. 이제 두 번째 팀이 들어옵니다.
제 규칙서가 의지할 단일 진실 원본(Single Source of Truth) 으로 제가 고른 곳은, 뜻밖에도 피그마 변수 테이블이 아니었습니다. Storybook 이었습니다.
여기서 제가 꼭 감사를 전하고 싶은 사람이 있습니다 — 프론트엔드 개발팀의 동료 엠엘 이 뼈를 깎는 작업으로 디자인 시스템 prop(property, 컴포넌트 속성) 체계를 Storybook으로 옮겨 담아 줬습니다. 그 작업이 없었다면, 이 규칙서는 성립할 수 없었습니다.
이 한 문장이 이 글 전체의 경첩입니다. 제가 만든 규칙서가, 프론트 개발자가 옮긴 Storybook 위에 올라섰습니다. 두 팀의 산출물이 한 흙이 된 순간입니다.
6-1. 왜 피그마가 아니라 Storybook이었나
이유는 TypeScript 인터페이스의 강제력 때문입니다.
| 단일 출처 후보 | 약점 / 강점 |
|---|---|
| 피그마 변수 테이블 | 디자인 의도는 담지만, 오래되면 거짓말을 한다. 강제력이 없다 |
| 디자인 문서(MD) | 사람은 읽지만, 코드와 충돌해도 코드가 이긴다 |
| Storybook + TypeScript 인터페이스 | 타입은 오래돼도 거짓말을 못 한다. 환각이 컴파일 타임에 죽는다 |
제가 규칙서 §0에 명문화한 원칙이 이것입니다.
디자인 문서와 Storybook이 충돌할 때, 실제 Props 인터페이스가 이긴다. AI가 임의로
variant="huge"같은 prop을 지어내면, 타입 체커가 바로 잡는다. 환각이 컴파일 타임에 죽는 구조다.
이 대목에서 하네스 시리즈를 읽은 분은 한 단어를 떠올릴 겁니다 — 단일 출처(canonical source). 이 시리즈의 문서 정원에서도 manuscript/ 가 단일 출처이고, 빌드 도구는 거기서 읽기만 합니다. 제 디자인 하네스에서는 그 자리를 Storybook이 맡습니다. 디자인 의도(디자인팀)와 타입 강제력(프론트팀)이 한 곳에서 만나, 누구도 혼자서는 거짓말로 덮을 수 없는 기준점이 됩니다.
6-2. 타입이 거짓말을 못 하는 이유
문서는 서술이고, 타입은 계약입니다. 서술은 시간이 지나면 현실과 어긋나도 아무도 죽지 않습니다. 그러나 타입 계약은 어긋나는 순간 빌드가 실패합니다 — 어긋남이 즉시, 기계적으로 드러납니다.
이것은 4-3에서 본 Hardik Pandya의 "자동 감사(린터)" 와 정확히 같은 메커니즘입니다. 닫힌 토큰 레이어(디자인팀의 규칙)가 무엇이 옳은지를 정하고, 타입 체커·린터(프론트팀의 집행)가 그것을 어겼는지를 기계적으로 잡습니다. 규칙과 집행이 두 팀에 나뉘어 있습니다.
7. 팀 크로스 하네스 — 왜 따로는 안 되는가
이제 이 글의 제목으로 돌아옵니다 — 팀 크로스 하네스.
처음엔 두 팀이 각자 자기 하네스를 짜려 했을 수도 있습니다. 디자인팀은 디자인 규칙을, 프론트팀은 코드 컨벤션과 린트를. 그런데 제 여정이 증명한 것은 정반대였습니다.
디자인 하네스와 프론트 하네스를 따로 짜면, 둘 다 작동하지 않습니다.
이유는 두 산출물이 서로를 필요로 하기 때문입니다.
| 한쪽만 있으면 | 무슨 일이 벌어지나 |
|---|---|
| 닫힌 토큰·규칙서만 있고 타입 강제력이 없으면 | 규칙은 서술에 머문다. AI도 사람도 어겨도 아무 일이 안 일어난다. 문서가 오래되면 거짓말을 시작한다 |
| 타입 체커·Storybook만 있고 규칙서가 없으면 | 타입은 형태만 강제한다. variant="primary" 가 문법적으로 맞아도, 한 화면에 다섯 개 쓰는 의미적 잘못은 못 잡는다 |
닫힌 토큰 레이어(디자인의 규칙)는 타입 체커(프론트의 집행)가 있어야 살아나고, 타입 체커는 규칙서(디자인의 의미)가 있어야 잡을 것이 생깁니다. 둘은 한 하네스의 햇빛과 물길입니다. 따로 떨어뜨리면 둘 다 죽습니다.
이것이 제가 생각하는 팀 크로스 하네스 의 정의입니다.
하나의 하네스를, 두 팀이 각자 다른 층을 채워 함께 소유한다. 디자인팀은 햇빛(규칙·의도)을, 프론트팀은 흙과 물길(Storybook·타입·린트)을 채운다. 어느 팀도 혼자서는 정원을 완성하지 못한다.
7-1. 70/30 합의가 가른 분업
5장의 70/30 선을 기억하시나요. 그 선이 여기서 두 팀의 분업선이 됩니다.
| 구간 | 누가 | 무엇을 |
|---|---|---|
| 70% (재현 가능한 일관성) | AI + 닫힌 규칙서 | 토큰 선택, 결정 트리, 금지 패턴 — 기계적으로 재현 |
| 30% (의도·튜닝) | 사람 (디자인팀 ↔ 프론트팀) | 모호한 판단, 새 패턴, 예외 승인 — 두 팀이 같이 결정 |
70%를 하네스가 자동화하기 때문에, 두 팀의 사람은 반복되는 70%를 두고 싸우지 않습니다. 남은 30% — 정말로 사람의 의도가 필요한 자리 — 에서만 두 팀이 만납니다. 하네스가 싸울 필요 없는 영역을 걷어내자, 협업이 가장 가치 있는 지점에 집중됐습니다.
7-2. 기획의 하네스와 이어 붙다
3편에서 기획자가 유비쿼터스 언어와 컨텍스트 맵으로 도메인의 언어를 잡았습니다. 그 언어가 디자인·프론트 계층으로 내려오면, 이번엔 디자인 토큰과 prop 인터페이스라는 더 구체적인 어휘로 번역됩니다.
기획 (3편) 디자인 (4편) 프론트 (4편)
유비쿼터스 언어 → 닫힌 토큰 · 규칙서 → prop 인터페이스 · 타입
컨텍스트 경계 → 컴포넌트 경계 → Storybook 스토리 단위
한 제품의 언어가 계층을 따라 끊기지 않고 번역되어 내려옵니다. 제가 이 시리즈에서 배운 것은, 하네스를 계층마다 따로 짜는 게 아니라 서로 이어 붙는 정원으로 키워야 한다는 점이었습니다.
8. 하네스는 특정 AI에 종속되지 않는다 — Claude·Codex·Gemini
규칙서가 완성된 뒤, 저는 조금 엉뚱한 테스트를 했습니다.
"Sort UI + AI 규칙서 + 프롬프트: 니 맘대로 아무거나 만들어봐" — 같은 시스템, 같은 규칙서, 같은 프롬프트를 Codex와 Claude에게 각각 던졌습니다.
결과는 디자인팀 안에서 한동안 회자됐습니다. 둘 다 의미 있는 수준의 결과물을 냈고, 더 중요한 건 둘이 만든 화면이 서로 상당히 닮아 있었다는 점입니다.
| AI가 자유롭게 만든 화면 | 규칙서가 작동한 지점 |
|---|---|
| Codex — 자동 분류 검수 작업대 | "검토 필요" 아이템만 border-destructive, 나머지는 border-default 로 통일 — 상태 보더 vs 기본 보더 구분이 규칙대로 |
| Claude — 고객 응대 트렌드 분석 | KPI(Key Performance Indicator, 핵심성과지표) 카드 4장이 모두 플랫 카드 — "같은 형태 2개 이상 반복이면 기본은 플랫" (§2.6) 이 정확히 적용 |
| 규칙서 데모 — 상담 배분 우선순위 리스트 | 6개 행 중 단 하나만 primary 배지 — "컨테이너당 primary 최대 1개" 가 시각적으로 드러남 |
핵심은 세 화면 모두 "같은 디자인 시스템에서 나왔다"는 인상을 준다는 점이었습니다. 하나는 Codex가, 하나는 Claude가, 하나는 규칙서 자체의 데모. 만든 주체가 달라도 일관성이 유지됐습니다.
그래서 저는 규칙서를 세 AI 모두에게 통과시켰습니다.
서로 장점이 달라 Codex가 잡는 것을 Claude가 못 잡기도 하고, Gemini만 놓치는 케이스도 있었습니다. 모든 AI에게 인정받아야 의미 있는 규칙서라고 생각했습니다.
이 원칙은 이 시리즈가 처음부터 강조해 온 하네스의 성질과 같았습니다 — 하네스는 도구(AI)에 종속되지 않는다. 3편에서 "모델은 도구이고, 시스템은 언어" 라고 했듯, 제 디자인 하네스도 특정 모델의 편향에 최적화되면 그 모델과 함께 낡습니다. 여러 AI에게 검증된 규칙은 AI에 무관한 규칙으로 수렴합니다.
새 모델이 등장했을 때 규칙서를 다시 써야 하는가 — 제 대답은 "아니오" 여야 했습니다.
하네스 카카시 정원의 검수 규칙이 마크다운으로만 적혀 Claude·Codex·Gemini 어느 손에서도 같은 판정을 내리도록 설계된 것과 같은 이유입니다.
9. 마치며 — 툴은 바뀌고, 시스템은 남는다
제가 일해 온 15년은 도구가 계속 바뀐 시간이었습니다.
| 시기 | 도구 | 저장 포맷의 성격 |
|---|---|---|
| 2010 | Photoshop | PSD — 사람만 읽을 수 있음 |
| 2015 | Sketch | 벡터·심볼 — 재사용 시작 |
| 2020 | Figma | 협업·토큰 — "토큰" 개념 정착 |
| 2026 | Cursor · Claude · Codex · Gemini | 대화 — 도구 이름을 다 외우기 전에 다음 도구가 등장 |
이 속도에 지치지 않은 사람이 있을까요. 하지만 이 이야기엔 반전이 있습니다.
도구는 계속 바뀌지만, 그 아래에서 바뀌지 않는 층이 있습니다. 그 층의 이름이 바로 디자인 시스템입니다.
디자인 시스템은 AI의 일부가 아닙니다. AI가 참조하는 컨텍스트입니다. 내일 더 좋은 모델이 나오면, 같은 디자인 시스템을 그 모델에도 건네주면 됩니다. 모델은 도구이고, 시스템은 언어입니다.
그리고 그 언어는 한 팀의 것이 아닙니다. 디자이너의 의도(디자인팀)와 타입의 강제력(프론트팀)이 Storybook이라는 한 흙에서 만나야 비로소 살아 있는 언어가 됩니다.
디자이너와 개발자가 싸우는 건 서로가 나빠서가 아니었습니다. 같은 화면을 다른 언어로 설명하고 있었기 때문입니다. AI는 그 사이에 새로 끼어든, 화성 출신도 금성 출신도 아닌 제3의 외계인이었습니다. 세 언어를 서로 번역할 도구가 필요했습니다.
그 번역기가 바로 두 팀이 함께 소유하는 하네스였습니다. 디자이너의 의도를, 프론트 개발자가 실행할 수 있는 타입으로, AI가 반복 가능한 형태로 바꿔 주는 — 세 번 번역된 한 장의 규칙. 이 한 장이 세 언어를 통합합니다.
이것은 우리 정원에 처음으로 두 팀이 함께 들어온 기록입니다. 1편은 문서를, 3편은 기획을 다뤘지만, 그때까지 정원에 들어온 것은 한 종류의 일이었습니다. 이번에 처음으로 — 디자인팀과 프론트팀이라는 서로 다른 두 팀이, 각자 다른 층을 채워 하나의 하네스를 함께 소유했습니다. 그것을 우리는 팀 크로스 하네스라 부르기로 했습니다.
혹시 지금 일관성 문제로 고통받고 있다면, 먼저 금지 규칙 10줄이라도 적어 보길 권합니다. 허용 규칙부터 쓰려 하면 끝이 없지만, 금지는 짧게 쓸 수 있고, 짧게 쓴 금지가 생각보다 훨씬 큰 차이를 만듭니다.
그리고 그 10줄을 적을 때 — 디자이너 혼자 적지 마세요. 옆자리 프론트 개발자와 같은 종이에 적으세요. 그 종이가 두 팀의 첫 번째 하네스가 됩니다.
Roma non uno die aedificata est. — 로마는 하루아침에 이루어지지 않았다. 정원도, 두 팀이 함께 짓는 첫 하네스도 마찬가지입니다.
하네스의 이야기는 계속됩니다. 감사합니다. 💙
참고
- 시리즈 본거지:
- 블룸AI 하네스 시리즈
- BlumnAI-Studio/harness-kakashi — 하네스 카카시 배포팩
- 디자인 토큰 · AI 친화 디자인 시스템:
- Sachin Patel, Cursor Isn't the Problem. Your Design Tokens Are (Medium, 2026-01)
- Hardik Pandya, Expose Your Design System to LLMs
- Oleksandra Huba, Dear LLM, here's how my design system works (UX Collective, 2025-11)
- Romina Kavcic 외, Agentic Design Systems (Into Design Systems)
- IBM Carbon Design System — Carbon for AI
- Shape Up (Breadboarding · Fat Marker Sketch):
- Ryan Singer / Basecamp, Shape Up — Find the Elements
- 자매 글:
- 원본 소재:
- 제나, 「AI가 이해하는 디자인 시스템 구축기 — 디자이너의 1인칭 기록」 (BlumnAI 디자인팀 사내 기고, 2026-04 / Notion 세컨드 에디션) — 이 글은 그 기록을 제가 직접 하네스 시리즈 4편으로 다시 정리한 1인칭 판본이다.