卡片與網格
金屬箔面
可包任何內容的燙金箔表面處理：五層漸層與混合模式隨捲動進度與游標位置變化光澤，不做傾斜。
把任何容器變成燙金箔、鐳射貼紙那種會流動的表面：徽章、會員卡、票券、標題字塊都適用。元件在內容之上疊五層漸層（彩色箔面、薄膜色塊、珍珠底、斜向亮帶、游標高光），以混合模式和內容混色；光澤由捲動進度與游標位置驅動，CSS 變數直接在 requestAnimationFrame 裡批次寫入，不經 React state、也沒有 transition。它只處理表面、不做傾斜——需要 3D 傾斜時，把它放進 tilt-card 裡組合；要一張現成的「卡片＋傾斜＋全息」則用 holographic-card。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add "https://webberui.com/r/foil-surface.json?t=<安裝 token>"Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
0.8
1
編輯中的呼叫預設屬性
<FoilSurface/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add "https://webberui.com/r/foil-surface.json?t=<安裝 token>"或在 components.json 設定 registries 後，改用 @webberui/foil-surface 安裝。
使用
import { FoilSurface } from "@/components/ui/foil-surface";
<FoilSurface className="rounded-full" intensity={0.8}>
<div className="flex size-40 items-center justify-center rounded-full bg-neutral-100">
限量會員 2026
</div>
</FoilSurface>
// 隨整頁捲動進度變化、不跟游標
<FoilSurface scrollProgressMode="document" interactive={false} className="rounded-xl">
<MemberCard />
</FoilSurface>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
children | React.ReactNode | — | 要包上箔面的任意內容；五層箔面疊在內容之上 |
scrollProgressMode | "element" | "document" | "element" | element：元素穿過視口的進度；document：整頁捲動進度 |
intensity | number | 0.8 | 光澤強度（0–1），乘在每一層的不透明度上 |
shineSpeed | number | 1 | 捲動時光澤流動的快慢倍率，乘在捲動係數（0.82 與 80°）上 |
interactive | boolean | true | 是否讓高光跟隨游標；false 時只隨捲動變化 |
as | "div" | "span" | "div" | 根元素標籤；包行內內容時用 span（會設為 inline-block） |
layerClassName | string | — | 套用到每一個箔面層的 class |
className | string | — | 透傳到根元素；圓角請設在這裡，五層會以 rounded-[inherit] 繼承 |
細節
- 更新迴圈：監聽 window 的 scroll（捕獲階段，連巢狀捲動容器一併接住）、resize 與元素的 pointermove／pointerleave，全部 passive。事件只記錄最新值並排一個 rAF，同一幀多個事件合併成一次寫入
- 捲動進度：
element模式為(視口高 − rect.top) ÷ (視口高 + rect.height)，夾在 0–1；document模式為scrollTop ÷ (scrollHeight − clientHeight)。element模式一律以瀏覽器視口為準，放在短的巢狀捲動容器裡時變化幅度較小，可調高shineSpeed補償 - 游標：相對元素的 0–1 座標，夾在 0.08–0.92；離開時回到正中央
- 寫入的 CSS 變數：
--foil-shift、--foil-y-shift、--glare-x、--glare-y、--shine-angle、--shine-opacity，直接寫在根元素的 style 上，可在子層或自訂layerClassName中引用 - 五層：foil（七色線性漸層、300% 尺寸隨變數平移、saturate／contrast 提高）、film（四個彩色色塊，
screen）、pearl（珍珠白，soft-light）、shine（斜向亮帶，角度隨捲動轉動，screen）、glare（游標圓形高光）。根元素isolate，混合模式只和本元件內容混色 - 離開視口時暫停：IntersectionObserver 回報不在視口時停止 rAF 寫入，回到視口時補寫一次
- 與 holographic-card 的分工：holographic-card 是一張卡片＋3D 傾斜；foil-surface 是任何容器的表面處理，捲動驅動、不傾斜。可以把 foil-surface 放進 tilt-card 內組合出傾斜效果
可及性
- 五層箔面都是
aria-hidden且pointer-events-none，不影響內容的閱讀順序、點擊與焦點 - 箔面只是視覺光澤，不承載任何資訊；強度上限受
intensity控制，內容文字仍需自行確保對比度 - 使用者系統開啟「減少動態效果」時，不監聽任何捲動或游標事件，光澤固定在中間狀態（捲動 0.5、游標置中）的靜態外觀