카드가 답답해 보인다
카드와 버튼이 각지고 글자가 가장자리에 붙어 보인다는 말이 나왔을 때
- 지시문에서
- radius.m 은 10px, space.4 는 16px
- 이렇게 바꾸세요
- radius.m 은 20px, space.4 는 20px
- 그러면
- 모서리 토큰 한 줄과 여백 토큰 한 줄만 바꿨는데 큰 카드, 작은 카드 둘, 입력칸, 버튼이 모두 20px 로 둥글어지고 카드 글자가 가장자리에서 4px 더 떨어진다.
Design Tokens in One File
색, 간격, 모서리, 글자 크기에 이름을 붙여 한 파일에 모아 두고 화면은 그 이름만 읽게 하는 방법이다. 다크 모드는 같은 이름에 값 한 벌을 더하는 일로 줄어든다.
‘연출 전’은 대충 시켰을 때를 가정해 만든 화면이고 실제 AI 결과와 다를 수 있다.
색이랑 크기 값 정리해서 일관되게 해줘→ ‘일관되게’가 어느 값을 하나로 합치라는 말인지 정해지지 않아, 화면 코드에 hex 와 px 가 그대로 남은 채 비슷하게만 맞춰져 나오곤 한다
토큰 11개를 한 파일에 정하고 화면은 이름만 읽게 해줘. radius.m 10px, space.4 16px, color.accent 라이트 #d92b12, 다크는 같은 이름에 값만 바꾸고 대비 4.5 미만은 붉게 표시해줘→ 직접 쓴 값 13개가 0개가 되고 모서리 3종이 10px 하나로 모이며, 3.0초에 라이트에서 다크로 바뀌는 앱 화면
장면: 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 미만이면 토큰을 저장하기 전에 막는다
팁은 데모에서 값만 바꿔 같은 장면과 비교한 것이다. AI가 같은 결과를 내는지는 직접 해 봐야 안다.
카드와 버튼이 각지고 글자가 가장자리에 붙어 보인다는 말이 나왔을 때
브랜드 색을 붉은색에서 바꾸자는 말이 나왔을 때
각 단계의 버튼을 누르면 위의 데모가 그 단계까지의 모습으로 바뀝니다.
연출 전 화면은 값 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);
같은 이름 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));
토큰 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
색, 간격, 모서리, 글자 크기 같은 값에 이름을 붙여 한 파일에 둔 것. 화면은 값 대신 이름을 읽는다.
값을 직접 쓰지 않고 다른 토큰을 가리키는 토큰. 원본 하나를 고치면 가리키는 쪽이 모두 따라온다.
값이 아니라 쓰임으로 지은 이름(text.body). 값을 넣은 이름은 값이 바뀌면 거짓이 된다.
같은 이름에 값 한 벌을 더 두는 것. 라이트와 다크가 각각 한 벌이다.
값이 확인된 것인지 가르는 꼬리표. adopted 는 쓰기로 한 값, unverified 는 확정 전, conflict 는 곳마다 값이 다른 것.
‘확인’은 출처 문서에서 사실로 확인한 내용, ‘추정’은 결과물을 보고 추론한 내용, ‘원본 없음’은 흔히 쓰이지만 대표 원본 사례를 확인하지 못해 성공 사례로 제시하지 않은 기법이다.