용어 · 앱·웹 화면 제작

디자인 토큰 한 파일

Design Tokens in One File

색, 간격, 모서리, 글자 크기에 이름을 붙여 한 파일에 모아 두고 화면은 그 이름만 읽게 하는 방법이다. 다크 모드는 같은 이름에 값 한 벌을 더하는 일로 줄어든다.

중급설명변화와 비교

01직접 돌려 보기

‘연출 전’은 대충 시켰을 때를 가정해 만든 화면이고 실제 AI 결과와 다를 수 있다.

연출 전흔한 첫 결과
연출 후완성본
0.00초 / 4.0초

02이름으로 시키는 지시문

대충 시킴색이랑 크기 값 정리해서 일관되게 해줘→ ‘일관되게’가 어느 값을 하나로 합치라는 말인지 정해지지 않아, 화면 코드에 hex 와 px 가 그대로 남은 채 비슷하게만 맞춰져 나오곤 한다
이름으로 시킴토큰 11개를 한 파일에 정하고 화면은 이름만 읽게 해줘. radius.m 10px, space.4 16px, color.accent 라이트 #d92b12, 다크는 같은 이름에 값만 바꾸고 대비 4.5 미만은 붉게 표시해줘→ 직접 쓴 값 13개가 0개가 되고 모서리 3종이 10px 하나로 모이며, 3.0초에 라이트에서 다크로 바뀌는 앱 화면
Claude Code · Codex에 그대로 붙여 넣기

장면: 640×360 무대 왼쪽에 tokens.json 창, 오른쪽에 그 파일만 읽어 그린 앱 화면(주문 현황: 큰 카드 하나, 작은 카드 둘, 입력칸, 버튼)을 둔다.

토큰: color.bg, color.surface, color.ink, color.ink-muted, color.accent, color.on-accent, space.4, radius.m, text.body, text.display, btn.bg. btn.bg 는 {color.accent} 별칭으로 두고, 화면 코드에는 색 hex 나 px 숫자를 직접 쓰지 않는다.

값: radius.m 은 10px, space.4 는 16px, text.body 는 14px, text.display 는 32px, color.accent 라이트 #d92b12 와 다크 #ff7a5c.

다크: 같은 이름에 값만 바꾼 두 번째 벌을 만들고 3.0초에 라이트에서 다크로 0.6초 동안 바꾼다(inOutCubic). 글자 대비는 코드가 계산해 4.5:1 미만이면 붉게 표시한다.

상태: 토큰마다 adopted, unverified, conflict 중 하나를 달고, 다른 복사본과 값이 다르면 conflict 로 적는다.

금지: 이름에 값을 넣는 것(gray-14 같은 이름), 별칭이 서로를 가리키는 순환, 화면 코드에 직접 박은 값.

연출 전: 같은 카드 셋이 6, 8, 10px 제각각 모서리와 조금씩 다른 흰색을 직접 쓴 화면.

구현에 쓰이는 기술: 토큰 파일은 JSON 이고 토큰은 $value 를 가진 객체다. 별칭은 "{color.accent}" 모양이고, 같은 그룹의 $type 은 아래 토큰이 물려받는다(W3C 2025.10 형식)CSS 에서는 :root 와 [data-theme=dark] 에 --이름: 값 을 두고 화면 규칙은 var(--이름) 만 읽는다별칭은 따라가다 순환하거나 없는 이름이면 오류로 멈추는 변환기를 둔다(조용히 넘어가지 않는다)대비는 두 색의 상대 휘도에서 계산하고 4.5 미만이면 토큰을 저장하기 전에 막는다

03응용 팁

팁은 데모에서 값만 바꿔 같은 장면과 비교한 것이다. AI가 같은 결과를 내는지는 직접 해 봐야 안다.

1

카드가 답답해 보인다

카드와 버튼이 각지고 글자가 가장자리에 붙어 보인다는 말이 나왔을 때

지시문에서
radius.m 은 10px, space.4 는 16px
이렇게 바꾸세요
radius.m 은 20px, space.4 는 20px
그러면
모서리 토큰 한 줄과 여백 토큰 한 줄만 바꿨는데 큰 카드, 작은 카드 둘, 입력칸, 버튼이 모두 20px 로 둥글어지고 카드 글자가 가장자리에서 4px 더 떨어진다.
확인
2

강조색을 초록으로?

브랜드 색을 붉은색에서 바꾸자는 말이 나왔을 때

지시문에서
color.accent 라이트 #d92b12
이렇게 바꾸세요
color.accent 라이트 #0f7a4a
그러면
큰 카드와 버튼이 붉은색에서 초록으로 한 번에 바뀐다. 흰 글자와의 대비는 4.9에서 5.4로 기준 4.5를 계속 넘고, 다크 값은 건드리지 않아 3.0초 뒤에는 다시 붉은 계열이 된다.
확인

04만드는 순서

각 단계의 버튼을 누르면 위의 데모가 그 단계까지의 모습으로 바뀝니다.

  1. 이름을 붙이고 이름으로 읽게 한다

    연출 전 화면은 값 13개(모서리 5곳, 카드 바탕 2곳, 강조색 2곳 등)를 규칙마다 직접 썼다. 같은 뜻의 모서리가 6, 8, 10px 세 가지이고 카드 바탕은 두 가지 흰색이다. 1단계에서는 줄마다 0.11초 간격으로 값이 {color.accent} 같은 이름으로 바뀐다. 직접 쓴 값 13이 0이 되고 모서리는 10px 하나로 모인다. 이 숫자는 화면에서 코드가 센 값이다. 비교로, 실제 CSS 한 파일은 변수가 0개이고 hex 색이 30곳에 그대로 박혀 있었다.

    const tv = tokAt(tok, mode);
    value = typeof lit === 'number' ? lerp(lit, tv, p) : mix(lit, tv, p);
  2. 이름은 그대로 두고 값만 두 벌

    같은 이름 11개에 라이트 값과 다크 값을 한 벌씩 둔다. 3.0초부터 0.6초 동안 화면이 라이트에서 다크로 바뀌고, 아래 줄의 대비가 코드로 다시 계산된다. 끝 장면의 대비는 ink 15.9, muted 7.1, 버튼 7.1 로 기준 4.5 를 넘는다. 실제 CSS 에서도 라이트와 다크 블록의 변수 이름 24개가 같았다. 한편 이 사이트 공용 틀은 다크 값 14개를 두 곳에 똑같이 적어 두어서, 한쪽만 고치면 어긋난다.

    const tokAt = (name, mp) => mix(resolve(name, 0), resolve(name, 1), mp);
    mp = inOutC(seg(t, SWITCH_T, SWITCH_T + FADE));
  3. 값마다 상태와 출처를 단다

    토큰 11개에는 adopted 9, unverified 1, conflict 1 이 붙는다. conflict 는 모서리 중간값처럼 복사본마다 값이 다른 곳(10px 대 6px)이다. 정본을 정하는 일은 여기서 하지 않는다. 상태 칸이 없으면 ‘쓰는 값’과 ‘확인된 값’이 섞인다. 영상용 공통 규격은 같은 방식으로 값마다 출처와 상태를 달았다.

    const count = (k) => TOK.filter((r) => r[4] === k).length;
    // adopted 9, unverified 1, conflict 1

05전문용어 풀이

디자인 토큰Design token

색, 간격, 모서리, 글자 크기 같은 값에 이름을 붙여 한 파일에 둔 것. 화면은 값 대신 이름을 읽는다.

AI에게“색은 hex 대신 color.accent 같은 이름으로만 읽어 줘”
별칭Alias

값을 직접 쓰지 않고 다른 토큰을 가리키는 토큰. 원본 하나를 고치면 가리키는 쪽이 모두 따라온다.

AI에게btn.bg 는 {color.accent} 별칭으로
역할 이름Semantic name

값이 아니라 쓰임으로 지은 이름(text.body). 값을 넣은 이름은 값이 바뀌면 거짓이 된다.

AI에게“이름에 숫자를 넣지 말고 역할로 지어 줘”
모드Mode (theme)

같은 이름에 값 한 벌을 더 두는 것. 라이트와 다크가 각각 한 벌이다.

AI에게이름은 그대로, 다크 값만 한 벌 더
상태 칸Status

값이 확인된 것인지 가르는 꼬리표. adopted 는 쓰기로 한 값, unverified 는 확정 전, conflict 는 곳마다 값이 다른 것.

AI에게토큰마다 status 와 출처 한 줄

06결과를 받으면 이것부터 확인

  • 연출 전 화면 아래 줄에 ‘직접 쓴 값 13 · 모서리 3종 · 카드 바탕 2종’이 적힌다
  • 1단계가 끝난 화면의 아래 줄이 ‘직접 쓴 값 0 · 이름으로 읽기 13 · 별칭 1’이고 세 카드 모서리가 같은가?
  • 3단계 아래 줄에 토큰 11, adopted 9, unverified 1, conflict 1 이 적히고 다크 화면으로 끝난다

07이럴 때 쓰세요

  • 새 앱 화면을 시작하면서 색, 간격, 모서리, 글자 크기를 코드보다 먼저 한 파일로 정하는 순서
  • AI 가 만든 화면 코드에 박힌 hex 와 px 숫자를 이름으로 바꾸라고 시킬 때
  • 다크 모드를 화면 다시 그리기가 아니라 값 한 벌 더 만들기로 줄이는 일
  • 프로젝트마다 값이 다를 때 어느 쪽이 확인된 값인지 상태 칸으로 표시하기

08같이 쓰는 용어

09근거와 확인 범위

‘확인’은 출처 문서에서 사실로 확인한 내용, ‘추정’은 결과물을 보고 추론한 내용, ‘원본 없음’은 흔히 쓰이지만 대표 원본 사례를 확인하지 못해 성공 사례로 제시하지 않은 기법이다.

  • 확인2026-11-14 열람(본문 114,216자 중 앞 100,000자까지 읽음). 토큰은 $value 를 가진 객체이고 $type 은 없으면 가까운 그룹에서 물려받으며 값에서 추측하지 않는다. 별칭은 "{group.token}", 파일은 JSON, 권장 확장자 .tokens.json. 색은 colorSpace 와 components, 치수는 value 와 unit(px 또는 rem). W3C Design Tokens Community Group — Design Tokens Format Module 2025.10
  • 확인2026-11-14 열람(앞 100,000자). 사용자 지정 속성은 --이름: 값 으로 적고 var(--이름, 대체값) 으로 읽는다. 이름은 대소문자를 가리고, :root 에 두면 문서 전체에서 쓰이며 자손에게 상속된다. var() 는 속성 이름, 선택자, 미디어 쿼리, 컨테이너 쿼리 안에서는 쓸 수 없다. MDN — Using CSS custom properties (variables)
  • 확인[기록] 영상 공장들이 쓰는 공통 규격 파일이 W3C 2025.10 형식으로 12개 그룹(캔버스, 안전 여백, 글꼴, 글자 단계, 간격, 색 등)을 담고, 값마다 출처와 상태(adopted, unverified)를 확장 칸에 단다. 충돌하는 값은 숨기지 않고 따로 적는다. 운영 규칙은 ‘진 뒤에는 공장 코드의 숫자가 아니라 이 파일을 고친다’. 영상 1080 폭 기준이라 앱 화면용 글자 단계는 들어 있지 않다(2026-10-20 기록, 이번에 파일을 다시 열어 그룹 이름 확인).
  • 확인[기록] 같은 사실이 공장 코드 여러 곳에 따로 적혀 있었다. 안전 여백 값은 값 묶음 3벌에 같은 값 복제 5곳, 색 리터럴은 고유 408종, 강조 노랑은 14가지 변형. 코드를 열어 센 값(정적 읽기)이고 가동 결과를 잰 것은 아니며 코드가 매일 바뀌어 숫자는 몇 건 달라질 수 있다고 적혀 있다(2026-10-20).
  • 확인[측정, 2026-11-14 이번 조사] 화면 CSS 파일의 변수와 직접 쓴 색을 정규식으로 셌다(주석 제외, hex 3~8자리, 선택자 오탐 0건 확인). 공개 사이트 쪽 기본 CSS 한 파일은 변수 정의 0, var() 0, hex 30곳(18가지), 본문 글꼴 Arial. 같은 프로젝트의 다른 CSS 한 파일은 hex 444곳(362가지)에 var() 59곳. 이 사이트 공용 틀은 변수 정의 45, var() 52, 변수 밖 hex 0. 같은 프로젝트의 또 다른 화면 CSS 는 정의 86에 var() 818, 변수 밖 hex 64. 줄 단위 문법을 단순화한 셈이라 몇 곳은 달리 셀 수 있다.
  • 확인[측정, 2026-11-14] 같은 화면 CSS 의 복사본 두 개를 비교했다. 한쪽은 --t12 가 12px, 다른 쪽은 이름은 --t12 인데 값이 14px 이고, 모서리 중간값 --r-m 은 10px 대 6px 이다. 이름에 값을 넣으면 값이 바뀔 때 이름이 거짓말을 한다는 사례. 어느 복사본이 지금 서비스되는지는 확인하지 못했다. 같은 CSS 의 라이트와 다크 블록은 변수 이름 24개가 같고 다크에만 1개가 더 있다.