Communitygithub.com

omd-cjk-type-shader — 먹 번짐:CJK 顯示字型作為墨跡於韓紙上

一個效果,做到極致:먹 번짐 — 大型韓文、日文或中文顯示標題,呈現如墨印於韓紙的效果。標題從第一幀起即為真實、可選取的 DOM 文字,墨水顏色;上層的 WebGL2 圖層添加了真實墨水的特性:濕潤光澤的筆觸帶有柔和的暈開效果,隨乾燥而縮小,墨汁在筆畫邊緣、末端與轉角匯聚變深,粗筆畫中顯露紙張纖維,以及僅在少數邊緣沿纖維產生的毛細擴散。在深色背景上,它會自動切換為 금니 on 감지(金泥於紺紙):無擴散,暗淡濕潤狀態,沉澱顆粒,一次緩慢光澤。兩個參數(擴散程度、持續時間),約 5 KiB gzip 的函式庫 JS,程序化紙紋,靜態降級方案,prefers-reduced-motion,真實 GPU 驗證腳本。用於 CJK 主視覺/啟動標題、品牌名稱、宣傳口號或章節開場,應具備印刷書法海報的感覺。觸發詞:'먹 번짐', '잉크 번짐', '한지 느낌 제목', '한글 타이포 셰이더', '제목에 셰이더', '墨のにじみ', '和紙', '筆文字っぽ...

omd-cjk-type-shader — 먹 번짐:CJK 顯示字型作為墨跡於韓紙上 是什麼?

此技能為大型韓文、日文或中文(CJK)顯示標題提供了一種視覺效果,使其看起來像是以墨汁印刷或書寫在韓紙(hanji)上。它並非一個簡單的濾鏡,而是透過 WebGL2 在真實的 DOM 文字上方疊加一層模擬墨水物理特性的效果:從濕潤光澤的筆觸開始,帶有柔和的暈開區域,隨著墨水乾燥而縮小;墨汁在筆畫邊緣、末端和轉角匯聚變深;粗筆畫乾燥後會顯露紙張纖維;並在特定邊緣產生沿纖維的毛細擴散效果。在深色背景上,它會自動切換為「금니 on 감지」(金泥於紺紙)風格,模擬高麗經卷上金粉顏料的質感,無擴散、有沉澱顆粒和緩慢光澤。此技能的核心價值在於保留文字的可選取性、可複製性、無障礙性與 SEO,因為底層文字始終是普通的 DOM 元素。它僅有兩個可調參數(bleed 和 duration),並透過 `@paper-design/shaders` 函式庫實現,壓縮後僅約 5 KiB,支援 WebGL2 瀏覽器,並內建了無 WebGL 支援與使用者偏好減少動畫的降級方案。此技能非常適合用於需要強調書法印刷感的品牌標題、活動口號或章節開場,但不應用於內文或小字。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nococn/omd-cjk-type-shader/tree/main

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

omd-cjk-type-shader — 먹 번짐:CJK 顯示字型作為墨跡於韓紙上 是做什麼的?

墨水滲入紙張是韓文、日文與中文書寫共通的意象。此技能讓大型 CJK 標題看起來像是用墨汁印刷或書寫於韓紙上。快速瀏覽時,它看起來應該像是一張書法海報,而不是一個濾鏡。

運作方式。標題是普通的 DOM 文字,使用墨水顏色,從第一幀起即可閱讀和選取。此技能追蹤瀏覽器佈局後的每個字素,並從該遮罩建立三個場域:筆畫外部的距離、筆畫內部的距離,以及局部墨汁覆蓋率。一個繪製在文字上方的 WebGL2 圖層,僅添加真實墨水的特性:

  • 濕 → 乾: 筆觸起始呈現帶有柔和暈開的濕潤暗色,暈開區域隨墨水乾燥而縮小;
  • 匯聚: 墨汁沿筆畫邊緣、筆畫末端以及凸起的轉角(局部覆蓋率低處)匯集變深;
  • 枯筆 (kasure): 乾燥後,粗筆畫中間顯露紙張纖維;
  • 滲化 (nijimi): 毛細擴散沿著部分邊緣的少數紙張纖維進行,由低頻噪聲選擇,絕非每個字形周圍的均勻環狀;
  • 紙張: 頁面上程序化生成的韓紙紋理(SVG 湍流,無圖像)。

在深色背景上,相同的特效會切換為 금니(金泥) on 감지(紺紙)。 高麗經卷抄寫師使用混合膠水的金粉顏料書寫於靛藍染色的紙上。顏料不像墨汁那樣滲入,因此此變體從不擴散,也無暈開。濕潤的膠水呈現暗淡且稍深;乾燥時,顆粒沉澱並捕捉光線(稀疏閃爍),一條緩慢的光澤掠過字行,筆刷停頓的末端和轉角處顏色顯得更濃郁,纖細的筆觸則讓靛藍色透出。當標題顏色比最近的繪製背景淺時,它會自動啟用(data-ink-ground="dark" 或 "light" 可強制指定)。它繪製的每一種顏色都是標題自身的顏色,更深或更亮,或是背景的顏色。

效果在標題進入視口時播放一次,然後渲染循環停止。換行、keep-all、字型切換和大小調整會重新追蹤。

運作範例:examples/demo.html(單一檔案,包含韓文、日文、繁體中文,分別在韓紙和 감지 章節上)。驗證:scripts/verify.mjs。

1. 何時使用 / 何時不使用

適用於:

  • 一個韓文、日文或中文的顯示標題(≥ 40px;主視覺、啟動標題、活動口號、章節開場)需要呈現墨跡、書法感、「印在韓紙 / 和紙 / 宣紙上」;
  • 品牌的墨水和紙張顏色已知(DESIGN.md 的前景色/畫布色,或標題的計算 color 與最近的繪製背景)。深色背景會觸發 금니 變體:使用溫暖淺色文字顏色,且需有足夠空間變暗(範例中的 #d4b062 在 #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 在 #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。
  • 絕不使用 canvas/Text 著色器元件繪製 CJK 標題。Canvas 文字會失去選取、無障礙性、索引和正確的 CJK 字型塑造(tf-shaders「不要」列表)。

4. CJK 排版(在著色器之前套用)

來自 /hangul(HG 規則)適用於韓文;日/中文範圍分別設定,以免韓文規則外洩:

.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>紙に染みこむ。)。在無頭 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。 決策記錄(2026-10-13 根據 npm tarballs 的 LICENSE 檔案、npm 元數據和 GitHub 授權 API 驗證):

@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 最小化 / 5.3 KiB gzip(esbuild,僅 ShaderMount);CDN 每檔案 +esm 16.4 KiB / 5.0 KiB gzip2,535 KiB 最小化 / 710 KiB gzip(esbuild,來自 shaders/react 的 Shader+MeshGradient)
遙測無(其唯一的 fetch() 讀取本地 blob 的內容類型)預設開啟:抽樣 5% 的工作階段至 shaders.com/api/telemetry;可傳遞 disableTelemetry 參數
自訂 GLSL + 紋理可以(ShaderMount(el, frag, uniforms),圖像 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 以上的字型中以一半解析度運行。
  • 紙張紋理: 一個內聯的 SVG feTurbulence data URI 放在 html 上(約 600 位元組),無圖像請求。
  • 字型才是真正的成本。 CJK 字型檔案很大。僅載入顯示用字重,並使用 unicode-range 切片。

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 或通過 lint 對於著色器來說無法證明任何事(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

它會啟動無頭 Chromium,並帶有 --enable-gpu --ignore-gpu-blocklist --use-angle=metal(macOS)參數,然後執行三次測試:GPU、減少動畫、無 WebGL。它會測量每個背景(data-ink-ground="light" 和 "dark")上的第一個標題。然後它會:

  • 記錄 WebGL 渲染器字串,讓你知道是真實 GPU 還是 SwiftShader 繪製了這些幀;
  • 確定性地步進著色器時鐘並儲存幀(提供給 ffmpeg 以製作示範 GIF/MP4);
  • 透過像素驗證渲染:在標題框內,著色器開啟 vs 關閉,以及第一幀 vs 乾燥後的幀;
  • 在整個效果過程中測量易讀性:每個取樣幀中,相對於背景紙張繪製的字形核心(文字開啟 vs 文字透明),取第 10 百分位數以排除反鋸齒邊緣的影響,並記錄最差的幀。顯示標題屬於 WCAG 大型文字,因此標準為 3:1;
  • 檢查選取的文字是否等於標題文字、圖層是否為 aria-hidden + pointer-events: none、減少動畫是否靜止、以及無 WebGL 是否未留下 canvas。

於 2026-11-06 測量(無頭 Chromium,ANGLE Metal Renderer: Apple M5 Pro,非 SwiftShader),所有檢查皆通過:

背景標題框像素被著色器改變濕 vs 乾字形易讀性 (p10, 最差幀)
淺色(韓紙上的墨,#3a3530 在 #f3eee4 上)10.2%5.9%8.01:1
深色(감지 上的 금니,#d4b062 在 #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(); }, [])。在伺服器端將標題渲染為純文字,這樣著色器只會在 Hydration 後裝飾它。不要在這裡使用 @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)。
  • 不要讓每個邊緣都擴散,或繪製均勻的光暈。每個字形周圍的均勻環狀看起來像貼紙,而非墨水;擴散屬於少數邊緣。
  • 不要使用純黑色的文字墨水。匯聚效果需要更暗的值來顯示,而墨汁是灰黑色的……

相關技能