디자인 시스템 문서화 자동화 — AI 초안 생성 워크플로 구성 방법

왜 디자인 시스템 문서화는 항상 뒤처지는가

컴포넌트는 Figma에 있고, 코드는 Storybook에 있고, 가이드라인은 Notion에 있다. 그런데 세 곳의 내용이 일치하는 경우는 드물다. 디자인 시스템 문서화가 뒤처지는 이유는 단순하다. 만드는 속도보다 업데이트하는 비용이 더 크기 때문이다. AI 워크플로를 끼워 넣으면 이 구조를 개선할 수 있다.

전체 파이프라인 구조

핵심은 세 단계다. ① 소스 추출 → ② AI 초안 생성 → ③ 검수 및 배포. 각 단계를 자동화 도구와 연결하면 사람이 개입하는 구간을 검수 단계 하나로 줄일 수 있다.

1단계: 소스 추출 — Figma API + Storybook

Figma REST API를 사용하면 컴포넌트 이름, 변형(Variants), 프로퍼티, 색상 토큰을 JSON으로 뽑을 수 있다. GET /v1/files/:file_key/components 엔드포인트로 전체 컴포넌트 목록을 가져오고, GET /v1/files/:file_key/component_sets로 변형 구조를 추출한다.

Storybook 측에서는 Storybook Docs의 자동 생성 ArgTypes 데이터를 활용한다. storybook build --docs 후 생성되는 인덱스 JSON 파일(Storybook 버전에 따라 stories.json 또는 index.json)에는 prop 타입, 기본값, 설명 필드가 포함된다. 이 두 JSON을 병합해 하나의 컴포넌트 스펙 파일을 만드는 것이 1단계의 목표다.

2단계: AI 초안 생성 — Claude API 활용

병합된 스펙 JSON을 프롬프트에 넣고 Claude API(claude-sonnet 계열)를 호출한다. 프롬프트 구조는 다음과 같다.

시스템 프롬프트: “너는 디자인 시스템 테크니컬 라이터다. 입력된 컴포넌트 스펙을 바탕으로 사용법, Props 테이블, 접근성 주의사항, 사용 예시 코드를 Markdown으로 작성하라.”
유저 프롬프트: 추출한 스펙 JSON을 그대로 붙여넣는다.
출력 포맷 지정: 응답 끝에 ---DONE--- 토큰을 붙이도록 지시해 파싱을 안정화한다.

이 호출을 GitHub Actions 워크플로로 묶으면 Figma 파일이 업데이트될 때마다 자동으로 트리거할 수 있다. Figma Webhook 이벤트와 GitHub Actions repository_dispatch를 연결하면 되는데, 디자인 시스템 용도라면 모든 파일 변경에 반응하는 FILE_UPDATE보다 컴포넌트 라이브러리 게시 시점에 발생하는 LIBRARY_PUBLISH 이벤트가 더 적합한 경우가 많다.

3단계: 검수 및 배포 — PR 기반 리뷰

AI가 생성한 Markdown 초안은 자동으로 Pull Request로 올라온다. 리뷰어는 내용의 정확성과 톤만 확인하면 된다. 초안을 처음부터 쓰는 것이 아니라 고치는 것이므로 소요 시간이 줄어든다. 승인 후 머지되면 Docusaurus나 Notion API를 통해 퍼블릭 문서 사이트에 자동 배포된다.

실전 팁 세 가지

컴포넌트당 토큰 예산을 정해라. 스펙이 복잡한 컴포넌트는 JSON이 길어져 컨텍스트 한도에 근접할 수 있다. 스펙 필드를 필수 항목만 남기도록 전처리 스크립트를 만들어 두면 호출 비용과 출력 품질을 함께 관리할 수 있다.
예시 코드는 Storybook 스토리에서 직접 가져와라. AI가 코드를 생성하면 실제 동작하지 않는 예시가 포함될 수 있다. 기존 스토리 파일에서 코드 블록을 추출해 프롬프트에 참조로 넣으면 정확도가 높아진다.
변경 감지 범위를 좁혀라. 모든 업데이트에 반응하면 불필요한 API 호출이 발생한다. Webhook 페이로드에서 변경된 컴포넌트 ID만 필터링해 해당 컴포넌트 문서만 재생성하도록 로직을 짜는 것이 효율적이다.

이 워크플로가 해결하는 진짜 문제

기술적인 자동화보다 중요한 것은 “문서가 항상 최신 상태”라는 팀 내 신뢰를 만드는 것이다. 디자이너가 컴포넌트를 수정할 때마다 문서가 자동으로 따라오는 구조가 되면, 개발자는 더 이상 “이거 최신 스펙이야?”라고 확인하는 과정을 반복하지 않아도 된다. 문서화 자동화의 실질적 가치는 절약된 작업 시간뿐 아니라 반복적인 확인 커뮤니케이션의 감소에서도 찾을 수 있다.