---
description: 'Instructions for writing CSS following project conventions and best practices'
applyTo: '**/*.css,**/*.vue'
---

# CSS Development Instructions

## Cascading Design & Style Hierarchy

**Central styles in `src/assets/main.css` are ALWAYS the preferred way to style.** They ensure a consistent design across all views and components.

### Cascade Layers (top to bottom)
1. **`src/assets/base.css`** — CSS variables, resets, root typography and color tokens
2. **`src/assets/main.css`** — Global layout, nav, buttons, modals, forms, loading states, typography, spacing — **all shared UI patterns go here**
3. **`<style scoped>` in `.vue` files** — Only for component-specific layout overrides that have no equivalent in `main.css`

### Rule: Central vs. Scoped CSS
- **Use `main.css`** for: buttons, modals, forms, inputs, nav, loading spinners, typography, color tokens, flex layout utilities — anything reused in 2+ places
- **Use `<style scoped>`** only when a style is truly unique to one component and cannot be expressed by an existing global class
- **Never** duplicate a style from `main.css` in a scoped block

## Key CSS Techniques

- **Flexbox** for all layouts — use `gap` instead of margins between flex children
- **CSS custom properties** (variables) from `base.css` — always reference via `var(--token-name)`
- **Transitions** (`transition: all 0.2s ease`) on all interactive elements
- **`@media` queries** in `main.css` for responsive breakpoints (mobile-first)
- **`z-index` layers** defined centrally: modals `1000`, dropdowns `100`, tooltips `200`

## Style Conventions

- Class selectors only — no IDs, no inline styles, no `!important`
- `rem`/`em` for font sizes; `px` only for borders and fixed-size icons
- Max 3 levels of selector nesting
- Always include `:hover`, `:focus`, `:disabled` states for interactive elements
- `box-sizing: border-box` set globally — do not override

## Anti-Patterns

❌ Don't add a scoped style that duplicates a `main.css` rule  
❌ Don't use inline styles in Vue templates  
❌ Don't use `!important`  
❌ Don't use IDs as CSS selectors  
❌ Don't use floats or `position: absolute` for layout — use flexbox  
❌ Don't add vendor prefixes manually — autoprefixer handles this