Communitygithub.com

CharbelElBateh/personal-website

Sonner React 提示库的完整指南——安装、配置、选择合适的 toast() 调用、处理 Promise 与加载状态、更新、关闭与持久化、样式与主题、图标、定位以及多个 Toaster。适用于使用或排查 Sonner 时遇到的问题,如 Toast 不显示、重复出现、样式丢失、忽略 Tailwind 类、被模态框遮挡或不跟随深色模式。

personal-website 是什么?

该技能是 Sonner 的完整指南,Sonner 是一个轻量级、可定制的 React Toast 通知库。它详细解释了如何正确设置 Sonner,包括在根布局中挂载一个 `<Toaster />` 组件,以及在客户端代码中使用 `toast()` 函数。技能涵盖了所有核心功能:从基本的 `toast('Title')` 到 `toast.success()`、`toast.error()` 等便捷方法,再到更高级的 `toast.promise()`(用于将加载状态与 Promise 绑定)、`toast.loading()`(用于手动管理状态)以及 `toast.custom()`(用于完全自定义 JSX)。此外,还提供了完整的调试指南,列出了 Toast 不显示、重复出现、Tailwind 样式失效、被模态框遮挡、深色模式不生效等常见问题的原因和解决方案。技能还包含一个“样式升级阶梯”,从使用默认样式和 richColors 开始,逐步过渡到通过 classNames 注入 !important 规则,最终推荐使用 headless 方式通过 `toast.custom()` 完全控制 UI。所有内容都基于 Sonner 的作者 Emil Kowalski 的官方文档,适用于任何使用 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(Toast 库)的指南技能。当任务涉及 Sonner——连接它、渲染 Toast、设置样式或修复问题——时,优先根据此文件回答。<Toaster /> 和 toast() 的完整属性表格位于 API.md 中;当您需要确切的属性名、类型或默认值时,请阅读该文件。

设置

只需两部分,且仅此两部分:

  1. 一个 <Toaster />,只挂载一次,尽可能靠近根节点(在 Next.js 中:layout.tsx——它能在服务端组件内工作)。切勿按页面或有条件地渲染它;挂载第二个 Toaster 会导致每条 Toast 重复显示。
  2. 从客户端代码调用 toast()——事件处理程序、副作用、回调函数。它是一个普通函数,不需要 Hook 或 Provider,但在服务端上不起作用:在服务端操作中,返回结果并在接收它的客户端代码中调用 toast()。
import { Toaster } from 'sonner'; // 一次,在布局中
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(),否则会关闭 Toast;cancel 是次要变体
自定义 JSX,使用默认 Toast 外壳toast(<jsx />)
自定义 JSX,无任何样式toast.custom((t) => <jsx />)——无头模式,t 提供用于关闭的 id

使用技巧

更新 Toast——使用相同的 id 再次调用 toast();仅传入的 props 会发生变化。切换到 toast.success(…, { id }) 会更改类型。这是在不使用 toast.promise 的情况下实现加载 → 成功流程的方法:

const id = toast.loading('上传中…');
toast.success('已上传', { id });

持久化——{ duration: Infinity }。关闭——toast.dismiss(id),或 toast.dismiss() 关闭所有。读取活跃的 Toast——在 React 中使用 useSonner(),在外部使用 toast.getActiveToasts()。

在文本中嵌入链接或组件——为标题或描述传递一个函数:toast(() => <a href="…">查看</a>)。

多个 Toaster——为每个 Toaster 指定 id,并通过 toast('…', { toasterId: 'canvas' }) 定位。如果没有 toasterId,每个 Toaster 都会渲染该 Toast。

关闭回调——onDismiss 在点击关闭按钮或滑动时触发;onAutoClose 在超时时触发。它们是分开的;不存在单一的“已关闭”回调。

样式——升级阶梯

仅按所需的程度升级;过早跳到最高等级是可以的(这是推荐的最终状态),但停留在中间等级则不可取。

  1. 默认样式——加上 Toaster 的 richColors 可实现多彩的成功/错误提示,invert 可根据主题翻转颜色。
  2. 内联调整——在 Toaster 上使用 toastOptions={{ style: {…} }} 可应用于所有 Toast,或在每个 toast() 调用中使用 style。
  3. 各部分类名——toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}。Sonner 注入的样式在级联中优先级更高,因此每个类都需要 !important(Tailwind:!text-red-900)。如果您对多个属性使用了 important,请停止——改用无头模式。
  4. 无头模式——使用 toast.custom() 搭配您自己的 JSX,保留 Sonner 的定位、堆叠和滑动功能。这是设计系统 Toast 的推荐方法:将其封装在您自己的 toast() 抽象中。(unstyled: true 可作为中间方案,但无头模式以同样的工作量提供了更多控制权。)

图标——通过 Toaster 的 icons 属性按类型替换默认图标,通过 icon 按 Toast 替换,设置为 null 可移除。

主题——theme 默认为 'light',不会跟随操作系统。传递 theme="system",或连接您的主题提供者:通过 next-themes 使用 <Toaster theme={resolvedTheme} />。

故障排除

症状原因 → 修复
Toast 从不出现未挂载 <Toaster />,或它被卸载了(条件渲染、按页面放置)。在根节点挂载一个。如果从服务端操作中调用:toast() 是客户端专用的——在客户端使用操作结果调用它。
同一条 Toast 出现两次挂载了两个 Toaster(布局 和 页面)——保留一个。或者 toast() 在 React StrictMode 的开发模式双重调用中于副作用内触发——改为从事件处理程序触发,或传递一个固定的 id,以便第二次调用更新而非重复。
Tailwind/CSS 类无效默认样式覆盖了它们。将它们标记为 !important,或使用 unstyled / 无头模式(参见上面的阶梯)。
Toast 完全无样式(常见于 Astro、视图过渡)Sonner 注入的样式表丢失了——在布局中显式导入:import 'sonner/dist/styles.css'。
在 Shadow DOM 内无样式样式最终位于 document.head 中,而非 Shadow 根节点。将文本包含 [data-sonner-toaster] 的 style 标签复制到 Shadow 根节点中。
Toast 被模态框/覆盖层遮挡,或被裁剪某个祖先元素创建了层叠上下文(transform、filter、overflow),或者覆盖层的 z-index 高于 Toaster。将 <Toaster /> 移动到文档根节点,任何对话框/门户容器之外。
深色模式被忽略theme 默认为 'light'——设置为 theme="system" 或传递已解析的主题(参见上面的主题部分)。
成功/错误显示为灰色,而非绿色/红色这是默认状态。向 Toaster 添加 richColors。
Toast 从不关闭duration: Infinity、dismissible: false,或 toast.promise 的 Promise 从未结算——加载 Toast 会一直等待。
toast.promise 卡在加载状态它需要一个 Promise(或返回 Promise 的函数)作为第一个参数,并且该 Promise 必须实际 resolve/reject。
滑动关闭方向错误/不起作用方向由 position 决定。通过 Toaster 的 swipeDirections 覆盖。
Toast 在每个 Toaster 中都出现多个 Toaster 需要定位:为每个 Toaster 指定 id,并在 toast() 调用中传递 toasterId。
在移动设备上 Toast 离屏幕边缘太近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.

相关技能