# CSS maintenance guide

This project currently ships two main CSS files.

## Load order

1. `style.css`
2. `floating-player.css`

`floating-player.css` is loaded later, so it wins the cascade when selectors have
similar specificity.

## File ownership

### `style.css`

Use this file for:

- Base design tokens in `:root`
- Global layout
- Sidebar and top bar base rules
- Common buttons, tables, forms, cards, alerts, modals
- Page-level sections that are not late responsive fixes

### `floating-player.css`

Use this file for:

- Floating mini player
- Fullscreen player
- Tablet app-shell layout
- Mobile/tablet final responsive guards
- Late bug-fix guards that must override older rules

## Fullscreen player rules

The fullscreen player has older compatibility blocks near the end of
`floating-player.css`.

Edit order:

1. Prefer section `67.0 fullscreen player structural guard`
2. Adjust the variables at the start of `67.0`
3. Avoid adding another broad final override unless the existing section cannot
   safely express the fix

Do not move the player DOM into page content. The player must stay outside PJAX
content replacement.

## Selector rules

Prefer scoped selectors:

- `.page-name ...`
- `body.is-tablet-layout ...`
- `body.is-mobile-layout ...`
- `.expand-player-overlay ...`

Avoid new global selectors with `!important` unless they are a deliberate final
guard and have a named section comment.

## Responsive rules

Use these ranges consistently:

- Mobile: `max-width: 767px`
- Tablet portrait/general: `768px` to `1023px`
- Tablet landscape candidate: `1024px` to `1199px`
- Desktop: `1200px` and up

Use `dvh` for fullscreen player height where possible, and keep `env()` /
safe-area handling on mobile and PWA surfaces.

## Quick sanity check

Run these from the project root after editing CSS:

```powershell
$files = 'assets\css\style.css','assets\css\floating-player.css'
foreach ($p in $files) {
    $text = Get-Content -LiteralPath $p -Raw
    $open = ($text.ToCharArray() | Where-Object { $_ -eq '{' }).Count
    $close = ($text.ToCharArray() | Where-Object { $_ -eq '}' }).Count
    $commentOpen = ([regex]::Matches($text, '/\*')).Count
    $commentClose = ([regex]::Matches($text, '\*/')).Count
    "$p braces $open/$close comments $commentOpen/$commentClose"
}
```

The two numbers in each pair should match.
