Communitygithub.com

CharbelElBateh/personal-website

Sonner、React用トーストライブラリのためのガイド — Toasterのインストールと配線、適切なtoast()の呼び出し方、プロミスとローディングトースト、更新、破棄、永続化、スタイリング、テーマ、アイコン、配置、複数Toasterの使い方を解説。Sonnerを使う時やトラブルシューティング時(トーストが表示されない、二重に表示される、スタイルが失われる、Tailwindクラスが無視される、モーダルの背後に隠れる、ダークモードに対応しないなど)に使用します。

personal-website とは?

このスキルは、Reactアプリケーション向けトースト通知ライブラリ「Sonner」をセットアップ、スタイリング、トラブルシューティングするための包括的なガイドです。作者Emil Kowalskiの知見に基づき、<Toaster />コンポーネントのルートへの単一マウント、クライアントコードからのtoast()関数呼び出し、成功・エラー・ローディング・カスタムJSXなど様々なトーストタイプの使い分け、プロミスベースのローディングから成功への遷移、トーストの更新・永続化・破棄、複数Toasterの管理方法を詳細に解説します。スタイリングに関しては、デフォルトからインライン調整、クラスによるパーツ指定、ヘッドレスカスタムJSXへと段階的にアプローチできる「エスカレーションラダー」を提供し、Tailwind CSSとの統合やテーマ切り替えにも対応。トラブルシューティングセクションでは、トーストが表示されない、二重表示、スタイルが効かない、モーダルの背後に隠れる、ダークモードが無視されるなど、開発者が陥りがちな問題とその原因・解決策を表形式でまとめています。Next.js、Astro、Shadow DOMを含む様々な環境での動作にも対応しており、Sonnerを使うすべての開発者にとって実用的なリファレンスとなるスキルです。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Sonnerを使いこなす

初回応答

このスキルが初めて呼び出され、特定の質問がない場合は、次のようにのみ応答します。

Sonnerのセットアップ、スタイル設定、トラブルシューティングをお手伝いします。私の知識は作者のEmil Kowalskiによるものです。

ユーザーが質問するまで、それ以外の情報は提供しないでください。

これはSonner、トーストライブラリのためのガイドスキルです。タスクがSonnerに関するもの(配線、トーストのレンダリング、スタイリング、修正)であれば、このファイルから最初に回答してください。<Toaster />とtoast()の完全なプロップテーブルはAPI.mdにあります。正確なプロップ名、型、デフォルト値が必要な場合はそちらを読んでください。

セットアップ

2つの要素だけです。

  1. <Toaster />を1つだけ、ルートにできるだけ近い場所にマウントする(Next.jsの場合はlayout.tsx — サーバーコンポーネント内でも動作します)。ページごとや条件付きでレンダリングしないでください。2つ目のToasterがマウントされると、すべてのトーストが重複します。
  2. クライアントコードからtoast()を呼び出す — イベントハンドラ、エフェクト、コールバック。これは通常の関数であり、フックやプロバイダは不要ですが、サーバー上では何も行いません。サーバーアクションの場合は、結果を返し、それを受け取るクライアントコードでtoast()を呼び出してください。
import { Toaster } from 'sonner'; // レイアウトに一度だけ
import { toast } from 'sonner';   // クライアントサイドのどこでも

適切な呼び出し方を選ぶ

やりたいこと呼び出し方
プレーンメッセージtoast('タイトル') — 2行目を追加するには { description } を追加
成功/エラー/情報/警告のアイコン付きtoast.success('…')、toast.error('…') など
自分で状態管理しながらスピナーを表示toast.loading('…')、その後IDで更新
プロミスに紐づいたローディング→成功/エラー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()を再呼び出し。渡したプロップのみが変更されます。toast.success(…, { id })に切り替えるとタイプが変わります。これがtoast.promiseを使わずにローディング→成功フローを実現する方法です。

const id = toast.loading('アップロード中…');
toast.success('アップロード完了', { id });

永続化 — { duration: Infinity }。破棄 — toast.dismiss(id)、またはすべて破棄する場合はtoast.dismiss()。アクティブなトーストの読み取り — ReactではuseSonner()、React外ではtoast.getActiveToasts()。

テキスト内のリンクやコンポーネント — タイトルまたは説明に関数を渡します: toast(() => <a href="…">表示</a>)。

複数の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プロップで置き換え、個別のトーストにはiconで設定、nullで削除。

テーマ — themeはデフォルトで'light'であり、OSに追従しません。theme="system"を渡すか、テーマプロバイダと連携します: next-themesから <Toaster theme={resolvedTheme} />。

トラブルシューティング

症状原因 → 修正方法
トーストが表示されない<Toaster />がマウントされていない、またはアンマウントされた(条件付きレンダリング、ページごとの配置)。ルートに1つマウントしてください。サーバーアクションから呼び出す場合: toast()はクライアント専用です — アクションの結果をクライアントで受け取って呼び出してください。
同じトーストが2回表示される2つのToasterがマウントされている(レイアウトとページ) — 1つだけにしてください。あるいは、React StrictModeの開発時二重呼び出しのエフェクト内でtoast()が実行されている — イベントハンドラから呼び出すか、安定したidを渡して2回目の呼び出しが重複ではなく更新になるようにしてください。
Tailwind/CSSクラスが効かないデフォルトスタイルが上書きしています。!importantを付けるか、unstyled/ヘッドレスを使用してください(上記のラダーを参照)。
トーストが完全にスタイルなしで表示される(Astro、ビュー遷移でよく発生)Sonnerの注入スタイルシートが失われました — レイアウトで明示的にインポート: import 'sonner/dist/styles.css'。
Shadow DOM内でスタイルが効かないスタイルはdocument.headに配置され、シャドウルートには配置されません。テキストに[data-sonner-toaster]を含むスタイルタグをシャドウルートにコピーしてください。
トーストがモーダル/オーバーレイの背後に隠れる、またはクリップされる祖先要素が重ね合わせコンテキスト(transform、filter、overflow)を作成しているか、オーバーレイのz-indexがToasterより高い。<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.

関連スキル