# CSS Conventions

## Hard Rules

- **Never use inline `style="..."` attributes in HTML.** Always use a class. If no class exists for the need, add it to `styles.css` first, then use it.
- No new colors outside the defined palette — use `styles.css` custom properties only.
- No custom fonts — system `sans-serif` only.

## Modern CSS Features

Use well-supported features (Baseline widely available by 2026). No preprocessors, no build tools.

**Use:**

- Native nesting (`&`) for scoped modifiers and states
- `:has()` for structure-based styling
- `:focus-visible` for keyboard-only focus rings
- `:is()`, `:where()` for selector grouping
- CSS custom properties for design tokens
- `clamp()` for fluid typography and spacing
- `color-mix()` for color variations
- `accent-color` for form control theming
- `text-wrap: balance` for headings
- `aspect-ratio` for media
- `@layer` for cascade control
- Logical properties (`margin-inline`, `padding-block`)
- Dynamic viewport units (`dvh`, `svh`, `lvh`)
- `object-fit` for responsive images

**Avoid (too new or partial support):**

- `@scope`, `anchor-positioning`, `@starting-style`, `scroll-timeline`, `contrast-color()`, `random()`, `@function`, `if()`, `corner-shape`, `text-box-trim`, `field-sizing`

## Naming Conventions

Component + scoped modifier pattern using native nesting:

```css
.pagination {
  display: flex;

  &.center {
    align-self: center;
  }
  &.end {
    align-self: flex-end;
  }
}
```

- Modifiers scoped to component: `.pagination.center`, not `.align-center`
- States nested: `&:focus-visible`, `&:disabled`, `&.active`
- Child elements nested: `& svg`, `& a`
- No BEM (`--`, `__`). No generic utility classes.

## Reset

Global reset on `*, ::backdrop, ::file-selector-button, :after, :before`:

- `border: 0 solid` — no default borders
- `box-sizing: border-box` — predictable sizing
- `margin: 0; padding: 0` — no default spacing
- `font: inherit` — buttons, inputs, selects match body typography

## Base Styles

- `html`: `font-family: sans-serif`, `line-height: 1.5`, `accent-color: #000`
- `body`: `max-width: 1280px`, `margin: 0 auto`, flex column, `2rem` gap, `1rem` padding
- `body.fluid`: full-width modifier — sets `max-width: none` (use for admin/wide-table layouts)
- `main`: flex column, `2rem` gap — use `<main>` to wrap page sections; gives same inter-section spacing as direct body children
- `a`: `color: inherit`, `text-decoration: none`
- `h1`, `h2`: `text-wrap: balance`
- `h1`–`h4` paired with `.h1`–`.h4` utility classes for visual size overrides

## Units

- `rem` for all sizing, spacing, border-radius
- `px` only for borders (`1px`) — sub-pixel borders render inconsistently
- No `em`, no absolute `px` for spacing

## Layout Patterns

- Flex column + `gap` for vertical stacking (sections, forms, cards)
- Flex row + `gap` for horizontal grouping (navs, button groups, pagination)
- No margin-based spacing — use `gap` exclusively
- `flex-wrap: wrap` on nav, chip-group, breadcrumb, button-group
- `overflow-x: auto` on tabs (never wrap)

## Focus & Interaction

- `:focus-visible` instead of `:focus` — no ring on mouse clicks
- `cursor: pointer` on interactive elements
- `opacity: 0.5` + `cursor: not-allowed` for disabled state
- No hover background changes (cursor feedback sufficient for now)

## File Structure

Single `styles.css` file. Section order:

1. Reset
2. Base (html, body, a, headings)
3. Section
4. Header & Footer
5. Inputs
6. Forms
7. Buttons
8. Navigation
9. Cards
10. Pagination
11. Alerts
12. Badges
13. Tables
14. Avatar
15. Divider
16. Lists
17. Blockquote
18. Code
19. Disclosure
20. Empty State
21. Hero

## Table Alignment Utilities

`.text-right` and `.text-center` are scoped inside `.table` — not global utilities. Use on `<th>` and `<td>` for column alignment:

```html
<th class="text-right">Price</th>
<td class="text-center"><input type="checkbox" /></td>
```

## Responsive Tables

Tables are wrapped in `.table-wrapper` with `overflow-x: auto`. Border and border-radius live on the wrapper, not the table. This prevents horizontal page scrolling on mobile.