오픈 소스 · MIT · Safari 패밀리
bleedblend
설정 없는 Safari 브라우저 크롬 색상 일치 — iPhone, iPad, Mac 동시 지원.
단 한 줄의 import만으로 Safari의 상태 표시줄과 주소창 색상을 웹페이지의 화면 경계와 자연스럽게 일치시켜 줍니다. 그라데이션, 고정 영역, 그리고 오버스크롤 바운스 영역까지 모두 자동으로 처리됩니다. 번거로운 theme-color 세팅이나 일치 작업을 할 필요가 없습니다. bleedblend는 임의의 독자적인 색상을 그리는 대신 Safari 고유의 색상 처리 로직을 최적화하며, Safari 26의 Liquid Glass 기술이 적용된 iPhone, iPad, Mac 전체에서 동일한 웹 구조적 예측 가능성을 제공합니다. iOS에서 나타나는 세세한 호환성 오류들을 적극적으로 보완하고, Mac의 경우 통합된 구조 모델 덕분에 물 흐르듯 작동합니다.
작동 방식
- 1.
기존 문제점
Safari 26은 iPhone, iPad, Mac 전반에 걸쳐 화면 가장자리에 위치한 콘텐츠를 분석하여 상단 바 및 주소창(크롬)의 배경 색상을 유추합니다. 그러나 이 내부 규정은 복잡하고 문서화되어 있지 않으며 버전마다 달라집니다. 특히 iPhone과 iPad에서 심각한 오류가 발생합니다. 그라데이션을 적용할 때 부자연스러운 경계선이 생기거나, 탭 바의 위치로 인해 약 30px 색상 오차가 생기고, 오버스크롤 바운스 시 엉뚱한 배경색이 드러나는 한편, iOS 26에서는 `theme-color` 태그마저 완전히 무시되는 현상이 벌어집니다.
- 2.
해결 방안
단 한 줄의 import만으로 어떠한 프레임워크 환경에서든 연동됩니다. bleedblend는 스크롤, 크기 조절, visualViewport 이벤트를 감시하고 각 뷰포트의 경계 지점에서 Safari 본연의 렌더링 처리를 위임할지, 혹은 최적의 색상으로 얇은 색조 레이어를 임의로 입힐지를 신속히 계산합니다. 수동으로 색상 배열을 매핑할 필요 없이, 페이지의 그라데이션 중단점(stops) 정보를 실시간으로 읽어와 완벽하게 대응합니다.
- 3.
구현 결과
상태 표시줄과 주소창이 웹페이지와 완벽히 동기화됩니다. 그라데이션 보간이 주소창 영역까지 자연스럽게 이어지고, 페이지 하단에서는 푸터(footer) 색상이 매끄럽게 연동되며, iOS의 바운스 오버스크롤 시 기본 배경색이 드러나는 대신 동일한 색상으로 칠해집니다.
주요 기능
설정 필요 없는 자동 감지
`import 'bleedblend/auto'`가 API의 전부입니다. `body::before`, `body`, 또는 `<html>`에서 그라데이션 중단점을 읽어와 각 모서리에 맞는 최적의 크롬 색상을 자동으로 계산하므로 번거롭게 색상 배열을 직접 관리할 필요가 없습니다.
화면 모서리를 인식하는 상태 머신
뷰포트 경계별로 3가지 상태 중 하나를 동적으로 선택합니다. 직접 구축한 sticky 헤더의 위치를 반영하거나, Safari 자체 샘플링이 올바른 경우 샘플링을 양보하고, 경계면 색상이 잘못 표현될 우려가 있는 경우에만 직접 색상을 채워 넣습니다.
오버스크롤 및 그라데이션 제어
그라데이션 효과를 브라우저 주소창 영역까지 매끄럽게 확장하며, `<html>`, `<body>`, `body::before`를 일체화하여 제어함으로써 iOS 바운스 오버스크롤 발생 시에도 동일한 색상 톤이 유지되도록 합니다. 페이지 끝단에서 배경색이 어색하게 새는 일이 생기지 않습니다.
프레임워크 무관 + Tailwind 호환
단 한 줄의 import만으로 어떠한 프레임워크 환경에서든 연동되며, 싱글 페이지 애플리케이션(SPA)의 화면 전환을 위한 `onPageLoad` 훅을 함께 지원합니다. 전용 Tailwind 플러그인과 더불어 `.bleedblend-top` / `.bleedblend-bottom` 클래스를 제공하므로, 나만의 sticky 헤더나 푸터가 Safari 패밀리 전체에서 자연스럽게 상하단 영역을 칠하도록 세부 설정할 수 있습니다.
설치 및 연동
npm을 통해 `bleedblend`를 설치하거나 소스 코드를 복사한 다음, 뷰포트 메타 태그를 `viewport-fit=cover`로 선언하고 진입점 파일에 `import 'bleedblend/auto'` 코드를 추가해 주세요. 이 한 줄로 모든 연동이 끝납니다. 커스텀 영역 선택기나 페이지 전환을 위한 훅이 필요하신가요? `bleedblend/utils`에 마련된 `createBleedblendAuto()` 함수를 사용해 보세요.