디자인 가이드가 업데이트될 때마다 개발자가 수동으로 컬러 코드와 간격 값을 코드에 옮겨 적는 비효율적인 상황, 아마 실무에서 한 번쯤은 겪어보셨을 거예요. 기껏 구축해 둔 디자인 시스템이 디자이너의 피그마 안에서만 머물고 개발 환경과 동기화되지 않는다면 그것은 살아있는 시스템이라기보다 정적인 문서에 가깝습니다.
이 글에서는 피그마의 변수(Variables) 기능을 활용해 디자인 토큰을 정의하고, 이를 Style Dictionary를 통해 실제 코드 베이스로 자동 배포하는 엔지니어링 파이프라인 구축 방법을 다룹니다. 이 과정을 이해하고 나면 소모적인 커뮤니케이션 비용을 줄이고, 디자인 변경 사항이 즉시 프로덕션에 반영되는 진정한 의미의 DesignOps를 경험하실 수 있습니다.
피그마 변수 설정, 왜 단순한 스타일 지정보다 강력할까
기존의 피그마 스타일(Styles)이 단순히 색상이나 텍스트의 외형을 정의했다면, 변수(Variables)는 프로그래밍의 변수 개념을 디자인 도구에 이식한 것입니다. 단순히 #3B82F6이라는 값을 전달하는 것이 아니라 button-primary-bg라는 논리적 이름을 전달할 수 있게 된 것이죠.
실무에서 변수를 설정할 때는 논리적 위계를 나누는 것이 핵심입니다. 단순히 ‘Red 500’이라고 명명하면 나중에 브랜드 컬러가 파란색으로 바뀔 때 모든 코드를 수정해야 합니다. 하지만 이를 brand-primary라는 에일리어스(Alias) 토큰으로 연결해두면, 기본 값만 바꿔도 전체 시스템이 동기화됩니다. 이러한 계층 구조는 다크 모드 전환이나 멀티 브랜드 테마 대응 시에 폭발적인 위력을 발휘합니다.
[💡 에디터의 실무 팁: 토큰의 이름은 ‘어떻게 보이는가(Red)’가 아니라 ‘어떻게 쓰이는가(Action-Danger)’에 집중해서 지어야 나중에 확장이 쉽습니다.]
Style Dictionary를 활용한 크로스 플랫폼 코드 연동
피그마에서 내보낸 JSON 형태의 토큰 데이터를 웹(CSS, SCSS, JSON), iOS(Swift), Android(Kotlin) 등 각 플랫폼에 맞는 포맷으로 변환해 주는 도구가 바로 Style Dictionary입니다. 디자인 엔지니어는 이 도구를 통해 진실의 단일 지점(Single Source of Truth)을 구축할 수 있습니다.
실제로 프로젝트를 진행하다 보면 피그마에서 내보낸 JSON 데이터 구조가 개발자가 사용하려는 라이브러리의 규격과 맞지 않는 경우가 빈번합니다. 이때 Style Dictionary의 ‘Transform’ 기능을 사용하면 해결할 수 있습니다. 예를 들어, 피그마의 픽셀(px) 단위 값을 웹 표준인 rem 단위로 자동 계산하여 변환해 주는 로직을 추가하는 식이죠.
// style-dictionary.config.js 예시
module.exports = {
source: [‘tokens/**/*.json’],
platforms: {
scss: {
transformGroup: ‘scss’,
buildPath: ‘build/scss/’,
files: [{
destination: ‘_variables.scss’,
format: ‘scss/variables’
}]
},
// 안드로이드, iOS 등 추가 플랫폼 설정 가능
}
};
위와 같은 설정 파일을 통해 명령어 한 번으로 수백 개의 토큰을 각 플랫폼별 코드로 배포할 수 있습니다. 수동으로 복사 붙여넣기를 하다가 발생할 수 있는 오타나 누락 문제를 원천적으로 차단하게 됩니다.
트러블슈팅: 다크 모드와 시맨틱 토큰의 충돌 해결
실무에서 가장 골치 아픈 지점은 다크 모드 구현 시 토큰이 꼬이는 상황입니다. 라이트 모드에서의 neutral-100(밝은 회색)이 다크 모드에서는 neutral-900(어두운 회색)으로 매핑되어야 하는데, 이를 단순히 ‘밝기’ 기준으로만 처리하면 가독성 문제가 발생합니다.
저는 이 문제를 해결하기 위해 ‘시맨틱 토큰(Semantic Tokens)’ 레이어를 적극 활용합니다. surface-default라는 중간 매개체 토큰을 만들고, 라이트 모드에서는 white를, 다크 모드에서는 gray-900을 가리키도록 참조 구조를 설계하는 방식입니다. 이렇게 하면 컴포넌트 코드에서는 모드에 상관없이 항상 var(--surface-default)만 참조하면 되므로 로직이 매우 깔끔해집니다.
[💡 에디터의 실무 팁: 다크 모드 작업 시에는 단순히 색상 반전이 아니라, 레이어의 높낮이(Elevation)에 따른 명도 차이를 고려해야 사용자 경험이 깨지지 않습니다.]
접근성(A11y)을 고려한 컴포넌트 설계 가이드
디자인 시스템 엔지니어링의 정점은 접근성입니다. 단순히 색상을 잘 전달하는 것을 넘어, 버튼이나 입력창 같은 컴포넌트가 웹 표준 접근성 가이드(WCAG)를 준수하도록 강제해야 합니다. 토큰 시스템에 최소 명도 대비(Contrast Ratio) 체크 로직을 포함시키는 것을 추천합니다.
예를 들어 테마 컬러를 정의할 때 배경색과 텍스트색의 대비가 4.5:1 미만으로 떨어지면 빌드 과정에서 경고를 띄우거나, 자동으로 보정된 값을 제안하는 자동화 스크립트를 결합할 수 있습니다. 기술은 단순히 예쁜 화면을 만드는 도구가 아니라, 모든 사용자가 소외되지 않고 정보를 얻을 수 있게 돕는 다리가 되어야 하니까요.
자주 묻는 질문(FAQ)
Q1. 피그마 변수와 스타일 중 무엇을 먼저 사용해야 하나요? 색상이나 수치 같은 정형 데이터는 ‘변수’를 우선적으로 사용하고, 그라데이션이나 복잡한 이펙트(Shadow)처럼 변수가 지원하지 않는 영역은 ‘스타일’을 병행해서 사용하는 것이 현재 가장 현실적인 실무 대안입니다.
Q2. Style Dictionary 적용 시 버전 관리는 어떻게 하나요? 디자인 토큰 전용 GitHub 레포지토리를 별도로 생성하는 것이 좋습니다. 피그마에서 토큰이 업데이트되어 JSON이 Push되면, GitHub Actions가 트리거되어 자동으로 Style Dictionary를 실행하고 각 플랫폼 라이브러리에 npm 패키지 형태로 배포하는 파이프라인을 구축하세요.
Q3. 개발자가 직접 JSON을 수정해도 되나요? 절대 추천하지 않습니다. 수정 사항이 있다면 반드시 피그마(Source of Truth)에서 수정한 뒤 배포 프로세스를 거쳐야 합니다. 코드를 직접 수정하기 시작하면 디자인과 코드의 싱크가 깨지며 시스템은 금세 붕괴됩니다.