Communitygithub.com

CharbelElBateh/personal-website

Guide pour Sonner, la bibliothèque React de toasts — installation et configuration du Toaster, choix du bon appel toast(), toasts de promesse et de chargement, mise à jour, fermeture et persistance des toasts, style, thème et icônes, positionnement et toasters multiples. À utiliser lorsque vous travaillez avec Sonner ou pour résoudre des problèmes : toasts qui n'apparaissent pas, apparaissent deux fois, perdent leur style, ignorent les classes Tailwind, se cachent derrière une modale ou ne suivent pas le mode sombre.

Qu'est-ce que personal-website ?

Ce skill est un guide complet et structuré pour Sonner, une bibliothèque de toasts légère pour React. Il couvre l'installation et la configuration, la sélection du bon appel toast() en fonction du cas d'usage (message simple, succès, erreur, chargement, promesse), la mise à jour et la persistance des toasts, ainsi qu'un système de résolution de problèmes pour les bugs courants. Il propose une « échelle d'escalade » pour le style, allant des valeurs par défaut aux modifications en ligne, en passant par les classes CSS avec !important, jusqu'à une approche headless avec toast.custom() pour un contrôle total. Le skill est destiné aux développeurs React, Next.js, Astro et autres framework similaires, et s'appuie sur des fichiers annexes (API.md) pour les tables de props complètes. Son objectif est de permettre une intégration rapide et fiable de Sonner, tout en offrant des solutions claires aux problèmes fréquents comme les toasts dupliqués, le non-respect du mode sombre ou les problèmes de superposition.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Travailler avec Sonner

Réponse initiale

Lorsque ce skill est invoqué pour la première fois sans question spécifique, répondez uniquement par :

Je suis prêt à vous aider à configurer, styliser et résoudre les problèmes avec Sonner, mes connaissances proviennent de son auteur, Emil Kowalski.

Ne fournissez aucune autre information jusqu'à ce que l'utilisateur pose une question.

Un skill guide pour Sonner, la bibliothèque de toasts. Lorsqu'une tâche implique Sonner — le connecter, afficher des toasts, les styliser ou les réparer — répondez d'abord à partir de ce fichier. Les tables de props complètes pour <Toaster /> et toast() se trouvent dans API.md ; lisez-les lorsque vous avez besoin d'un nom de prop, d'un type ou d'une valeur par défaut exacts.

Configuration

Deux éléments, et seulement deux :

  1. Un seul <Toaster />, monté une fois, aussi proche de la racine que possible (dans Next.js : layout.tsx — il fonctionne à l'intérieur des composants serveur). Ne le rendez jamais par page ou conditionnellement ; un deuxième Toaster monté duplique chaque toast.
  2. toast() appelé depuis du code client — gestionnaires d'événements, effets, callbacks. C'est une simple fonction, pas besoin de hook ou de fournisseur, mais elle ne fait rien côté serveur : dans une action serveur, retournez le résultat et appelez toast() dans le code client qui le reçoit.
import { Toaster } from 'sonner'; // une fois, dans le layout
import { toast } from 'sonner';   // n'importe où côté client

Choisir le bon appel

Vous voulezAppel
Un message simpletoast('Titre') — ajoutez { description } pour une deuxième ligne
Icône de succès / erreur / info / avertissementtoast.success('…'), toast.error('…'), etc.
Spinner pendant que vous gérez vous-même l'étattoast.loading('…'), puis mettez-le à jour par id
Chargement → succès/erreur lié à une promessetoast.promise(promise, { loading, success, error }) — success/error acceptent des fonctions recevant la valeur résolue / l'erreur
Bouton qui fait quelque chose{ action: { label, onClick } } — ferme le toast sauf si onClick appelle event.preventDefault() ; cancel est la variante secondaire
JSX personnalisé, coque de toast par défauttoast(<jsx />)
JSX personnalisé, sans aucun styletoast.custom((t) => <jsx />) — headless, t vous donne l'id pour fermer

Recettes

Mettre à jour un toast — appelez toast() à nouveau avec le même id ; seules les props que vous passez changent. Passer à toast.success(…, { id }) change le type. C'est ainsi que fonctionnent les flux chargement → succès sans toast.promise :

const id = toast.loading('Téléchargement…');
toast.success('Téléchargé', { id });

Persister — { duration: Infinity }. Fermer — toast.dismiss(id), ou toast.dismiss() pour tout fermer. Lire les toasts actifs — useSonner() dans React, toast.getActiveToasts() en dehors.

Liens ou composants dans le texte — passez une fonction pour le titre ou la description : toast(() => <a href="…">Voir</a>).

Toasters multiples — donnez à chacun un id et ciblez avec toast('…', { toasterId: 'canvas' }). Sans toasterId, chaque toaster affiche le toast.

Callbacks de fermeture — onDismiss se déclenche sur le bouton de fermeture ou le balayage ; onAutoClose se déclenche lors du délai d'attente. Ils sont séparés ; il n'y a pas de callback unique « fermé ».

Style — l'échelle d'escalade

Ne montez que jusqu'au niveau requis par le changement ; sauter trop tôt à l'échelon supérieur est acceptable (c'est l'état final recommandé), mais rester au milieu ne l'est pas.

  1. Valeurs par défaut — plus richColors sur le Toaster pour des succès/erreurs colorés, invert pour inverser par rapport au thème.
  2. Ajustements en ligne — toastOptions={{ style: {…} }} sur le Toaster pour tous les toasts, ou style par appel toast().
  3. Classes sur les parties — toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}. Les styles injectés de Sonner gagnent la cascade, donc chaque classe a besoin de !important (Tailwind : !text-red-900). Si vous marquez plus de quelques éléments comme importants, arrêtez — passez au headless.
  4. Headless — toast.custom() avec votre propre JSX, en conservant le positionnement, l'empilement et le balayage de Sonner. L'approche recommandée pour un toast de système de design : enveloppez-le dans votre propre abstraction toast(). (unstyled: true existe comme solution intermédiaire, mais le headless offre plus de contrôle pour le même effort.)

Icônes — remplacez les valeurs par défaut par type avec la prop icons du Toaster, par toast avec icon, supprimez avec null.

Thème — theme par défaut à 'light' et ne suit pas le système d'exploitation. Passez theme="system", ou connectez votre fournisseur de thème : <Toaster theme={resolvedTheme} /> depuis next-themes.

Résolution des problèmes

SymptômeCause → correctif
Le toast n'apparaît jamaisAucun <Toaster /> monté, ou il a été démonté (render conditionnel, placement par page). Montez-en un à la racine. Si appel depuis une action serveur : toast() est réservé au client — appelez-le avec le résultat de l'action côté client.
Le même toast apparaît deux foisDeux Toasters montés (layout et page) — gardez-en un. Ou toast() déclenché dans un effet sous la double invocation de développement de React StrictMode — déclenchez-le depuis le gestionnaire d'événements à la place, ou passez un id stable pour que le deuxième appel mette à jour plutôt que duplique.
Les classes Tailwind/CSS n'ont aucun effetLes styles par défaut les écrasent. Marquez-les !important, ou utilisez unstyled / headless (voir l'échelle ci-dessus).
Les toasts sont rendus complètement sans style (courant dans Astro, transitions de vue)La feuille de style injectée de Sonner a été perdue — importez-la explicitement dans un layout : import 'sonner/dist/styles.css'.
Sans style à l'intérieur du Shadow DOMLes styles atterrissent dans document.head, pas dans la racine shadow. Copiez la balise style dont le texte inclut [data-sonner-toaster] dans la racine shadow.
Toast derrière une modale/overlay, ou rognéUn ancêtre crée un contexte d'empilement (transform, filter, overflow) ou l'overlay a un z-index supérieur au toaster. Déplacez <Toaster /> à la racine du document, en dehors de tout conteneur de dialogue/portail.
Mode sombre ignorétheme par défaut à 'light' — définissez theme="system" ou passez le thème résolu (voir Thème ci-dessus).
Succès/erreur semblent gris, pas vert/rougeC'est le comportement par défaut. Ajoutez richColors au Toaster.
Le toast ne se ferme jamaisduration: Infinity, dismissible: false, ou une toast.promise dont la promesse ne se résout jamais — le toast de chargement attend indéfiniment.
toast.promise bloqué sur le chargementIl nécessite une promesse (ou une fonction qui en retourne une) comme premier argument, et la promesse doit réellement se résoudre/rejeter.
Le balayage pour fermer va dans la mauvaise direction / ne fonctionne pasLes directions dérivent de position. Remplacez avec swipeDirections sur le Toaster.
Le toast apparaît dans chaque toasterLes toasters multiples nécessitent un ciblage : donnez un id à chaque Toaster et passez toasterId dans l'appel toast().
Toasts trop proches du bord de l'écran sur mobileoffset (desktop, par défaut 32px) et mobileOffset (<600px, par défaut 16px) — nombres, chaînes CSS, ou objets par côté.

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.

Skills associés