Communitygithub.com

omd-cjk-type-shader — 먹 번짐: 한지 위의 수묵 같은 CJK 타이틀

한 가지 효과를 제대로 구현합니다: 한글·일본어·중국어 대형 제목이 한지에 인쇄된 수묵처럼 보이게 하는 WebGL2 셰이더. 텍스트는 첫 프레임부터 선택 및 복사 가능하며, 잉크가 번지고 마르는 자연스러운 과정을 재현합니다.

omd-cjk-type-shader — 먹 번짐: 한지 위의 수묵 같은 CJK 타이틀란 무엇인가요?

이 스킬은 한글, 일본어, 중국어(CJK) 대형 헤드라인(h1/h2, 40px 이상)에 수묵(먹)이 한지에 번져드는 효과를 더하는 WebGL2 셰이더입니다. 실제 돔 텍스트 위에 오버레이 레이어를 입혀 텍스트 자체는 그대로 유지하면서(선택, 복사, 시맨틱 접근성, 검색 엔진 모두 정상), 잉크가 젖어 있을 때의 광택과 번짐, 마르면서 생기는 농담, 획 가장자리의 먹 농축, 종이 섬유가 비치는 현상(카스레), 모세관 번짐(니지미) 등을 재현합니다. 어두운 배경에서는 자동으로 금니(금가루+아교)가 감지(쪽염색 종이) 위에 칠해진 효과로 전환되어, 번짐 없이 광택과 입자 감촉을 보여줍니다. `bleed`(번짐 정도)와 `duration`(마름 시간) 두 가지 매개변수만 조절 가능하며, 라이브러리 JS는 약 5KiB gzip으로 가볍습니다. WebGL2를 지원하지 않는 환경이나 `prefers-reduced-motion` 설정 시 정적 대체 스타일로 우아하게 대체되며, 실제 GPU에서 테스트하는 검증 스크립트가 포함되어 있습니다. Next.js/React에서도 클라이언트 컴포넌트로 쉽게 통합 가능합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nococn/omd-cjk-type-shader/tree/main

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

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

문서

omd-cjk-type-shader — 먹 번짐: 한지 위의 수묵 같은 CJK 타이틀은(는) 무엇을 하나요?

잉크가 종이에 스며드는 이미지는 한국, 일본, 중국 작문이 공유하는 하나의 이미지입니다. 이 스킬은 큰 CJK 헤드라인이 한지에 인쇄되거나 붓으로 쓴 것처럼 읽히게 만듭니다. 빠르게 훑어볼 때 필터가 아니라 캘리그래피 포스터처럼 보여야 합니다.

작동 방식. 제목은 잉크 색상의 일반 DOM 텍스트로, 첫 프레임부터 읽고 선택할 수 있습니다. 이 스킬은 브라우저가 배치한 모든 그래핌을 추적하고 그 마스크로부터 세 가지 필드(획 바깥 거리, 획 안쪽 거리, 국소 잉크 커버리지)를 만듭니다. 텍스트 위에 그려진 WebGL2 레이어는 실제 잉크가 하는 것만 추가합니다:

  • 젖음 → 마름: 획은 광택이 나는 어두운 색으로 시작해 주변에 부드러운 번짐(bloom)이 생기고, 잉크가 마르면서 번짐이 줄어듭니다;
  • 농축(pooling): 잉크가 획 가장자리와 획 끝, 볼록한 모서리(낮은 국소 커버리지)에 더 어둡게 모입니다;
  • 카스레(kasure): 마르면 두꺼운 획 중간에 종이 섬유가 비쳐 보입니다;
  • 니지미(nijimi): 저주파 노이즈에 의해 선택된 일부 가장자리에서 종이 섬유를 따라 모세관 번짐이 발생하며, 모든 글리프 주위에 고른 고리로 나타나지 않습니다;
  • 종이: 페이지에 절차적 한지 텍스처(SVG 난류, 이미지 없음)가 적용됩니다.

어두운 바탕에서는 동일한 시그니처가 금니(金泥) on 감지(紺紙)로 전환됩니다. 고려 사경 필사자들은 쪽염색 종이에 금가루를 아교에 섞어 썼습니다. 안료는 잉크처럼 스며들지 않으므로 이 변형은 결코 번지거나 번짐이 없습니다. 젖은 아교는 탁하고 약간 어둡게 보입니다. 마르면서 입자가 가라앉고 빛을 받습니다(드문드문 반짝임). 한 줄에 느린 광택이 스쳐 지나가고, 붓이 멈춘 끝과 모서리는 더 풍부하게 읽히며, 얇게 지나간 부분은 쪽빛이 비쳐 보입니다. 제목의 색상이 가장 가까운 칠해진 배경보다 밝으면 자동으로 켜집니다(data-ink-ground="dark" 또는 "light"로 강제 지정 가능). 그리는 모든 색상은 제목 자체의 색상(어둡거나 밝게)이거나 바탕의 색상입니다.

제목이 뷰포트에 들어오면 한 번 재생된 후 렌더 루프가 멈춥니다. 줄 바꿈, keep-all, 글꼴 변경 및 크기 조정은 다시 추적됩니다.

작동 예시: examples/demo.html (단일 파일, 한국어 + 일본어 + 번체 중국어, 한지 및 감지 섹션에서). 증명: scripts/verify.mjs.

1. 사용 시기 / 사용하지 말아야 할 때

사용:

  • 한국어, 일본어 또는 중국어 디스플레이 헤드라인(≥ 40px; 히어로, 출시 타이틀, 캠페인 라인, 섹션 오프너)이 잉크처럼, 캘리그래피처럼, "한지/와시/선지에 인쇄된" 느낌이 들어야 할 때;
  • 브랜드의 잉크와 종이 색상이 알려져 있을 때(DESIGN.md 전경/캔버스, 또는 제목의 계산된 color와 가장 가까운 칠해진 배경). 어두운 바탕은 금니 변형을 사용합니다: 어두워질 여유가 있는 따뜻하고 밝은 텍스트 색상을 사용하세요(데모의 #d4b062 on #1a2440은 7.4:1).

사용하지 마세요:

  • 본문 텍스트, 레이블, 버튼, 내비게이션, 약 32px 미만(농축과 번짐이 획 너비를 필요로 함);
  • 라틴 문자 전용 헤드라인(작동은 하지만 문화적 포인트가 사라짐);
  • 페이지당 하나 또는 두 개 이상의 헤드라인. 한 곳에만 과감하게 사용하세요(tf-shaders 규칙).

2. 효과와 두 가지 매개변수

매개변수범위기본값설명
bleed0–10.7모세관 번짐이 섬유를 따라 이동하는 거리(최대 0.12em × bleed, 노이즈가 선택한 가장자리에서)와 젖은 번짐의 크기. 0.4 = 거의 없음, 0.8 = 젖은 붓.
duration초2.6젖은 상태에서 마를 때까지의 시간. 번짐은 일찍 최고조에 달했다가 줄어듦; 농축과 섬유 투과는 마르면서 나타남. 1.5초 미만이면 번쩍임으로 읽히고, 4초 이상이면 로딩 상태로 읽힘.

그 외 모든 것은 의도적으로 고정됩니다. 잉크 = 제목의 계산된 color, 농축을 위해 25% 어두워짐; 종이 = 페이지 배경색. 텍스트 잉크는 순수한 검정이 아닌 수묵 회색-검정이어야 합니다(데모는 #3a3530 on #f3eee4, 약 10:1 사용). 그러면 더 어두운 농축이 나타날 공간이 생깁니다. 하나의 시그니처이지 제어판이 아닙니다.

3. 텍스트를 텍스트로 유지하는 계약

  • 제목은 실제 텍스트가 포함된 일반 <h1>/<h2>입니다. inkBleed()는 텍스트를 .ink-text로 감싸고 그 위에 aria-hidden="true", pointer-events: none 레이어(z-index 2)를 삽입합니다. 레이어는 이미 있는 것을 어둡게, 밝게 또는 확장만 합니다. 글리프를 대체하거나 다시 그리지 않으며, 레이어를 제거해도 제목은 여전히 완전합니다.
  • 헤드라인은 첫 번째 프레임에 그려집니다. opacity: 0, 클립, 셰이더 대기 없음. tf-shaders는 히어로 카피가 셰이더를 기다릴 때 LCP가 7.8초까지 증가하는 것을 측정했습니다.
  • 선택, 복사, 페이지 내 찾기, 번역, 스크린 리더 및 SEO는 일반 텍스트를 봅니다. verify.mjs는 각 패스에서 제목을 선택하면 전체 텍스트가 반환되는지 확인합니다.
  • 헤드라인 주위에 약 0.4em의 여유 공간을 남겨 둡니다(데모는 margin-bottom: 0.4em 사용). 번짐과 블룸은 글리프 너머 약 0.3em까지 확장됩니다.
  • CJK 헤드라인을 캔버스/Text 셰이더 구성 요소로 그리지 마세요. 캔버스 텍스트는 선택, 접근성, 인덱싱 및 올바른 CJK 조합을 잃습니다(tf-shaders "Don't" 목록).

4. CJK 조판(셰이더 전에 적용)

/hangul (HG 규칙)에서 한국어용; ja/zh는 별도 범위로 지정되어 한국어 규칙이 누출되지 않음:

.ink:lang(ko) { word-break: keep-all; overflow-wrap: anywhere;  /* HG-10, :lang(ko)로 범위 지정 */
                letter-spacing: -0.02em;                          /* HG-7: 디스플레이 절대 -0.03em 미만 */
                line-height: 1.3; }                               /* HG-5: 줄바꿈 디스플레이 >= 1.3 */
.ink:lang(ja), .ink:lang(zh-Hant) {
  line-break: strict;                                 /* 금칙처리: 줄 시작에 작은 가나/닫는 기호 금지 */
  word-break: keep-all; overflow-wrap: anywhere;      /* 사용자가 배치한 <wbr> 구문 마크에서만 나눔 */
  letter-spacing: 0; line-height: 1.4; }
:lang(ko), :lang(ja), :lang(zh) { font-synthesis: none; } /* CJK에 가짜 볼드/이탤릭 금지 */
  • 일본어/중국어 구문 경계를 <wbr>로 표시하세요(BudouX 스타일: 墨がにじむように、<wbr>名前が<wbr>紙に染みこむ。). headless Chrome 149에서 word-break: auto-phrase는 올바르게 계산되었지만 이 데모에서 구문 나누기를 생성하지 않았으므로 의존하지 마세요.
  • 한국어: 어절 사이의 공백에서만 줄바꿈, 음절 단위로 나누지 않음. 카피라이터가 신경 쓸 때 디스플레이 줄바꿈을 수동으로 배치하세요(tf-shaders cjk-type.md).
  • 제목에 lang을 설정하세요(ko, ja, zh-Hant/zh-Hans). 공유 한자 코드 포인트에 대한 올바른 글리프 변형을 선택하고 위 규칙의 범위를 지정합니다.
  • 글꼴: 설정한 두께를 제공하는 페이스를 사용하세요(HG-12). 데모는 Google Fonts의 Noto Serif KR / JP / TC 700을 사용하며, 페이지에서 사용하는 글리프 조각만 로드합니다. 명조/민초/송체 페이스가 잉크에 적합합니다. Pretendard도 작동합니다. document.fonts.ready 이후에 추적하여 필드가 대체 글꼴이 아닌 실제 페이스를 따르도록 합니다.

5. 라이브러리, 라이선스, 예산

라이브러리: @paper-design/shaders (바닐라 ShaderMount), 0.0.82로 고정 (2026-10-21; dispose()가 이제 WebGL 컨텍스트를 해제), WebGL2. 의사 결정 기록 (npm tarball의 LICENSE 파일, npm 메타데이터 및 GitHub 라이선스 API에서 2026-10-13 확인):

@paper-design/shaders 0.0.81shaders 4.0.4 (shaders.com)
라이선스Apache-2.0 (LICENSE + NOTICE "Paper Shaders, Copyright 2026 Paper")MIT (© 2026 Shader Effects Inc.); 종속성 typegpu 0.12.3 MIT (Software Mansion)
스킬/템플릿에서 재배포허용됨; 코드를 벤더링하는 경우 NOTICE 유지허용됨
런타임WebGL2: 모든 최신 데스크톱 및 모바일 브라우저WebGPU 전용, 대체 없음 (Chrome/Edge, Android 12+ Chrome, Safari 26+, 최신 Firefox)
이 효과를 위한 JS17.5 KiB min / 5.3 KiB gzip (esbuild, ShaderMount만); CDN 파일별 +esm 16.4 KiB / 5.0 KiB gzip2,535 KiB min / 710 KiB gzip (esbuild, shaders/react의 Shader+MeshGradient)
텔레메트리없음 (유일한 fetch()는 로컬 blob의 콘텐츠 유형을 읽음)기본 켜짐: 세션의 5%를 shaders.com/api/telemetry로 샘플링; disableTelemetry 전달
사용자 정의 GLSL + 텍스처예 (ShaderMount(el, frag, uniforms), 이미지 유니폼)컴포넌트 그래프를 통해

효과에는 사용자 정의 프래그먼트 셰이더와 하나의 텍스처가 필요하며, 이는 정확히 ShaderMount가 하는 일입니다. WebGPU 런타임 무게의 1/130이고 브라우저 도달 범위는 두 배입니다. 데모는 jsDelivr(고정, 파일별 빌드)에서 Paper를 가져오며 벤더링하지 않으므로 NOTICE 복사본이 필요하지 않습니다. Paper 파일을 벤더링하는 경우 NOTICE를 함께 복사하세요. 프로젝트에 이미 shaders가 있는 경우에도 이 효과는 Paper에서 실행됩니다. 한 페이지에 두 런타임을 모두 로드하지 마세요.

하나의 헤드라인에 대한 예산:

  • JS: 5.0–5.3 KiB gzip 라이브러리 + 5.3 KiB gzip 효과 코드(셰이더, 두 거리 변환, 커버리지 블러, 추적; 주석 제거 및 축소 전 측정).
  • GPU: 하나의 쿼드, 픽셀당 하나의 텍스처 조회 및 7개의 값 노이즈 호출, 헤드라인 상자 + ≤0.32em 패딩 영역, minPixelRatio: 1, 1920×1080 px로 제한. duration 동안 실행된 후 setSpeed(0)가 rAF 루프를 중지합니다. Paper는 또한 화면 밖 및 숨겨진 탭에서 일시 중지합니다.
  • CPU: 레이아웃 변경(글꼴 교체, 크기 조정, 줄바꿈; 120ms 디바운스) 시, 두 유클리드 거리 변환(획 외부 및 내부) 및 하나의 분리 가능한 박스 블러, 64px 이상 유형의 경우 절반 해상도에서 수행.
  • 종이 텍스처: html에 인라인 SVG feTurbulence 데이터 URI(~600바이트), 이미지 요청 없음.
  • 글꼴이 실제 비용입니다. CJK 페이스는 큽니다. 유니코드 범위 조각으로 디스플레이 두께만 로드하세요.

6. 대체 및 동작 감소

  • WebGL2 없음 (마운트 전 canvas.getContext('webgl2') 탐색; ShaderMount는 컨텍스트를 얻거나 프로그램을 연결할 수 없으면 오류 발생): 레이어가 삽입되지 않고 제목이 .ink-static(희미한 CSS text-shadow)을 얻습니다. 제목은 이미 질감이 있는 종이에 잉크로 표시되어 있으므로 셰이더 없이도 완전합니다. verify.mjs는 getContext를 스텁하여 이 경로를 강제합니다.
  • prefers-reduced-motion: reduce: 속도 0으로 마른 프레임에서 마운트. 사용자는 움직임 없이, rAF 루프 없이 최종 잉크 상태를 하나의 정지 프레임으로 얻습니다.
  • 셰이더 컴파일 실패 (이것을 빌드하는 동안 한 번 발생: Paper의 버텍스 셰이더와의 정밀도 불일치)는 동일한 .ink-static 경로를 따릅니다. 자체 GLSL에서는 uniform mediump vec2 u_resolution;을 선언하세요. 정밀도가 Paper의 버텍스 셰이더와 일치해야 하기 때문입니다.

7. 실제 GPU에서 확인

next build 또는 린트 통과는 셰이더에 대해 아무 것도 증명하지 않습니다(tf-shaders 규칙). 실행:

npm i -D playwright-core && npx playwright-core install chromium   # 새 Playwright Chromium, 자신의 Chrome 아님
node <skill>/scripts/verify.mjs path/to/page.html ./ink-verify --frames 36

headless Chromium을 --enable-gpu --ignore-gpu-blocklist --use-angle=metal(macOS)로 실행하고 세 가지 패스(GPU, 동작 감소, WebGL 없음)를 수행합니다. 각 바탕(data-ink-ground="light" 및 "dark")에서 첫 번째 제목을 측정합니다. 그런 다음:

  • WebGL 렌더러 문자열을 기록하여 실제 GPU 또는 SwiftShader가 프레임을 그렸는지 확인합니다;
  • 셰이더 클록을 결정론적으로 단계별로 진행하고 프레임을 저장합니다(demo GIF/MP4용 ffmpeg에 제공);
  • 픽셀로 렌더링 증명: 헤드라인 상자 내 셰이더 켜짐 vs 꺼짐, 첫 프레임 vs 마른 프레임;
  • 전체 효과를 통한 가독성 측정: 샘플링된 각 프레임에서 그 뒤의 종이에 대해 그려진 글리프 코어(텍스트 켜짐 vs 텍스트 투명), 10번째 백분위수로 앤티앨리어싱된 가장자리가 결정하지 않도록, 최악의 프레임. 디스플레이 헤드라인은 WCAG 큰 텍스트이므로 기준은 3:1입니다;
  • 선택한 텍스트가 헤드라인 텍스트와 동일한지, 레이어가 aria-hidden + pointer-events: none인지, 동작 감소가 정지인지, WebGL 없음이 캔버스를 남기지 않는지 확인합니다.

2026-11-06 측정(headless Chromium, ANGLE Metal Renderer: Apple M5 Pro, SwiftShader 아님), 모든 검사 통과:

바탕셰이더로 변경된 헤드라인 상자 픽셀젖음 vs 마름글리프 가독성 (p10, 최악 프레임)
밝음 (한지 위 수묵, #3a3530 on #f3eee4)10.2%5.9%8.01:1
어두움 (감지 위 금니, #d4b062 on #1a2440)8.8%8.7%4.58:1
어쨌든 프레임을 전체 크기로 보세요: 정렬이 잘못된 필드(잘못된 기준선)는 획에서 오프셋된 농축으로 표시되고, 너무 강한 번짐 설정은 털처럼 읽힙니다. 당신의 눈만이 그것들을 잡아냅니다.

8. Next.js / React 포팅

'use client' 리프에서 동일한 함수와 라이프사이클을 유지하세요: useEffect(() => { let h; document.fonts.ready.then(async () => { const { ShaderMount } = await import('@paper-design/shaders'); h = await inkBleed(ref.current, { bleed, duration }); }); return () => h?.mount.dispose(); }, []). 제목을 서버 측에서 일반 텍스트로 렌더링하여 셰이더가 하이드레이션 후에만 장식하도록 합니다. 여기서 @paper-design/shaders-react의 <ShaderMount>를 사용하지 마세요: WebGL2 프로브, 대체 클래스 또는 필드가 다시 추적되는 시점을 제어할 수 없습니다.

9. 저작자 표시

예산 우선 프레이밍, 대체-는-디자인 규칙, 첫 프레임 LCP 규칙, 어절-아닌-음절 공개, keep-all 및 실제 GPU 스크린샷 루프는 소유자의 tf-shaders 실험(skill/shader-landing/SKILL.md, references/cjk-type.md, scripts/shoot.mjs, RESEARCH.md, 2026-10)에서 비롯되었습니다. 한국어 타이포그래피 값은 OmD의 /hangul 스킬에서 비롯되었습니다. 거리 변환은 Felzenszwalb & Huttenlocher의 선형 시간 EDT이며, 여기서 새로 작성되었습니다. 어두운 바탕 변형은 Leonxlnx/taste-skill의 print3d.js(MIT)에 명시된 패턴 "어두운 종이에서 잉크는 빛이다"를 따릅니다: 처리는 반전되며, 단순히 색상만 변경하지 않습니다. 코드가 복사되지 않았습니다. 금 모델은 감지금니 관행에서 새로 작성되었습니다.

하지 말 것

  • 셰이더가 준비될 때까지 제목을 숨기지 마세요. 텍스트가 콘텐츠입니다. 잉크는 프레임입니다.
  • 음절 단위로 애니메이션하지 말고, 한글을 문자별 범위로 나누어 공개하지 마세요.
  • 루프를 영원히 실행하지 마세요. 마른 잉크 효과는 아무 비용이 들지 않습니다. 루핑하는 것은 배터리를 소모합니다.
  • 하나의 헤드라인을 위해 한 페이지에 두 개의 런타임(Paper + shaders)을 두지 마세요.
  • 모든 가장자리를 번지게 하거나 균일한 후광을 그리지 마세요. 각 글리프 주위의 고른 고리는 스티커처럼 읽히고 잉크처럼 읽히지 않습니다. 번짐은 몇몇 가장자리에 속합니다.
  • 순수한 검정 텍스트 잉크를 사용하지 마세요. 농축이 표시되려면 더 어두운 값이 필요하며, 수묵은 회색-검정입니다.

관련 스킬