스크롤바 하나 고쳤는데, 원인은 아직도 모른다

"테마 전환은 됐는데, 스크롤바가 왜 저러지?"

원래 있는 줄도 몰랐던 버그였다. 테마 전환하다가 우연히 발견했고, 금방 끝날 줄 알았는데 생각보다 오래 걸렸다.

다크/라이트 전환 자체는 잘 됐다. 근데 전환할 때마다 우측 스크롤바 track이 순간 회색으로 꽉 찼다가 돌아왔다. 마우스 휠을 살짝 굴리면 즉시 정상으로 복구됐다.

증상

테마 전환 시 스크롤바 track이 순간적으로 브라우저 기본 회색으로 렌더링됐다가 복구되는 깜빡임. 재현 환경은 Chrome, next-themes의 ThemeProvider, 전환 방식은 html[data-theme] attribute 교체다.

먼저 시도한 것들

scrollbar-gutter: stable — 레이아웃 시프트 방지용이라 이 문제랑 관계없었다.

::-webkit-scrollbar-thumb에 min-height: 40px — thumb 크기 문제가 아니었다.

color-scheme: dark / light 명시 — 브라우저 네이티브 스크롤바에는 먹히는데, 커스텀 스크롤바엔 해당 없었다.

원인 분석

::-webkit-scrollbar-track에 background: transparent가 적용되어 있었다.

테마 전환 시 html[data-theme]가 변경되면서 스타일 재계산 및 리페인트가 발생하는데, 이 과정에서 Chrome이 scrollbar track을 일시적으로 기본 스타일로 렌더링하는 현상을 확인했다.

정확한 내부 원인은 확인하지 못했지만, background: transparent를 사용한 경우에만 문제가 발생했고, 명시적인 색상(var(--color-bg-primary))을 지정하면 현상이 사라졌다.

결국 scrollbar track의 투명 배경이 테마 전환 타이밍과 맞물리면서 생긴 문제로 보인다.

해결

/* before */
::-webkit-scrollbar-track {
  background: transparent;
}

/* after */
::-webkit-scrollbar-track {
  background: var(--color-bg-primary);
}

/* before */
::-webkit-scrollbar-track {
  background: transparent;
}

/* after */
::-webkit-scrollbar-track {
  background: var(--color-bg-primary);
}

정리

테마 전환이 있는 프로젝트에서 -webkit-scrollbar를 커스터마이징한다면, transparent는 조심하는 게 좋을 것 같다.

이번엔 background: transparent 때문에 테마 바꿀 때마다 track이 순간 회색으로 꽉 차는 현상을 봤는데, var(--color-bg-primary)로 바꾸니까 해결됐다.

정확한 원인이 불분명한 렌더링 이슈일수록, 해결책보다 재현 조건과 비교 결과를 명확히 남기는 게 나중에 더 도움이 된다.