shadcn-aesthetic

Modern CSS Architecture (shadcn Aesthetic)

This skill provides comprehensive guidance for writing modern, refined CSS/SCSS that matches the shadcn/ui aesthetic - clean, minimal, accessible, and beautifully crafted.

When This Skill Activates

Apply these patterns when:

• Writing any CSS, SCSS, or styling code
• Creating component styles from scratch
• Refactoring existing styles
• Building design systems or theme systems
• Working on Blazor, React, Vue, or any web UI

Core Principles

1. Use CSS variables for everything themeable
2. HSL color system for easy manipulation
3. Consistent spacing scale (4px base)
4. Subtle, layered shadows
5. Quick, smooth transitions (150ms)
6. Proper focus states
7. Modern layout primitives (Grid/Flex with gap)
8. Dark mode first-class citizen

Color System

Variable Structure

Always use HSL-based CSS variables for colors:

:root {
  // Background colors
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  
  // Card colors
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  
  // Popover colors
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  
  // Primary brand colors
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  
  // Secondary colors
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  
  // Muted colors
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  
  // Accent colors
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  
  // Destructive/error colors
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  
  // Border and input
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  
  // Border radius
  --radius: 0.5rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  
  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;
  
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
  
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 98%;
  
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  
  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 210 40% 98%;
  
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 212.7 26.8% 83.9%;
}

Usage

// Always use hsl() with var()
.component {
  background-color: hsl(var(--primary));
  color: hsl(var(--primary-foreground));
  
  // With opacity
  border: 1px solid hsl(var(--border) / 0.5);
  
  &:hover {
    background-color: hsl(var(--primary) / 0.9);
  }
}

❌ Anti-Pattern (Don't Do This)

// Hard-coded hex colors
.button {
  background: #007bff;
  color: #ffffff;
}

// RGB without variables
.card {
  background: rgb(255, 255, 255);
  border: 1px solid rgba(0, 0, 0, 0.1);
}

Spacing Scale

Use a consistent spacing scale based on 4px increments:

:root {
  --spacing-0: 0;
  --spacing-px: 1px;
  --spacing-0-5: 0.125rem;  // 2px
  --spacing-1: 0.25rem;     // 4px
  --spacing-1-5: 0.375rem;  // 6px
  --spacing-2: 0.5rem;      // 8px
  --spacing-2-5: 0.625rem;  // 10px
  --spacing-3: 0.75rem;     // 12px
  --spacing-3-5: 0.875rem;  // 14px
  --spacing-4: 1rem;        // 16px
  --spacing-5: 1.25rem;     // 20px
  --spacing-6: 1.5rem;      // 24px
  --spacing-7: 1.75rem;     // 28px
  --spacing-8: 2rem;        // 32px
  --spacing-9: 2.25rem;     // 36px
  --spacing-10: 2.5rem;     // 40px
  --spacing-11: 2.75rem;    // 44px
  --spacing-12: 3rem;       // 48px
  --spacing-14: 3.5rem;     // 56px
  --spacing-16: 4rem;       // 64px
  --spacing-20: 5rem;       // 80px
  --spacing-24: 6rem;       // 96px
  --spacing-32: 8rem;       // 128px
}

Usage

.button {
  padding: var(--spacing-2) var(--spacing-4);  // 8px 16px
  gap: var(--spacing-2);                       // 8px
}

.card {
  padding: var(--spacing-6);    // 24px
  margin-bottom: var(--spacing-4); // 16px
}

❌ Anti-Pattern (Don't Do This)

// Random pixel values
.button {
  padding: 10px 22px;
  margin: 13px;
}

// Inconsistent spacing
.card {
  padding: 15px;
  margin-bottom: 18px;
}

Shadow System

Use subtle, layered shadows for depth:

:root {
  // Subtle shadows
  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-base: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
  --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
  
  // Inner shadow
  --shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
}

Usage

.card {
  box-shadow: var(--shadow-sm);
  
  &:hover {
    box-shadow: var(--shadow-md);
  }
}

.dropdown {
  box-shadow: var(--shadow-lg);
}

.input {
  box-shadow: var(--shadow-sm);
  
  &:focus {
    box-shadow: var(--shadow-sm), 0 0 0 2px hsl(var(--ring) / 0.2);
  }
}

❌ Anti-Pattern (Don't Do This)

// Heavy, dated shadows
.card {
  box-shadow: 0 5px 15px rgba(0, 0, 0, 0.3);
}

// Single-layer shadows
.button {
  box-shadow: 2px 2px 5px #999;
}

Typography Scale

Use a harmonious type scale:

:root {
  // Font sizes
  --text-xs: 0.75rem;      // 12px
  --text-sm: 0.875rem;     // 14px
  --text-base: 1rem;       // 16px
  --text-lg: 1.125rem;     // 18px
  --text-xl: 1.25rem;      // 20px
  --text-2xl: 1.5rem;      // 24px
  --text-3xl: 1.875rem;    // 30px
  --text-4xl: 2.25rem;     // 36px
  --text-5xl: 3rem;        // 48px
  
  // Line heights
  --leading-none: 1;
  --leading-tight: 1.25;
  --leading-snug: 1.375;
  --leading-normal: 1.5;
  --leading-relaxed: 1.625;
  --leading-loose: 2;
  
  // Font weights
  --font-thin: 100;
  --font-light: 300;
  --font-normal: 400;
  --font-medium: 500;
  --font-semibold: 600;
  --font-bold: 700;
  --font-extrabold: 800;
  
  // Font families
  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Consolas, "Liberation Mono", Menlo, monospace;
}

Usage

.heading {
  font-size: var(--text-2xl);
  font-weight: var(--font-semibold);
  line-height: var(--leading-tight);
  letter-spacing: -0.025em;
}

.body-text {
  font-size: var(--text-base);
  line-height: var(--leading-relaxed);
}

.small-text {
  font-size: var(--text-sm);
  color: hsl(var(--muted-foreground));
}

❌ Anti-Pattern (Don't Do This)

// Random font sizes
h1 { font-size: 28px; }
h2 { font-size: 22px; }
p { font-size: 15px; }

// Hard-coded weights
.title { font-weight: 600; }

Transitions & Animations

Use quick, smooth transitions:

:root {
  // Timing functions
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  
  // Durations
  --duration-75: 75ms;
  --duration-100: 100ms;
  --duration-150: 150ms;
  --duration-200: 200ms;
  --duration-300: 300ms;
  --duration-500: 500ms;
}

Usage

.button {
  transition: all var(--duration-150) var(--ease-in-out);
  
  &:hover {
    transform: translateY(-1px);
  }
  
  &:active {
    transform: translateY(0);
  }
}

// For specific properties
.dropdown {
  transition-property: opacity, transform;
  transition-duration: var(--duration-150);
  transition-timing-function: var(--ease-out);
}

❌ Anti-Pattern (Don't Do This)

// Slow, dated transitions
.button {
  transition: all 0.3s ease;
}

// Transitioning too many properties
.card {
  transition: all 0.5s;
}

Focus