피그마에서 정성껏 정의한 디자인 토큰이 개발 환경으로 넘어오는 과정에서 “복사해서 붙여넣기”라는 원시적인 수작업에 의존하고 있지는 않으신가요? 디자이너가 헥사 코드를 하나 바꿀 때마다 개발자에게 슬랙을 보내고, 개발자는 소스 코드 어딘가에 숨겨진 변수를 찾아 수정하는 방식은 단순히 귀찮은 일을 넘어 휴먼 에러의 온상이 됩니다.
이런 소모적인 과정을 단번에 해결해 주는 도구가 바로 아마존에서 만든 Style Dictionary입니다. Style Dictionary는 디자인 토큰(JSON)을 입력받아 웹(CSS, SCSS), 안드로이드, iOS 등 각 플랫폼에 맞는 변수 형태로 변환해 주는 ‘디자인 데이터 빌드 시스템’입니다. 이번 글에서는 JSON 형태의 디자인 데이터를 실제 CSS 변수로 자동 배포하는 파이프라인 구축법을 실무 관점에서 상세히 살펴보겠습니다.
왜 Style Dictionary가 DesignOps의 핵심인가요?
디자인 시스템 엔지니어링의 핵심은 ‘진실의 단일 지점(Single Source of Truth)’을 만드는 것입니다. 피그마 변수(Variables)나 토큰 플러그인에서 추출한 JSON 파일은 기계는 읽을 수 있지만, 브라우저가 바로 해석할 수는 없습니다. 그렇다고 매번 수동으로 CSS 파일을 만드는 것은 시스템의 확장성을 가로막는 장애물이 됩니다.
Style Dictionary를 사용하면 디자인 데이터가 코드 베이스의 ‘의존성’이 됩니다. 즉, 디자인 변경 사항이 발생하면 JSON 파일만 교체하고 빌드 명령어를 실행하는 것만으로 프로젝트 전체의 스타일이 동기화되는 것이죠. 이는 개발자가 디자인 세부 사항을 신경 쓰지 않고 비즈니스 로직에만 집중할 수 있는 환경을 만들어 줍니다.
[💡 에디터의 실무 팁: 단순 변환을 넘어 프로젝트의 규모가 커질수록 Style Dictionary의 ‘Transform’ 기능을 활용해 네이밍 컨벤션을 강제하거나 단위를 일괄 변경하는 등의 전처리가 필수적입니다.]
설치부터 첫 번째 빌드까지: 5분 완성 파이프라인
가장 먼저 프로젝트 폴더에서 npm을 통해 패키지를 설치해야 합니다. 터미널을 열고 npm install style-dictionary를 입력하세요. 설치가 완료되었다면 프로젝트 루트에 tokens/ 폴더를 만들고 디자인 데이터가 담긴 color.json 파일을 생성해 보겠습니다.
{
“color”: {
“brand”: {
“primary”: { “value”: “#007bff” },
“secondary”: { “value”: “#6c757d” }
}
}
}
이제 이 JSON을 CSS로 변환하기 위한 설정 파일인 config.js를 작성할 차례입니다. JSON 형식보다는 자바스크립트 형식을 추천하는데, 그 이유는 나중에 단위 변환이나 복잡한 로직을 추가하기에 훨씬 유연하기 때문입니다.
module.exports = {
source: [‘tokens/**/*.json’],
platforms: {
css: {
transformGroup: ‘css’,
buildPath: ‘build/css/’,
files: [{
destination: ‘variables.css’,
format: ‘css/variables’
}]
}
}
};
설정이 끝났다면 터미널에 npx style-dictionary build를 입력해 보세요. build/css/variables.css 파일이 생성되면서 :root 스코프 안에 --color-brand-primary: #007bff;와 같은 형태로 변수가 깔끔하게 담긴 것을 확인할 수 있습니다.
실무 트러블슈팅: px 단위를 rem으로 자동 변환하기
실무에서 가장 많이 겪는 문제 중 하나는 피그마에서 내보낸 JSON 데이터가 픽셀(px) 단위라는 점입니다. 현대적인 웹 접근성과 반응형 설계를 위해서는 이를 rem 단위로 변환해야 하죠. 매번 계산기를 두드릴 수는 없으니 Style Dictionary의 커스텀 트랜스포머(Custom Transformer)를 활용해 해결해 봅시다.
저는 실제 프로젝트에서 16px을 1rem으로 계산하는 로직을 빌드 프로세스에 직접 포함시킵니다. 아래 코드처럼 registerTransform을 사용하면 빌드 시점에 모든 수치 데이터를 rem으로 자동 계산해 줍니다.
const StyleDictionary = require(‘style-dictionary’);
StyleDictionary.registerTransform({
name: ‘size/pxToRem’,
type: ‘value’,
matcher: (token) => token.attributes.category === ‘size’,
transformer: (token) => `${token.value / 16}rem`
});
이렇게 설정해 두면 디자인 수정 시 픽셀 값만 업데이트해도 코드는 자동으로 접근성이 최적화된 rem 단위로 배포됩니다. 개발자는 그저 생성된 파일을 import 해서 쓰기만 하면 됩니다.
[💡 에디터의 실무 팁: 트랜스포머를 적용할 때는 matcher 함수를 정교하게 짜야 합니다. 색상 값이나 일반 문자열 토큰까지 계산 로직이 돌아가서 에러가 나는 경우가 생각보다 빈번하기 때문이죠.]
성공적인 디자인 시스템 동기화를 위한 제언
Style Dictionary 도입은 단순히 기술적인 변화를 넘어 협업 문화의 변화를 요구합니다. 디자인 토큰의 JSON 구조가 깨지면 빌드 에러가 발생하므로, 디자이너와 개발자가 사전에 JSON 스키마를 엄격하게 합의해야 합니다.
또한, 깃허브 액션(GitHub Actions)과 같은 CI/CD 도구와 연동하는 것을 강력히 권장합니다. 피그마에서 토큰이 업데이트되어 레포지토리에 푸시되는 순간, Style Dictionary가 자동으로 돌아가며 npm 패키지 버전까지 올려주는 파이프라인을 구축해 보세요. 이것이 바로 전문가들이 말하는 ‘진정한 의미의 DesignOps’이자, 비즈니스 속도를 획기적으로 높이는 비결입니다.
자주 묻는 질문(FAQ)
Q1. SCSS나 리액트용 JSON 등 여러 포맷을 동시에 만들 수 있나요? 네, config.js의 platforms 객체 안에 scss, js, json 등 필요한 플랫폼 설정을 추가하기만 하면 빌드 한 번에 모든 포맷의 파일이 동시에 생성됩니다.
Q2. 피그마에서 JSON을 어떻게 자동으로 추출하나요? ‘Tokens Studio’ 플러그인이나 피그마의 최신 기능인 ‘Variables’를 사용하면 됩니다. 특히 Variables를 사용한다면 별도의 유료 플러그인 없이도 API를 통해 JSON 데이터를 가져와 Style Dictionary와 연결할 수 있습니다.
Q3. 빌드된 파일이 너무 많은데 어떻게 관리하는 게 좋을까요? 배포용 파일은 별도의 dist나 build 폴더로 격리하고, 버전 관리는 소스인 tokens/*.json 파일 위주로 진행하세요. 빌드된 결과물은 프로젝트 배포 시점에 생성되도록 설정하는 것이 깔끔합니다.