shadcn-aesthetic

What this skill does

# 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:

```scss
: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

```scss
// 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)

```scss
// 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:

```scss
: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

```scss
.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)

```scss
// 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:

```scss
: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

```scss
.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)

```scss
// 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:

```scss
: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

```scss
.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)

```scss
// 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:

```scss
: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

```scss
.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)

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

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

---

## Focus