Ari.dev

배포된 토큰의 알파값이 사라져 있었다

Figma 스펙과 대조하다 발견한 디자인 토큰 알파값 유실 버그. Tokens Studio의 hex/alpha 분리 필드가 원인이었고, 전수조사와 렌더값 검증으로 마무리한 과정.

2분 읽기디자인 시스템

Tooltip을 만들려고 Figma 스펙을 보다가 배경색이 #151b26cc(알파 80%)인 걸 확인했다. 그런데 우리 토큰 파일에는 #151B26으로, 알파가 없었다.

같은 토큰을 Modal 오버레이(scrim)가 쓰고 있었다. Modal을 열면 뒤 화면이 완전히 가려진다. 반투명이어야 하는데 불투명이었다. 이미 0.1.1로 배포된 상태였다.

원인: hex와 alpha가 별도 필드였다

Tokens Studio가 내보내는 색상 값은 hex와 alpha를 별도 필드로 둔다.

"color/surface/opacity/background": { "hex": "#151B26", "alpha": 0.8 }

tokens.json을 만들 때 hex만 읽고 alpha를 무시해서 알파가 사라졌다. 빌드 스크립트는 값을 변형하지 않고 그대로 출력하므로, 빌드 문제가 아니라 소스 데이터 문제였다.

같은 유형이 3개 있었는데 2개는 이미 고쳐져 있었다

토큰alpha상태
drop-shadow/toast0.12primitive 참조로 수정됨
drop-shadow/modal0.2이미 다른 커밋에서 수정됨
surface/opacity/background0.8누락

같은 유형의 버그를 고친 커밋이 있었는데, 이 토큰만 빠져 있었다.

해결: primitive 참조로 변경

알파가 살아 있는 primitive 토큰을 참조하도록 바꿨다.

{
  "var": "--h2o-color-surface-opacity-background",
  "light": "var(--h2o-color-opacity-gray-80)",
  "dark": "var(--h2o-color-opacity-white-30)"
}

Figma 원본 hex·alpha와 primitive 값이 정확히 일치하는지 대조 확인했다.

전수조사

같은 실수가 더 있는지 Tokens Studio 소스 전체에서 알파가 1 미만인 토큰을 전부 뽑았다. light·dark 각 3개, 총 6개. 추가 피해 없음을 확인했다.

검증: 실제 렌더값으로 확인

빌드 산출물을 Storybook에 직접 연결해서 브라우저 콘솔로 실제 렌더 값을 확인했다.

getComputedStyle(document.documentElement)
  .getPropertyValue('--h2o-color-surface-overlay-scrim')

수정 전 → '#151B26'                (알파 없음)
수정 후 → 'rgba(21, 27, 38, 0.80)'  (알파 80%)

결과

  • 배포된 버전의 버그를 소비처가 Modal을 쓰기 전에 잡았다.
  • 다크모드는 참조 체인이 동일해서 자동으로 같이 해결됐다.
  • 재발 방지: 알파가 있는 semantic 토큰은 hex 직접 사용을 금지하고, primitive 참조를 강제하기로 했다.

Figma 원본과 최종 산출물을 대조하는 절차가 없었다면 이 버그는 눈에 잘 띄지 않았을 것이다. "Modal이 좀 어둡네" 정도로 넘어가기 쉬운 차이였다. 원천(Figma)과 산출물(CSS 변수)을 나란히 놓고 대조하는 게 핵심이었다.

같은 날 다른 두 가지 문제도 함께 발견했다.

댓글