Communitygithub.com

Liquid Glass · 전 기능 구현

Apple WWDC25 Liquid Glass의 모든 기능을 단일 파일 WebGL로 구현: 26가지 재질 특성 + 82개 동작(클릭/더블클릭/길게 누르기/우클릭/드래그/관성/잔상/펼치기/접기/분리/합치기/융합/키보드/접근성/스크롤 경계). 사용자가 Apple 액체유리, 유리모피즘 UI, 투명 굴절 유리, Liquid Glass 버튼·메뉴·Dock을 요청하거나, 눌림 반응·변형·광로 분석이 필요할 때 사용합니다. 바로 실행 가능한 단일 파일 liquid-glass-all.html(WebGL 프래그먼트 셰이더, 2개 program, 10회 draw call, 헤드리스 Chrome으로 실제 실행 및 ?selftest=1 내장 자체 테스트)이 함께 제공됩니다.

Liquid Glass · 전 기능 구현란 무엇인가요?

이 스킬은 Apple WWDC25에서 발표된 'Liquid Glass' 효과를 WebGL로 완전히 재현하는 단일 HTML 파일(`liquid-glass-all.html`)을 제공합니다. 프래그먼트 셰이더에서 모든 광학 효과(굴절, 두께, 프레넬, 분산, 림, 내부 발광)를 실시간으로 계산하며, DOM은 텍스트, 버튼 및 그림자만 렌더링합니다. Claude Code, Cursor, Codex 등의 AI 에이전트가 사용자 요청에 따라 이 파일을 생성, 수정 또는 분석하는 데 특화되어 있습니다. 셰이더 작성 시 일반적인 함정(예: uniform 배열 최적화, 텍스처 Y축 뒤집기, GLSL 예약어 충돌)을 방지하는 상세한 지침과 함께, 9개 범주의 82개 동작(포인터, 드래그, 형태 변형, 누름 반응, 광학 애니메이션, 적응형, 시스템/접근성, 컨트롤, 키보드)을 지원합니다. 내장 자체 테스트(?selftest=1)와 성능 예산 가이드라인을 제공하여 구현의 완전성과 효율성을 검증합니다. 주요 AI 에이전트(Claude Code, Cursor, Codex, GitHub Copilot, Windsurf)와 호환되며, 헤드리스 Chrome을 통한 실제 스크린샯 검증을 요구합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cyt-56/liquid-glass-webgl/tree/HEAD/skill

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

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

문서

Liquid Glass · 전 기능 구현은(는) 무엇을 하나요?

단일 파일 WebGL 구현, 유리의 굴절/두께/Fresnel/분산/림/내부 발광을 모두 프래그먼트 셰이더에서 계산하며, DOM은 텍스트, 버튼 및 그림자만 렌더링합니다. 셰이더를 처음부터 직접 작성하지 마세요: 90줄이면 실행되지만, 400줄을 처음부터 작성하면 성공률이 매우 낮습니다. liquid-glass-all.html에서 수정하세요.

0. 가장 빠른 경로 (1분 안에 효과 확인)

  1. Chrome / Edge로 liquid-glass-all.html을 엽니다.
  2. 오른쪽 제어판에 5개의 슬라이더(refract / mag / rim / disp / tint) + 4개의 레시피 키가 있으며, 수정 즉시 변경 사항을 확인할 수 있습니다.
  3. 모든 동작이 포함되어 있습니다: 캡슐 클릭하여 펼치기, 길게 눌러 드래그, 길게 누르면 버블 생성, 우클릭으로 다른 메뉴, 더블클릭으로 들어올리기, Dock 분리 키, 키보드 Space/S/W/Esc.
  4. 내장 자체 테스트로 검증: 주소 뒤에 ?selftest=1을 추가하면 페이지 왼쪽 상단에 13개의 PASS / FAIL이 직접 출력됩니다.
  5. 스크린샷 촬영: ?pose=1로 '펼치기 + 분리 + 버블'을 한 번에 배치하고, ?pose&wire=1로 광로 진단 필드를 겹칩니다.
chrome --headless=new --enable-unsafe-swiftshader --virtual-time-budget=6000 ^
  --window-size=1280,800 --screenshot=out.png "file:///<absolute-path>/liquid-glass-all.html?selftest=1"

스크린샷을 찍은 후 실제로 이미지를 읽어서 왼쪽 상단이 FAIL 0인지 확인하세요. 코드만 보고 완료했다고 판단하지 마세요.

1. 자산

liquid-glass-all/
├── SKILL.md                       # 이 파일: 경로, 동작, 광로, 함정, 검증
├── liquid-glass-all.html          # 전 기능 구현 (유일한 실행 산출물)
└── references/
    ├── action-matrix.md           # 82개 동작 전체 표 (트리거 / 변경 사항 / 매개변수 / 역동작)
    ├── feature-matrix.md          # 26개 재질 특성 × 본 구현의 적용 범위
    ├── optics-model.md            # 광로 물리 모델과 상수 (셰이더 작성 전 필독)
    └── interaction-playbook.md    # 상태 기계, 타이밍, 히트 테스트, 검증

2. 82개 동작 빠른 참조 (9개 범주)

전체 표는 references/action-matrix.md를 참조하세요. 여기서는 골격만 제공합니다.

범주개수내용
A 포인터13호버 진입/이동/이탈, 주변 감쇠, press, release, 클릭, 드래그 시작/추종/탄성 복귀, 경계 clamp, 우클릭 메뉴, 길게 누르기 메뉴
B 드래그 관성6방향 스트레칭, 탄성 평행 이동, 변형 감쇠, 관성 슬라이드, 드래그 들어올리기, 지연 잔상
C 형태 Morph10펼치기/접기, 메뉴 항목 페이드 인, 모서리 둥글기 추종, 분리/오른쪽 조각 생성/합치기, 분열 강세, 너비 0 건너뛰기, 융합 연결 목
D 누름 반응8수축, 굴절 강화, 두께 증가, 내부 발광, 이웃 패널 전파, 하단 아치 밝아짐, 방향 하이라이트, flash 길 안내
E 광학 애니메이션83가지 굴절 모드, 변형 전환, tint 매핑, 명암 반전, 환경 오버플로 색상, 적응형 그림자, 초점 흐려짐 퇴장, 배경 광점 표류
F 적응형7밝기/주 색상 샘플링, 배경 업로드, 적응형 해상도, 광로 갱신, DPR 상한, 성능 저하 체인
G 시스템 및 접근성8resize 재배치, 스크롤 soft/hard, 3개 접근성 스위치, 창 포커스 상실, Tab 포커스 링, 스크린 리더 시맨틱
H 컨트롤8주 작업 버튼, 5개 슬라이더, 변형 세그먼트, 모드 3키, 4개 스위치, 4개 레시피, 분리 키, 펼치기 헤더
K 키보드7Space / S / W / Esc / Tab / ↑↓ / Enter

동작 모니터 막대가 페이지 하단에 있습니다: 각 동작을 기록하고 최근 4개를 표시하여 '이 동작이 실제로 트리거되었는지' 확인합니다.

3. 광로 7단계 (순서 변경 불가)

  1. 윤곽: sdRoundBox로 부호 있는 거리 d를 구합니다. x = clamp(-d/band, 0, 1), 0=윤곽, 1=중심, band = max(5, min(hx,hy)*0.30).
  2. 볼록 높이 필드: H(x)=sqrt(1-(1-x)²), H'(x)=v/sqrt(1-v²) (v=clamp(1-x,0.02,0.9995)). pow 대신 sqrt를 사용합니다.
  3. 입사각: sinI = min(H'/sqrt(1+H'²), 0.62), thT = asin(sinI/1.5168). 0.62는 하드 상한이며, 0.93으로 올리면 가장자리가 200px 수준으로 밀려나 전체가 검게 변합니다.
  4. 두께: tpx = mdim*(0.05+0.28*H)*(1+0.40*thick)*vg, vg = 1+0.24*(1-smoothstep(-0.85,0.35,q.y)) (아래는 두껍고 위는 얇음).
  5. 변위: off = -dir*tan(thI-thT)*tpx*refract*Tf, 가장자리 항 추가; 마지막으로 clamp(off,-10,10).
  6. 초점/림: focal = mag*magMul*(0.50*cW - 0.40*eW); 1-focal은 항상 양수여야 합니다. 그렇지 않으면 국소적으로 180° 뒤집혀 글자가 거꾸로 보입니다. magMul은 패널 수준: lens 1.30 / capsule 0.85 / plate 0.55 / nav 0.90 / dock 0.80.
  7. 합성: sp = c + rel*(1-focal) - off; RGB를 ±disp*7*eW로 분리 샘플링; tint 밝기 압축 0.58*L+0.133, 환경 오버플로 색상 0.10, Fresnel rim, 유백색, 상단 거울, 하단 아치, 내부 발광.

텍스처 Y는 뒤집어야 합니다: uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y), 이 한 줄이 없으면 이미지가 미러링되고 글자가 거꾸로 표시됩니다.

4. 상태 기계 및 주요 임계값

동작임계값 / 매개변수
hover패널 내부; 패널 외부 180px 내에서 fade 감쇠
presspress→1(k=0.19/프레임), scale 0.965, 굴절 ×1.3, 하단 아치 ×1.75
클릭pointerup 및 변위 ≤4px → 240ms 지연 후 트리거, 더블클릭과 충돌 방지
더블클릭두 번의 pointerdown 간격 <300ms, 두 번째 down에서 즉시 클릭 타이머 취소
길게 누르기pointerdown 후 500ms, 이동 >4px이면 취소; 진행 점이 터치 포인트에서 확대
드래그변위 >4px여야 드래그로 전환; clamp 8px 내부 여백
관성손을 놓은 속도 >6px/이벤트 → v*1.05 시작, 프레임당 ×0.94, <1px에서 종료 및 고정
펼치기136×48 → 236×296, 아래쪽 가장자리 고정: ty = lay.y + lay.h - 296; 메뉴 항목은 높이 110→250으로 페이드 인, 절반 이상에서 pointerEvents 활성화
분리Dock 300 → 왼쪽 140; 오른쪽 조각 tx를 lay.x + lay.w - 140에 고정, 너비 0→140
합치기오른쪽 조각이 먼저 너비를 줄이고 위치는 고정('미끄러짐' 방지)
융합분리 후 두 조각 사이에 20px 간격 유지, rim이 서로 반응; 실제 메타볼 합집합은 SDF smooth-min이 필요하며 Web 단일 패스 버전에서는 구현되지 않음
스프링위치 ω=15, 너비 ω=18.5, ζ=0.66, dt=1/60 → 약 0.45초, 6% 오버슈트

5. 매개변수 레시피

원하는 효과refractmagrimdisptintthick
두꺼운 유리 캡슐1.200.350.950.220.24✓
렌즈 아래 색띠1.500.601.000.180.10✓
두꺼운 유리 덮개 작은 글자1.250.420.800.300.16✓
상단 내비게이션(절제)0.900.200.600.150.10✗
제어판(가독성)1.000.150.550.120.14✗

조정 순서: refract로 변위 설정 → mag로 림 설정 → rim으로 가장자리 설정 → disp/tint로 질감 설정, 순서를 뒤집으면 항상 서로 충돌합니다.

6. 반드시 겪는 8가지 함정

  1. uniform 배열은 신뢰할 수 없음: ANGLE/D3D에서 uGeo[12]에 값을 할당해도 오류가 발생하지 않지만 적용되지 않음 → 패널당 한 번의 draw call.
  2. 루프 내부의 uniform 분기는 최적화되어 제거됨: 루프 내에서는 mix/step을 사용한 분기 없는 작성 방식 사용.
  3. 선언되었지만 사용되지 않은 uniform이 최적화되어 제거됨: getUniformLocation이 null을 반환하여 uniform 누락으로 잘못 보고됨.
  4. gl.getUniform(prog, null)이 TypeError를 발생시킴: 전체 프레임의 이후 코드가 모두 건너뛰어짐(마치 멈춘 것처럼 보임).
  5. 텍스처 Y축: 뒤집지 않으면 이미지가 미러링되고 글자가 거꾸로 표시됨.
  6. click만 바인딩하면 이벤트가 손실됨: pointerdown + pointerup + 변위 임계값 사용.
  7. half는 GLSL ES 예약어: vec2 half를 작성하면 전체 컴파일이 실패하고, 로그에는 구문 오류만 표시됨. 유사한 위험 단어: filter / input / output / long / short / packed.
  8. 역순 smoothstep은 정의되지 않은 동작: smoothstep(1.0,-1.0,d)는 머신에 따라 실패하므로 항상 1.0 - smoothstep(작은값, 큰값, x)로 작성.

추가로 동작 레이어 전용 함정:

  • 길게 누른 후 손을 떼면 클릭으로 간주하면 안 됨(longFired 플래그로 표시). 그렇지 않으면 길게 누르기 메뉴가 열리자마자 펼치기가 바로 이어짐.
  • 우클릭은 pointerdown보다 먼저 차단해야 함(e.button !== 0일 때 바로 return). 그렇지 않으면 우클릭이 드래그를 시작함.

7. 검증 (수정할 때마다 실행)

?selftest=1은 13개 항목을 테스트합니다: 클릭으로 펼치기/접기, 길게 눌러 버블, Esc로 버블 닫기, 우클릭으로 다른 메뉴, Dock 분리와 합치기, 융합 목, 방향키 선택, Esc 전체 접기, 더블클릭 들어올리기, 관성, W 광로 필드.

추가로 수동 확인:

  • 유리 안의 콘텐츠 방향이 올바름(거꾸로 또는 미러링 없음)
  • 가장자리 둘레의 rim, 상단 거울, 하단 밝은 아치가 모두 있음
  • 어두운 배경에서 유리 내부가 완전히 검지 않음(안개 낀 회색이 있음)
  • 드래그 시 잔상이 지연되고, 손을 놓으면 관성이 있다가 고정됨
  • 분리 시 두 조각이 '찢어지는' 것이지 '서로 당기는' 것이 아님
  • 스크롤 텍스트가 가장자리에서 점차 사라지고, 끝점에 도달하면 hard로 전환되어 가는 선 표시
  • 3가지 접근성 스위치가 모두 작동(투명도 낮춤/대비 강화/동작 줄임)

8. 성능 예산

항목예산
동시 화면 유리 조각≤10개(본 구현 10개, 필요에 따라 나타나는 0 너비 버블/브리지 포함)
draw call2개 program + 조각당 1회 AABB draw
배경 업로드5프레임마다; 정지 시 8프레임 가능
밝기 샘플링10프레임마다, w*h>24000인 패널만 샘플링
렌더링 배율<42fps → 0.72, >56fps → 1.0, DPR 상한 2
성능 저하 체인패널 감소 → 배율 감소 → 업로드 감소 → 색 분산 끄기 → CSS 버전으로 후퇴

9. 레드라인 및 플랫폼 경계

  • 유리는 내비게이션 레이어에만 적용됨; 콘텐츠 레이어에는 유리를 깔지 않음.
  • 유리를 겹쳐서 사용하지 않음(굴절 참조를 잃어 더러운 얼룩처럼 보임); Regular와 Clear를 같은 화면에 혼용하지 않음.
  • tint는 주 작업에만 사용; 하이라이트는 절제하며, rim > 1.2이면 가짜처럼 보임.
  • Web에서 구현 불가능한 것: 유리 위의 텍스트/아이콘이 자체 굴절되는 것(iOS 26 시스템 합성 파이프라인에 해당); CSS 폴백은 픽셀 단위 렌즈 림과 색 분산을 구현할 수 없음.
  • 자체 렌더링 버전에서 미포함: 실제 메타볼 합집합(본 구현은 좁은 목 근사치 사용), 기기 기울기 조명, 실시간 비디오의 프레임별 주 색상 통계.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬