zhongwei/gh-bejranonda-llm-autonomous-agent-plugin-for-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c5931553a6d2a912d65193a92024e9c1a689f60a
gh-bejranonda-llm-autonomou…/skills/frontend-aesthetics/SKILL.md
Zhongwei Li c5931553a6 Initial commit
2025-11-29 18:00:50 +08:00

18 KiB
Raw Blame History

name, description, version
name description version
frontend-aesthetics Distinctive frontend design principles for avoiding generic AI defaults, implementing thoughtful typography/color/animations, and creating polished user experiences based on Claude Code design research 1.0.0

Overview

This skill provides specific design principles and patterns for creating distinctive, polished frontend interfaces that avoid "AI slop" - the generic, obviously-generated aesthetic that results from default AI model choices. Based on official research from "Improving frontend design through Skills" by Anthropic.

Skills Methodology: This follows Anthropic's skills approach - reusable markdown documents that provide altitude-appropriate design guidance without permanent context overhead. Skills make effective design prompts contextual and reusable across projects.

Core Problem: Distributional Convergence: Language models naturally sample from the high-probability center of their training data distribution. This causes them to default to statistically common "safe choices" (Inter fonts, purple gradients, minimal animations, standard grid layouts) because these patterns dominate web design datasets. The result is bland, forgettable interfaces that lack intentional design decisions.

Altitude-Appropriate Guidance: This skill avoids both extremes:

  • Too Specific: Prescribing exact hex codes or pixel values limits creativity
  • Too Vague: Assuming models know design principles leads to generic defaults

Instead, it provides contextual principles with concrete examples that guide toward distinctive choices while preserving flexibility.

The "AI Slop" Problem

What Models Default To (Avoid These)

Generic Fonts:

  • Inter, Roboto, Open Sans, Lato
  • Default system fonts without customization
  • Single font family for everything

Generic Colors:

  • Purple-to-white gradients (#a855f7 → #ffffff)
  • Plain white backgrounds
  • Pastel color schemes without contrast
  • Rainbow gradients

Minimal Visual Interest:

  • No animations or micro-interactions
  • Flat, single-layer backgrounds
  • Standard grid layouts only
  • No depth or texture

Result: Interface that looks "obviously AI-generated" - bland, safe, forgettable

How to Recognize "AI Slop"

Calculate AI Slop Score (0-100, lower is better):

  • +30 points: Using Inter/Roboto/Open Sans fonts
  • +25 points: Purple gradient color scheme
  • +20 points: Plain white background with no depth
  • +15 points: No animations whatsoever
  • +10 points: Standard grid layout only

Score 60+: High AI slop - needs significant design enhancement Score 30-59: Moderate - some generic patterns present Score 0-29: Distinctive - thoughtful design choices evident

Typography Principles

Avoid Generic Font Families

Never Use (Without Strong Justification):

  • Inter
  • Roboto
  • Open Sans
  • Lato
  • Helvetica Neue (as primary)
  • Default system fonts

Distinctive Font Recommendations

Code/Technical Aesthetic:

Primary: JetBrains Mono (headings, code blocks)
Secondary: Space Grotesk (body, UI)
Character: Modern, technical, developer-focused

Editorial/Content:

Primary: Playfair Display (headings, hero)
Secondary: Source Sans 3 (body)
Character: Classic, sophisticated, content-heavy

Technical/Data:

Primary: IBM Plex Sans (all text)
Secondary: IBM Plex Mono (code, data)
Character: Professional, systematic, dashboard-friendly

Friendly/Playful:

Primary: Fredoka (headings)
Secondary: Manrope (body)
Character: Approachable, consumer-facing, warm

Elegant/Premium:

Primary: Crimson Pro (headings)
Secondary: Karla (body)
Character: Sophisticated, refined, premium feel

Font Pairing Principles

High-Contrast Pairings (Recommended): Pair fonts from different categories for maximum distinctiveness:

  • Display + Monospace: Playfair Display + JetBrains Mono
  • Serif + Geometric Sans: Crimson Pro + Space Grotesk
  • Heavy Display + Light Sans: Fredoka (700) + Manrope (300)

Serif + Sans Pairing:

  • Use serif for headings (authority, elegance)
  • Use sans-serif for body (readability)
  • Ensure sufficient contrast in style (not both humanist)
  • Example: Playfair Display + Source Sans 3

Geometric + Humanist:

  • Geometric sans for headings (modern, structured)
  • Humanist sans for body (friendly, readable)
  • Example: Space Grotesk + Source Sans 3 (avoid Inter)

Monospace + Sans:

  • Monospace for code, technical data, or distinctive headings
  • Geometric/humanist sans for regular text
  • Unified family approach when available (IBM Plex, JetBrains)
  • Example: JetBrains Mono + Space Grotesk

Extreme Weight Variations: Create hierarchy through dramatic weight differences:

  • Headings: Use 100-200 (ultra-thin) OR 800-900 (extra-bold)
  • Body: Use 300-400 (light to regular)
  • Avoid: Medium weights (500-600) for headings - not distinctive enough
  • Example: Manrope 200 for hero headings, Manrope 400 for body

Size Jumps (3x+ Ratio): Create clear hierarchy with large size differences:

  • Hero: 4rem (64px)
  • H1: 2.5rem (40px) - not quite 3x but close
  • Body: 1rem (16px) - 4x from hero
  • Avoid: Incremental 1.5x jumps (too subtle)

Variable Fonts (Modern Approach):

  • Single font file with multiple weights/styles
  • Reduces HTTP requests
  • Enables smooth weight transitions in animations
  • Example: Manrope Variable, Inter Variable (if used thoughtfully)

Typography Implementation

/* Fluid Typography with clamp() */
:root {
  --text-xs: clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem);
  --text-sm: clamp(0.875rem, 0.825rem + 0.25vw, 1rem);
  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
  --text-lg: clamp(1.125rem, 1.075rem + 0.25vw, 1.25rem);
  --text-xl: clamp(1.25rem, 1.15rem + 0.5vw, 1.5rem);
  --text-2xl: clamp(1.5rem, 1.35rem + 0.75vw, 2rem);
  --text-3xl: clamp(2rem, 1.75rem + 1.25vw, 3rem);
  --text-4xl: clamp(2.5rem, 2rem + 2.5vw, 4rem);
}

/* Type Scale with Clear Hierarchy */
.heading-1 {
  font-family: 'Playfair Display', serif;
  font-size: var(--text-4xl);
  font-weight: 700;
  line-height: 1.1;
  letter-spacing: -0.02em;
}

.heading-2 {
  font-family: 'Playfair Display', serif;
  font-size: var(--text-3xl);
  font-weight: 600;
  line-height: 1.2;
}

.body {
  font-family: 'Source Sans 3', sans-serif;
  font-size: var(--text-base);
  font-weight: 400;
  line-height: 1.6;
}

Color Theory & Schemes

Avoid Generic Color Schemes

Never Use (Without Intentional Justification):

  • Purple-on-white gradients (AI default)
  • Plain #FFFFFF backgrounds
  • Pastel rainbow without cohesion
  • Generic Material Design colors verbatim

Intentional Color Palette Design

Principle: Choose colors that create a mood and brand identity

Ocean/Tech Professional:

Primary: #0ea5e9 (sky blue)
Accent: #f59e0b (amber)
Background: #0f172a → #1e293b (dark slate gradient)
Text: #f8fafc / #cbd5e1 / #64748b
Mood: Professional, trustworthy, technical

Sunset/Energetic:

Primary: #f97316 (orange)
Accent: #ec4899 (pink)
Background: #fff7ed (light warm) with subtle gradients
Text: #1c1917 / #57534e / #78716c
Mood: Energetic, warm, inviting

Forest/Calm:

Primary: #059669 (emerald)
Accent: #facc15 (yellow)
Background: #f0fdf4 (light green) with layered depth
Text: #14532d / #166534 / #4ade80
Mood: Calm, natural, wellness

Cyberpunk/Bold:

Primary: #06b6d4 (cyan)
Accent: #f0abfc (fuchsia)
Background: #18181b (very dark) with neon glows
Text: #fafafa / #a1a1aa / #52525b
Mood: Modern, bold, tech-forward

Color Application Principles

Dominance Hierarchy:

  • Background: 60% of visual space
  • Primary: 30% of elements
  • Accent: 10% for highlights

Contrast Requirements:

  • Text on background: Minimum 4.5:1 (WCAG AA)
  • Large text: Minimum 3:1 (WCAG AA)
  • Interactive elements: Clear hover/focus states
  • Use tools: WebAIM Contrast Checker

Semantic Color Usage:

Success: Greens (#10b981, #22c55e)
Warning: Yellows/Oranges (#f59e0b, #eab308)
Error: Reds (#ef4444, #dc2626)
Info: Blues (#3b82f6, #0891b2)

Implementation:

:root {
  --color-primary: 14 165 233;  /* RGB values for hsl() */
  --color-accent: 245 158 11;
  --color-bg-base: 15 23 42;
  --color-bg-surface: 30 41 59;
  --color-text-primary: 248 250 252;
}

/* Use with opacity */
.element {
  background-color: hsl(var(--color-primary) / 0.1);  /* 10% opacity */
  color: hsl(var(--color-text-primary));
}

Background Depth & Texture

Avoid Plain Backgrounds

Never Use:

  • Solid white (#FFFFFF) with no variation
  • Single-color backgrounds without depth
  • Generic gradients alone

Layered Background Techniques

1. Subtle Noise Texture:

.background-noise {
  background-image:
    linear-gradient(135deg, hsl(var(--bg-base)) 0%, hsl(var(--bg-surface)) 100%),
    url("data:image/svg+xml,%3Csvg viewBox='0 0 400 400' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)' opacity='0.05'/%3E%3C/svg%3E");
}

2. Geometric Grid Pattern:

.background-grid {
  background-image:
    linear-gradient(90deg, rgba(255,255,255,0.05) 1px, transparent 1px),
    linear-gradient(180deg, rgba(255,255,255,0.05) 1px, transparent 1px);
  background-size: 50px 50px;
}

3. Radial Ambient Glow:

.background-glow {
  background:
    radial-gradient(circle at 20% 50%, rgba(14, 165, 233, 0.15) 0%, transparent 50%),
    radial-gradient(circle at 80% 50%, rgba(245, 158, 11, 0.1) 0%, transparent 50%),
    hsl(var(--bg-base));
}

4. Layered SVG Waves:

.background-waves {
  background:
    linear-gradient(180deg, hsl(var(--primary) / 0.1) 0%, transparent 100%),
    url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1440 320'%3E%3Cpath fill='rgba(255,255,255,0.05)' d='M0,96L48,112C96,128,192,160,288,160C384,160,480,128,576,122.7C672,117,768,139,864,144C960,149,1056,139,1152,128C1248,117,1344,107,1392,101.3L1440,96L1440,320L1392,320C1344,320,1248,320,1152,320C1056,320,960,320,864,320C768,320,672,320,576,320C480,320,384,320,288,320C192,320,96,320,48,320L0,320Z'%3E%3C/path%3E%3C/svg%3E") no-repeat bottom;
}

5. Mesh Gradient (Modern):

.background-mesh {
  background:
    radial-gradient(at 27% 37%, hsla(215, 98%, 61%, 0.3) 0px, transparent 50%),
    radial-gradient(at 97% 21%, hsla(125, 98%, 72%, 0.3) 0px, transparent 50%),
    radial-gradient(at 52% 99%, hsla(354, 98%, 61%, 0.3) 0px, transparent 50%),
    radial-gradient(at 10% 29%, hsla(256, 96%, 67%, 0.3) 0px, transparent 50%),
    radial-gradient(at 97% 96%, hsla(38, 60%, 74%, 0.3) 0px, transparent 50%),
    radial-gradient(at 33% 50%, hsla(222, 67%, 73%, 0.3) 0px, transparent 50%),
    radial-gradient(at 79% 53%, hsla(343, 68%, 79%, 0.3) 0px, transparent 50%);
}

Animation & Motion Design

Principle: High-Impact Moments Over Random Motion

Core Insight: One well-orchestrated page load with staggered reveals is worth more than a dozen random micro-animations scattered across the interface.

Avoid:

  • Random animations everywhere without purpose
  • Slow, drawn-out transitions that delay user interaction
  • No animations at all (static interfaces feel lifeless)
  • Animations that don't respect reduced-motion preferences

Focus On High-Impact Moments:

  • Page Load: Create memorable first impression with orchestrated entrance
  • Major Transitions: Route changes, modal appearances, significant state shifts
  • Content Reveal: Progressive disclosure as user scrolls or interacts
  • Success Moments: Celebrate user achievements with intentional motion
  • Purposeful Micro-Interactions: Hover/click feedback that reinforces UI affordances

Motion Priority:

  1. Page Load Animation (highest impact) - Users see this every time
  2. Major State Changes (high impact) - Crucial for UX comprehension
  3. Micro-Interactions (supporting) - Polish, not primary focus
  4. Decorative Motion (lowest priority) - Use sparingly or omit

Motion Library Selection

Decision Framework:

  • HTML-Only Projects: Always use CSS animations (no dependencies, better performance)
  • React Projects: Use Framer Motion for complex choreography
  • Simple Transitions: CSS is sufficient even in React
  • Complex Orchestration: Motion library provides easier sequencing and stagger control

Page Load Animation

CSS-Only Approach (HTML Projects, Simple React):

@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.page-enter {
  animation: fadeInUp 0.6s cubic-bezier(0.22, 1, 0.36, 1);
}

/* Staggered children */
.stagger > :nth-child(1) { animation-delay: 0.1s; }
.stagger > :nth-child(2) { animation-delay: 0.2s; }
.stagger > :nth-child(3) { animation-delay: 0.3s; }
.stagger > :nth-child(4) { animation-delay: 0.4s; }

React + Framer Motion (For Complex Animations):

import { motion } from 'framer-motion'

export default function Page({ children }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -20 }}
      transition={{ duration: 0.5, ease: [0.22, 1, 0.36, 1] }}
    >
      {children}
    </motion.div>
  )
}

// Staggered list
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((item) => (
    <motion.li key={item.id} variants={item}>
      {item.name}
    </motion.li>
  ))}
</motion.ul>

Micro-Interactions

Button Hover:

.button {
  transition: all 0.3s cubic-bezier(0.22, 1, 0.36, 1);
}

.button:hover {
  transform: translateY(-2px);
  box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.2);
}

.button:active {
  transform: translateY(0);
  transition-duration: 0.1s;
}

Card Hover:

.card {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.card:hover {
  transform: scale(1.02);
  box-shadow: 0 20px 40px -10px rgba(0, 0, 0, 0.15);
}

Link Underline Animation:

.link {
  position: relative;
  text-decoration: none;
}

.link::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  width: 100%;
  height: 2px;
  background: currentColor;
  transform: scaleX(0);
  transform-origin: right;
  transition: transform 0.3s ease;
}

.link:hover::after {
  transform: scaleX(1);
  transform-origin: left;
}

Accessibility: Respect Reduced Motion

Always Include:

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Layout Innovation

Break from Standard Grids

Asymmetric Grid:

.hero-grid {
  display: grid;
  grid-template-columns: 1fr 1.5fr 1fr;
  grid-template-rows: auto auto;
  gap: 2rem;
}

.hero-text {
  grid-column: 1 / 3;
  grid-row: 1;
}

.hero-image {
  grid-column: 2 / 4;
  grid-row: 1 / 3;
  transform: translateY(-2rem);  /* Break alignment */
}

Broken Grid Layout:

.content-grid {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: 1.5rem;
}

.card-1 {
  grid-column: 1 / 6;
  grid-row: 1 / 3;
}

.card-2 {
  grid-column: 6 / 10;
  grid-row: 1 / 2;
  transform: translateY(2rem);  /* Offset for visual interest */
}

.card-3 {
  grid-column: 10 / 13;
  grid-row: 1 / 3;
}

Overlapping Elements:

.overlap-container {
  position: relative;
}

.background-card {
  position: relative;
  z-index: 1;
}

.foreground-element {
  position: absolute;
  top: -2rem;
  left: -2rem;
  z-index: 2;
}

Design Enhancement Checklist

Before considering design complete:

Typography:

  • No generic fonts (Inter, Roboto, Open Sans, Lato)
  • Clear font pairing strategy (serif + sans, mono + sans, etc.)
  • Fluid typography with clamp() or responsive scale
  • Clear hierarchy with size, weight, and spacing

Color:

  • Intentional color palette (not purple-on-white default)
  • Mood/brand identity expressed through colors
  • WCAG AA contrast compliance (4.5:1 minimum)
  • Semantic colors for success/warning/error/info

Background:

  • Layered depth (not plain solid color)
  • Subtle texture or pattern
  • Visual interest without overwhelming content

Animation:

  • Page load/transition animations present
  • Micro-interactions on hover/click
  • Purposeful animations (not random)
  • prefers-reduced-motion respected

Layout:

  • Not just standard grid (visual interest added)
  • Clear visual rhythm and spacing
  • Asymmetry or broken-grid elements where appropriate
  • Responsive across all breakpoints

Overall:

  • AI Slop Score < 30 (distinctive, intentional design)
  • Design feels crafted, not generated
  • Accessibility standards met
  • Performance optimized (animations use transform/opacity)

When to Apply

Use this skill when:

  • Creating new frontend interfaces
  • Enhancing existing designs that look generic
  • Avoiding "AI-generated" aesthetic
  • Implementing distinctive brand identity
  • Designing landing pages, dashboards, or web applications
  • Reviewing designs for visual appeal and distinction
  • Training models to generate better design outputs

This approach ensures frontend designs are distinctive, polished, and intentional - not generic AI defaults.

Reference in New Issue View Git Blame Copy Permalink