Communitygithub.com

CharbelElBateh/personal-website

Guia para Sonner, a biblioteca React de toasts — instalar e configurar o Toaster, escolher a chamada toast() correta, toasts de promise e loading, atualizar, descartar e persistir toasts, estilização, temas e ícones, posicionamento e múltiplos toasters. Use ao trabalhar com Sonner ou solucionar problemas — toasts que não aparecem, aparecem duas vezes, perdem estilos, ignoram classes Tailwind, ficam atrás de um modal ou não seguem o modo escuro.

O que é personal-website?

Este skill fornece um guia completo e prático para trabalhar com a biblioteca Sonner de toasts em React. Ele cobre desde a configuração inicial — montando um único `<Toaster />` na raiz da aplicação e usando `toast()` em código cliente — até a escolha correta do tipo de chamada, como `toast.success()`, `toast.promise()` ou `toast.custom()`. O skill detalha receitas comuns como atualizar um toast mantendo o mesmo ID, persistir toasts com duração infinita e usar múltiplos toasters com IDs distintos. Além disso, oferece uma "escada de escalada" para estilização, começando com padrões e `richColors`, passando por ajustes inline, classes com `!important`, até a abordagem headless com `toast.custom()`, recomendada para sistemas de design. Uma seção extensa de solução de problemas aborda sintomas frequentes como toasts que não aparecem (Toaster ausente ou condicional), toasts duplicados (dois Toasters montados), falha de classes Tailwind (necessidade de `!important`), problemas com Shadow DOM e modais, além de configurações de tema e posicionamento. O skill é ativado quando o assunto é configurar, estilizar ou depurar Sonner, e inicialmente responde apenas informando que está pronto para ajudar, aguardando uma pergunta específica do usuário.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Trabalhando com Sonner

Resposta Inicial

Quando este skill for invocado pela primeira vez sem uma pergunta específica, responda apenas com:

Estou pronto para ajudar você a configurar, estilizar e solucionar problemas do Sonner. Meu conhecimento vem de seu autor, Emil Kowalski.

Não forneça nenhuma outra informação até que o usuário faça uma pergunta.

Um guia sobre Sonner, a biblioteca de toasts. Quando uma tarefa envolver Sonner — configurá-lo, renderizar toasts, estilizá-los ou corrigi-los — responda a partir deste arquivo primeiro. As tabelas completas de propriedades para <Toaster /> e toast() estão em API.md; leia-as quando precisar de um nome de propriedade, tipo ou valor padrão exato.

Configuração

Duas peças, e apenas duas:

  1. Um <Toaster />, montado uma vez, o mais próximo possível da raiz (no Next.js: layout.tsx — funciona dentro de componentes servidor). Nunca o renderize por página ou condicionalmente; um segundo Toaster montado duplica todos os toasts.
  2. toast() chamado a partir de código cliente — manipuladores de eventos, efeitos, callbacks. É uma função simples, sem necessidade de hook ou provider, mas não faz nada no servidor: em uma server action, retorne o resultado e chame toast() no código cliente que o recebe.
import { Toaster } from 'sonner'; // uma vez, no layout
import { toast } from 'sonner';   // em qualquer lugar no lado cliente

Escolhendo a chamada correta

Você querChamada
Mensagem simplestoast('Título') — adicione { description } para uma segunda linha
Ícone de sucesso / erro / informação / avisotoast.success('…'), toast.error('…'), etc.
Spinner enquanto gerencia o estado manualmentetoast.loading('…'), depois atualize pelo id
Loading → sucesso/erro vinculado a uma promisetoast.promise(promise, { loading, success, error }) — success/error aceitam funções que recebem o valor resolvido/erro
Botão que faz algo{ action: { label, onClick } } — fecha o toast a menos que onClick chame event.preventDefault(); cancel é a variante secundária
JSX personalizado, com invólucro padrão do toasttoast(<jsx />)
JSX personalizado, sem estilostoast.custom((t) => <jsx />) — headless, t fornece o id para descartar

Receitas

Atualizar um toast — chame toast() novamente com o mesmo id; apenas as props passadas são alteradas. Mudar para toast.success(…, { id }) altera o tipo. É assim que fluxos loading → sucesso funcionam sem toast.promise:

const id = toast.loading('Enviando…');
toast.success('Enviado', { id });

Persistir — { duration: Infinity }. Descartar — toast.dismiss(id), ou toast.dismiss() para todos. Ler toasts ativos — useSonner() no React, toast.getActiveToasts() fora dele.

Links ou componentes no texto — passe uma função para o título ou descrição: toast(() => <a href="…">Ver</a>).

Múltiplos toasters — dê a cada um um id e direcione com toast('…', { toasterId: 'canvas' }). Sem toasterId, todos os toasters renderizam o toast.

Callbacks de fechamento — onDismiss é acionado pelo botão de fechar ou swipe; onAutoClose é acionado no timeout. Eles são separados; não existe um callback único "fechado".

Estilização — a escada de escalada

Suba apenas até onde a mudança exige; pular para o degrau mais alto cedo demais é aceitável (é o estado final recomendado), mas permanecer no meio não é.

  1. Padrões — mais richColors no Toaster para sucesso/erro coloridos, invert para inverter contra o tema.
  2. Ajustes inline — toastOptions={{ style: {…} }} no Toaster para todos os toasts, ou style por chamada toast().
  3. Classes em partes — toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}. Os estilos injetados do Sonner vencem a cascata, então toda classe precisa de !important (Tailwind: !text-red-900). Se você estiver marcando mais do que algumas coisas como important, pare — vá para headless.
  4. Headless — toast.custom() com seu próprio JSX, mantendo o posicionamento, empilhamento e swipe do Sonner. A abordagem recomendada para um toast de sistema de design: envolva-o em sua própria abstração toast(). (unstyled: true existe como meio-termo, mas headless oferece mais controle pelo mesmo esforço.)

Ícones — substitua os padrões por tipo com a prop icons do Toaster, por toast com icon, remova com null.

Tema — theme padrão é 'light' e não acompanha o SO. Passe theme="system", ou conecte seu provedor de tema: <Toaster theme={resolvedTheme} /> do next-themes.

Solução de Problemas

SintomaCausa → correção
O toast nunca apareceNenhum <Toaster /> montado, ou foi desmontado (renderização condicional, posicionamento por página). Monte um na raiz. Se estiver chamando de uma server action: toast() é apenas cliente — chame-o com o resultado da ação no cliente.
O mesmo toast aparece duas vezesDois Toasters montados (layout e página) — mantenha um. Ou toast() disparado em um efeito sob a dupla invocação de desenvolvimento do React StrictMode — dispare do manipulador de evento em vez disso, ou passe um id estável para que a segunda chamada atualize em vez de duplicar.
Classes Tailwind/CSS não têm efeitoOs estilos padrão as sobrescrevem. Marque-as com !important, ou use unstyled / headless (veja a escada acima).
Toasts renderizam completamente sem estilo (comum no Astro, transições de visualização)A folha de estilo injetada do Sonner foi perdida — importe-a explicitamente em um layout: import 'sonner/dist/styles.css'.
Sem estilo dentro de Shadow DOMOs estilos vão parar em document.head, não na raiz da sombra. Copie a tag style cujo texto inclui [data-sonner-toaster] para dentro da raiz da sombra.
Toast atrás de um modal/overlay, ou cortadoUm ancestral cria um contexto de empilhamento (transform, filter, overflow) ou o overlay tem z-index maior que o toaster. Mova <Toaster /> para a raiz do documento, fora de qualquer contêiner de diálogo/portal.
Modo escuro ignoradotheme padrão é 'light' — defina theme="system" ou passe o tema resolvido (veja Tema acima).
Sucesso/erro parecem cinza, não verde/vermelhoIsso é o padrão. Adicione richColors ao Toaster.
O toast nunca fechaduration: Infinity, dismissible: false, ou uma toast.promise cuja promise nunca é resolvida — o toast de loading espera para sempre.
toast.promise preso no loadingEle precisa de uma promise (ou uma função que retorne uma) como primeiro argumento, e a promise deve realmente resolver/rejeitar.
Swipe-para-descartar vai na direção errada / não funcionaAs direções derivam de position. Substitua com swipeDirections no Toaster.
O toast aparece em todos os toastersMúltiplos toasters precisam de direcionamento: dê a cada Toaster um id e passe toasterId na chamada toast().
Toasts muito próximos da borda da tela no celularoffset (desktop, padrão 32px) e mobileOffset (<600px, padrão 16px) — números, strings CSS ou objetos por lado.

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.

Habilidades Relacionadas