Token Transformer는 Figma Tokens Studio plugin에서 추출된 json 파일을 변환하는 도구이다.
그런데 공식문서가 그닥 친절하지 않다. GitHub 저장소에 옵션별 결과 파일들이 있긴 하지만 어떤 명령어에 대한 결과 파일인지 직접 확인해봐야 한다. 솔직히 말하면 공식문서라고 하기도 애매함
그래서 직접 옵션들을 바꿔가면서 테스트를 해봤고, 각 옵션에 대해 설명하고자 한다.
명령어로 실행하기
패키지를 설치해서 실행해도 되고, npx로 바로 실행시킬 수 있다.
npx token-transformer input.json output.json sets excludes
실행 명령어는 간단하며, 파라미터에 대해 알아보자.
파라미터
기본적으로 변환 작업에 대한 정의를 하는데 사용되는 파라미터들이다.
- input.json : 변환할 대상 파일
- output.json : 추출할 대상 파일 (존재하지 않으면 생성함)
- sets : 변환시 참조할 대상 key값
- excludes : 추출 제외 대상 key값
sets와 excludes에 대해서는 조금 더 자세한 설명이 필요하다.
{
"global": {...},
"light": {
"bg": {
"default": {
"value": "{colors.white}",
"type": "color"
}
}
},
"dark": {
"bg": {
"default": {
"value": "{colors.gray.900}",
"type": "color"
}
}
}
}여기에 input에 사용될 tokens.json이 있다. light, dark는 global의 colors의 값을 참조해서 값을 설정하고 있다.
만약 특정 테마만 변환해서 추출할 때, global을 참조하도록 설정하는 것이 필요하다.
light 테마만 추출하기
npx token-transformer input.json light.json global,light global
global과 light을 참조해서 추출하되, global은 추출하지 말라는 명령어다.
dark 테마만 추출하기
npx token-transformer input.json dark.json global,dark global
dark 테마도 light와 동일하게, global을 참조하되 global은 추출하지 않는다.
옵션
변환시 사용할 수 있는 옵션들이다. -- prefix로 시작하며 =로 값을 대입해준다.
| 옵션 | 기본 값 | 설명 |
|---|---|---|
| expandTypography | false | Typography 유형의 자동 확장을 활성화한다. |
| expandShadow | false | boxShadow 유형의 자동 확장을 활성화한다. |
| expandBorder | false | stroke 유형의 자동 확장을 활성화한다. |
| preserveRawValue | false | 원시 값을 가지는 rawValue를 추가한다. |
| throwErrorWhenNotResolved | false | 참조 해결되지 않을 시 오류를 사용하지 않는다. |
| resolveReferences | true | 참조를 해결하고, 별칭이나 수학 표현식을 제거해서 토큰을 생성한다. |
| expandComposition | false | 레이어 관련 설정이라는데, 설명이 없다... |
옵션들에 대해 더 자세히 알아보자.
expand로 시작하는 옵션들
expand로 시작하는 옵션들은 자동 확장 여부를 결정한다. (expandTypography, expandShadow, expandBorder)
자동 확장 여부란, 추출된 토큰이 참조한 대상 토큰의 type도 함께 포함하는 것을 의미한다.
대표로 expandTypography 옵션을 예로 들어 확인해보자.
{
"H1": {
"Bold": {
"type": "typography",
"value": {
"fontFamily": "Inter",
"fontWeight": "Bold",
"lineHeight": "110%",
"fontSize": 48.829,
"paragraphSpacing": 32,
"letterSpacing": "-5%"
}
}
}
}expandTypography=false, 즉 기본값으로 추출했을 경우다.
{
"typography": {
"H1": {
"Bold": {
"fontFamily": { "value": "Inter", "type": "fontFamilies" },
"fontWeight": { "value": "Bold", "type": "fontWeights" },
"lineHeight": { "value": "110%", "type": "lineHeight" },
"fontSize": { "value": 48.829, "type": "fontSizes" },
"paragraphSpacing": { "value": 32, "type": "paragraphSpacing" },
"letterSpacing": { "value": "-5%", "type": "letterSpacing" }
}
}
}
}반면에, true로 설정하면 fontFamily, fontSize 등의 토큰들이 어떤 토큰을 참조했는지 함께 추출된다.
preserveRawValue 옵션
preserveRawValue 옵션도 expand로 시작하는 옵션들과 비슷한데, 이 경우에는 기존에 참조하던 형태를 그대로 가져온다.
light 테마 preserveRawValue 옵션 사용해서 추출하기
npx token-transformer input.json light.json global,light global --preserveRawValue=true
{
"bg": {
"default": {
"value": "#ffffff",
"type": "color",
"rawValue": "{colors.white}"
}
}
}false인 경우에 rawValue 필드가 없다.
config 파일로 실행하기
사실상 config를 읽어서 실행하는게 아니라, 직접 실행 방식을 정의해야 한다.
tt.config.js
const fs = require('fs');
const path = require('path');
const { transformTokens } = require('token-transformer');
// 추출 대상 파일 경로
const filePath = 'src/tokens';
const dir = path.join(__dirname, filePath);
// 만약 없다면 생성
if (!fs.existsSync(dir)) {
fs.mkdirSync(dir, { recursive: true });
}
// 변환 옵션
const transformerOptions = {};
// 파일 읽기
fs.readFile('tokens.json', 'utf8', (err, data) => {
if (err) throw err;
const tokens = JSON.parse(data);
// $metadata에 token key가 있음
const tokenKeys = [...tokens.$metadata.tokenSetOrder];
tokenKeys.forEach((key) => {
// 변환 작업
const resolved = transformTokens(
tokens, // 변환할 파일
key === 'light' || key === 'dark' ? ['global', key] : tokenKeys, // 참조 대상
[...tokenKeys].filter((k) => k !== key), // 추출 제외 대상
transformerOptions // 변환 옵션
);
// 파일 생성
fs.writeFileSync(
`${filePath}/${key}.json`,
JSON.stringify(resolved),
(err) => {
if (err) throw err;
}
);
});
});이후 node로 config 파일을 실행하면 된다.
node tt.config.js
👍👍