Communitygithub.com

CharbelElBateh/personal-website

Sonner(React 토스트 라이브러리) 설정, 스타일링, 문제 해결 가이드. Toaster 설치 및 연결, 올바른 toast() 호출 선택, 프로미스 및 로딩 토스트, 업데이트, 닫기, 유지, 스타일링, 테마, 아이콘, 위치 지정, 다중 Toaster 사용법을 다룹니다. Sonner 사용 시 토스트가 나타나지 않거나, 두 번 나타나거나, 스타일이 사라지거나, Tailwind 클래스가 무시되거나, 모달 뒤에 위치하거나, 다크 모드를 따르지 않는 문제를 해결할 때 사용합니다.

personal-website란 무엇인가요?

이 스킬은 React 애플리케이션에서 토스트 알림을 쉽게 구현할 수 있도록 도와주는 라이브러리인 Sonner에 대한 포괄적인 가이드입니다. Sonner의 창작자 Emil Kowalski의 지식을 바탕으로 하며, 설치부터 고급 사용자 정의 및 문제 해결까지 모든 단계를 다룹니다. 주요 기능으로는 다양한 토스트 유형(success, error, loading 등), 프로미스 기반 토스트, 토스트 업데이트 및 유지, 완전한 사용자 정의가 가능한 headless 모드, 다중 Toaster 지원 등이 있습니다. 이 스킬은 개발자에게 가장 적합한 toast() 호출 방법을 선택하는 방법, 스타일링 우선순위에 따른 문제 해결 접근법(기본값 → 인라인 조정 → 클래스 기반 → headless), 그리고 토스트가 나타나지 않거나, 중복 표시되거나, 스타일이 무시되는 등 일반적인 문제에 대한 구체적인 원인과 해결책을 제시합니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 활용할 수 있습니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Sonner 사용하기

초기 응답

이 스킬이 특정 질문 없이 처음 호출되면, 다음 내용으로만 응답하세요:

Sonner 설정, 스타일링 및 문제 해결을 도와드릴 준비가 되었습니다. 제 지식은 Sonner의 창작자 Emil Kowalski의 자료를 바탕으로 합니다.

사용자가 질문을 하기 전까지는 다른 정보를 제공하지 마세요.

Sonner(토스트 라이브러리)에 대한 가이드 스킬입니다. 작업에 Sonner가 관련된 경우(연결, 토스트 렌더링, 스타일링 또는 문제 해결) 이 파일의 내용을 먼저 참고하여 답변하세요. 전체 <Toaster /> 및 toast() prop 테이블은 API.md에 있습니다. 정확한 prop 이름, 타입 또는 기본값이 필요할 때 이 파일을 읽으세요.

설정

두 가지 요소만 있으면 됩니다:

  1. 하나의 <Toaster />를 한 번만 마운트하고, 가능한 루트에 가깝게 배치하세요(Next.js: layout.tsx — 서버 컴포넌트 내에서도 작동합니다). 페이지별로 또는 조건부로 렌더링하지 마세요. 두 번째 Toaster가 마운트되면 모든 토스트가 중복됩니다.
  2. 클라이언트 코드에서 toast() 호출 — 이벤트 핸들러, effects, 콜백에서 사용합니다. 일반 함수이며, 훅이나 프로바이더가 필요하지 않지만 서버에서는 아무 작업도 하지 않습니다. 서버 액션에서는 결과를 반환하고, 이를 받는 클라이언트 코드에서 toast()를 호출하세요.
import { Toaster } from 'sonner'; // layout에서 한 번
import { toast } from 'sonner';   // 클라이언트 측 어디서든

올바른 호출 선택하기

원하는 기능호출 방법
일반 메시지toast('Title') — 두 번째 줄을 위해 { description } 추가
성공 / 오류 / 정보 / 경고 아이콘toast.success('…'), toast.error('…') 등
상태를 직접 관리하면서 스피너 표시toast.loading('…'), 그런 다음 id로 업데이트
프로미스에 연결된 로딩 → 성공/오류toast.promise(promise, { loading, success, error }) — success/error는 확인된 값/오류를 받는 함수 허용
작업을 수행하는 버튼{ action: { label, onClick } } — onClick이 event.preventDefault()를 호출하지 않으면 토스트를 닫습니다. cancel은 보조 변형입니다.
기본 토스트 셸을 가진 사용자 JSXtoast(<jsx />)
스타일이 전혀 없는 사용자 JSXtoast.custom((t) => <jsx />) — headless, t는 닫을 id를 제공

레시피

토스트 업데이트 — 동일한 id로 toast()를 다시 호출하면 전달한 prop만 변경됩니다. toast.success(…, { id })로 전환하면 타입이 변경됩니다. toast.promise 없이 로딩 → 성공 흐름을 구현하는 방법입니다:

const id = toast.loading('업로드 중…');
toast.success('업로드 완료', { id });

유지 — { duration: Infinity }. 닫기 — toast.dismiss(id), 또는 전체 닫기는 toast.dismiss(). 활성 토스트 읽기 — React에서는 useSonner(), React 외부에서는 toast.getActiveToasts().

텍스트 내 링크 또는 컴포넌트 — title 또는 description에 함수 전달: toast(() => <a href="…">보기</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를 표시하고 있다면 중단하고 headless로 가세요.
  4. Headless — toast.custom()으로 자체 JSX를 사용하고, Sonner의 위치 지정, 쌓기, 스와이프 기능을 유지합니다. 디자인 시스템 토스트에 권장되는 방법: 자체 toast() 추상화로 래핑하세요. (unstyled: true가 중간 단계로 존재하지만, headless가 동일한 노력으로 더 많은 제어를 제공합니다.)

아이콘 — Toaster의 icons prop으로 유형별 기본 아이콘 교체, 각 토스트에는 icon 사용, null로 제거.

테마 — theme 기본값은 'light'이며 OS를 추적하지 않습니다. theme="system"을 전달하거나 테마 프로바이더 연결: next-themes를 사용하여 <Toaster theme={resolvedTheme} />.

문제 해결

증상원인 → 해결 방법
토스트가 나타나지 않음<Toaster />가 마운트되지 않았거나, 마운트가 해제됨(조건부 렌더링, 페이지별 배치). 루트에 하나를 마운트하세요. 서버 액션에서 호출하는 경우: toast()는 클라이언트 전용입니다 — 클라이언트에서 액션 결과와 함께 호출하세요.
동일한 토스트가 두 번 나타남두 개의 Toaster가 마운트됨(layout 및 page) — 하나만 유지하세요. 또는 React StrictMode의 개발 시 이중 호출로 인해 effect에서 toast()가 실행됨 — 이벤트 핸들러에서 호출하거나, 안정적인 id를 전달하여 두 번째 호출이 중복이 아닌 업데이트되도록 하세요.
Tailwind/CSS 클래스가 적용되지 않음기본 스타일이 이를 재정의합니다. !important를 표시하거나 unstyled/headless를 사용하세요(위 사다리 참조).
토스트가 완전히 스타일이 없는 상태로 렌더링됨(Astro, view transition에서 자주 발생)Sonner의 주입된 스타일시트가 손실됨 — layout에서 명시적으로 가져오기: import 'sonner/dist/styles.css'.
Shadow DOM 내에서 스타일 없음스타일이 document.head에 배치되며 shadow root에는 배치되지 않음. [data-sonner-toaster]가 포함된 스타일 태그를 shadow root에 복사하세요.
토스트가 모달/오버레이 뒤에 있거나 잘림조상 요소가 쌓임 컨텍스트(transform, filter, overflow)를 만들거나 오버레이가 toaster보다 z-index가 높음. <Toaster />를 문서 루트로 이동하여 대화상자/포털 컨테이너 외부에 배치하세요.
다크 모드 무시theme 기본값은 'light' — theme="system"을 설정하거나 확인된 테마를 전달하세요(위 테마 참조).
성공/오류가 녹색/빨간색이 아닌 회색으로 표시됨기본값입니다. Toaster에 richColors를 추가하세요.
토스트가 닫히지 않음duration: Infinity, dismissible: false, 또는 프로미스가 해결되지 않는 toast.promise — 로딩 토스트가 영원히 기다림.
toast.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.

관련 스킬