Style Dictionary v4 × Tailwind v4: 디자인 토큰을 유틸리티 클래스까지 자동 전파하는 단일 소스 파이프라인 구축

tokens/color.json          sd.config.js          dist/tokens.css        globals.css
(DTCG JSON 토큰)   →  (Style Dictionary v4)  →  (@layer tokens 출력)  →  (@theme inline 연결)
                                                                                ↓
                                                                    bg-brand-primary 등
                                                                    Tailwind 유틸리티 자동 생성

// tokens/color.json (DTCG 형식)
{
  "color": {
    "brand": {
      "primary": { "$value": "#0055FF", "$type": "color" },
      "secondary": { "$value": "#00C2A8", "$type": "color" }
    }
  }
}

/* 레이어 순서 선언: 나중에 선언된 레이어가 더 높은 우선순위 */
@layer tokens, base, components, utilities;

@theme {
  --color-brand-primary: #0055ff;
  /* → bg-brand-primary, text-brand-primary, border-brand-primary 자동 생성 */
}

// tokens/color.json — 최상위 키 'token'으로 접두사 자동 부여
{
  "token": {
    "color": {
      "brand": {
        "primary": { "$value": "#0055FF", "$type": "color" },
        "secondary": { "$value": "#00C2A8", "$type": "color" }
      }
    },
    "spacing": {
      "4": { "$value": "1rem", "$type": "dimension" }
    },
    "font-size": {
      "lg": { "$value": "1.125rem", "$type": "dimension" }
    }
  }
}

// sd.config.js
import StyleDictionary from 'style-dictionary';
 
// @layer tokens로 출력을 감싸는 커스텀 포맷
StyleDictionary.registerFormat({
  name: 'css/layer-tokens',
  format: ({ dictionary, options }) => {
    const selector = options.selector ?? ':root';
    const vars = dictionary.allTokens
      .map(token => `    ${token.name}: ${token.value};`)
      .join('\n');
    return `@layer tokens {\n  ${selector} {\n${vars}\n  }\n}\n`;
  },
});
 
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'token',
      files: [
        {
          destination: 'dist/tokens.css',
          format: 'css/layer-tokens',
          options: {
            selector: ':root',
            outputReferences: true,
          },
        },
      ],
    },
  },
};

@layer tokens {
  :root {
    --token-color-brand-primary: #0055ff;
    --token-color-brand-secondary: #00c2a8;
    --token-spacing-4: 1rem;
    --token-font-size-lg: 1.125rem;
  }
}

/* src/globals.css */
@import "tailwindcss";
@import "../dist/tokens.css";
 
/* 레이어 우선순위 명시적 선언 (항상 최상단에 위치) */
@layer tokens, base, components, utilities;
 
@theme inline {
  /* SD 접두사 변수 → Tailwind 토큰으로 매핑 (자기 참조 없음) */
  --color-brand-primary: var(--token-color-brand-primary);
  --color-brand-secondary: var(--token-color-brand-secondary);
  --spacing-4: var(--token-spacing-4);
  --font-size-lg: var(--token-font-size-lg);
}

// package.json
{
  "scripts": {
    "build:tokens": "style-dictionary build --config sd.config.js",
    "build:css": "tailwindcss -i src/globals.css -o dist/output.css",
    "build": "pnpm build:tokens && pnpm build:css"
  }
}

// sd.config.js — 라이트/다크 파일 분리 출력
StyleDictionary.registerFormat({
  name: 'css/layer-tokens',
  format: ({ dictionary, options }) => {
    const selector = options.selector ?? ':root';
    const vars = dictionary.allTokens
      .map(token => `    ${token.name}: ${token.value};`)
      .join('\n');
    return `@layer tokens {\n  ${selector} {\n${vars}\n  }\n}\n`;
  },
});
 
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'token',
      files: [
        {
          destination: 'dist/tokens.css',
          format: 'css/layer-tokens',
          filter: token => !token.filePath.includes('dark'),
          options: { selector: ':root' },
        },
        {
          destination: 'dist/tokens-dark.css',
          format: 'css/layer-tokens',
          filter: token => token.filePath.includes('dark'),
          options: { selector: '[data-theme="dark"]' },
        },
      ],
    },
  },
};

/* dist/tokens.css */
@layer tokens {
  :root {
    --token-color-bg: #ffffff;
    --token-color-text: #111111;
  }
}

/* dist/tokens-dark.css */
@layer tokens {
  [data-theme="dark"] {
    --token-color-bg: #111111;
    --token-color-text: #f5f5f5;
  }
}

/* src/globals.css */
@import "tailwindcss";
@import "../dist/tokens.css";
@import "../dist/tokens-dark.css";
 
@layer tokens, base, components, utilities;
 
@theme inline {
  --color-bg: var(--token-color-bg);
  --color-text: var(--token-color-text);
}

/* src/globals.css */
@utility btn-primary {
  background-color: var(--token-color-brand-primary);
  color: var(--token-color-white);
  padding: var(--token-spacing-2) var(--token-spacing-4);
  border-radius: var(--token-radius-md);
  font-weight: 600;
}
 
@utility btn-secondary {
  background-color: var(--token-color-brand-secondary);
  color: var(--token-color-white);
  padding: var(--token-spacing-2) var(--token-spacing-4);
  border-radius: var(--token-radius-md);
}

pnpm add -D style-dictionary @tokens-studio/sd-transforms

// sd.config.js — Tokens Studio 전체 파이프라인
import StyleDictionary from 'style-dictionary';
import { registerTransforms } from '@tokens-studio/sd-transforms';
 
// StyleDictionary 인스턴스에 Tokens Studio 전처리 transform 등록
registerTransforms(StyleDictionary);
 
StyleDictionary.registerFormat({
  name: 'css/layer-tokens',
  format: ({ dictionary, options }) => {
    const selector = options.selector ?? ':root';
    const vars = dictionary.allTokens
      .map(token => `    ${token.name}: ${token.value};`)
      .join('\n');
    return `@layer tokens {\n  ${selector} {\n${vars}\n  }\n}\n`;
  },
});
 
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'tokens-studio',
      prefix: 'token',
      files: [
        {
          destination: 'dist/tokens.css',
          format: 'css/layer-tokens',
          options: {
            selector: ':root',
            outputReferences: true,
          },
        },
      ],
    },
  },
};