Ultimate UI

When this skill is activated, always start your first response with the 🧢 emoji.

Ultimate UI

A comprehensive design system knowledge base for building UIs that feel crafted by a senior designer, not generated by a prompt. This skill encodes specific, opinionated rules - exact spacing values, proven color ratios, real typography scales, and battle-tested component patterns. Every recommendation is actionable with concrete CSS/Tailwind values, not vague advice like "make it clean."

The difference between AI slop and a polished UI comes down to constraint and restraint - fewer colors used with intention, consistent spacing from a scale, typography that creates hierarchy without screaming, and micro-interactions that feel responsive without being distracting.

When to use this skill

Trigger this skill when the user:

• Asks to build or style a UI component (button, card, form, table, nav)
• Needs help with layout, spacing, or grid decisions
• Wants to implement dark mode or theme switching
• Asks about typography, font choices, or text styling
• Needs accessible and WCAG-compliant designs
• Wants landing page, onboarding, or conversion-focused layouts
• Asks about animations, transitions, or micro-interactions
• Needs help with responsive design or mobile navigation
• Wants feedback patterns (toasts, tooltips, loading states)
• Asks to make something "look better" or "more professional"

Do NOT trigger this skill for:

• Backend logic, API design, or database schema questions
• Brand identity or logo design (this is implementation, not branding)

Key principles

1. Use a spacing scale, never arbitrary values - Pick a base unit (4px or 8px) and only use multiples: 4, 8, 12, 16, 24, 32, 48, 64, 96. Tailwind's default scale does this. Random padding like 13px or 27px is the #1 tell of amateur UI.

2. Limit your palette to 1 primary + 1 neutral + 1 accent - More colors = more chaos. Use 5-7 shades of your primary (50-900), a full neutral gray scale, and one accent for destructive/success states. Never more than 3 hues on a single screen.

3. Create hierarchy through contrast, not decoration - Size, weight, color, and spacing create hierarchy. You should never need borders, shadows, AND color differences simultaneously. One or two signals per level of hierarchy.

4. Every interactive element needs 4 states - Default, hover, active/pressed, and disabled. If you skip any state, the UI feels broken. Focus states are mandatory for accessibility.

5. Whitespace is a feature, not wasted space - Generous padding makes UIs feel premium. Cramped UIs feel cheap. When in doubt, add more space. The content-to-whitespace ratio should favor whitespace.

6. Consistency beats novelty - Use the same border-radius everywhere (pick one: 6px, 8px, or 12px). Same shadow scale. Same transition timing. Inconsistency is what makes AI-generated UIs look "off."

7. Use real icons, never emojis - Unicode emojis (e.g. ✅, ⚡, 🔥, 📊) render inconsistently across operating systems and browsers, cannot be styled with CSS (no size, color, or stroke control), break visual consistency, and hurt accessibility. Always use a proper icon library - Lucide React (recommended), React Icons, Heroicons, Phosphor, or Font Awesome. Icons from these libraries are SVG-based, styleable, consistent, and accessible.

Core concepts

The 8px grid - All spacing, sizing, and layout decisions snap to an 8px grid. Component heights: 32px (small), 40px (medium), 48px (large). Padding: 8px, 12px, 16px, 24px. Gaps: 8px, 16px, 24px, 32px. This single rule eliminates 80% of "why does this look wrong" problems.

Visual weight - Every element has visual weight determined by size, color darkness, border thickness, and shadow. A page should have one clear heavyweight (the CTA or primary content), with everything else progressively lighter. Squint at your page - if nothing stands out, your hierarchy is flat.

The 60-30-10 rule - 60% dominant color (background/neutral), 30% secondary (cards, sections), 10% accent (CTAs, active states). This ratio works for any color scheme and prevents the "everything is colorful" trap.

Optical alignment - Mathematical center doesn't always look centered. Text in buttons needs 1-2px more padding on top visually. Icons next to text need optical adjustment. Always trust your eyes over the inspector.

Progressive disclosure - Don't show everything at once. Start with the essential action, reveal complexity on demand. This applies to forms (multi-step > one long form), settings (basic > advanced), and navigation (primary > secondary > tertiary).

Common tasks

Style a button hierarchy

Every app needs 3 button levels: primary (filled), secondary (outlined), and ghost (text-only). Never use more than one primary button per visual section.

/* Primary - solid fill, high contrast */
.btn-primary {
  background: var(--color-primary-600);
  color: white;
  padding: 10px 20px;
  border-radius: 8px;
  font-weight: 500;
  font-size: 14px;
  border: none;
  transition: background 150ms ease, transform 100ms ease;
}
.btn-primary:hover { background: var(--color-primary-700); }
.btn-primary:active { transform: scale(0.98); }

/* Secondary - outlined */
.btn-secondary {
  background: transparent;
  color: var(--color-primary-600);
  padding: 10px 20px;
  border: 1.5px solid var(--color-primary-200);
  border-radius: 8px;
  font-weight: 500;
  font-size: 14px;
  transition: border-color 150ms ease, background 150ms ease;
}
.btn-secondary:hover {
  border-color: var(--color-primary-400);
  background: var(--color-primary-50);
}

/* Ghost - text only */
.btn-ghost {
  background: transparent;
  color: var(--color-gray-600);
  padding: 10px 20px;
  border: none;
  border-radius: 8px;
  font-weight: 500;
  font-size: 14px;
}
.btn-ghost:hover { background: var(--color-gray-100); }

Button height should be 36px (sm), 40px (md), or 48px (lg). Never smaller than 36px for touch targets.

Set up a type scale

Use a modular scale with ratio 1.25 (major third). Base size: 16px.

:root {
  --text-xs: 0.75rem;    /* 12px - captions, labels */
  --text-sm: 0.875rem;   /* 14px - secondary text, metadata */
  --text-base: 1rem;     /* 16px - body text */
  --text-lg: 1.125rem;   /* 18px - lead paragraphs */
  --text-xl: 1.25rem;    /* 20px - card titles */
  --text-2xl: 1.5rem;    /* 24px - section headings */
  --text-3xl: 1.875rem;  /* 30px - page titles */
  --text-4xl: 2.25rem;   /* 36px - hero subheading */
  --text-5xl: 3rem;      /* 48px - hero heading */

  --leading-tight: 1.25;  /* headings */
  --leading-normal: 1.5;  /* body text */
  --leading-relaxed: 1.75; /* small text, captions */
}

Limit to 2 font families max: one for headings (Inter, Manrope, or a geometric sans), one for body (same or a humanist like Source Sans). Using 3+ fonts is a red flag.

Build a responsive layout with CSS Grid

/* Content-first responsive grid - no media queries needed */
.grid-auto {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 320px), 1fr));
  gap: 24px;
}

/* Holy grail layout */
.page-layout {
  display: grid;
  grid-template-columns: minmax(240px, 1fr) minmax(0, 3fr) minmax(200px, 1fr);
  gap: 32px;
  max-width: 1280px;
  margin: 0 auto;
  padding: 0 24px;
}

/* Stack on mobile */
@media (max-width: 768px) {
  .page-layout {
    grid-template-columns: 1fr;
  }
}

Max content width: 1280px for apps, 720px for reading content. Never let text lines exceed 75 characters.

Implement dark mode properly

:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;
  --bg-tertiary: #f3f4f6;
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
  --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: #0f172a;
    --bg-secondary: #1e293b;
    --bg-tertiary: #334155;
    --text-primary: #f1f5f9;
    --text-secondary: #94a3b8;
    --border: #334155;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  }
}

Never just invert colors. Dark mode backgrounds should be dark blue-gray (#0f172a, #1e293b), not pure black. Reduce white text to #f1f5f9 (not #ffffff) to prevent eye strain. Shadows need higher opacity in dark mode.

Add a toast notification system

.toast {
  position: fixed;
  bottom: 24px;
  right: 24px;
  padding: 12px 20px;
  border-radius: 8px;
  font-size: 14px;
  font-weight: 500;
  display: flex;
  align-items: center;
  gap: 8px;
  animation: slide-up 200ms ease-out;
  z-index: 50;
}

.toast-success { background: #ecfdf5; color: #065f46; border: 1px solid #a7f3d0; }
.toast-error { background: #fef2f2; color: #991b1b; border: 1px solid #fecaca; }
.toast-info { background: #eff6ff; color: #1e40af; border: 1px solid #bfdbfe; }

@keyframes slide-up {
  from { transform: translateY(16px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

Auto-dismiss success toasts after 3-5s. Error toasts should persist until dismissed. Stack multiple toasts with 8px gap. Max 3 visible at once.