📜 CSS Scroll-driven Animations 완벽 가이드: JS 없는 60fps 스크롤 인터랙션

// ❌ 고전적인 메인 스레드 스크롤 리스너 안티패턴
window.addEventListener('scroll', () => {
  const scrollY = window.scrollY;
  const height = document.documentElement.scrollHeight - window.innerHeight;
  const progress = scrollY / height;
  
  // 매 스크롤 틱마다 메인 스레드에서 DOM 스타일을 강제로 변경 -> Layout Thrashing 유발
  document.getElementById('progress-bar').style.transform = `scaleX(${progress})`;
});

/* scroll([ <scroller> || <axis> ]) */
.progress-bar {
  animation-name: fill-bar;
  animation-timeline: scroll(); /* 기본값: scroll(nearest block) */
}

@keyframes fill-bar {
  from {
    transform: scaleX(0);
  }
  to {
    transform: scaleX(1);
  }
}

/* 스크롤을 발생시키는 컨테이너 */
.custom-scroll-container {
  overflow-y: scroll;
  scroll-timeline-name: --galleryTimeline;
  scroll-timeline-axis: block;
  /* 단축 표기: scroll-timeline: --galleryTimeline block; */
}

/* 해당 스크롤 진행률을 참조하는 내부 또는 관련 자식 */
.gallery-counter {
  animation-name: update-counter;
  animation-timeline: --galleryTimeline;
}

.reveal-card {
  animation-name: fade-in-up;
  animation-timeline: view(); /* 기본값: view(block nearest) */
  animation-fill-mode: both;
}

@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(60px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.card-with-offset {
  /* 상단 10%, 하단 20% 마진을 두어 타임라인 활성 영역을 좁힘 */
  animation-timeline: view(block 10% 20%);
}

/* 예시 1: 요소가 화면 아래에서 0% 보일 때 시작하여, 완전히 다 들어왔을 때 애니메이션 100% 완료 */
.fade-box {
  animation-name: reveal;
  animation-timeline: view();
  animation-range: entry 0% entry 100%;
}

/* 예시 2: 단축 문법 (하나만 적으면 해당 페이즈의 0%~100%를 의미) */
.fade-box-short {
  animation-range: entry; /* entry 0% entry 100% 와 동일 */
}

/* 예시 3: 진입 중간부터 화면 탈출 직전까지 */
.sticky-highlight {
  animation-range: entry 50% exit 50%;
}

<!-- HTML 구조 -->
<div class="reading-progress"></div>
<main class="article-content">
  <!-- 긴 본문 내용 -->
</main>

/* CSS */
.reading-progress {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 5px;
  background: linear-gradient(90deg, #5B8FD4, #279866);
  transform-origin: 0% 50%;
  z-index: 9999;
  
  /* Scroll Progress Timeline 바인딩 */
  animation-name: progress-scale;
  animation-timing-function: linear;
  animation-timeline: scroll(root block);
}

@keyframes progress-scale {
  from {
    transform: scaleX(0);
  }
  to {
    transform: scaleX(1);
  }
}

<div class="card-grid">
  <article class="feature-card">
    <div class="image-wrapper">
      <img src="./images/css/sample.png" alt="Demo Preview" class="parallax-img" />
    </div>
    <h3>초고속 렌더링 파이프라인</h3>
    <p>CSS 네이티브 스레드에서 구동되는 초경량 인터랙션을 경험해 보세요.</p>
  </article>
</div>

.feature-card {
  border-radius: 16px;
  overflow: hidden;
  background: #ffffff;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.08);
  
  /* 카드 전체의 뷰포트 등장 애니메이션 */
  animation: card-appear linear both;
  animation-timeline: view();
  animation-range: entry 10% contain 25%;
}

.parallax-img {
  width: 100%;
  height: 280px;
  object-fit: cover;
  transform-origin: center center;
  
  /* 이미지 자체의 연속 패럴랙스 줌 */
  animation: image-zoom linear both;
  animation-timeline: view();
  animation-range: cover 0% cover 100%;
}

@keyframes card-appear {
  from {
    opacity: 0;
    transform: translateY(50px) scale(0.96);
  }
  to {
    opacity: 1;
    transform: translateY(0) scale(1);
  }
}

@keyframes image-zoom {
  from {
    transform: scale(1.15);
  }
  to {
    transform: scale(1);
  }
}

<div class="stack-container">
  <div class="stack-card" style="--index: 1;">Card 01</div>
  <div class="stack-card" style="--index: 2;">Card 02</div>
  <div class="stack-card" style="--index: 3;">Card 03</div>
  <div class="stack-card" style="--index: 4;">Card 04</div>
</div>

.stack-container {
  padding-bottom: 50vh;
}

.stack-card {
  position: sticky;
  top: 120px;
  height: 350px;
  margin-bottom: 40px;
  background: #1E3A5F;
  color: #ffffff;
  border-radius: 24px;
  padding: 40px;
  transform-origin: 50% 0%;
  
  /* 스택 카드 축소 애니메이션 */
  animation: stack-down linear both;
  animation-timeline: view();
  /* 카드가 상단 sticky 위치에 도달하여 다음 요소와 겹쳐 나갈 때만 발동 */
  animation-range: exit-crossing 0% exit-crossing 100%;
}

@keyframes stack-down {
  to {
    transform: scale(calc(1 - 0.08 * (4 - var(--index))));
    filter: brightness(0.65);
  }
}

<div class="carousel-wrapper">
  <!-- 슬라이드 스크롤러 컨테이너 -->
  <div class="slides-scroller">
    <div class="slide">Slide A</div>
    <div class="slide">Slide B</div>
  </div>
  
  <!-- 형제 위치에 존재하는 외부 인디케이터 닷(Dots) -->
  <div class="timeline-pagination"></div>
</div>

/* 상위 공통 조상에서 스코프를 미리 선언 */
.carousel-wrapper {
  timeline-scope: --carouselTimeline;
}

.slides-scroller {
  overflow-x: auto;
  scroll-timeline-name: --carouselTimeline;
  scroll-timeline-axis: inline;
}

/* 형제 관계인 인디케이터가 스크롤러의 타임라인을 그대로 제어 */
.timeline-pagination {
  animation: sync-dots linear both;
  animation-timeline: --carouselTimeline;
}

@keyframes sync-dots {
  from { transform: translateX(0); }
  to { transform: translateX(100px); }
}

/* ❌ 치명적인 성능 저하 유발 */
@keyframes bad-progress {
  from { width: 0; margin-top: 100px; }
  to { width: 100%; margin-top: 0; }
}

/* ⭕ 컴포지터 스레드 유지 (무조건 60fps) */
@keyframes good-progress {
  from { transform: scaleX(0) translateY(100px); }
  to { transform: scaleX(1) translateY(0); }
}

@media (prefers-reduced-motion: reduce) {
  .reveal-card,
  .parallax-img,
  .stack-card {
    animation: none !important;
    transform: none !important;
    opacity: 1 !important;
  }
}

/* 기본 스타일: 모든 환경에서 콘텐츠가 안전하게 노출되도록 보장 */
.feature-item {
  opacity: 1;
  transform: none;
}

/* Scroll-driven Animations를 지원하는 브라우저에서만 고급 모션 활성화 */
@supports (animation-timeline: view()) {
  .feature-item {
    animation: smooth-fade-in linear both;
    animation-timeline: view();
    animation-range: entry 15% contain 30%;
  }
  
  @keyframes smooth-fade-in {
    from {
      opacity: 0;
      transform: translateY(40px);
    }
    to {
      opacity: 1;
      transform: translateY(0);
    }
  }
}

npm install @flackr/scroll-timeline

// 브라우저가 지원하지 않을 때만 조건부 동적 임포트
if (!CSS.supports('animation-timeline', 'scroll()')) {
  import('@flackr/scroll-timeline');
}