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. 效果及其兩個參數
| 參數 | 範圍 | 預設值 | 作用 |
|---|---|---|---|
bleed | 0–1 | 0.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.81 | shaders 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) |
| 此效果的 JS | 17.5 KiB 最小化 / 5.3 KiB gzip(esbuild,僅 ShaderMount);CDN 每檔案 +esm 16.4 KiB / 5.0 KiB gzip | 2,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
feTurbulencedata URI 放在html上(約 600 位元組),無圖像請求。 - 字型才是真正的成本。 CJK 字型檔案很大。僅載入顯示用字重,並使用 unicode-range 切片。
6. 降級方案與減少動畫
- 無 WebGL2(掛載前檢查
canvas.getContext('webgl2');如果無法取得上下文或連結程式,ShaderMount會拋出錯誤):不插入圖層,標題獲得.ink-static類別(一個微弱的 CSStext-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)。 - 不要讓每個邊緣都擴散,或繪製均勻的光暈。每個字形周圍的均勻環狀看起來像貼紙,而非墨水;擴散屬於少數邊緣。
- 不要使用純黑色的文字墨水。匯聚效果需要更暗的值來顯示,而墨汁是灰黑色的……