Design.md 파일 하나로 AI 코딩 도구의 디자인 부채 해결하기
makedream2026년 5월 8일
0
컴퓨터/소프트웨어
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
AI 코딩 도구로 프롬프트를 몇 번 던지면 그럴싸한 페이지가 나옵니다. 문제는 그다음입니다. 새로 생성한 버튼의 곡률이 옆 페이지와 다르고, 브랜드 컬러는 미세하게 채도가 비틀려 있습니다. 개발 속도는 빠른데 결과물은 조잡합니다. AI는 맥락을 모르면 가장 흔한 평균값을 던지기 때문입니다. 이 문제를 해결하려면 프로젝트 루트에 Design.md를 박아넣고 AI에게 엄격한 제약 조건을 강제해야 합니다.
AI에게 "세련된 파란색"을 써달라고 말하는 건 시간 낭비입니다. AI는 형용사가 아니라 정규화된 데이터를 먹고 삽니다. 디자인 시스템을 원시(Primitive), 시맨틱(Semantic), 컴포넌트(Component)의 3계층으로 쪼개서 명세하십시오.
blue-500: #3B82F6처럼 절대적인 값을 선언합니다.bg-primary: var(--blue-500)처럼 기능적인 역할을 부여합니다.[category]-[property]-[modifier] 형식을 강제하여 $color-background-hover 같은 이름을 쓰게 만듭니다.2025년 UI 협업 사례 연구에 따르면, 이렇게 구조화된 토큰을 사용한 팀은 UI 버그 발생률을 스프린트당 14건에서 4건으로 줄였습니다. AI가 색상 코드가 아닌 기능을 보고 클래스를 선택하기 시작하면 디자인 수정 시간의 70%가 사라집니다. Tailwind CSS를 쓴다면 이 토큰들을 tailwind.config.js와 일대일로 매핑하라고 AI에게 명령하십시오.
AI는 자유도가 높을수록 멍청한 선택을 합니다. 페이지마다 제각각인 여백을 잡으려면 명세서에 수치를 테이블 형태로 때려 넣어야 합니다.
| 속성 | 수치 | 적용 규칙 |
|---|---|---|
| 버튼 곡률 | 8px | rounded-lg 고정, 임의 변경 금지 |
| 섹션 간격 | 64px | 모든 주요 섹션 사이의 수직 간격 |
| 최대 너비 | 1280px | 메인 컨텐츠의 중앙 정렬 한계선 |
간격 단위를 8px 배수로 제한하고 카드 패딩을 24px로 고정하십시오. 특히 안티 패턴 섹션을 만드는 게 효과적입니다. "한 화면에 CTA 버튼을 3개 이상 넣지 말 것", "그림자 대신 1px 테두리를 쓸 것" 같은 금지 조항을 넣으면 AI는 오답 후보를 먼저 지우고 작업을 시작합니다. 이 단순한 표 하나가 수동 수정 횟수를 절반 넘게 줄여줍니다.
기능마다 말투가 다르고 아이콘 스타일이 섞여 있으면 앱이 저렴해 보입니다. 브랜드 페르소나를 Design.md에 명시하십시오. 성공 메시지를 "업데이트 완료"로 쓸지, "준비 완료!"로 쓸지 미리 정해줘야 합니다.
아이콘은 다음 프로토콜을 따릅니다.
stroke-width를 1.5px로 고정합니다.다크 모드도 마찬가지입니다. 단순히 색을 반전시키면 가독성이 망가집니다. 구글 머티리얼 디자인 가이드라인이 권장하듯 배경에 순수 검정 대신 짙은 회색(#121212)을 쓰도록 명시하고, 대비 비율을 로 유지하라는 공식을 넣어두면 접근성 버그를 알아서 피해 갑니다.
명세서를 잘 써도 AI가 안 읽으면 의미 없습니다. .cursor/rules/ 디렉토리에 UI 전용 규칙을 만들고, 모든 작업 전 반드시 Design.md를 참조하라고 강제하십시오. 2025년 개발 데이터에 따르면 이 루틴을 도입한 팀은 기능 개발 시간을 평균 12.5시간에서 8.1시간으로 단축했습니다.
이제 개발자는 코드를 고치는 게 아니라 문서의 수치만 조정해서 서비스 전체의 인상을 바꿉니다. 디자인은 감각의 영역이 아니라 정밀한 엔지니어링의 영역이어야 속도가 납니다. 초반 30분의 문서화 작업이 이후 수십 시간의 삽질을 막아줍니다.