---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Use when building landing pages, dashboards, components, or any user-facing web interface. Applies typography, color, motion, and background best practices to generate memorable, branded experiences.
---

# Frontend Design Skill

## Overview

This skill guides creation of distinctive, production-grade frontend interfaces that avoid the generic "AI slop" aesthetic—the predictable pattern of Inter fonts, purple gradients, centered layouts, and cookie-cutter components that make AI-generated interfaces immediately recognizable and dismissible.

**The Problem**: LLMs tend toward distributional convergence—sampling from the high-probability center of training data where safe, generic design choices dominate.

**The Solution**: Targeted guidance across typography, color, motion, and backgrounds that breaks free from these defaults.

## When to Use This Skill

Use this skill when:

- Building landing pages, marketing sites, or product pages
- Creating dashboards, admin panels, or data visualization interfaces
- Designing React/Next.js components with visual requirements
- Implementing any user-facing web interface
- Refreshing existing UI to feel more distinctive

## Design Thinking Framework

Before coding, commit to a BOLD aesthetic direction:

### 1. Understand the Context

- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme direction (see Aesthetic Vocabulary below)
- **Constraints**: Technical requirements, accessibility, performance

### 2. Choose an Aesthetic Direction

Pick ONE and execute with precision:

| Aesthetic              | Characteristics                                            | Example Use           |
| ---------------------- | ---------------------------------------------------------- | --------------------- |
| Brutally Minimal       | Massive whitespace, stark contrasts, one accent color      | Portfolio, agency     |
| Maximalist Chaos       | Dense information, layered elements, controlled complexity | Data dashboards       |
| Retro-Futuristic       | Neon accents, dark backgrounds, glowing effects            | Gaming, tech          |
| Organic/Natural        | Earthy tones, flowing shapes, subtle textures              | Wellness, food        |
| Luxury/Refined         | Gold/cream palette, elegant typography, generous spacing   | Finance, fashion      |
| Playful/Toy-like       | Bright primaries, rounded shapes, bouncy animations        | Kids apps, casual     |
| Editorial/Magazine     | Strong typography hierarchy, asymmetric layouts            | Media, publishing     |
| Brutalist/Raw          | System fonts, visible grid, stark utility                  | Developer tools       |
| Art Deco/Geometric     | Bold patterns, metallic accents, symmetric layouts         | Events, hospitality   |
| Industrial/Utilitarian | Monospace fonts, warning colors, functional beauty         | Logistics, enterprise |

## Typography Guidelines

Typography instantly signals quality. The right font choice creates immediate differentiation.

### ❌ NEVER Use (Overexposed)

- Inter (AI default)
- Roboto (generic)
- Open Sans (bland)
- Lato (invisible)
- Arial, Helvetica (system defaults)
- Default system fonts

### ✅ Distinctive Font Categories

**Code/Technical Aesthetic:**

```
JetBrains Mono, Fira Code, Space Grotesk, IBM Plex Mono
```

**Editorial/Refined:**

```
Playfair Display, Crimson Pro, Newsreader, Cormorant Garamond
```

**Modern Geometric:**

```
Outfit, Sora, Manrope, General Sans, Plus Jakarta Sans
```

**Bold Display:**

```
Clash Display, Cabinet Grotesk, Bricolage Grotesque
```

**Minimal/Clean:**

```
Satoshi, DM Sans, Switzer, Geist
```

### Typography Pairing Principles

High contrast creates interest:

- Display + Monospace (headlines in Clash Display, body in JetBrains Mono)
- Serif + Geometric Sans (headers in Playfair, body in Outfit)
- Variable weight extremes (100/200 vs 800/900, not 400 vs 600)

Size jumps should be dramatic:

- 3x+ between heading levels, not 1.5x
- Hero text: 4-6rem, body: 1rem
- Create clear visual hierarchy

### Loading Fonts

```html
<!-- Google Fonts example -->
<link
  href="https://fonts.googleapis.com/css2?family=Outfit:wght@100..900&family=JetBrains+Mono:wght@400;700&display=swap"
  rel="stylesheet"
/>
```

```css
/* CSS usage */
:root {
  --font-display: "Outfit", sans-serif;
  --font-mono: "JetBrains Mono", monospace;
}

h1,
h2,
h3 {
  font-family: var(--font-display);
}
code,
pre {
  font-family: var(--font-mono);
}
```

## Color & Theme Guidelines

### Core Principles

1. **Dominant + Sharp Accents** beats evenly distributed palettes
2. **Commit to an aesthetic** - don't hedge with neutral choices
3. **Use CSS variables** for consistency and easy theming
4. **Draw from proven palettes** - IDE themes, cultural aesthetics

### ❌ Avoid

- Purple gradients on white backgrounds (AI cliché #1)
- Pure black (#000) for dark themes
- Pure white (#fff) for light themes
- Evenly distributed rainbow palettes
- Low-contrast, "safe" color schemes

### ✅ Strong Color Approaches

**Dark Themes (avoid pure black):**

```css
:root {
  --bg-primary: #0a0a0f; /* Rich dark, not pure black */
  --bg-secondary: #13131a;
  --text-primary: #f4f4f5;
  --text-muted: #71717a;
  --accent: #22d3ee; /* Cyan accent */
  --accent-glow: rgba(34, 211, 238, 0.15);
}
```

**Light Themes (avoid pure white):**

```css
:root {
  --bg-primary: #fafaf9; /* Warm white, not sterile */
  --bg-secondary: #f5f5f4;
  --text-primary: #1c1917;
  --text-muted: #78716c;
  --accent: #ea580c; /* Orange accent */
}
```

**IDE-Inspired Palettes:**

```css
/* Dracula-inspired */
--bg: #282a36;
--fg: #f8f8f2;
--accent-cyan: #8be9fd;
--accent-pink: #ff79c6;
--accent-purple: #bd93f9;

/* One Dark-inspired */
--bg: #1e2127;
--fg: #abb2bf;
--accent-blue: #61afef;
--accent-green: #98c379;
--accent-orange: #d19a66;

/* Tokyo Night-inspired */
--bg: #1a1b26;
--fg: #c0caf5;
--accent-cyan: #7dcfff;
--accent-magenta: #bb9af7;
--accent-green: #9ece6a;
```

## Motion & Animation Guidelines

### Core Principles

1. **High-impact moments** over scattered micro-interactions
2. **Page load with staggered reveals** creates more delight than hover effects
3. **CSS-only solutions** when possible (performance, simplicity)
4. **Use Motion library** for React when needed (framer-motion)

### Page Load Animation Pattern

```css
/* Staggered reveal on load */
@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.reveal {
  animation: fadeInUp 0.6s ease-out forwards;
  opacity: 0;
}

/* Stagger with delays */
.reveal:nth-child(1) {
  animation-delay: 0.1s;
}
.reveal:nth-child(2) {
  animation-delay: 0.2s;
}
.reveal:nth-child(3) {
  animation-delay: 0.3s;
}
.reveal:nth-child(4) {
  animation-delay: 0.4s;
}
```

### Micro-Interactions

```css
/* Button hover with scale and glow */
.btn {
  transition: all 0.2s ease;
}
.btn:hover {
  transform: scale(1.02);
  box-shadow: 0 0 20px var(--accent-glow);
}

/* Card lift on hover */
.card {
  transition:
    transform 0.3s ease,
    box-shadow 0.3s ease;
}
.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.15);
}
```

### React Motion Examples

```tsx
import { motion } from "framer-motion";

// Staggered container
const container = {
  hidden: { opacity: 0 },
  show: {
    opacity: 1,
    transition: { staggerChildren: 0.1 },
  },
};

const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0 },
};

<motion.ul variants={container} initial="hidden" animate="show">
  {items.map((i) => (
    <motion.li key={i.id} variants={item}>
      {i.name}
    </motion.li>
  ))}
</motion.ul>;
```

## Background & Atmosphere Guidelines

### Core Principles

1. **Create depth and atmosphere**, not flat solid colors
2. **Layer CSS gradients** for dimension
3. **Use geometric patterns** or noise textures
4. **Match effects to aesthetic** direction

### ❌ Avoid

- Flat, solid color backgrounds
- Stock photo backgrounds
- Overly busy patterns that distract

### ✅ Atmospheric Backgrounds

**Gradient Mesh:**

```css
.bg-mesh {
  background:
    radial-gradient(at 40% 20%, hsla(210, 100%, 16%, 1) 0, transparent 50%),
    radial-gradient(at 80% 0%, hsla(189, 100%, 56%, 0.1) 0, transparent 50%),
    radial-gradient(at 0% 50%, hsla(355, 100%, 93%, 0.05) 0, transparent 50%),
    var(--bg-primary);
}
```

**Subtle Grid Pattern:**

```css
.bg-grid {
  background-image:
    linear-gradient(to right, rgba(255, 255, 255, 0.05) 1px, transparent 1px),
    linear-gradient(to bottom, rgba(255, 255, 255, 0.05) 1px, transparent 1px);
  background-size: 40px 40px;
}
```

**Noise Texture:**

```css
.bg-noise {
  position: relative;
}
.bg-noise::before {
  content: "";
  position: absolute;
  inset: 0;
  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
  opacity: 0.03;
  pointer-events: none;
}
```

**Glow Effects:**

```css
.glow-accent {
  position: relative;
}
.glow-accent::after {
  content: "";
  position: absolute;
  width: 200px;
  height: 200px;
  background: var(--accent);
  filter: blur(100px);
  opacity: 0.15;
  border-radius: 50%;
  z-index: -1;
}
```

## Layout Guidelines

### ❌ Avoid

- Everything centered (boring, predictable)
- Uniform rounded corners everywhere
- Predictable grid-only layouts
- Equal spacing throughout

### ✅ Interesting Layouts

**Asymmetry:**

```css
.hero {
  display: grid;
  grid-template-columns: 1.5fr 1fr;
  gap: 4rem;
}
```

**Overlap Effects:**

```css
.overlap-card {
  margin-top: -60px;
  position: relative;
  z-index: 10;
}
```

**Mixed Border Radius:**

```css
/* Sharp and round in same component */
.card {
  border-radius: 0 24px 24px 0; /* Asymmetric radius */
}
```

**Generous Negative Space:**

```css
.section {
  padding: 8rem 0; /* Don't be afraid of space */
}
.hero-title {
  margin-bottom: 4rem; /* Breathing room */
}
```

## Quick Reference Checklist

### Before Starting

- [ ] Chose a specific aesthetic direction
- [ ] Selected distinctive fonts (NOT Inter/Roboto)
- [ ] Defined a dominant color + sharp accent palette
- [ ] Planned key animation moments

### During Implementation

- [ ] Using CSS variables for consistency
- [ ] Added atmospheric background treatment
- [ ] Implemented staggered load animations
- [ ] Created visual hierarchy with typography scale
- [ ] Used asymmetry or overlap where appropriate

### Final Check

- [ ] Does NOT look like generic AI output
- [ ] Has distinctive, memorable character
- [ ] Typography is interesting and readable
- [ ] Color palette is cohesive and bold
- [ ] Motion adds delight, not distraction
- [ ] Background creates atmosphere and depth

## Mawidi Editorial Design System

**IMPORTANT**: This is the PRIMARY design system for all Mawidi pages. Every new page and component MUST follow these patterns to ensure visual consistency across the site.

### Design Philosophy

Mawidi uses an **Editorial/Magazine** aesthetic - inspired by high-end publications with:

- Strong typography hierarchy
- Numbered sections for scanability
- Asymmetric layouts
- Light backgrounds with strategic green accents
- Minimal animation (CSS transitions only, no Framer Motion)

### Brand Colors (Definitive)

```css
:root {
  /* Primary Brand Green */
  --mawidi-green: #10b981;
  --mawidi-green-hover: #059669;
  --mawidi-green-light: rgba(16, 185, 129, 0.1);

  /* Ink - For text and headings */
  --mawidi-ink: #1e293b;
  --mawidi-ink-light: #334155;
  --mawidi-ink-dark: #0f172a;

  /* Sand - For backgrounds */
  --mawidi-sand: #fafafa;
  --mawidi-sand-dark: #f5f5f5;

  /* Muted text */
  --mawidi-muted: #64748b;

  /* Borders */
  --mawidi-border: #e2e8f0;
  --mawidi-border-light: rgba(226, 232, 240, 0.5);
}
```

### Typography

```css
:root {
  /* Display/Headings - English */
  --font-display: "Plus Jakarta Sans", system-ui, sans-serif;

  /* Arabic - RTL optimized */
  --font-arabic: "IBM Plex Sans Arabic", "Noto Sans Arabic", sans-serif;

  /* Monospace - For section numbers */
  --font-mono: "JetBrains Mono", "Fira Code", monospace;
}
```

### Section Numbering Pattern (CRITICAL)

Every major section MUST have a numbered header. This is the signature Mawidi pattern:

```tsx
{
  /* Section Header Pattern */
}
<div className="flex items-center gap-4 mb-8">
  <div className="flex items-center gap-3">
    <span className="text-[#10B981] font-mono text-sm tracking-wider">01</span>
    <div className="w-12 h-px bg-[#10B981]" />
  </div>
  <h2 className="text-4xl md:text-5xl font-bold text-[#1E293B]">
    Section Title
  </h2>
</div>;
```

**Compact Variant (for lists/cards):**

```tsx
<div className="flex items-center gap-3">
  <span className="text-[#10B981] font-mono text-xs">01</span>
  <span className="text-[#1E293B] font-medium">Item Title</span>
</div>
```

### Editorial Grid Layout

For feature grids and comparison sections, use thin 1px lines between items:

```tsx
{
  /* Editorial Grid - Creates thin lines between cards */
}
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-px bg-slate-200">
  {items.map((item, idx) => (
    <div key={idx} className="bg-white p-8">
      <div className="flex items-center gap-3 mb-4">
        <span className="text-[#10B981] font-mono text-xs">
          {String(idx + 1).padStart(2, "0")}
        </span>
        <h3 className="font-semibold text-[#1E293B]">{item.title}</h3>
      </div>
      <p className="text-[#64748B]">{item.description}</p>
    </div>
  ))}
</div>;
```

### Hover Animations (CSS Only)

**Expanding Underline:**

```tsx
<div className="group cursor-pointer">
  <h3 className="font-semibold text-[#1E293B]">Title</h3>
  <div className="w-0 group-hover:w-12 h-0.5 bg-[#10B981] mt-2 transition-all duration-300" />
</div>
```

**Button Fill-Up Effect:**

```tsx
<button className="group relative px-8 py-4 bg-[#10B981] text-white overflow-hidden">
  <span className="relative z-10">Get Started</span>
  <div className="absolute inset-0 bg-[#059669] transform translate-y-full group-hover:translate-y-0 transition-transform duration-300" />
</button>
```

**Card Hover with Border:**

```tsx
<div className="group bg-white p-8 border border-transparent hover:border-[#10B981] transition-colors duration-300">
  {/* Card content */}
</div>
```

### Feature Lists - Square Bullets

Use small square bullets instead of checkmark circles:

```tsx
{
  /* Square bullet pattern */
}
<ul className="space-y-3">
  {features.map((feature, idx) => (
    <li key={idx} className="flex items-start gap-3">
      <div className="w-1.5 h-1.5 bg-[#10B981] mt-2 flex-shrink-0" />
      <span className="text-[#64748B]">{feature}</span>
    </li>
  ))}
</ul>;
```

### Background Rules

**NEVER use dark backgrounds** (`bg-[#1E293B]`, `bg-[#0F172A]`, etc.) for main content sections.

**DO use:**

- `bg-white` - Primary content areas
- `bg-[#FAFAFA]` - Alternating sections
- `bg-[#F8FAFC]` - Subtle variation
- `bg-slate-50` - Very light sections

**Exception:** Hero sections can have subtle gradients, but keep them light:

```tsx
<section className="bg-gradient-to-br from-white via-[#FAFAFA] to-[#F0FDF4]">
```

### Complete Page Section Example

```tsx
{
  /* Standard Content Section */
}
<section className="py-24 bg-[#FAFAFA]">
  <div className="max-w-7xl mx-auto px-6">
    {/* Section Header */}
    <div className="flex items-center gap-4 mb-12">
      <div className="flex items-center gap-3">
        <span className="text-[#10B981] font-mono text-sm tracking-wider">
          02
        </span>
        <div className="w-12 h-px bg-[#10B981]" />
      </div>
      <div>
        <h2 className="text-4xl md:text-5xl font-bold text-[#1E293B]">
          {isAr ? "العنوان بالعربي" : "Section Title"}
        </h2>
        <p className="mt-4 text-lg text-[#64748B] max-w-2xl">
          {isAr ? "الوصف بالعربي" : "Section description text"}
        </p>
      </div>
    </div>

    {/* Editorial Grid */}
    <div className="grid grid-cols-1 md:grid-cols-3 gap-px bg-slate-200">
      {items.map((item, idx) => (
        <div
          key={idx}
          className="group bg-white p-8 hover:bg-[#FAFAFA] transition-colors"
        >
          <div className="flex items-center gap-3 mb-4">
            <span className="text-[#10B981] font-mono text-xs">
              {String(idx + 1).padStart(2, "0")}
            </span>
            <h3 className="font-semibold text-[#1E293B]">{item.title}</h3>
          </div>
          <p className="text-[#64748B] mb-6">{item.description}</p>
          <div className="w-0 group-hover:w-12 h-0.5 bg-[#10B981] transition-all duration-300" />
        </div>
      ))}
    </div>
  </div>
</section>;
```

### RTL Support Pattern

```tsx
// Bilingual layout component
interface PageProps {
  lang: "en" | "ar";
}

export default function Page({ lang }: PageProps) {
  const isAr = lang === "ar";

  return (
    <div
      dir={isAr ? "rtl" : "ltr"}
      className={isAr ? "font-arabic" : "font-display"}
    >
      {/* Section numbers stay LTR even in Arabic */}
      <span className="text-[#10B981] font-mono text-sm" dir="ltr">
        01
      </span>

      {/* Content adapts to direction */}
      <h2>{isAr ? "العنوان" : "Title"}</h2>
    </div>
  );
}
```

### Animation Guidelines

- **CSS transitions only** - Do NOT use Framer Motion
- **Duration**: 200-300ms for hover states
- **Easing**: `ease-out` or `ease-in-out`
- **Properties**: `transition-all`, `transition-colors`, `transition-transform`

```css
/* Standard transitions */
.transition-standard {
  transition: all 0.3s ease-out;
}
.transition-fast {
  transition: all 0.2s ease-out;
}

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  * {
    transition: none !important;
  }
}
```

### Logo Assets

Located in `/public/brand/`:

| File                   | Use Case              | Size      |
| ---------------------- | --------------------- | --------- |
| `logo-horizontal.jpeg` | Navigation, headers   | `h-10`    |
| `logo-icon.jpg`        | Favicon, small spaces | `h-8 w-8` |
| `logo-stacked.jpg`     | Hero sections         | `h-24`    |

### Quick Reference Checklist - Editorial Design

Before shipping any page, verify:

- [ ] All sections have numbered headers (01, 02, 03...)
- [ ] Green accent line after section numbers
- [ ] Light backgrounds only (white, #FAFAFA, #F8FAFC)
- [ ] Square bullets for feature lists
- [ ] Hover underline animations on interactive cards
- [ ] Editorial grid layout for multi-column content
- [ ] CSS transitions only (no Framer Motion)
- [ ] Proper RTL support for Arabic
- [ ] Plus Jakarta Sans (EN) / IBM Plex Sans Arabic (AR) fonts

## Examples

### SaaS Landing Page

```tsx
// Distinctive SaaS landing with modern aesthetics
<section className="min-h-screen bg-[#0a0a0f] text-white">
  <div className="absolute inset-0 bg-grid opacity-5" />
  <div
    className="absolute top-0 right-0 w-[500px] h-[500px] 
                  bg-cyan-500/10 rounded-full blur-[100px]"
  />

  <div className="container mx-auto px-6 py-24 relative">
    <motion.h1
      initial={{ opacity: 0, y: 30 }}
      animate={{ opacity: 1, y: 0 }}
      className="font-display text-7xl font-black tracking-tight"
    >
      Build faster.
      <br />
      <span className="text-cyan-400">Ship smarter.</span>
    </motion.h1>
  </div>
</section>
```

### Dashboard Card

```tsx
// Elevated card with atmospheric glow
<div className="relative group">
  <div
    className="absolute -inset-1 bg-gradient-to-r from-cyan-500 to-purple-500 
                  rounded-2xl blur opacity-20 group-hover:opacity-40 transition"
  />
  <div className="relative bg-[#13131a] rounded-xl p-6 border border-white/5">
    <h3 className="font-display text-2xl font-bold">Revenue</h3>
    <p className="text-4xl font-mono text-cyan-400 mt-2">$47,230</p>
  </div>
</div>
```

## Resources

- [Google Fonts](https://fonts.google.com) - Font discovery
- [Coolors](https://coolors.co) - Palette generation
- [UI Colors](https://uicolors.app) - Tailwind palette generator
- [CSS Gradient](https://cssgradient.io) - Gradient builder
- [Framer Motion](https://www.framer.com/motion) - React animations
