CSS @property 완전 가이드 — 타입 안전 디자인 토큰 선언과 CSS 변수 애니메이션(`css @property animation`, `design tokens type safety`) 구현까지

:root {
  --color-primary: #3b82f6;
}
 
.button {
  /* 브라우저 입장에서는 "#3b82f6"이라는 문자열을 붙여넣는 것과 같음 */
  background-color: var(--color-primary);
}

@property --color-primary {
  syntax: "<color>";
  inherits: true;
  initial-value: hsl(217 91% 60%);
}

@property --opacity-overlay {
  syntax: "<number>";
  inherits: false;   /* 자식 요소에 전파 안 함 */
  initial-value: 0;
}

CSS.registerProperty({
  name: '--color-primary',
  syntax: '<color>',
  inherits: true,
  initialValue: 'hsl(217 91% 60%)',
});

@layer tokens, base, components, utilities;
 
@layer tokens {
  @property --color-primary {
    syntax: "<color>";
    inherits: true;
    initial-value: hsl(217 91% 60%);
  }
 
  @property --spacing-base {
    syntax: "<length>";
    inherits: true;
    initial-value: 4px;
  }
 
  @property --radius-md {
    syntax: "<length>";
    inherits: true;
    initial-value: 8px;
  }
}

@layer tokens {
  /* 색상 토큰 */
  @property --color-primary {
    syntax: "<color>";
    inherits: true;
    initial-value: hsl(217 91% 60%);
  }
 
  @property --color-surface {
    syntax: "<color>";
    inherits: true;
    initial-value: hsl(0 0% 100%);
  }
 
  /* 간격 토큰 */
  @property --spacing-base {
    syntax: "<length>";
    inherits: true;
    initial-value: 4px;
  }
 
  /* 모서리 반경 토큰 */
  @property --radius-md {
    syntax: "<length>";
    inherits: true;
    initial-value: 8px;
  }
 
  /* 오버레이 불투명도 — 컴포넌트 로컬, 상속 차단 */
  @property --opacity-overlay {
    syntax: "<number>";
    inherits: false;
    initial-value: 0;
  }
}
 
@layer components {
  .button {
    background-color: var(--color-primary);
    border-radius: var(--radius-md);
    padding: var(--spacing-base) calc(var(--spacing-base) * 4);
    color: var(--color-surface);
  }
}

@layer tokens {
  @property --gradient-start {
    syntax: "<color>";
    inherits: false;
    initial-value: #3b82f6;
  }
 
  @property --gradient-end {
    syntax: "<color>";
    inherits: false;
    initial-value: #8b5cf6;
  }
}
 
@layer components {
  .card {
    background: linear-gradient(
      135deg,
      var(--gradient-start),
      var(--gradient-end)
    );
    transition:
      --gradient-start 0.4s ease,
      --gradient-end 0.4s ease;
  }
 
  .card:hover {
    --gradient-start: #ef4444;
    --gradient-end: #f97316;
  }
}

@layer tokens {
  @property --arc-end {
    syntax: "<angle>";
    inherits: false;
    initial-value: 0deg; /* @keyframes from이 생략될 때 이 값에서 시작 */
  }
}
 
@layer components {
  .progress-ring {
    width: 80px;
    height: 80px;
    border-radius: 50%;
    background: conic-gradient(
      #3b82f6 var(--arc-end),
      #e5e7eb 0
    );
    transition: --arc-end 0.5s ease-out;
  }
}

function setProgress(element, percent) {
  const angle = percent * 3.6; // 100% → 360deg
  element.style.setProperty('--arc-end', `${angle}deg`);
}
 
setProgress(document.querySelector('.progress-ring'), 75); // 270deg로 부드럽게 이동

@layer tokens {
  @property --progress {
    syntax: "<number>";
    inherits: false;
    initial-value: 0;
  }
}
 
@layer components {
  .progress-bar {
    position: relative;
    height: 8px;
    background: #e5e7eb;
    border-radius: 4px;
    overflow: hidden;
    transition: --progress 0.6s ease-out;
  }
 
  .progress-bar::after {
    content: "";
    position: absolute;
    inset: 0;
    background: #3b82f6;
    width: calc(var(--progress) * 1%);
    border-radius: inherit;
  }
}

function setProgress(element, value) {
  element.style.setProperty('--progress', value);
}
 
setProgress(document.querySelector('.progress-bar'), 75);

// tokens/color.json — W3C DTCG(W3C 디자인 토큰 커뮤니티 그룹 표준 포맷)
{
  "color": {
    "primary": {
      "$value": "#3b82f6",
      "$type": "color"
    },
    "surface": {
      "$value": "#ffffff",
      "$type": "color"
    }
  },
  "spacing": {
    "base": {
      "$value": "4px",
      "$type": "dimension"
    }
  }
}

// style-dictionary.config.js
import StyleDictionary from 'style-dictionary';
 
const typeMap = {
  color: '<color>',
  dimension: '<length>',
  number: '<number>',
  fontWeight: '<number>',
};
 
StyleDictionary.registerFormat({
  name: 'css/at-property',
  format: ({ dictionary }) => {
    const declarations = dictionary.allTokens.map(token => {
      const syntax = typeMap[token.$type] ?? '*';
      // Style Dictionary의 기본 name transform이 중첩 구조를 평탄화합니다:
      // color.primary → color-primary
      return `@property --${token.name} {
  syntax: "${syntax}";
  inherits: true;
  initial-value: ${token.value};
}`;
    });
 
    return `@layer tokens {\n${declarations.join('\n\n')}\n}`;
  },
});
 
const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      files: [
        {
          destination: 'dist/tokens.css',
          format: 'css/at-property',
        },
      ],
    },
  },
});
 
await sd.buildAllPlatforms();

if (typeof CSS !== 'undefined' && typeof CSS.registerProperty === 'function') {
  document.documentElement.classList.add('supports-at-property');
}

/* 기본 정적 스타일 — 모든 브라우저에서 동작 */
.card {
  background: linear-gradient(135deg, #3b82f6, #8b5cf6);
}
 
/* @property 지원 브라우저용 향상 */
.supports-at-property .card {
  background: linear-gradient(
    135deg,
    var(--gradient-start),
    var(--gradient-end)
  );
  transition: --gradient-start 0.4s ease, --gradient-end 0.4s ease;
}

/* 항상 동작하는 기본 스타일 */
.card {
  background: linear-gradient(135deg, #3b82f6, #8b5cf6);
}
 
/* @property가 지원되면 변수 기반 동적 그라디언트로 덮어씌워짐 */
@layer tokens {
  @property --gradient-start {
    syntax: "<color>";
    inherits: false;
    initial-value: #3b82f6;
  }
 
  @property --gradient-end {
    syntax: "<color>";
    inherits: false;
    initial-value: #8b5cf6;
  }
}
 
@layer components {
  .card {
    background: linear-gradient(
      135deg,
      var(--gradient-start),
      var(--gradient-end)
    );
    transition: --gradient-start 0.4s ease, --gradient-end 0.4s ease;
  }
}