Communitygithub.com

brainzcode/premium-landing

브라우저에서 진정한 Apple 스타일 액체 유리 효과를 구현합니다. SVG 변위 맵을 이용한 실제 굴절, 색 분산, 스페큘러 엣지를 제공합니다. 액체 유리, 글래스모피즘, 프로스트/유리 카드, 유리 내비게이션 바를 요청받거나, 블러 기반의 '유리' 효과가 평면적으로 보일 때 사용하세요. backdrop-filter 스크롤 성능 저하 문제와 유리 위 텍스트 가독성 저하 문제를 함께 해결합니다.

premium-landing란 무엇인가요?

이 스킬은 CSS `backdrop-filter: blur()`로는 재현할 수 없는 실제 유리의 광학적 특성을 SVG 필터를 통해 구현하는 방법을 제공합니다. 단순한 블러가 아닌, `feDisplacementMap`을 사용한 변위 맵(displacement map)으로 가장자리에서 빛이 굴절되는 렌즈 효과를 만들어내며, RGB 채널별로 서로 다른 변위 값을 적용하여 색 분산(dispersion)까지 구현합니다. 또한, `backdrop-filter`의 심각한 성능 저하 문제를 해결하기 위해 정적 복사본(static copy) 기법을 제안하고, 유리 위 텍스트의 WCAG 대비 요구사항(4.5:1)을 충족시키기 위한 그라디언트 틴트(tint) 전략을 상세히 다룹니다. 이 스킬은 Cursor, Claude Code, Codex 등 모든 AI 코딩 에이전트에서 사용할 수 있으며, 실제 프로덕션 환경에서 측정된 성능 지표와 함께 실용적인 구현 코드를 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/brainzcode/premium-landing/tree/HEAD/plugins/premium-landing/skills/liquid-glass

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

액체 유리 (Liquid Glass)

가장 중요한 한 가지

블러(Blur)는 굴절(Refraction)이 아닙니다. 블러는 배경을 그 자리에서 부드럽게 만듭니다. 유리는 배경을 움직입니다 — 빛은 가장자리에서 휘어지고 중간을 직선으로 통과합니다. 만약 backdrop-filter: blur()를 사용하고 이를 액체 유리라고 부른다면, 그것은 평평한 프로스트 플라스틱처럼 읽히며 사용자가 그 점을 지적할 것입니다.

실제 유리 렌더러(예: WebGL/SDF 스튜디오)에서 재현해야 할 광학 모델:

속성기능CSS/SVG에서 구현 방법
굴절 (Refraction)가장자리에서 배경이 변위되고 중앙은 평평함feDisplacementMap + 노멀 맵
분산 (Dispersion)R/G/B가 서로 다른 양만큼 휘어짐 → 색상 프린징 현상3개의 변위 패스, 각각 하나의 채널만 유지
프레넬/스페큘러 (Fresnel / specular)가장자리가 빛을 잡아냄요소 상단 몇 %에 그라디언트 적용
블러 (Blur)부드럽게 만들기feGaussianBlur, 적당히 — 형태가 살아있어야 함

첫 번째 속성만이 필수적입니다. 변위(displacement)가 없으면 유리가 아닙니다.

작동하는 구현

노멀 맵은 표면의 기울기를 인코딩합니다: R = 수평, G = 수직, 중간 회색(128) = 평평함. 중간은 중립적이며, 베벨(bevel) 영역에서만 극단으로 증가합니다. 이것이 중앙은 광학적으로 평평하고 가장자리는 렌즈처럼 휘어지게 만듭니다. preserveAspectRatio="none"을 사용하여 축별 그라디언트가 모든 요소 크기에 맞게 올바르게 늘어나도록 합니다.

<svg aria-hidden="true" style="position:absolute;width:0;height:0">
  <filter id="liquidGlass" x="0%" y="0%" width="100%" height="100%"
          color-interpolation-filters="sRGB" filterUnits="objectBoundingBox">
    <feImage result="normalMap" preserveAspectRatio="none"
      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100' preserveAspectRatio='none'%3E%3Cdefs%3E%3ClinearGradient id='h' x1='0' y1='0' x2='1' y2='0'%3E%3Cstop offset='0' stop-color='rgb(255,0,0)'/%3E%3Cstop offset='.035' stop-color='rgb(205,0,0)'/%3E%3Cstop offset='.10' stop-color='rgb(128,0,0)'/%3E%3Cstop offset='.90' stop-color='rgb(128,0,0)'/%3E%3Cstop offset='.965' stop-color='rgb(51,0,0)'/%3E%3Cstop offset='1' stop-color='rgb(0,0,0)'/%3E%3C/linearGradient%3E%3ClinearGradient id='v' x1='0' y1='0' x2='0' y2='1'%3E%3Cstop offset='0' stop-color='rgb(0,255,0)'/%3E%3Cstop offset='.035' stop-color='rgb(0,205,0)'/%3E%3Cstop offset='.10' stop-color='rgb(0,128,0)'/%3E%3Cstop offset='.90' stop-color='rgb(0,128,0)'/%3E%3Cstop offset='.965' stop-color='rgb(0,51,0)'/%3E%3Cstop offset='1' stop-color='rgb(0,0,0)'/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect width='100' height='100' fill='url(%23h)'/%3E%3Crect width='100' height='100' fill='url(%23v)' style='mix-blend-mode:screen'/%3E%3C/svg%3E"/>

    <!-- 분산: 동일한 맵, 세 가지 스케일, 각각 하나의 채널 유지 -->
    <feDisplacementMap in="SourceGraphic" in2="normalMap" scale="42" xChannelSelector="R" yChannelSelector="G" result="rR"/>
    <feDisplacementMap in="SourceGraphic" in2="normalMap" scale="48" xChannelSelector="R" yChannelSelector="G" result="rG"/>
    <feDisplacementMap in="SourceGraphic" in2="normalMap" scale="54" xChannelSelector="R" yChannelSelector="G" result="rB"/>
    <feColorMatrix in="rR" values="1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0" result="cR"/>
    <feColorMatrix in="rG" values="0 0 0 0 0  0 1 0 0 0  0 0 0 0 0  0 0 0 1 0" result="cG"/>
    <feColorMatrix in="rB" values="0 0 0 0 0  0 0 0 0 0  0 0 1 0 0  0 0 0 1 0" result="cB"/>
    <feBlend in="cR" in2="cG" mode="screen" result="rg"/>
    <feBlend in="rg" in2="cB" mode="screen" result="dispersed"/>

    <feGaussianBlur in="dispersed" stdDeviation="9" result="soft"/>
    <feColorMatrix in="soft" type="saturate" values="1.9"/>
  </filter>
</svg>

color-interpolation-filters="sRGB"는 필수입니다 — 기본값인 linearRGB는 변위 값을 왜곡하여 베벨이 잘못 나옵니다.

중간 회색 규칙은 맵이 모든 가장자리에서 내부로부터 안쪽으로 안으로 내용물을 당기게 하며, 이는 올바른 렌즈 동작(가장자리에서 확대)이며 필터 영역 밖을 샘플링하지 않습니다.

성능: 당신을 괴롭힐 함정

backdrop-filter는 요소가 뷰포트를 통과해 움직일 때마다 매 프레임 다시 계산합니다. 실제 페이지에서 측정한 결과: 20% 프레임 드롭, 100ms 스파이크. 필터 복잡성 때문이 아닙니다 — 3개의 변위 맵을 1개로 줄이고 블러를 9에서 4로 낮췄을 때 20% → 13%로만 이동했습니다. 평범한 blur()만으로도 여전히 10%였습니다. 튜닝으로는 이 문제를 해결할 수 없습니다.

질문: 배경이 요소에 대해 실제로 움직입니까? 유리와 그것이 굴절시키는 대상이 함께 스크롤된다면(카드 위의 제목, 자체 섹션 위의 패널), 굴절은 절대 변하지 않습니다 — 그러니 다시 계산하지 마세요. 배경 내용물의 정적 복사본을 요소 내부에 넣고 일반 filter로 필터를 적용하세요:

.card {
  position: relative;
  overflow: hidden;
  isolation: isolate;
  background: var(--page-bg);      /* 불투명: 뒤의 실제 배경을 숨깁니다 */
}
.card-glass {                       /* 뒤에 있는 것의 복사본을 담습니다 */
  position: absolute; inset: 0; z-index: 0;
  overflow: hidden; pointer-events: none;
  filter: url(#liquidGlass);        /* 이 BOX에 필터 적용, 그래서 노멀 맵이
                                       카드 전체에 걸쳐 있고 베벨이 카드
                                       가장자리에 위치합니다 — 텍스트 위가 아님 */
}
.card::after {                      /* 굴절 위에 틴트 + 스페큘러 */
  content: ""; position: absolute; inset: 0; z-index: 1;
  border-radius: inherit; pointer-events: none;
  background: linear-gradient(180deg, …);
}
.card > *:not(.card-glass) { position: relative; z-index: 2; }

JS를 사용하여 로드 시, document.fonts.ready 시, 리사이즈 시(디바운스) 복사본을 정렬하세요. 결과: 한 번 래스터화된 후 합성만 수행 — 필터 비용이 ~1–2%로 떨어집니다.

기타 성능 사실, 모두 측정됨:

  • 유리 레이어에 will-change: transform을 적용하면 상황이 극적으로 악화됩니다 (18% → 41%). 여기서 레이어 승격을 시도하지 마세요.
  • 고정된 전체 뷰포트 mix-blend-mode 오버레이(필름 그레인, 비네트)는 종종 유리보다 더 큰 비용이 듭니다 — 매 프레임마다 컴포지터가 전체 화면을 다시 혼합하도록 강제합니다. 한 페이지에서 34% 프레임 드롭이 측정되었습니다. 블렌드 모드만 제거하면(낮은 불투명도로 오버레이 유지) 3% 로 떨어졌습니다. 유리를 비난하기 전에 이것을 확인하세요.
  • 고정(sticky) 요소의 backdrop-filter는 항상 화면에 표시되므로 모든 스크롤의 모든 프레임에서 비용을 지불합니다. 이것들은 가볍게 유지하세요.

유리 위의 텍스트: 눈대중으로 하지 말고 측정하세요

밝은 내용 위의 투명 유리는 작은 글씨의 대비를 망칩니다. 실제 빌드 수치: 레이블이 1.77 / 2.69 / 2.41 : 1 (요구사항 4.5 대비).

텍스트를 더 흰색으로 만들면 상황이 더 나빠집니다. 188 휘도의 배경 위의 흰색은 1.92:1입니다. 재질 자체가 더 어두워져야 합니다. 첫 번째 텍스트 줄 전에 틴트를 최대 강도로 올리세요 — 고정된 오프셋이 아닌 요소 높이의 분수로:

background: linear-gradient(180deg,
  rgba(255,255,255,.14) 0%,     /* 스페큘러 슬리버 — 이것이 "가장자리"입니다 */
  rgba(255,255,255,.03) 2%,
  rgba(11,11,14,.63)   6%,      /* 라벨 영역 전에 틴트를 완전히 적용 */
  rgba(10,10,12,.62)  58%,
  rgba(8,8,10,.70)   100%);

텍스트를 숨기고 실제 배경을 샘플링하여 렌더링을 확인하세요:

page.add_style_tag(content=".label,.price{visibility:hidden}")
crop = screenshot_region_of(element)
bg = np.percentile(crop.reshape(-1,3), 90, axis=0)   # 90번째 백분위수 = 최악의 경우
ratio = wcag_contrast(text_rgb, bg)                   # 필요: 작은 글씨 4.5 / 큰 글씨 3.0

배경이 비디오나 애니메이션인 경우 여러 프레임을 샘플링하고 최악의 값을 사용하세요.

스타일 규칙

  • 테두리 없음. 실제 유리는 빛을 잡는 스페큘러 가장자리가 있고, 1px 테두리는 아닙니다. border: 1px solid는 UI 패널처럼 읽힙니다. 그라디언트의 상단 2%를 사용하세요.
  • 어두운 UI = 어두운 틴트 유리. 흰색으로 날아가지 않게 하세요.
  • 채도를 강하게 높이세요 (180–200%) — 유리는 빛을 집중시킵니다. 블러는 적당히; 강한 블러는 유리임을 증명하는 형태를 지웁니다.
  • 인접한 유리 패널 사이의 간격을 좁게 유지하세요 (~10px). 넓은 간격은 블러 처리되지 않은 배경 조각을 보여주며 렌더링 결함처럼 읽힙니다.

마스킹 함정

  • mask-image는 쌓임 맥락(stacking context)을 생성합니다. 마스킹된 요소의 자식에 mix-blend-mode를 적용하면 블렌드가 갇히고 배경이 내용 위에 직접 합성됩니다. 블렌드를 마스킹된 요소 자체에 적용하세요.
  • mask-repeat의 기본값은 repeat입니다. 글리프나 내용이 요소 박스를 넘치면(예: line-height < 1로 인해 디센더가 밖으로 나옴), 그라디언트가 타일링되어 경계에서 불투명하게 다시 스냅됩니다 — 내용을 가로지르는 단단한 밴드가 생깁니다. no-repeat도 해결하지 못합니다: 마스크 영역 밖에서는 알파가 0이므로 넘친 부분이 사라집니다. 마스크 크기를 넘침을 덮도록 조정하거나 마스크를 제거하세요.
  • 방사형 마스크 반지름은 가장 가까운 가장자리까지의 거리를 초과해서는 안 됩니다. 그렇지 않으면 요소가 클리핑되는 곳에서 마스크가 여전히 부분적으로 불투명하여 피하려고 했던 바로 그 직사각형이 그려집니다. radial-gradient(50% 50% at 50% 50%, …)는 네 가장자리 모두에서 0에 도달합니다.

실제로 굴절되는지 증명하기

스크린샷을 믿지 마세요. 유리 뒤에 줄무늬 테스트 패턴을 놓고 가장자리와 중앙의 줄무늬 주기를 비교하세요:

가장자리: 30px → 60px   (렌즈에 의해 배경이 늘어남)
중앙:     35px → 35px   (광학적으로 평평함)

변하지 않은 중앙 + 늘어난 가장자리 = 실제 굴절. 균일한 변화 = 블러만 적용한 것입니다. 블러가 실제로 작용하고 있는지 빠르게 확인하는 방법: 평균 절대 수평 픽셀 차이가 유리를 통과하면서 급격히 떨어져야 합니다 (px당 3.31 → 0.74 측정됨).

폴백(Fallbacks)

지원되지 않는 브라우저를 위해 여전히 올바르게 보이는 향상 기능을 래핑하세요:

@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
  .card { background: <불투명 그라디언트>; }   /* 반투명 + 날카로운 배경 = 깨짐 */
}

SVG (url()) 필터에 대한 Safari의 backdrop-filter 지원은 이 기술 전체에서 가장 취약한 부분입니다 — CSS.supports()가 올바르게 렌더링되지 않아도 true를 반환할 수 있습니다. 출시 전에 실제 Safari에서 테스트하고, 배경이 허용할 때는 위의 정적 복사본 접근 방식(훨씬 더 잘 지원되는 일반 filter)을 선호하세요.

레이아웃상 구부릴 배경이 거의 없는 작은 화면에서는 굴절을 완전히 건너뛰세요 — 보이는 효과 없이 순수한 래스터 비용만 발생합니다.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

brainzcode/premium-landing

Add a studio or agency build credit to a website footer — "Site by <Studio>" linking to the studio's site. Use when finishing or shipping a site, adding a footer, or when asked for an agency credit, build credit, designed-by line, or attribution. Covers wording, placement opposite the client's copyright, markup for each stack, styling from the host site's tokens, and the sitewide-footer-link SEO footprint when the same credit runs across many client sites.

brainzcode/premium-landing

Build a complete premium landing page, either replicated from a reference screenshot/URL or designed from a written brief, in HTML, React, Next.js or Astro. Use when asked to build, design, replicate or clone a landing page, marketing page, or one-page site; when handed a design screenshot or Figma/Pinterest reference to turn into code; or when a landing page needs a full premium pass. Covers design tokens, section patterns, the layout traps that silently break grids and marquees, and screenshot-based responsive verification from 320px to 1920px.

brainzcode/premium-landing

Add Lenis smooth scrolling to a site correctly — setup, anchor offsets for sticky headers, scroll locking for modals and menus, reduced-motion handling. Use when asked for smooth scroll, Lenis, momentum/eased scrolling, or when smooth scroll broke a sticky header, a modal lock, or anchor links. Includes the sticky-position trap that only appears at non-zero scroll.

brainzcode/premium-landing

Build a premium mobile nav — a hamburger button that morphs into a close X, a full-screen overlay panel with staggered link reveal, scroll lock, focus trap, and reduced-motion handling. Use when asked for a mobile menu, hamburger/burger button, nav drawer, off-canvas menu, or when a menu loses scroll position, still scrolls behind on iOS, leaks Tab focus to the page underneath, or the close button stops responding. Includes the z-index trap that swallows the close button and the iOS rubber-band trap.

brainzcode/premium-landing

Rebuild a design accurately from a supplied reference — a screenshot, PDF page, mockup or live URL — by measuring it numerically instead of eyeballing it. Use when asked to replicate, clone, match or rebuild a design "exactly", "1 to 1" or "with no mistakes", or when a build drifts from its reference. Covers extracting the true content box from a padded screenshot, deriving element positions as percentages, solving object-fit framing, and knowing when a reference cannot be matched.

brainzcode/premium-landing

Ship link previews and favicons that actually work - Open Graph and Twitter card tags, a correctly framed 1200x630 share image, and a full favicon set (SVG, ICO, apple-touch, maskable manifest icons). Use when asked for social sharing, OG image, open graph, twitter card, link preview, share image, favicon, app icon, apple touch icon, or web manifest. Also use when a shared link previews blank, shows the wrong image, or a favicon will not appear. Includes the absolute-URL trap that silently blanks every preview and the font trap that breaks SVG favicons on other machines.

brainzcode/premium-landing

Source free, licence-clear photography for a site from Unsplash — searching by mood rather than noun, sizing and cropping for the slot, honouring the API's hotlink and download-tracking requirements, and writing real alt text. Use when a page needs a hero image, section photography, avatars or card art and none was supplied; when placeholder greys need replacing with real imagery; or when asked to find, pick or swap photos for a design.

관련 스킬