Sonner Principles for Building Loved Components: 6 Design Rules from the emilkowalski/skills Repository

The Sonner principles are six design-engineering rules documented in the emilkowalski/skills repository that transform generic UI components into "loved" user experiences through intentional naming, cohesive motion, relative transformations, incremental feedback, simplicity, and visual consistency.

The Sonner principles for building loved components originate from the emilkowalski/skills repository's design engineering documentation, specifically within the context of the Sonner toast library (used by over 13 million projects weekly). These guidelines, outlined in skills/emil-design-eng/SKILL.md, provide a practical framework for creating UI components that feel intentional and polished rather than purely utilitarian. By applying these six rules, developers can elevate standard components—like toast notifications—into memorable interface elements that resonate with users and stand out in crowded design systems.

What Are the Sonner Principles?

The Sonner principles are a set of design-driven rules extracted from the Sonner library implementation and documented in the repository's skill files. According to skills/emil-design-eng/SKILL.md, these principles can be applied to any UI component to make it feel "loved" by users. The guidelines emphasize that great components require more than functional code—they need personality, cohesive motion, and thoughtful engineering that prioritizes user perception over rigid technical specifications.

The 6 Core Sonner Principles

1. Identity via Naming

"Naming creates identity." Choose a memorable, evocative name instead of a purely functional descriptor. The Sonner library itself derives from the French word meaning "to ring," conveying the auditory metaphor of a notification bell. This stands in contrast to generic names like react-toast or notification-system. A strong name gives the component personality and makes it stand out in a sea of generic utilities.

2. Cohesive Motion

"Match motion to the component's personality." Use easing curves, duration, and animation styles that fit the component's vibe. For example, Sonner uses slightly slower ease timing functions instead of snappy ease-out curves to create a more elegant, deliberate feel. Consistent motion reinforces the component's character and avoids jarring transitions that break user immersion.

3. Relative Transformations

"Translate percentages are relative to the element itself." Position elements using relative units like translateY(100%) so movement calculations reference the element's own dimensions rather than viewport or container sizes. This guarantees predictable behavior across different screen sizes and layouts, preventing positioning bugs when content changes or responsive breakpoints activate.

4. Incremental Feedback

"Opacity + height transitions are tuned by trial-and-error." Layer multiple transition properties—specifically combining opacity fade-in/out with height growth/shrink—to create natural entry and exit animations. This blended approach provides subtle cues that the UI is actively responding to user actions, increasing perceived responsiveness and satisfaction without overwhelming the user with heavy motion.

5. Simplicity Over Over-Engineering

"Avoid hard-coded pixel values." Prefer relative units (percentages, rem) and fluid calculations rather than fixed px values. This reduces maintenance overhead when design systems change and improves adaptability across different themes, accessibility settings, and device pixel densities. The Sonner source code demonstrates this through CSS custom properties and relative transforms.

6. Consistency Across the UI

"Everything is in harmony." Align toast styling, animation timing, and even naming conventions with the surrounding page design and broader design system. When a component matches the established visual language, users perceive it as a seamless native part of the product rather than a third-party afterthought or foreign attachment.

How to Implement Sonner Principles in Code

The following examples demonstrate how to apply these principles when building a React toast component.

Creating Identity Through Naming

Instead of Toast or Notification, choose a name that evokes the component's purpose:

import { useState } from "react";

// The component name "RingToast" echoes the Sonner idea of ringing.
export function RingToast({ message }: { message: string }) {
  const [visible, setVisible] = useState(true);
  return visible ? (
    <div className="ring-toast">{message}</div>
  ) : null;
}

Applying Cohesive Motion and Relative Transforms

Use relative transforms and consistent easing in your CSS:

/* ring-toast.css */
.ring-toast {
  position: fixed;
  bottom: 1rem;
  right: 1rem;
  background: #323232;
  color: #fff;
  padding: 0.75rem 1rem;
  border-radius: 6px;
  /* Relative transform – moves by its own height */
  transform: translateY(100%);
  /* Cohesive motion – slower, elegant easing */
  transition: transform 300ms ease, opacity 300ms ease;
  opacity: 0;
}

/* When the toast is shown */
.ring-toast[data-visible="true"] {
  transform: translateY(0);
  opacity: 1;
}

Implementing Incremental Feedback

Combine height and opacity transitions for smooth expand/collapse behavior:

/* Add height animation for smooth expanding */
.ring-toast {
  overflow: hidden;
  max-height: 0;
  transition: max-height 300ms ease, opacity 300ms ease;
}

.ring-toast[data-visible="true"] {
  max-height: 5rem; /* enough for typical content */
}

Where to Find the Original Documentation

The Sonner principles are formally documented in the following repository files:

• skills/emil-design-eng/SKILL.md – Contains the complete "Sonner Principles" section with detailed explanations and philosophical context.
• skills/pick-ui-library/SKILL.md – Lists Sonner within the recommended UI stack, providing context for when to select this library over alternatives.
• skills/review-animations/STANDARDS.md – Discusses translation percentages and motion matching standards that complement the Sonner principles.

Summary

• Name components intentionally to create identity and personality rather than using utilitarian descriptors.
• Match motion to personality using consistent easing curves and timing that reinforce the component's character.
• Use relative transformations (percentages) to ensure predictable positioning across all screen sizes.
• Layer transitions by combining opacity and height animations for natural-feeling state changes.
• Avoid hard-coded pixels in favor of relative units to maintain flexibility across design systems.
• Maintain harmony with the surrounding UI through consistent styling and animation language.

Frequently Asked Questions

What makes a component "loved" according to Sonner principles?

A "loved" component feels intentional and cohesive rather than purely functional. According to skills/emil-design-eng/SKILL.md, this quality emerges when developers combine memorable naming, motion that matches the component's personality, and technical implementation using relative units and layered transitions. These elements signal to users that care was taken in the component's creation.

Why does naming matter for UI components?

Naming creates identity. The Sonner library exemplifies this by using a French word meaning "to ring" instead of generic terms like "toast" or "notification." As documented in the repository's design engineering skills, evocative names give components personality that helps them stand out in crowded design systems and creates stronger mental models for developers and users alike.

How do relative transforms improve component reliability?

Using percentages like translateY(100%) ensures that movement calculations reference the element's own dimensions rather than fixed pixel values or viewport sizes. This approach, detailed in skills/emil-design-eng/SKILL.md and cross-referenced in skills/review-animations/STANDARDS.md, prevents positioning bugs when content changes length or when components render in different responsive contexts.

Where can I apply Sonner principles beyond toast notifications?

The Sonner principles apply to any UI component requiring entry/exit animations or identity definition—modals, dropdowns, banners, or interactive cards. The skills/emil-design-eng/SKILL.md file presents these as universal design engineering rules that translate across component types, emphasizing that "loved" components result from thoughtful naming, motion, and technical simplicity regardless of specific use case.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}