VIEW
← 돌아가기
Also · 피에프씨테크놀로지스 · 디자인 시스템

AI가 읽기 좋은 디자인시스템

디자인 시스템

코드를 주로 AI가 쓰는 환경을 전제로 만든 디자인 시스템이에요. AI가 모르면 조용히 틀리는 함정은 글로 남기고, 지켜야 하는 규칙은 기계가 막게 했어요.

역할
동료와 공동 구축
상태
서비스 적용 준비 중
스택
Tailwind · Storybook · Figma MCP · Claude Code
0
설계 결정(ADR)
1벌
Figma와 코드가 같은 어휘

01Problem

이제 코드는 대부분 AI가 써요. 그런데 AI는 학습한 습관대로 text-sm, bg-slate-500, w-[312px] 같은 값을 쓰고, 그럴듯한 대안(다른 Tooltip 라이브러리, state prop 등)으로 슬쩍 바꿔 놓기도 해요. 에러는 나지 않고, 화면만 조용히 틀려요.

기존 디자인 시스템은 사람이 읽는 문서 사이트와 리뷰어의 기억에 기대고 있어서, AI가 만든 이런 실수를 막을 장치가 없었어요.

02Decision

글로 남기고, 기계가 막는다

방향은 두 가지였어요. 하나는 규칙을 처음 보는 동료가 모르면 조용히 틀리는 것 위주로 글로 남기는 것, 다른 하나는 그 규칙 대부분이 지켜지는지 기계가 검사하게 하는 것이에요.

AI는 경고 문구는 놓칠 수 있어도, 실패한 검사는 놓치지 않는다.

03Context

무엇을 적었나

  • 함정 목록 (AGENTS.md)사용법 문서가 아니라 「모르면 조용히 틀리는 것」 목록이에요. 에러 없이 스타일만 안 먹는 경우, 이름만 닮은 토큰(bg-red와 bg-red-300) 같은 함정을 증상·원인·근거 순서로 적었어요.
  • 용어집 (CONTEXT.md)단어마다 쓰면 안 되는 이름을 붙였어요(Chip ≠ Tag, Chips ≠ ChipGroup). AI가 더 흔한 이름으로 바꿔 부르지 못하게요.
  • ADR 27건「왜 이렇게 했는가」를 남겨서 AI가 그럴듯한 대안으로 되돌리지 못하게 했어요. 제목 자체가 결론이에요(예: button-state-is-not-a-prop).
  • 타입 주석 = 문서props 설명을 한 곳에만 쓰면 Storybook, IDE 툴팁, 타입 선언에 그대로 흘러가요. 쓰는 쪽의 AI가 실제로 읽는 건 이거예요.

04Vocabulary

쓸 수 있는 말을 한 벌로 고정

  • Tailwind 기본값 지우기기본 스케일을 비워서 AI가 습관대로 text-sm을 써도 클래스가 아예 생성되지 않아요. 쓸 수 있는 이름은 Figma의 이름 하나뿐이에요.
  • Figma 이름 그대로디자이너, Figma MCP가 돌려주는 변수 이름, 코드가 모두 같은 단어를 써요.
  • 감싸는 컴포넌트 만들지 않기<Typography> 같은 한 겹을 두지 않아 AI가 외울 추상화가 하나 줄었어요.

05Enforce

글로 끝내지 않고 기계가 막게

1
AI가 파일을 고치는 순간
Claude Code hook이 바로 임의값(w-[312px]) 검사를 돌리고, 원하면 토큰으로 자동 치환해요.
2
CI에서
토큰·아이콘·로고는 전부 생성물이라 원본과 다르면 실패해요. 모션은 스펙 목록과 대조하고, 적용하지 않은 이유도 따로 적게 해서 조용히 빠지는 걸 막아요.
3
눈에 안 보이는 회귀
글꼴 렌더링, 반응형 경계값처럼 화면 비교로는 안 잡히는 것들은 전용 테스트가 지켜요. 화면 비교는 Docker로 환경을 고정해 어느 기기에서 찍어도 같은 기준이에요.
4
PR 리뷰
PR마다 AI 리뷰가 같은 규칙 문서를 기준으로 봐요. 「Figma와 대조하지 않았으면 대조했다고 쓰지 말 것」처럼 리뷰어의 환각을 막는 조항도 넣었어요.

06Result

  • AI가 규칙을 어기면, 사람이 리뷰에서 찾기 전에 검사가 먼저 멈춰요.
  • 규칙의 출처가 하나라서 리뷰 기준과 규칙이 둘로 갈라지지 않아요.
  • 남은 숙제함정 목록·ADR·용어집은 패키지에 실리지 않아서, 지금은 이 레포를 고치는 AI에게만 닿아요. 서비스 레포의 AI에게는 고정된 어휘와 타입 주석 정도만 전달돼요. 쓰는 쪽을 위한 요약 문서(예: llms.txt)를 함께 배포하는 걸 다음 단계로 보고 있어요.

07Learning

사람에게는 문서가 규칙이지만, AI에게는 실패하는 검사가 규칙이다. 지켜야 할 것을 글로만 남기면 언젠가 조용히 틀린다.