5장. 3계층 토큰 아키텍처 — Primitive / Semantic / Component 토큰 설계

AI 시대에 토큰이 더 중요해진 이유

토큰은 색상표의 다른 이름이 아니다. 토큰은 디자인 결정을 이름 붙여 저장하는 방식이다. 다시 말해, 예쁜 값을 모아두는 일이 아니라 팀의 판단을 구조로 바꾸는 일이다.¹²

예전에는 토큰이 조금 엉성해도 사람이 눈치로 메웠다. 디자이너는 비슷한 회색 두 개를 보고도 어느 쪽이 더 맞는지 감으로 골랐고, 개발자는 CSS를 보며 대충 맥락을 추론했다. 하지만 2026년의 워크플로우에서는 AI가 그 빈칸을 메우려 든다. 문제는 AI가 맥락을 추측할 수는 있어도, 팀의 암묵지를 자동으로 이해하지는 못한다는 데 있다. 그래서 토큰이 정리되지 않은 시스템에 AI를 붙이면 생산성보다 증폭 효과가 먼저 나타난다. 좋은 규칙은 더 빨리 퍼지고, 나쁜 규칙도 더 빨리 퍼진다.

특히 피그마 파일이 MCP나 각종 자동화 도구와 연결되면, 토큰은 사람끼리의 약속을 넘어 기계가 읽는 인터페이스가 된다. 이때 가장 위험한 상황은 단순하다. 파일은 그럴듯해 보이는데, AI가 primitive 값을 직접 가져다 쓰면서 일관성을 무너뜨리는 경우다. 빨강이 필요할 때마다 red/600, red/500, error 중 아무거나 골라 쓰기 시작하면 결과는 금방 화려한 혼돈이 된다.

사람은 의미로 기억하고, AI는 계층으로 이해한다

토큰 구조를 가장 쉽게 이해하는 방법은 요리를 떠올리는 것이다.

• Primitive 토큰은 재료다. 소금, 설탕, 밀가루처럼 있는 값을 정의한다.

• Semantic 토큰은 역할이다. 간을 맞추는 소금인지, 디저트용 설탕인지처럼 쓰임을 정의한다.

• Component 토큰은 레시피다. 이 버튼의 기본 배경, 저 입력창의 포커스 테두리처럼 실제 부품의 자리를 정의한다.

이 세 층이 분리되어 있으면 수정도 쉬워진다. 브랜드 블루가 바뀌면 primitive를 바꾸거나 semantic 연결만 조정하면 된다. 다크 모드를 추가할 때도 컴포넌트 하나하나를 뜯어고치지 않고 semantic 층의 연결을 바꾸면 된다. 그리고 AI는 바로 이 계층 덕분에 무엇이 재료이고 무엇이 의도인지 구분할 수 있다.³

짧게 말하면, 3계층 아키텍처의 목적은 값의 재사용이 아니다. 의도의 재사용이다.

1층 Primitive — 시스템의 원재료

Primitive 토큰은 가장 밑바닥에 있는 원시 값이다. 색상, 간격, 반경, 글자 크기, 그림자 같은 값이 여기에 들어간다. 중요한 점은 이 층에는 의미를 너무 일찍 넣지 않는다는 것이다. 아직은 브랜드 버튼인지, 경고 메시지인지 모른다. 그냥 시스템에 존재하는 값 자체를 정리한다.

예를 들면 이런 식이다.

• color/blue/500

• color/gray/900

• space/4

• space/8

• space/16

• radius/4

• radius/8

• font/size/14

• font/size/16

Primitive 층의 장점은 단순함이다. 값이 명확하고, 코드로 옮기기 쉽고, 스케일을 관리하기 좋다. 대신 이 층을 그대로 화면에 바르기 시작하면 곧 문제가 생긴다. color/blue/500은 파란색이라는 사실만 말해 줄 뿐, 그 파랑이 주요 CTA인지 링크인지 정보 배지인지 설명하지 못한다.

그래서 primitive는 원칙적으로 재료 창고에 가깝다. 존재는 꼭 필요하지만, 최종 화면에 직접 등장하는 일은 최소화하는 편이 좋다. 피그마 공식 학습 자료도 primitive를 다른 토큰의 기반이 되는 참조 층으로 설명한다.¹

2층 Semantic — 값에 목적을 붙이는 층

Semantic 토큰은 토큰 시스템의 진짜 중심이다. 여기서 비로소 색과 간격이 의미를 얻는다. 파란색이 아니라 주요 상호작용 색이 되고, 회색이 아니라 본문 기본 텍스트 색이 된다.

예를 들면 이런 이름들이다.

• color/text/primary

• color/text/secondary

• color/background/default

• color/background/elevated

• color/border/default

• color/border/focus

• color/feedback/error

• color/action/primary

이 이름들의 좋은 점은 값이 바뀌어도 이름이 오래 살아남는다는 데 있다. 브랜드가 바뀌어 파랑이 보라가 되어도 color/action/primary는 그대로다. 라이트 모드에서는 검은 글자였던 color/text/primary가 다크 모드에서는 흰 글자로 바뀌어도 이름은 바뀌지 않는다. 바로 이 안정성이 디자인 시스템의 수명을 늘린다.

AI 관점에서도 semantic 층은 특히 중요하다. AI는 red/600이라는 이름만 보면 그 색이 오류용인지, 위험한 삭제 버튼용인지, 강조 배지용인지 알 수 없다. 하지만 color/feedback/error라고 적혀 있으면 훨씬 덜 헤맨다. 여기에 설명까지 붙어 있으면 더 좋다. 예를 들어 폼 검증 오류, 파괴적 액션, 시스템 에러 메시지에 사용 같은 설명이 있으면 AI는 그 토큰을 고를 근거를 얻는다.³

즉, semantic 토큰은 사람에게는 기억 장치이고, AI에게는 사용 설명서다.

3층 Component — 부품 단위의 정확한 연결

Component 토큰은 특정 컴포넌트의 특정 속성에 연결되는 토큰이다. 여기서는 질문이 더 구체적이다. 어디에 쓰는가를 넘어서, 정확히 어느 부위에 쓰는가를 다룬다.

예를 들면 다음과 같다.

• button/bg/primary/default

• button/text/primary/default

• button/border/focus

• input/bg/default

• input/border/error

• card/padding/md

• modal/shadow/default

이 층이 있으면 컴포넌트 수준의 일관성이 아주 강해진다. 버튼 패딩이 언제나 space/16과 space/12를 쓰게 만들 수도 있고, 입력창 에러 보더가 언제나 color/feedback/error를 따라가게 만들 수도 있다. 큰 팀이나 복잡한 제품군에서는 이 층이 유지보수 비용을 크게 줄여 준다.¹

하지만 여기서 욕심이 과해지면 오히려 시스템이 무거워진다. 작은 팀이 첫날부터 button/icon/leading/size/md/pressed 같은 토큰을 다 만들기 시작하면, 라이브러리를 만드는 것이 아니라 미로를 만드는 셈이다. Component 토큰은 자주 반복되고, 컴포넌트별 규칙이 분명하며, 변경 비용이 큰 영역부터 만드는 편이 좋다.

한마디로 정리하면 이렇다.

Primitive는 있어야 하고, Semantic은 반드시 필요하며, Component는 규모와 복잡도에 따라 선택적으로 깊이를 늘린다.

설계 순서는 아래에서 위로, 적용은 위에서 아래로

3계층 아키텍처는 만드는 순서와 쓰는 순서가 다르다. 설계는 아래에서 위로 올라가고, 실제 적용은 위에서 아래로 내려온다.

먼저 primitive 스케일을 정한다. 브랜드 컬러 램프, 중립 회색, spacing 스케일, radius 단계처럼 시스템의 기본 재료를 만든다. 그다음 semantic 토큰을 만든다. 이때 핵심은 값이 아니라 역할 중심으로 묶는 것이다. 마지막으로 반복적으로 쓰는 버튼, 입력창, 카드 같은 컴포넌트에 한해서 component 토큰을 얹는다.

반대로 화면에 적용할 때는 가능하면 component나 semantic부터 쓴다. primitive를 직접 바르는 일은 마지막 예외로 남겨 둔다. 이 규칙만 지켜도 시스템의 절반은 이미 건강해진다.

피그마에서는 3개 컬렉션으로 시작하면 된다

피그마에서 가장 실무적인 출발점은 의외로 단순하다. 컬렉션을 너무 잘게 쪼개지 말고 다음 세 개로 시작하는 편이 안정적이다.

• Primitives

• Semantic

• Component

그리고 각 컬렉션 안에서 slash 구조로 그룹을 나눈다. 예를 들어 Primitives 안에는 color, space, radius, type이 들어가고, Semantic 안에는 text, background, border, feedback, action이 들어간다. Component 안에는 button, input, card, modal 같은 그룹이 들어간다.

이 방식이 좋은 이유는 두 가지다. 첫째, 피그마 안에서 찾기 쉽다. 둘째, 나중에 JSON이나 코드로 내보낼 때 구조를 거의 그대로 유지할 수 있다. Figma 변수 이름과 코드 키 구조가 1:1에 가깝게 맞아떨어질수록 동기화 스크립트, Style Dictionary, MCP 기반 에이전트가 훨씬 덜 헷갈린다.⁴

예를 들어 피그마에서 semantic/color/text/primary라고 이름을 지었다면, 코드에서는 semantic.color.text.primary나 --semantic-color-text-primary 같은 형태로 자연스럽게 바꿀 수 있다. 반대로 피그마와 코드의 이름이 다르면 중간에 번역표가 필요해지고, 번역표는 시간이 지나면 반드시 사고를 친다.

모드는 주로 Semantic 층에 둔다

라이트와 다크, 브랜드 A와 브랜드 B처럼 같은 역할이지만 값만 달라지는 경우에는 모드를 쓴다. 여기서 중요한 원칙 하나만 기억하면 된다. 문맥이 바뀌는 것은 mode의 문제이고, 모양이 바뀌는 것은 variant의 문제다.

예를 들어 color/text/primary는 라이트 모드에서 gray/900을 가리키고, 다크 모드에서는 gray/0을 가리킬 수 있다. 하지만 button size가 md에서 lg로 바뀌는 것은 mode가 아니라 다른 토큰이거나 컴포넌트 variant다. 이 구분이 무너지면 변수 패널이 금방 엉망이 된다.

실무에서는 primitive는 비교적 고정해 두고, semantic 컬렉션에서 mode를 운용하는 방식이 가장 다루기 쉽다. 원재료는 그대로 두고 의미 층에서 문맥별 연결만 바꾸는 셈이다. 다음 장에서 다룰 라이트/다크와 브랜드 분기도 바로 이 구조 위에서 가장 매끄럽게 작동한다.

버튼 하나를 3계층으로 분해해 보기

버튼은 토큰 구조를 설명하기에 딱 좋은 예시다. 겉보기엔 단순하지만, 실제로는 색상, 텍스트, 간격, 반경, 상태가 모두 얽혀 있기 때문이다.

먼저 primitive를 만든다.

• color/blue/600

• color/white

• space/12

• space/16

• radius/8

그다음 semantic을 만든다.

• color/action/primary → color/blue/600

• color/text/on-action → color/white

• radius/control/default → radius/8

마지막으로 component를 만든다.

• button/bg/primary/default → color/action/primary

• button/text/primary/default → color/text/on-action

• button/padding/x/md → space/16

• button/padding/y/md → space/12

• button/radius/default → radius/control/default

이 구조의 장점은 변경의 방향이 아주 명확하다는 점이다. 브랜드 메인 색이 바뀌면 color/action/primary의 연결만 바꾸면 된다. 버튼만 특별히 더 둥글게 만들고 싶다면 button/radius/default만 조정하면 된다. 다크 모드에서 텍스트 대비를 높이고 싶다면 color/text/on-action의 mode 값만 수정하면 된다.

그리고 AI에게도 이 구조는 친절하다. red/600보다 color/feedback/error가 낫고, color/feedback/error보다 input/border/error가 더 구체적이다. 즉, 위로 올라갈수록 선택의 여지가 줄고, 결과는 더 일관돼진다.

좋은 이름은 검색을 돕고, 좋은 설명은 판단을 돕는다

토큰 이름은 짧을수록 좋은 게 아니라, 오해가 적을수록 좋다. 특히 AI와 함께 일할 때는 이름만으로 의도를 어느 정도 복원할 수 있어야 한다.

다음 표를 보자.

이름만큼 중요한 것이 설명이다. 사람끼리 일할 때는 설명이 빠져 있어도 버티는 경우가 많다. 하지만 AI는 이름과 값만 가지고는 팀의 금기를 알지 못한다. 그래서 상위 토큰, 자주 쓰는 토큰, 오남용이 잦은 토큰에는 description을 꼭 넣는 편이 좋다.³

예를 들어 color/feedback/error에 다음과 같은 설명을 붙일 수 있다.

폼 검증 오류, 파괴적 버튼, 시스템 에러 메시지에 사용. 일반적인 강조 색으로 사용하지 않음.

이 한 줄이 있으면 디자이너에게는 기준이 생기고, AI에게는 안전장치가 생긴다.

모든 카테고리에 같은 깊이가 필요한 것은 아니다

3계층 아키텍처라고 해서 모든 토큰이 반드시 똑같이 세 층을 지나야 하는 것은 아니다. 색상은 semantic 층이 거의 필수지만, spacing이나 radius는 팀에 따라 primitive에서 component로 바로 연결해도 충분할 수 있다.

예를 들어 color는 의미가 중요하므로 semantic이 강하게 필요하다. 반면 spacing은 space/4, space/8, space/16 같은 스케일만 잘 정리되어 있으면 많은 경우 그 자체로도 충분히 일관성을 유지할 수 있다. 물론 대형 조직이라면 spacing/component/button/padding처럼 더 세밀하게 나눌 수도 있다.

중요한 것은 층의 숫자를 억지로 맞추는 일이 아니다. 어느 영역에서 의미 충돌이 자주 나는지, 어느 영역을 AI가 자주 잘못 고르는지 보고 깊이를 조정하는 일이다.

시작은 작게, 규칙은 단단하게

처음부터 모든 컴포넌트를 토큰화할 필요는 없다. 오히려 작은 세트로 시작하는 편이 성공 확률이 높다. 추천하는 최소 출발선은 이 정도다.

• Primitive: color, space, radius, type size

• Semantic: text, background, border, action, feedback

• Component: button, input, card

이 정도만 잡아도 파일의 톤이 정리되기 시작한다. 버튼과 입력창만 안정돼도 제품 전체의 인상이 꽤 단정해진다. 이후에는 사용량이 많고 변경 비용이 큰 컴포넌트부터 차례로 component 토큰을 늘리면 된다.

중요한 것은 처음부터 완벽한 토큰 사전을 만드는 일이 아니다. 디자이너, 개발자, AI가 같은 말을 쓰도록 공용 문법을 세우는 일이다.

자주 실패하는 패턴

토큰 시스템은 복잡해서 실패하는 경우보다, 애매해서 실패하는 경우가 더 많다. 특히 아래 네 가지는 초반에 가장 자주 만난다.

• Primitive를 바로 컴포넌트에 적용한다.

• Semantic 이름이 값 중심이라 역할을 설명하지 못한다.

• Component 토큰을 너무 촘촘하게 만들어 아무도 찾지 못한다.

• 피그마 이름과 코드 이름이 달라서 동기화 과정에 번역이 필요해진다.

첫 번째 실수는 AI 시대에 특히 치명적이다. primitive가 직접 쓰이기 시작하면 semantic 층은 장식품이 되고, AI는 가장 가까운 raw value를 집어 든다. 두 번째와 세 번째는 인간에게도 괴롭다. 이름이 애매하면 검색이 안 되고, 종류가 너무 많으면 선택이 안 된다. 네 번째는 운영 단계에서 가장 비싸다. 번역표가 생기는 순간, 시스템은 느리게 무너지기 시작한다.⁴

기억해야 할 한 문장

토큰은 값을 정리하는 도구가 아니다. 판단을 재사용하는 도구다.

Primitive는 무엇이 존재하는지 말하고, Semantic은 왜 쓰는지 말하고, Component는 정확히 어디에 쓰는지 말한다. 이 세 층이 분리되어 있을수록 사람은 덜 헷갈리고, AI는 덜 멋대로 한다.

결국 좋은 디자인 시스템은 화면만 예쁘게 만드는 시스템이 아니다. 디자이너의 의도가 흔들리지 않게 전달되는 시스템이다. 그리고 AI 시대의 토큰 아키텍처는 바로 그 전달력을 설계하는 일이다.

참고

¹Update 1: Tokens, variables, and styles – Figma Learn - Help Center

²Intro to Design Tokens  Tokens Studio for Figma

³Design tokens that AI can actually read

⁴Figma MCP + AI: design tokens from variables to production JSON