quartz/.cursor/rules/styling-conventions.mdc

---
globs: *.scss,*.css
description: SCSS styling conventions and theme guidelines for the Plastic Labs blog
---

# SCSS Styling Conventions

## File Organization

### Global Styles
- **Base styles**: [quartz/styles/base.scss](mdc:quartz/styles/base.scss) - Core HTML element styles
- **Variables**: [quartz/styles/variables.scss](mdc:quartz/styles/variables.scss) - CSS custom properties and SCSS variables
- **Custom styles**: [quartz/styles/custom.scss](mdc:quartz/styles/custom.scss) - Site-specific overrides

### Component Styles  
- Component SCSS files live alongside their .tsx files in [quartz/components/styles/](mdc:quartz/components/styles/)
- Name SCSS files to match component names (e.g., `search.scss` for Search component)
- Import component styles in the component's .css property

## Theme System

### Color Variables
Use CSS custom properties defined in the theme configuration:
```scss
.my-element {
  background-color: var(--light);
  color: var(--dark);
  border: 1px solid var(--lightgray);
}
```

### Available Color Variables
- `--light` - Background color
- `--lightgray` - Subtle elements (code, graph edges, outlines)  
- `--gray` - Graph nodes, medium contrast text
- `--darkgray` - High contrast text
- `--dark` - Primary text color
- `--secondary` - Secondary text/UI elements
- `--tertiary` - Accent color (green: #C0FFE1)
- `--highlight` - Selection/hover backgrounds
- `--customCallout` - Custom callout backgrounds

### Typography Variables
```scss
.text-element {
  font-family: var(--headerFont); // Departure Mono
  font-family: var(--bodyFont);   // Roboto Mono  
  font-family: var(--codeFont);   // Ubuntu Mono
}
```

## Responsive Design

### Breakpoints
Use consistent breakpoints across the site:
```scss
// Mobile-first approach
.component {
  // Mobile styles by default
  
  @media (min-width: 600px) {
    // Tablet styles
  }
  
  @media (min-width: 1200px) {
    // Desktop styles
  }
}
```

### Display Classes
Leverage existing responsive classes:
- `.mobile-only` - Hidden on desktop
- `.desktop-only` - Hidden on mobile/tablet

## SCSS Best Practices

### BEM Methodology
Use Block-Element-Modifier naming:
```scss
.search-component {           // Block
  &__input {                  // Element
    border: 1px solid var(--lightgray);
    
    &--focused {              // Modifier  
      border-color: var(--tertiary);
    }
  }
  
  &__results {                // Element
    background: var(--light);
  }
}
```

### Nesting Guidelines
- Limit nesting to 3 levels maximum
- Use parent selectors (&) judiciously
- Prefer flat selectors for better performance

### Variable Usage
```scss
// Local variables for component-specific values
.graph-component {
  $node-size: 8px;
  $link-opacity: 0.6;
  
  .node {
    width: $node-size;
    height: $node-size;
  }
}
```

## Dark/Light Mode Support

### Automatic Theme Switching
Colors automatically switch based on the theme configuration. Always use CSS custom properties:

```scss
// ✅ Good - Uses theme variables
.card {
  background: var(--light);
  border: 1px solid var(--lightgray);
  color: var(--dark);
}

// ❌ Bad - Hard-coded colors
.card {
  background: #E2E2E2;
  border: 1px solid #4e4e4e;
  color: #4E4E4E;
}
```

### Theme-Specific Overrides
When necessary, use the body class for theme-specific styles:
```scss
.special-element {
  // Default styles
  
  :root[data-theme="dark"] & {
    // Dark mode overrides
  }
}
```

## Animation Guidelines

### Subtle Animations
Keep animations minimal and performant:
```scss
.interactive-element {
  transition: all 0.2s ease;
  
  &:hover {
    transform: translateY(-1px);
  }
}
```

### Reduced Motion
Respect user preferences:
```scss
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

## Common Patterns

### Card Components
```scss
.card {
  background: var(--light);
  border: 1px solid var(--lightgray);
  border-radius: 8px;
  padding: 1rem;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
```

### Interactive Elements
```scss
.button {
  background: var(--tertiary);
  color: var(--dark);
  border: none;
  padding: 0.5rem 1rem;
  border-radius: 4px;
  cursor: pointer;
  transition: opacity 0.2s ease;
  
  &:hover {
    opacity: 0.8;
  }
  
  &:focus {
    outline: 2px solid var(--tertiary);
    outline-offset: 2px;
  }
}
```

## Performance Considerations

### Efficient Selectors
- Avoid universal selectors (*) where possible
- Use class selectors over element selectors for components
- Minimize expensive properties (box-shadow, filters, transforms)

### Asset Optimization
- Use relative units (rem, em) for scalability
- Prefer CSS transforms over changing layout properties
- Test performance impact of new styles on slower devices