Distinctive Frontend Design

Distinctive Frontend Design

Build frontend interfaces with genuine design intent. Every interface should feel like it was crafted by a human designer with a strong point of view — never like default AI output.

Project Context

This is a Next.js App Router project with the following stack:

• Styling: Tailwind CSS v4 (CSS-first config via @theme inline in globals.css)
• Fonts: Currently uses Geist Sans & Geist Mono via next/font/google (defined in app/layout.tsx)
• UI Components: Custom components in components/ui/ (Button, Input, Select, Dropdown, Textarea, Alert) — uses cn() utility for class merging, consistent variant/size patterns
• Icons: @mui/icons-material (Material UI icons package)
• Animations: CSS transitions only (no framer-motion installed). Consider adding motion (framer-motion) for complex animations.
• Theme: Light mode only (color-scheme: light), CSS variables at :root
• Auth: Clerk with Spanish localization (lang="es")
• Color system: --background: #ffffff, --foreground: #171717, blue primary (blue-500/blue-600), domain-specific color maps (categories, statuses, deal stages)
• Layout pattern: AppLayout wrapper with PageHeader + PageContent, white cards on bg-gray-50/30, mobile-responsive with bottom nav

Working Within This Stack

When building new interfaces in this project:

• Fonts: Add new display fonts via next/font/google in the component or layout that needs them. Set as CSS variable and reference in Tailwind via arbitrary values font-[var(--font-name)] or extend @theme.
• Tailwind v4: Extend colors/tokens in globals.css using @theme inline { } — no JS config file.
• Components: Follow existing patterns — cn() for class merging, variant/size props, consistent API shape. Import from @/components/ui/.
• CSS custom properties: Define at :root in globals.css or scoped to component.
• Animations: Use CSS @keyframes + Tailwind animate-* for simple cases. For orchestrated sequences, suggest installing motion (framer-motion).

Design Thinking (Before Code)

Before writing any code, spend time on these four questions:

1. Purpose: What problem does this solve? Who is the audience?
2. Tone: Commit to a BOLD aesthetic direction. Pick one and go deep:
   • Brutally minimal | Maximalist chaos | Retro-futuristic | Organic/natural
   • Luxury/refined | Playful/toy-like | Editorial/magazine | Brutalist/raw
   • Art deco/geometric | Soft/pastel | Industrial/utilitarian | Neo-grotesque
   • Typographic-forward | Glassmorphic depth | Monochrome drama | Warm analog
   • Use these as inspiration — design something true to the chosen direction.
3. Constraints: Performance targets, accessibility, consistency with existing app pages.
4. Differentiator: What single element makes this UNFORGETTABLE?

Output a brief design brief (2-4 sentences) before implementation. Example:

"Dashboard for creative professionals. Art deco geometric aesthetic: sharp angles, gold accent on deep navy, Playfair Display headings with DM Sans body. Differentiator: animated geometric border patterns that respond to data state."

Core Aesthetic Principles

Typography

Choose fonts that have genuine character. Pair a distinctive display font with a refined body font.

• For curated pairings organized by aesthetic, see font-pairings.md
• Load via next/font/google — set as CSS variable, use in Tailwind classes
• Set a clear typographic scale (e.g., 1.25 or 1.333 ratio)
• Use letter-spacing, line-height, and text-transform intentionally

NEVER use: Inter, Roboto, Arial, Open Sans, Lato, Geist, system-ui as display/heading fonts. These are generic defaults. Geist is fine for body/UI text since it's the project default, but headings and hero text deserve character.

Color & Theme

Commit fully. Dominant colors with sharp accents beat timid, evenly-distributed palettes.

• Define palette as CSS custom properties at :root or scoped via @theme inline
• Use a clear hierarchy: 1 dominant, 1-2 accents, neutrals
• This project is light-mode only — avoid pure #fff; use warm or cool off-whites
• Respect existing color semantics (blue primary for actions, status colors for states)
• New pages/features can have their own sub-palette while staying coherent with the app

Motion & Interaction

Prioritize high-impact orchestrated moments over scattered micro-interactions.

• Page load: Staggered reveals using animation-delay on sequential elements
• Scroll: Intersection Observer for scroll-triggered entrances
• Hover states: Surprising, delightful transitions (scale, color shift, shadow lift, underline animations)
• CSS animations: Use @keyframes in global CSS or component-scoped styles
• For complex motion: Consider adding motion (framer-motion) — npm install motion
• One well-orchestrated sequence > many small animations

Spatial Composition

Break predictable layouts. Not every design needs to be wild — but every design needs intentional spatial choices.

• Asymmetric grids, overlapping elements, diagonal flow
• Grid-breaking hero elements or pull-quotes
• Generous negative space OR controlled density — both are valid; pick one
• Consider viewport-relative sizing (dvh, vw, clamp())
• Work within the existing AppLayout > PageHeader + PageContent structure when building app pages

Backgrounds & Visual Depth

Create atmosphere. Solid flat colors are a missed opportunity.

• Gradient meshes, noise/grain textures, geometric patterns
• Layered transparencies and backdrop-filter effects
• Dramatic shadows (layered box-shadow stacks, not single default shadows)
• Decorative borders, custom dividers, ornamental elements
• Subtle background patterns or textures that reinforce the aesthetic

Anti-Patterns (AI Slop Checklist)

NEVER produce interfaces with these characteristics:

Implementation Guidelines

Match Complexity to Vision

• Maximalist designs: Elaborate code, extensive animations, layered effects, decorative elements
• Minimal/refined designs: Restraint and precision in spacing, typography, subtle details
• Elegance = executing the vision well, regardless of complexity level

Code Quality

• Production-grade: no placeholder content, no TODO comments, no broken states
• Semantic HTML, accessible by default (aria-labels, focus states, contrast ratios)
• CSS custom properties for theming consistency
• Responsive: mobile-first, test mental model across breakpoints
• Follow existing component API conventions (cn(), variant props, size props)

Tailwind v4 in This Project

• Extend tokens in globals.css via @theme inline { --color-*: ...; --font-*: ...; }
• Use arbitrary values [...] liberally to break out of default Tailwind system
• Layer custom CSS (in globals.css or component-scoped files) for effects Tailwind can't express
• For new fonts: define in next/font/google, set CSS variable, reference as font-[var(--font-name)]

New Component Pattern

Follow existing conventions when creating new UI components:

import { cn } from '@/lib/utils';

interface Props {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  className?: string;
  children: React.ReactNode;
}

export function MyComponent({ variant = 'primary', size = 'md', className, children }: Props) {
  return (
    <div className={cn(
      'base-classes-here',
      variant === 'primary' && 'primary-classes',
      size === 'md' && 'md-classes',
      className
    )}>
      {children}
    </div>
  );
}

Variety Mandate

NEVER converge on the same choices across different generations:

• Use different font families each time
• Vary aesthetic directions (don't always pick the same style)
• Different color palettes, layout approaches, animation strategies

Each interface should feel like it came from a different designer with a different perspective.

Additional Resources

• For curated font pairings by aesthetic, see font-pairings.md
• For detailed aesthetic directions with visual descriptions, see aesthetics-reference.md