# Uber가 만든 uSpec — AI가 Figma에 디자인 스펙을 직접 그려준다

Philipy (윤상필)·2026년 3월 25일

Claude Code로 디자인하기

목록 보기

2/3

디자인 스펙, 누가 만들고 있나

디자인 시스템을 운영하다 보면 "문서화"라는 벽에 부딪힌다.

컴포넌트 하나를 만들면 따라붙는 문서가 한둘이 아니다. 해부도(anatomy), 속성(properties) 테이블, 색상 토큰 매핑, 크기·간격 스펙, 접근성 명세, 모션 타임라인… 디자이너가 컴포넌트 하나 만드는 시간보다 스펙 문서 정리하는 시간이 더 긴 경우도 많다.

Uber의 Base 디자인 시스템 리드 디자이너 Ian Guisard가 이 문제를 정면으로 풀었다. 2026년 3월 11일, Uber 엔지니어링 블로그에서 uSpec이라는 오픈소스 도구를 공개했다.

"How Uber Built an Agentic System to Automate Design Specs in Minutes"

한 줄 요약: AI 에이전트에게 컴포넌트를 알려주면, Figma 파일 안에 스펙 페이지를 직접 렌더링해준다.

uSpec이 뭔데

uSpec은 AI 기반 디자인 문서 자동화 도구다. MIT 라이선스 오픈소스.

하는 일은 단순하다:

1. Figma에서 컴포넌트를 선택한다
2. Claude Code에서 /create-{스펙유형} 명령을 실행한다
3. AI가 컴포넌트를 분석한다
4. Figma 파일 안에 스펙 페이지가 생성된다

"AI한테 말로 설명하면 Figma에 그림이 그려진다"라고 생각하면 거의 맞다.

생성 가능한 7가지 스펙

명령	뭘 만들어주나	언제 쓰나
`/create-anatomy`	번호 마커가 붙은 컴포넌트 해부도 + 속성 테이블	"이 컴포넌트가 어떤 요소로 구성돼 있지?"
`/create-api`	속성, 값, 기본값, 설정 예시 테이블	"개발자한테 넘길 props 문서 필요해"
`/create-property`	Variant 축, boolean 토글, variable mode 전시	"이 컴포넌트의 모든 조합을 보여줘"
`/create-color`	모든 상태별 디자인 토큰 매핑	"어떤 색이 어디에 쓰이는지 정리해줘"
`/create-structure`	높이, 패딩, 간격 치수 스펙	"px 단위로 정확한 수치 문서 필요해"
`/create-voice`	VoiceOver + TalkBack + ARIA 접근성 명세	"스크린 리더가 이걸 어떻게 읽어야 하지?"
`/create-motion`	애니메이션 타임라인 + 이징 곡선	"After Effects 데이터를 스펙으로 옮겨야 해"

아키텍처 — 2레이어 구조

uSpec은 두 개의 레이어로 나뉜다.

레이어 1: AI 스킬 (Application Layer)

7개의 스킬 파일이 각각 도메인 지식을 담고 있다. 접근성 시맨틱 분류법, 토큰 매핑 규칙, 구조화된 스키마, 검증 로직 같은 것들이 인코딩되어 있고, AI는 이걸 읽고 해석해서 스펙을 생성한다.

레이어 2: Figma Console MCP (Infrastructure Layer)

Southleft에서 만든 MCP 서버. 로컬 WebSocket으로 AI 에이전트를 Figma Desktop에 직접 연결한다. Plugin API를 사용해서 완전한 읽기/쓰기 접근 권한을 제공한다. 도구가 84개 이상.

이전 글에서 다뤘던 공식 Figma MCP와의 차이를 다시 정리하면:

항목	공식 Figma MCP	Figma Console MCP
API 계층	REST API (클라우드)	Plugin API (로컬 Desktop Bridge)
도구 수	~13개	84개+
쓰기 기능	제한적	완전한 읽기/쓰기
임의 코드 실행	불가	`figma_execute`로 가능
데이터 경로	Figma 서버 경유	완전 로컬

핵심 차이: 공식 MCP는 "읽기 위주의 리모컨"이고, Console MCP는 "Figma 안에서 코드를 실행할 수 있는 터미널"이다.

참고로 uSpec v1.4.1부터는 공식 Figma MCP도 지원한다. 다만 figma_execute가 필요한 고급 기능은 Console MCP에서만 가능하다.

설치 과정 — 생각보다 단계가 많다

솔직히 설치가 원클릭은 아니다. 하지만 한 번 세팅하면 이후로는 편하다.

사전 조건

Figma Desktop 앱 (웹 버전 안 됨)
Node.js
Claude Code (또는 Cursor)
Anthropic API 키 또는 Figma Access Token

설치 순서

Step 1: uSpec 리포 클론
        git clone https://github.com/redongreen/uSpec.git

Step 2: Figma Console MCP 설치 및 MCP 서버 등록

Step 3: Desktop Bridge 플러그인 설치
        Figma → Plugins → Development → Import plugin from manifest
        (~/.figma-console-mcp/plugin/manifest.json)

Step 4: uSpec 디렉토리에서 Claude Code 실행
        cd uSpec && claude

Step 5: /firstrun 실행
        → MCP 제공자 선택 (figma-console 또는 figma-remote)
        → 환경 선택 (Cursor, Claude Code, Codex)
        → 7개 스킬 자동 배포
        → 템플릿 라이브러리 연결

/firstrun이 끝나면 uspecs.config.json에 7개 템플릿 키가 기록되고, 스킬 파일들이 .claude/skills/ 아래에 배포된다.

실제 사용 — 하단 탭바 컴포넌트로 테스트

진행 중인 모바일 앱 프로젝트의 하단 탭바 컴포넌트로 테스트해봤다.

사용 전 준비 (매번)

1. Figma Desktop에서 대상 파일 열기
2. Plugins → Development → "Figma Desktop Bridge" 실행
   (좌측 하단 "Connected" 확인)
3. 터미널에서 uSpec 디렉토리로 이동 후 claude 실행

anatomy 스펙 생성 예시

/create-anatomy https://www.figma.com/design/{파일ID}/{파일명}?node-id={노드ID}

이것은 하단 탭바 컴포넌트입니다.
홈, 리스트, MY, 바로가기 4개 메뉴가 있습니다.
각 메뉴는 아이콘 + 라벨로 구성되며 활성/비활성 상태가 있습니다.

명령을 실행하면 AI가:
1. 해당 Figma 노드를 읽고
2. 컴포넌트 구조를 분석한 뒤
3. 템플릿 라이브러리에서 anatomy 레이아웃을 가져와서
4. Figma 파일 안에 번호 마커가 붙은 해부도 페이지를 직접 생성한다

중요: 스펙 생성 중에는 Figma 캔버스를 절대 조작하면 안 된다. AI가 참조하는 노드 ID가 깨진다.

이전 글과의 연결 — Code to Canvas vs uSpec

이전 글에서 Figma MCP의 "Code to Canvas" 기능으로 디자인 시안을 생성하는 이야기를 했다. uSpec은 그것과는 목적이 다르다.

구분	Code to Canvas	uSpec
목적	디자인 시안 생성	디자인 스펙 문서화
입력	자연어 설명	기존 Figma 컴포넌트
출력	UI 화면	스펙 페이지 (해부도, API 표 등)
대상	디자이너, PM	디자이너, 개발자, QA
MCP	공식 Figma MCP 또는 Console MCP	Console MCP (권장)

둘은 경쟁이 아니라 상호보완 관계다:

Code to Canvas로 디자인 시안 생성
    ↓
uSpec으로 해당 컴포넌트의 스펙 문서 자동 생성
    ↓
개발자에게 전달

실제로 내 프로젝트에서는 Code to Canvas로 70개 화면을 생성한 뒤, uSpec으로 주요 컴포넌트의 스펙 문서를 만드는 워크플로우를 구성하고 있다.

운영 시 주의사항

몇 가지 알아두면 좋은 것들.

토큰 소모가 크다

스펙 하나 생성에 Figma 노드 읽기 → 분석 → 템플릿 인스턴스 생성 → 데이터 채우기 → 스크린샷 검증까지 거치기 때문에, 한 번 실행에 꽤 많은 토큰을 소모한다. Claude Opus 4.6 기준으로 스펙 1회당 $0.5~2 정도.

모델은 Opus 급 권장

스킬 파일에 인코딩된 도메인 지식을 정확히 해석하고, 84개 이상의 MCP 도구를 적절히 조합해서 써야 하기 때문에 모델 성능이 중요하다. Sonnet으로도 돌아가긴 하지만, 복잡한 컴포넌트에서는 Opus가 확실히 낫다.

한 번에 하나씩

Figma 파일당 하나의 에이전트만 실행해야 한다. 동시에 두 개의 스킬을 돌리면 노드 참조가 충돌한다.

Desktop Bridge 상태 확인

가끔 Figma를 오래 켜두면 Desktop Bridge 연결이 끊어진다. 스킬 실행 전에 플러그인 패널에서 "Connected" 상태인지 확인하는 습관을 들이면 좋다.

누가 쓰면 좋을까

역할	활용 시나리오
디자이너	컴포넌트 만들고 스펙 문서 자동 생성 — 문서화 시간 90% 절약
개발자	props 테이블, 치수 스펙을 Figma에서 바로 확인
QA	접근성 스펙(VoiceOver/TalkBack)으로 테스트 기준 확보
PM/마케터	디자인 시스템의 현재 상태를 시각적으로 파악

특히 디자인 시스템을 운영하는 팀이라면, 컴포넌트가 추가될 때마다 수작업으로 스펙 문서를 만드는 반복 작업을 자동화할 수 있다는 점이 가장 크다.

정리

uSpec은 "AI가 디자인을 대신 해준다"는 도구가 아니다. 이미 만들어진 디자인 컴포넌트의 스펙 문서를 자동으로 생성해주는 도구다.

Uber 규모의 디자인 시스템에서 태어났지만, 오픈소스(MIT)라 누구나 쓸 수 있다. Figma Console MCP와 조합하면 로컬에서 완전한 읽기/쓰기가 가능하고, 공식 Figma MCP만으로도 기본적인 스펙 생성은 된다.

설치 과정이 좀 길지만, 한 번 세팅하면 /create-anatomy {링크} 한 줄로 Figma 안에 스펙 페이지가 생긴다. 디자인 시스템 문서화에 지쳐있다면 시도해볼 가치가 있다.

참고 자료

GitHub: redongreen/uSpec (MIT)
Uber 엔지니어링 블로그: "How Uber Built an Agentic System to Automate Design Specs in Minutes" (2026.03.11)
Figma Console MCP: southleft/figma-console-mcp
uSpec 공식 사이트: uspec.design

Written with Claude Code (Anthropic CLI) — 2026.03.25

Philipy (윤상필)

Tech Phase-smith, Karax wannabe

이전 포스트

Claude Code에서 Figma "Code to Canvas"가 안 되는 이유 — 삽질 끝에 찾은 답

다음 포스트