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:

```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 States

Modern, accessible focus rings:

```scss
.button, .input, .link {
  // Remove default outline
  outline: none;
  
  // Add custom focus ring
  &:focus-visible {
    outline: 2px solid hsl(var(--ring));
    outline-offset: 2px;
  }
}

// For inputs with borders
.input {
  &:focus-visible {
    outline: none;
    border-color: hsl(var(--ring));
    box-shadow: 0 0 0 2px hsl(var(--ring) / 0.2);
  }
}

// For cards and containers
.card {
  &:focus-visible {
    outline: 2px solid hsl(var(--ring));
    outline-offset: 2px;
    border-radius: var(--radius);
  }
}
```

### ❌ Anti-Pattern (Don't Do This)

```scss
// Removing outline without replacement
button {
  outline: none;
}

// Ugly focus states
input:focus {
  border: 2px solid blue;
}
```

---

## Modern Layout Patterns

### Grid Layouts

```scss
// Auto-fit grid
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: var(--spacing-6);
}

// Fixed columns with gap
.two-column {
  display: grid;
  grid-template-columns: 1fr 2fr;
  gap: var(--spacing-8);
}

// Complex grid
.dashboard-layout {
  display: grid;
  grid-template-columns: 250px 1fr;
  grid-template-rows: 60px 1fr;
  gap: var(--spacing-4);
  height: 100vh;
}
```

### Flex Layouts

```scss
// Modern flex with gap (not margin)
.button-group {
  display: flex;
  align-items: center;
  gap: var(--spacing-2);
}

// Flex with proper wrapping
.tag-list {
  display: flex;
  flex-wrap: wrap;
  gap: var(--spacing-2);
}

// Center content
.centered {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
}
```

### ❌ Anti-Pattern (Don't Do This)

```scss
// Using margins instead of gap
.buttons button {
  margin-right: 8px;
  
  &:last-child {
    margin-right: 0;
  }
}

// Floats
.columns {
  float: left;
  width: 50%;
}
```

---

## Component Patterns

### Button

```scss
.button {
  // Base styles
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--spacing-2);
  
  // Typography
  font-size: var(--text-sm);
  font-weight: var(--font-medium);
  line-height: var(--leading-none);
  
  // Spacing
  padding: var(--spacing-2) var(--spacing-4);
  
  // Visual
  border-radius: var(--radius);
  border: 1px solid transparent;
  background-color: hsl(var(--primary));
  color: hsl(var(--primary-foreground));
  box-shadow: var(--shadow-sm);
  
  // Interaction
  cursor: pointer;
  transition: all var(--duration-150) var(--ease-in-out);
  user-select: none;
  
  // States
  &:hover {
    background-color: hsl(var(--primary) / 0.9);
    box-shadow: var(--shadow-md);
  }
  
  &:active {
    transform: translateY(1px);
    box-shadow: var(--shadow-sm);
  }
  
  &:focus-visible {
    outline: 2px solid hsl(var(--ring));
    outline-offset: 2px;
  }
  
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
    pointer-events: none;
  }
  
  // Variants
  &--secondary {
    background-color: hsl(var(--secondary));
    color: hsl(var(--secondary-foreground));
    
    &:hover {
      background-color: hsl(var(--secondary) / 0.8);
    }
  }
  
  &--outline {
    background-color: transparent;
    border-color: hsl(var(--input));
    color: hsl(var(--foreground));
    box-shadow: none;
    
    &:hover {
      background-color: hsl(var(--accent));
      color: hsl(var(--accent-foreground));
    }
  }
  
  &--ghost {
    background-color: transparent;
    box-shadow: none;
    
    &:hover {
      background-color: hsl(var(--accent));
      color: hsl(var(--accent-foreground));
    }
  }
  
  // Sizes
  &--sm {
    padding: var(--spacing-1-5) var(--spacing-3);
    font-size: var(--text-xs);
  }
  
  &--lg {
    padding: var(--spacing-3) var(--spacing-8);
    font-size: var(--text-base);
  }
}
```

### Input

```scss
.input {
  // Base styles
  display: flex;
  width: 100%;
  
  // Typography
  font-size: var(--text-sm);
  line-height: var(--leading-normal);
  
  // Spacing
  padding: var(--spacing-2) var(--spacing-3);
  
  // Visual
  border-radius: var(--radius);
  border: 1px solid hsl(var(--input));
  background-color: hsl(var(--background));
  color: hsl(var(--foreground));
  box-shadow: var(--shadow-sm);
  
  // Interaction
  transition: all var(--duration-150) var(--ease-in-out);
  
  // Placeholder
  &::placeholder {
    color: hsl(var(--muted-foreground));
  }
  
  // States
  &:hover {
    border-color: hsl(var(--input) / 0.8);
  }
  
  &:focus {
    outline: none;
    border-color: hsl(var(--ring));
    box-shadow: 0 0 0 2px hsl(var(--ring) / 0.2);
  }
  
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
    background-color: hsl(var(--muted));
  }
  
  // Error state
  &--error {
    border-color: hsl(var(--destructive));
    
    &:focus {
      border-color: hsl(var(--destructive));
      box-shadow: 0 0 0 2px hsl(var(--destructive) / 0.2);
    }
  }
}
```

### Card

```scss
.card {
  // Base styles
  display: flex;
  flex-direction: column;
  
  // Spacing
  padding: var(--spacing-6);
  gap: var(--spacing-4);
  
  // Visual
  border-radius: calc(var(--radius) + 2px);
  border: 1px solid hsl(var(--border));
  background-color: hsl(var(--card));
  color: hsl(var(--card-foreground));
  box-shadow: var(--shadow-sm);
  
  // Interaction
  transition: box-shadow var(--duration-150) var(--ease-in-out);
  
  &:hover {
    box-shadow: var(--shadow-md);
  }
  
  // Sub-components
  &__header {
    display: flex;
    flex-direction: column;
    gap: var(--spacing-1-5);
  }
  
  &__title {
    font-size: var(--text-2xl);
    font-weight: var(--font-semibold);
    line-height: var(--leading-tight);
    letter-spacing: -0.025em;
  }
  
  &__description {
    font-size: var(--text-sm);
    color: hsl(var(--muted-foreground));
  }
  
  &__content {
    flex: 1;
  }
  
  &__footer {
    display: flex;
    align-items: center;
    gap: var(--spacing-2);
    padding-top: var(--spacing-4);
    border-top: 1px solid hsl(var(--border));
  }
}
```

### Badge

```scss
.badge {
  // Base styles
  display: inline-flex;
  align-items: center;
  
  // Typography
  font-size: var(--text-xs);
  font-weight: var(--font-semibold);
  line-height: var(--leading-none);
  text-transform: uppercase;
  letter-spacing: 0.05em;
  
  // Spacing
  padding: var(--spacing-1) var(--spacing-2-5);
  
  // Visual
  border-radius: calc(var(--radius) - 2px);
  border: 1px solid transparent;
  background-color: hsl(var(--primary));
  color: hsl(var(--primary-foreground));
  
  // Variants
  &--secondary {
    background-color: hsl(var(--secondary));
    color: hsl(var(--secondary-foreground));
  }
  
  &--outline {
    background-color: transparent;
    border-color: hsl(var(--border));
    color: hsl(var(--foreground));
  }
  
  &--destructive {
    background-color: hsl(var(--destructive));
    color: hsl(var(--destructive-foreground));
  }
}
```

---

## Dark Mode Strategy

### CSS Variable Approach

```scss
// Define light mode in :root
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  // ... all other variables
}

// Override for dark mode
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  // ... all other variables
}

// Components automatically adapt
.card {
  background-color: hsl(var(--background));
  color: hsl(var(--foreground));
}
```

### ❌ Anti-Pattern (Don't Do This)

```scss
// Media query approach (harder to control)
.card {
  background: white;
  color: black;
  
  @media (prefers-color-scheme: dark) {
    background: black;
    color: white;
  }
}
```

---

## Border Radius System

```scss
:root {
  --radius-none: 0;
  --radius-sm: 0.125rem;    // 2px
  --radius-base: 0.25rem;   // 4px
  --radius-md: 0.375rem;    // 6px
  --radius-lg: 0.5rem;      // 8px
  --radius-xl: 0.75rem;     // 12px
  --radius-2xl: 1rem;       // 16px
  --radius-3xl: 1.5rem;     // 24px
  --radius-full: 9999px;
  
  // Default radius (customize per theme)
  --radius: var(--radius-lg);
}

// Usage
.button {
  border-radius: var(--radius);
}

.card {
  border-radius: calc(var(--radius) + 2px); // Slightly larger
}

.avatar {
  border-radius: var(--radius-full); // Circle
}
```

---

## Z-Index System

```scss
:root {
  --z-0: 0;
  --z-10: 10;
  --z-20: 20;
  --z-30: 30;
  --z-40: 40;
  --z-50: 50;
  --z-dropdown: 1000;
  --z-sticky: 1100;
  --z-fixed: 1200;
  --z-modal-backdrop: 1300;
  --z-modal: 1400;
  --z-popover: 1500;
  --z-tooltip: 1600;
  --z-toast: 1700;
}

.dropdown {
  z-index: var(--z-dropdown);
}

.modal {
  z-index: var(--z-modal);
}
```

---

## Accessibility Patterns

### Keyboard Navigation

```scss
// Show focus states only for keyboard navigation
.button {
  &:focus {
    outline: none;
  }
  
  &:focus-visible {
    outline: 2px solid hsl(var(--ring));
    outline-offset: 2px;
  }
}
```

### Screen Reader Only

```scss
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}
```

### High Contrast Support

```scss
@media (prefers-contrast: high) {
  .button {
    border-width: 2px;
  }
  
  .input {
    border-width: 2px;
  }
}
```

### Reduced Motion

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

---

## Complete Example: Modern Component

```scss
// Alert Component
.alert {
  // Layout
  display: flex;
  align-items: flex-start;
  gap: var(--spacing-3);
  
  // Spacing
  padding: var(--spacing-4);
  
  // Visual
  border-radius: var(--radius);
  border: 1px solid hsl(var(--border));
  background-color: hsl(var(--background));
  
  // Typography
  font-size: var(--text-sm);
  line-height: var(--leading-relaxed);
  
  // Icon
  &__icon {
    flex-shrink: 0;
    width: 1rem;
    height: 1rem;
    margin-top: 0.125rem;
  }
  
  // Content
  &__content {
    flex: 1;
  }
  
  &__title {
    font-weight: var(--font-medium);
    margin-bottom: var(--spacing-1);
  }
  
  &__description {
    color: hsl(var(--muted-foreground));
  }
  
  // Variants
  &--info {
    border-color: hsl(210 100% 90%);
    background-color: hsl(210 100% 97%);
    
    .alert__icon {
      color: hsl(210 100% 45%);
    }
  }
  
  &--success {
    border-color: hsl(142 76% 85%);
    background-color: hsl(142 76% 96%);
    
    .alert__icon {
      color: hsl(142 76% 36%);
    }
  }
  
  &--warning {
    border-color: hsl(38 92% 85%);
    background-color: hsl(38 92% 95%);
    
    .alert__icon {
      color: hsl(38 92% 50%);
    }
  }
  
  &--error {
    border-color: hsl(0 84% 85%);
    background-color: hsl(0 84% 97%);
    
    .alert__icon {
      color: hsl(0 84% 60%);
    }
  }
}

// Dark mode
.dark {
  .alert {
    &--info {
      border-color: hsl(210 100% 20%);
      background-color: hsl(210 100% 10%);
      
      .alert__icon {
        color: hsl(210 100% 70%);
      }
    }
    
    // ... other variants
  }
}
```

---

## Quality Checklist

Before finalizing any CSS, verify:

- [ ] Using CSS variables for colors
- [ ] HSL color format with opacity support
- [ ] Consistent spacing scale (4px base)
- [ ] Subtle, layered shadows
- [ ] Quick transitions (150ms default)
- [ ] Proper focus-visible states
- [ ] Modern layout (Grid/Flex with gap)
- [ ] Dark mode support
- [ ] Reduced motion support
- [ ] High contrast support
- [ ] Semantic class names (BEM or similar)
- [ ] No hard-coded colors
- [ ] No random pixel values
- [ ] Keyboard accessible
- [ ] Screen reader friendly

---

## Reference Resources

When in doubt, reference these patterns:
1. shadcn/ui components: https://ui.shadcn.com
2. Radix UI primitives: https://www.radix-ui.com
3. Tailwind CSS utilities: https://tailwindcss.com

Remember: **Subtle beats flashy. Consistent beats clever. Accessible beats everything.**