mcouthon/agents/design

Premium UI Design & Implementation

A comprehensive guide to premium UI design and implementation. Part 1 establishes design direction, Part 2 covers craft principles, and Part 3 provides the 9-phase implementation approach.

Part 1: Design Direction (REQUIRED)

Before writing any code, commit to a design direction. Don't default. Think about what this specific product needs to feel like.

Think About Context

• What does this product do? A finance tool needs different energy than a creative tool.
• Who uses it? Power users want density. Occasional users want guidance.
• What's the emotional job? Trust? Efficiency? Delight? Focus?
• What would make this memorable? Every product has a chance to feel distinctive.

SaaS ≠ Marketing. A SaaS product isn't a landing page. Marketing sites sell with visuals and emotion. Product interfaces serve with clarity and function. Resist the urge to make things "pop"—make them _work_. Glass morphism, gradients, and glow effects are spices, not the meal. The meal is information hierarchy, fast interactions, and clear feedback.

Start with Intent, Not Aesthetics

Before choosing a personality or color palette, answer these questions:

1. Who is this human? What's their context, expertise, and emotional state when they open this tool?
2. What must they accomplish? Map the top 3 user tasks. What's primary, secondary, tertiary?
3. What should this feel like? Confident? Fast? Calm? The feeling drives every surface decision.
4. Where does the user need confidence? Destructive actions, financial data, status indicators.
5. Where does the user need speed? Frequent actions, navigation, data scanning.
6. What information hierarchy does that create? What's primary, secondary, tertiary?

Design direction flows FROM these answers. If you can't articulate the intent, you're decorating, not designing.

Intent → Structure → Surface: Get the information architecture right first. Then establish visual hierarchy. Only then choose personality and aesthetics.

Choose a Personality

Enterprise/SaaS UI has more range than you think:

Pick one. Or blend two. But commit.

Personality → Implementation Mapping

Use these as starting points—adapt to your specific context.

Choose a Color Foundation

Don't default to warm neutrals. Consider the product:

• Warm foundations (creams, warm grays) — approachable, comfortable, human
• Cool foundations (slate, blue-gray) — professional, trustworthy, serious
• Pure neutrals (true grays, black/white) — minimal, bold, technical
• Tinted foundations (slight color cast) — distinctive, memorable, branded

Light or dark? Dark feels technical, focused, premium. Light feels open, approachable, clean.

Accent color — Pick ONE that means something. Blue for trust. Green for growth. Orange for energy. Violet for creativity.

Choose a Layout Approach

The content should drive the layout:

• Dense grids for information-heavy interfaces where users scan and compare
• Generous spacing for focused tasks where users need to concentrate
• Sidebar navigation for multi-section apps with many destinations
• Top navigation for simpler tools with fewer sections
• Split panels for list-detail patterns where context matters

Choose Typography

• System fonts — fast, native, invisible (utility-focused products)
• Geometric sans (Geist, Inter) — modern, clean, technical
• Humanist sans (SF Pro, Satoshi) — warmer, more approachable
• Monospace influence — technical, developer-focused, data-heavy

Part 2: Core Craft Principles

These apply regardless of design direction. This is the quality floor.

The 4px Grid

All spacing uses a 4px base grid:

Touch Targets & Cursor Discipline

44px minimum hit area for all interactive elements. This isn't just mobile—it's motor accessibility and Fitts's Law. Small targets slow everyone down.

• Buttons, links, icons, toggles, tabs: all ≥ 44×44px hit area
• If the visual element is smaller (e.g., a 24px icon), expand the clickable area with padding
• Navigation items, list items, dropdown options: ≥ 44px height

cursor: pointer on everything clickable. No exceptions. If a user can click it, the cursor must change. Buttons, links, cards, tabs, toggles, chips, dropdown triggers—all get cursor-pointer.

Symmetrical Padding

TLBR must match. If top padding is 16px, left/bottom/right must also be 16px.

/* Good */
padding: 16px;
padding: 12px 16px; /* Only when horizontal needs more room */
 
/* Bad */
padding: 24px 16px 12px 16px;

Border Radius Consistency

Stick to the 4px grid. Sharper corners feel technical, rounder corners feel friendly:

• Sharp: 4px, 6px, 8px
• Soft: 8px, 12px
• Minimal: 2px, 4px, 6px

Don't mix systems. Consistency creates coherence.

Depth & Elevation Strategy

Match your depth approach to your design direction. Choose ONE:

Borders-only (flat) — Clean, technical, dense. Works for utility-focused tools. Linear, Raycast use almost no shadows—just subtle borders.

Subtle single shadows — Soft lift without complexity: 0 1px 3px rgba(0,0,0,0.08)

Layered shadows — Rich, premium, dimensional. Stripe and Mercury use this approach.

Surface color shifts — Background tints establish hierarchy without shadows. A card at #fff on #f8fafc already feels elevated.

/* Borders-only approach */
--border: rgba(0, 0, 0, 0.08);
border: 0.5px solid var(--border);
 
/* Single shadow approach */
--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
 
/* Layered shadow approach */
--shadow-layered:
  0 0 0 0.5px rgba(0, 0, 0, 0.05), 0 1px 2px rgba(0, 0, 0, 0.04),
  0 2px 4px rgba(0, 0, 0, 0.03), 0 4px 8px rgba(0, 0, 0, 0.02);

The craft is in the choice, not the complexity.

Glass, not glow. Glass morphism is a depth technique—frosted layers that establish hierarchy through translucency and blur. It's NOT about making things shiny. Use glass to separate content layers (sidebar, modals, floating panels). If glass doesn't serve a structural purpose, don't use it. A solid bg-card is often better than a blurred panel.

Card Layouts

Monotonous card layouts are lazy design. A metric card doesn't have to look like a plan card doesn't have to look like a settings card.

Design each card's internal structure for its specific content—but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale, typography.

Isolated Controls

UI controls deserve container treatment. Date pickers, filters, dropdowns should feel like crafted objects.

Never use native form elements for styled UI. Native <select>, <input type="date"> render OS-native controls that cannot be styled. Build custom components instead.

Custom select triggers must use display: inline-flex with white-space: nowrap to keep text and chevron icons on the same row.

Monospace for Data

Numbers, IDs, codes, timestamps belong in monospace. Use tabular-nums for columnar alignment. Mono signals "this is data."

Iconography

Use Phosphor Icons (@phosphor-icons/react). Icons clarify, not decorate—if removing an icon loses no meaning, remove it.

Give standalone icons presence with subtle background containers.

Contrast Hierarchy

Build a four-level system: foreground (primary) → secondary → muted → faint. Use all four consistently.

Color for Meaning Only

Gray builds structure. Color only appears when it communicates: status, action, error, success. Decorative color is noise.

Ask whether each use of color is earning its place. Score bars don't need to be color-coded by performance—a single muted color works.

Anti-Default Tests

Every design decision should survive four tests. If a choice is just "what the framework gave me," it's not a decision—it's a default.

The Swap Test: Could you swap this component with any other app's version and nobody would notice? If yes, you haven't designed it—you've assembled it.

The Squint Test: Squint at the screen. Can you still see the hierarchy? If everything blurs into the same gray mass, your visual hierarchy is broken. Primary actions, key data, and navigation should remain distinct even when blurred.

The Signature Test: Cover the logo. Can you tell which product this is? If not, the design has no point of view. At least ONE element should be distinctive to this product.

The Token Test: Is every value (color, spacing, radius, shadow) coming from your design tokens? If you're using arbitrary values (mt-[13px], text-[#3a3a3a]), you're creating inconsistency. Every value should trace back to the system.

Also question: Is the grid alignment consistent? Is the depth strategy coherent across every surface?

Navigation Context

Screens need grounding. A data table floating in space feels like a component demo, not a product. Consider including:

• Navigation — sidebar or top nav showing where you are in the app
• Location indicator — breadcrumbs, page title, or active nav state
• User context — who's logged in, what workspace/org

When building sidebars, consider using the same background as the main content area. Tools like Supabase, Linear, and Vercel rely on a subtle border for separation rather than different background colors.

Dark Mode Considerations

Borders over shadows — Shadows are less visible on dark backgrounds. Lean more on borders for definition. A border at 10-15% white opacity might look nearly invisible but it's doing its job.

Adjust semantic colors — Status colors (success, warning, error) often need to be slightly desaturated for dark backgrounds.

Same structure, different values — The hierarchy system (foreground → secondary → muted → faint) still applies, just with inverted values.