Communitygithub.com

CharbelElBateh/personal-website

Sonner React 吐司函式庫的操作指南 — 安裝與設定 Toaster、選擇正確的 toast() 呼叫、Promise 與載入中吐司、更新、關閉與持續顯示吐司、樣式、主題與圖示、定位與多個 Toaster。適用於使用 Sonner 或排解問題時 — 吐司不顯示、顯示兩次、遺失樣式、忽略 Tailwind 類別、位於模態框後方或不跟隨暗色模式。

personal-website 是什麼?

這個技能(SKILL.md)是一份專門針對 Sonner React 吐司函式庫的完整指南。它涵蓋了從基本設定開始的所有步驟:如何正確安裝 `<Toaster />` 元件(僅需一個,並盡可能靠近根目錄),以及如何在客戶端程式碼中使用 `toast()` 函式。技能詳細解釋了各種 toast 呼叫方式(如成功、錯誤、載入中、Promise、自訂 JSX),並提供了實用範例,包括更新、持續顯示、關閉吐司,以及處理多個 Toaster 的場景。此外,它還提供了一個「逐步升級」的樣式處理階梯,從預設樣式、行內調整、類別(需加上 `!important`),到完全無頭部的 `toast.custom()` 自訂樣式。最後,技能包含一個詳盡的故障排除表格,針對常見問題(如吐司未出現、出現兩次、樣式失效、被模態框遮擋等)提供具體的成因與解決方案。這個技能支援所有使用 Sonner 的 React 專案,特別是在 Next.js 架構中。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/ask-sonner

在你喜歡的 AI 中提問

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

說明文件

使用 Sonner 工作

初始回應

當此技能首次被呼叫且沒有具體問題時,請僅回覆:

我已準備好協助您設定、樣式化和排解 Sonner 的問題,我的知識來自其作者 Emil Kowalski。

在用戶提出問題之前,請勿提供任何其他資訊。

這是 Sonner 吐司函式庫的技能指南。當任務涉及 Sonner — 連線設定、渲染吐司、樣式化或修復它們時,請優先從此檔案回答。<Toaster /> 和 toast() 的完整 props 表格位於 API.md;在您需要確切的 prop 名稱、類型或預設值時,請閱讀該檔案。

設定

兩個部分,而且只有兩個:

  1. 一個 <Toaster />,只掛載一次,盡可能靠近根目錄(在 Next.js 中:layout.tsx — 它可以在伺服器元件內運作)。切勿按頁面或有條件地渲染它;第二個掛載的 Toaster 會使每個吐司都重複顯示。
  2. 從客戶端程式碼呼叫 toast() — 事件處理器、副作用、回呼。它是一個純函式,不需要 hook 或 provider,但在伺服器端無效:在伺服器動作中,請回傳結果並在接收該結果的客戶端程式碼中呼叫 toast()。
import { Toaster } from 'sonner'; // 一次,在 layout 中
import { toast } from 'sonner';   // 任何客戶端位置

選擇正確的呼叫

你想要呼叫方式
純文字訊息toast('Title') — 加上 { description } 可顯示第二行
成功 / 錯誤 / 資訊 / 警告圖示toast.success('…'), toast.error('…') 等
自行管理狀態時的旋轉圖示toast.loading('…'),然後透過 id 更新它
與 Promise 綁定的載入中 → 成功/錯誤toast.promise(promise, { loading, success, error }) — success/error 可接受接收解析值/錯誤的函式
執行某動作的按鈕{ action: { label, onClick } } — 除非 onClick 呼叫 event.preventDefault(),否則關閉吐司;cancel 是次要變體
自訂 JSX,使用預設吐司外殼toast(<jsx />)
自訂 JSX,無任何樣式toast.custom((t) => <jsx />) — 無頭部,t 提供用於關閉的 id

實用範例

更新吐司 — 使用相同的 id 再次呼叫 toast();只有你傳入的 props 會改變。切換到 toast.success(…, { id }) 則會改變類型。這就是無需 toast.promise 即可實現載入中 → 成功流程的方式:

const id = toast.loading('Uploading…');
toast.success('Uploaded', { id });

持續顯示 — { duration: Infinity }。關閉 — toast.dismiss(id),或 toast.dismiss() 關閉全部。讀取啟用中的吐司 — 在 React 中使用 useSonner(),在 React 外部使用 toast.getActiveToasts()。

在文字中加入連結或元件 — 為標題或描述傳入一個函式:toast(() => <a href="…">View</a>)。

多個 Toaster — 為每個 Toaster 指定一個 id,並使用 toast('…', { toasterId: 'canvas' }) 來定位。若未指定 toasterId,每個 Toaster 都會渲染該吐司。

關閉回呼 — onDismiss 在點擊關閉按鈕或滑動時觸發;onAutoClose 在超時時觸發。它們是分開的;沒有單一的「已關閉」回呼。

樣式處理 — 逐步升級階梯

僅根據需求提升到所需的層級;過早跳到最高層級是可以的(這是推薦的最終狀態),但停留在中間層級則不建議。

  1. 預設值 — 加上 Toaster 的 richColors 可顯示彩色的成功/錯誤,invert 則可根據主題翻轉顏色。
  2. 行內調整 — 在 Toaster 上使用 toastOptions={{ style: {…} }} 影響所有吐司,或在每個 toast() 呼叫中使用 style。
  3. 部件的類別 — 使用 toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}。Sonner 注入的樣式在級聯中優先權更高,因此每個類別都需要 !important(Tailwind:!text-red-900)。如果你需要對超過幾個項目加上 important,請停止 — 改用無頭部模式。
  4. 無頭部模式 — 使用 toast.custom() 搭配你自己的 JSX,保留 Sonner 的定位、堆疊和滑動功能。這是設計系統中吐司的推薦方法:將其包裝在你自己的 toast() 抽象層中。(unstyled: true 存在作為折衷方案,但無頭部模式以相同的工作量提供了更多控制權。)

圖示 — 使用 Toaster 的 icons props 替換每種類型的預設圖示,使用 icon 替換每個吐司的圖示,使用 null 移除圖示。

主題 — theme 預設為 'light' 且不會追蹤作業系統設定。請傳入 theme="system",或連線你的主題提供者:從 next-themes 使用 <Toaster theme={resolvedTheme} />。

故障排除

症狀原因 → 修正方式
吐司從未出現沒有掛載 <Toaster />,或它被卸載了(條件式渲染、按頁面放置)。在根目錄掛載一個。如果是從伺服器動作中呼叫:toast() 僅限客戶端 — 請在客戶端使用動作的結果來呼叫它。
同一個吐司出現兩次掛載了兩個 Toaster(layout 和 page) — 保留一個。或者 toast() 在 React StrictMode 的開發模式雙重呼叫下的副作用中被觸發 — 改從事件處理器觸發,或傳入一個穩定的 id,這樣第二次呼叫會更新而非重複。
Tailwind/CSS 類別無效預設樣式覆蓋了它們。請加上 !important,或使用 unstyled / 無頭部模式(參見上方階梯)。
吐司渲染完全無樣式(常見於 Astro、視圖轉場)Sonner 注入的樣式表遺失了 — 請在 layout 中明確匯入:import 'sonner/dist/styles.css'。
在 Shadow DOM 內無樣式樣式被放置在 document.head,而非 shadow root 內。請將 text 包含 [data-sonner-toaster] 的 style 標籤複製到 shadow root 中。
吐司位於模態框/覆蓋層後方,或被裁切上層元素建立了堆疊上下文(transform, filter, overflow)或覆蓋層的 z-index 高於 toaster。將 <Toaster /> 移到文件根目錄,放置在任何對話框/portal 容器之外。
暗色模式被忽略theme 預設為 'light' — 請設定 theme="system" 或傳入已解析的主題(參見上方主題說明)。
成功/錯誤看起來是灰色,而非綠色/紅色這是預設值。請在 Toaster 加上 richColors。
吐司從不關閉duration: Infinity、dismissible: false,或 toast.promise 的 promise 從未完成 — 載入中的吐司會永遠等待。
toast.promise 卡在載入中它需要一個 promise(或一個回傳 promise 的函式)作為第一個參數,且該 promise 必須實際 resolve/reject。
滑動關閉方向錯誤 / 無法運作方向根據 position 推導。使用 Toaster 的 swipeDirections 覆蓋。
吐司出現在每個 toaster 中多個 Toaster 需要定位:為每個 Toaster 指定一個 id,並在 toast() 呼叫中傳入 toasterId。
在手機上吐司太靠近螢幕邊緣offset(桌面,預設 32px)和 mobileOffset(<600px,預設 16px)— 數值、CSS 字串或按邊的物件。

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or reviewed on mobile, when something "works in Chrome but feels wrong on my phone", when building a PWA, a bottom sheet, a carousel, a full-screen layout, or any touch interaction. For motion itself use animate; for React Native use animate-expo.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

相關技能