Style Dictionary `outputReferences`로 다크모드·브랜드 테마를 단 하나의 옵션으로 런타임 전환하는 법

// tokens/color.tokens.json
{
  "color": {
    "red": { "$value": "#ff0000", "$type": "color" },
    "danger": { "$value": "{color.red}", "$type": "color" }
  }
}

/* outputReferences: false (기본) — 참조가 해석되어 값으로 펼쳐짐 */
:root {
  --color-red: #ff0000;
  --color-danger: #ff0000;
}
 
/* outputReferences: true — var() 참조 체인이 그대로 유지됨 */
:root {
  --color-red: #ff0000;
  --color-danger: var(--color-red);
}

// DTCG 형식 (.tokens.json)
{
  "color": {
    "red": {
      "$value": "#ff0000",
      "$type": "color"
    },
    "danger": {
      "$value": "{color.red}",
      "$type": "color"
    }
  }
}

// tokens/global.json — Primitive 토큰 (라이트·다크 공통)
{
  "color": {
    "red": { "$value": "#ef4444", "$type": "color" },
    "green": { "$value": "#22c55e", "$type": "color" },
    "gray": {
      "900": { "$value": "#111827", "$type": "color" },
      "100": { "$value": "#f3f4f6", "$type": "color" }
    },
    "white": { "$value": "#ffffff", "$type": "color" }
  }
}

// tokens/light.json — Semantic 토큰 (라이트 기본값)
{
  "color": {
    "bg": { "$value": "{color.white}", "$type": "color" },
    "text": { "$value": "{color.gray.900}", "$type": "color" },
    "danger": { "$value": "{color.red}", "$type": "color" }
  }
}

// tokens/dark.json — Semantic 토큰 (달라지는 것만)
{
  "color": {
    "bg": { "$value": "{color.gray.900}", "$type": "color" },
    "text": { "$value": "{color.white}", "$type": "color" }
  }
}

tokens/
├── global.json      # Primitive 토큰 (공통)
├── light.json       # 라이트 모드 Semantic 토큰
└── dark.json        # 다크 모드 Semantic 토큰 (달라지는 것만)

// style-dictionary.config.js (v4, ES Modules)
export default {
  source: ['tokens/global.json', 'tokens/light.json', 'tokens/dark.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      files: [
        {
          destination: 'dist/variables.css',
          format: 'css/variables',
          filter: token => !token.filePath.includes('dark'),
          options: {
            outputReferences: true,
            selector: ':root',
          },
        },
        {
          destination: 'dist/variables-dark.css',
          format: 'css/variables',
          filter: token => token.filePath.includes('dark'),
          options: {
            outputReferences: true,
            selector: '[data-theme="dark"], .dark',
          },
        },
      ],
    },
  },
};

/* dist/variables.css */
:root {
  --color-red: #ef4444;
  --color-gray-900: #111827;
  --color-white: #ffffff;
 
  /* Semantic — 라이트 기본값 */
  --color-bg: var(--color-white);
  --color-text: var(--color-gray-900);
  --color-danger: var(--color-red);
}
 
/* dist/variables-dark.css */
[data-theme="dark"], .dark {
  /* Semantic만 덮어씀 — Primitive는 그대로 재사용 */
  --color-bg: var(--color-gray-900);
  --color-text: var(--color-white);
  /* --color-danger는 동일하므로 자동으로 제외됨 */
}

// theme.js
const toggleTheme = (theme) => {
  if (theme === 'dark') {
    // 다크: 속성 추가 → [data-theme="dark"] 셀렉터 활성화
    document.documentElement.setAttribute('data-theme', 'dark');
  } else {
    // 라이트: 속성 제거 → :root 기본값으로 복귀
    document.documentElement.removeAttribute('data-theme');
  }
  localStorage.setItem('theme', theme);
};
 
// 초기 로드: 시스템 설정 감지 + 사용자 오버라이드
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
const savedTheme = localStorage.getItem('theme') ?? (prefersDark.matches ? 'dark' : 'light');
toggleTheme(savedTheme);
 
// 시스템 설정 변경 감지
prefersDark.addEventListener('change', (e) => {
  if (!localStorage.getItem('theme')) {
    toggleTheme(e.matches ? 'dark' : 'light');
  }
});

tokens/
├── global/           # 공통 Primitive (모든 브랜드 공유)
│   └── color.json
├── brand-a/          # 브랜드 A Semantic 토큰
│   ├── light.json
│   └── dark.json
└── brand-b/          # 브랜드 B Semantic 토큰
    ├── light.json
    └── dark.json

// build.js
import StyleDictionary from 'style-dictionary';
 
const brands = ['brand-a', 'brand-b'];
const modes = ['light', 'dark'];
 
// 브랜드가 늘어도 selectors 객체만 추가하면 됩니다
const selectors = {
  'brand-a': '.brand-a',
  'brand-b': '.brand-b',
};
 
for (const brand of brands) {
  for (const mode of modes) {
    const sd = new StyleDictionary({
      source: [
        'tokens/global/**/*.json',
        `tokens/${brand}/${mode}.json`,
      ],
      platforms: {
        css: {
          transformGroup: 'css',
          files: [{
            destination: `dist/${brand}-${mode}.css`,
            format: 'css/variables',
            options: {
              outputReferences: true,
              selector: selectors[brand],
            },
          }],
        },
      },
    });
 
    await sd.buildAllPlatforms();
  }
}

<!-- 브랜드 클래스를 루트에, data-theme으로 모드 전환 -->
<html class="brand-a">
  <head>
    <!-- 라이트를 기본으로 로드하고, 다크는 오버라이드로 추가 -->
    <link rel="stylesheet" href="dist/brand-a-light.css">
    <link rel="stylesheet" href="dist/brand-a-dark.css"
          media="(prefers-color-scheme: dark)">
  </head>
</html>

// 함수 시그니처
outputReferences: (token: TransformedToken, options: { dictionary: Dictionary }) => boolean

import StyleDictionary, { outputReferencesFilter } from 'style-dictionary';
 
export default {
  platforms: {
    css: {
      files: [{
        destination: 'dist/variables.css',
        format: 'css/variables',
        filter: token => token.attributes.category !== 'internal',
        options: {
          // 필터링된 토큰을 참조하는 경우 var() 대신 해석된 값 사용
          outputReferences: (token, { dictionary }) => {
            return outputReferencesFilter(token, { dictionary });
          },
        },
      }],
    },
  },
};

// style-dictionary.config.js
import StyleDictionary from 'style-dictionary';
import { register } from '@tokens-studio/sd-transforms';
 
// Tokens Studio 전용 transforms 등록
register(StyleDictionary);
 
export default {
  source: [
    'tokens/$metadata.json',
    'tokens/**/*.json',
  ],
  preprocessors: ['tokens-studio'], // Tokens Studio 형식 전처리
  platforms: {
    css: {
      transformGroup: 'tokens-studio', // 등록된 transform 그룹 사용
      files: [{
        destination: 'dist/variables.css',
        format: 'css/variables',
        options: { outputReferences: true },
      }],
    },
  },
};