CSS @property 완전 가이드 — 디자인 토큰 타입 등록부터 Style Dictionary v4·Tailwind v4 트랜지션 자동화까지

@property --color-primary {
  syntax: "<color>";
  inherits: true;
  initial-value: #6366f1;
}
 
@property --spacing-base {
  syntax: "<length>";
  inherits: true;
  initial-value: 16px;
}
 
@property --opacity-overlay {
  syntax: "<number>";
  inherits: false;
  initial-value: 0;
}

/* globals.css */
 
/* 1. 색상 토큰 타입 등록 */
@property --color-bg {
  syntax: "<color>";
  inherits: true;
  initial-value: #ffffff;
}
 
@property --color-text {
  syntax: "<color>";
  inherits: true;
  initial-value: #111111;
}
 
/* 2. 루트에서 트랜지션 선언 */
:root {
  --color-bg: #ffffff;
  --color-text: #111111;
  transition: --color-bg 0.3s ease, --color-text 0.3s ease;
}
 
/* 3. 다크 테마 값만 덮어쓰기 */
[data-theme="dark"] {
  --color-bg: #0f0f0f;
  --color-text: #f5f5f5;
}
 
body {
  background-color: var(--color-bg);
  color: var(--color-text);
}

@property --grad-start {
  syntax: "<color>";
  inherits: false;
  initial-value: #6366f1;
}
 
@property --grad-end {
  syntax: "<color>";
  inherits: false;
  initial-value: #ec4899;
}
 
.button {
  background: linear-gradient(135deg, var(--grad-start), var(--grad-end));
  transition: --grad-start 0.4s ease, --grad-end 0.4s ease;
}
 
.button:hover {
  --grad-start: #8b5cf6;
  --grad-end: #f43f5e;
}

@property --progress {
  syntax: "<number>";
  inherits: false;
  initial-value: 0;
}
 
.progress-ring {
  /* stroke-dasharray: 100으로 전체 둘레를 100으로 설정한 경우 */
  stroke-dasharray: 100;
  --progress: 0;
  stroke-dashoffset: calc(100 - var(--progress));
  transition: --progress 1s cubic-bezier(0.4, 0, 0.2, 1);
}
 
/* JS에서 --progress 값만 변경하면 부드러운 애니메이션이 적용됩니다 */
/* element.style.setProperty('--progress', '75'); */

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#6366f1"
    },
    "secondary": {
      "$type": "color",
      "$value": "#ec4899"
    }
  },
  "spacing": {
    "base": {
      "$type": "dimension",
      "$value": "16px"
    }
  }
}

// style-dictionary.config.mjs
import StyleDictionary from 'style-dictionary';
 
const TYPE_MAP = {
  color:     '<color>',
  number:    '<number>',
  dimension: '<length>',
  duration:  '<time>',
};
 
StyleDictionary.registerFormat({
  name: 'css/at-property',
  format: async ({ dictionary }) => {
    // transformGroup: 'css' 적용 후 token.name은 kebab-case
    // CSS 변수명으로 사용하려면 -- 접두사를 직접 붙여야 합니다
    const registrations = dictionary.allTokens
      .filter(token => TYPE_MAP[token.$type])
      .map(token => `@property --${token.name} {
  syntax: "${TYPE_MAP[token.$type]}";
  inherits: true;
  initial-value: ${token.value};
}`)
      .join('\n\n');
 
    const variables = dictionary.allTokens
      .map(token => `  --${token.name}: ${token.value};`)
      .join('\n');
 
    return `${registrations}\n\n:root {\n${variables}\n}`;
  },
});
 
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      destination: 'tokens.css',
      format: 'css/at-property',
    },
  },
};

/* globals.css */
@import "tailwindcss";
 
@theme {
  --color-brand-500: #6366f1;
  --color-brand-600: #4f46e5;
 
  --duration-fast:  150ms;
  --duration-base:  300ms;
  --ease-spring:    cubic-bezier(0.34, 1.56, 0.64, 1);
 
  --color-hero-from: #6366f1;
  --color-hero-to:   #ec4899;
}
 
/*
  Tailwind의 @property 자동 등록은 Tailwind 내부 토큰에 한정됩니다.
  사용자가 @theme에 추가한 커스텀 토큰을 트랜지션에 활용하려면
  @property를 별도로 명시적으로 선언해야 합니다.
*/
@property --color-hero-from {
  syntax: "<color>";
  inherits: false;
  initial-value: #6366f1;
}
 
@property --color-hero-to {
  syntax: "<color>";
  inherits: false;
  initial-value: #ec4899;
}
 
.hero {
  background: linear-gradient(135deg, var(--color-hero-from), var(--color-hero-to));
  transition: --color-hero-from 0.5s ease, --color-hero-to 0.5s ease;
}

디자인 도구 (Figma / Tokens Studio)
        ↓ JSON 토큰 내보내기
Style Dictionary v4
  ├── 커스텀 포매터: @property 선언 자동 생성
  └── 출력: tokens.css
        ↓ CSS 파일 import
globals.css (@theme 블록에 병합)
        ↓ Tailwind v4 엔진 처리 (Lightning CSS)
최종 CSS (타입 등록 + 유틸리티 클래스)

/* globals.css */
@import "tailwindcss";
@import "./tokens.css"; /* Style Dictionary 출력물 */
 
/*
  @theme inline: @theme 블록 내 변수를 Tailwind가 별도 CSS 변수로 재출력하지 않고
  참조 위치에 값을 직접 인라인으로 치환합니다.
  이미 tokens.css에 --color-brand-500이 정의되어 있으므로 중복 출력을 방지할 수 있습니다.
*/
@theme inline {
  --color-brand: var(--color-brand-500);
  --duration-transition: var(--duration-base);
}

// @property 지원 여부 감지 (JavaScript)
const supportsAtProperty = CSS.supports(
  '@property --x { syntax: "<color>"; inherits: false; initial-value: red; }'
);
 
if (supportsAtProperty) {
  // 향상된 트랜지션 경험 제공
}

/* CSS 폴백 패턴 — @property 미지원 브라우저는 @property 블록을 무시합니다 */
:root {
  --color-bg: #ffffff; /* 미지원 환경: 즉시 값 변경 (트랜지션 없음) */
}
 
/* 지원 환경: @property 등록 및 트랜지션 활성화 */
@property --color-bg {
  syntax: "<color>";
  inherits: true;
  initial-value: #ffffff;
}
 
:root {
  transition: --color-bg 0.3s ease;
}