Style Dictionary: 토큰 변환 및 생성

Style Dictionary(Amazon이 만든 도구)는 JSON 형식의 디자인 토큰 정의를 받아 CSS 사용자 지정 속성, JavaScript ES 모듈, Sass 변수, iOS Swift 상수, Android XML 리소스 및 직접 정의하는 모든 사용자 지정 형식으로 출력하는 빌드 도구입니다. 하나의 진실 공급원으로 여러 형식을 출력할 수 있습니다.

npm install --save-dev style-dictionary로 설치합니다. npx style-dictionary init으로 프로젝트 구조를 초기화하면 config.json(또는 config.js)과 tokens/ 디렉터리가 생성됩니다. 설정은 Style Dictionary에 토큰 파일의 위치와 출력 파일을 작성할 위치를 알려 줍니다.

Style Dictionary는 끝 노드에 value 속성이 있는 중첩 JSON 구조를 사용합니다. 예를 들면 { "color": { "primary": { "500": { "value": "#3b82f6" } } } }과 같습니다. 값으로 이어지는 경로(color, primary, 500)는 변환 후 토큰 이름이 되며, 일반적으로 color-primary-500 또는 --color-primary-500 형식으로 지정됩니다.

npx style-dictionary build --config config.json을 실행합니다. 또는 package.json의 스크립트에 설정되어 있다면 style-dictionary build를 실행합니다. Style Dictionary는 설정된 원본 위치에서 모든 토큰 파일을 읽고, 변환을 적용한 다음, 설정된 출력 대상에 결과를 작성합니다. 토큰 형식의 오류는 파일 이름 및 경로와 함께 보고됩니다.

config.json은 플랫폼을 정의합니다. css는 사용자 지정 속성이 포함된 CSS 파일을 출력하고, js는 JS 객체를 출력하며, scss는 Sass 변수를 출력합니다. 각 플랫폼은 출력 디렉터리, 파일 이름, 형식(템플릿), 적용할 변환(이름과 값의 처리 함수)을 지정합니다.

Style Dictionary에는 기본 제공 변환이 포함되어 있습니다. name/cti/kebab은 중첩 경로를 color-primary-500으로 변환하고, name/cti/camel은 colorPrimary500을 생성하며, size/rem은 픽셀 값을 rem으로 변환하고, color/hex는 색상을 16진수로 정규화합니다. 변환은 조합할 수 있으며 지정된 순서대로 적용됩니다.

StyleDictionary.registerTransform()으로 사용자 지정 변환을 등록할 수 있습니다. 예를 들어 픽셀 값을 iOS 포인트로 변환하거나 모든 토큰 이름에 회사별 접두사를 추가하는 변환을 만들 수 있습니다. 사용자 지정 변환을 사용하면 출력 전에 값을 처리하는 방식을 완전히 제어할 수 있습니다.

사용자 지정 형식은 출력 파일의 템플릿을 정의합니다. StyleDictionary.registerFormat()은 변환된 토큰 사전을 받아 문자열, 즉 파일 내용을 반환합니다. 토큰을 TypeScript 형식, React 테마 객체, Tailwind 설정 확장 또는 기술 스택에 필요한 다른 형식으로 출력할 수 있습니다.

빌드가 끝나면 전역 스타일시트에서 CSS 출력을 가져옵니다. @import './tokens/tokens.css'를 사용합니다. 컴포넌트나 Tailwind 설정에서는 JS 출력을 가져옵니다. import tokens from './tokens/tokens.js'를 사용합니다. CSS는 런타임 테마 적용을 위한 사용자 지정 속성을 제공하고, JS는 Tailwind와 JavaScript 로직에 사용할 타입이 지정된 상수를 제공합니다.

Style Dictionary는 중괄호를 사용한 토큰 참조를 지원합니다. { "value": "{color.primary.500}" }과 같이 작성합니다. 이렇게 하면 의미 토큰 별칭이 생성되어 의미 토큰이 기본 토큰을 참조하게 됩니다. 빌드 시 Style Dictionary는 참조를 해석하고 최종 값을 출력합니다. 형식에 따라 CSS 변수 참조를 출력할 수도 있습니다.

애플리케이션을 빌드하기 전에 토큰이 항상 다시 생성되도록 Style Dictionary를 prebuild npm 스크립트로 실행합니다. package.json에 "prebuild": "style-dictionary build"를 추가합니다. 이렇게 하면 토큰 JSON 파일의 변경 사항이 React 빌드에서 처리되기 전에 CSS 및 JS 출력에 반영됩니다.

Style Dictionary에서 변환의 목적은 무엇입니까?

Style Dictionary는 토큰 JSON을 CSS 변수, JS 모듈, Sass, iOS, Android 등 모든 출력 형식으로 변환합니다. 토큰 JSON은 value 끝 노드가 포함된 중첩 객체를 사용합니다. 변환은 이름과 값(camelCase, 픽셀에서 rem으로의 변환)을 처리하고, 형식은 출력 템플릿을 정의합니다. 토큰 참조({color.primary.500})를 사용하면 의미 토큰 별칭을 만들 수 있습니다. prebuild 스크립트로 자동화하면 React 빌드 전에 토큰이 항상 최신 상태로 유지됩니다.