css

What this skill does

# CSS

**Predictability is the highest CSS virtue. If your styles require `!important` to work, restructure the cascade.**

CSS rewards explicit, low-specificity selectors and intentional cascade ordering. Prefer boring, readable patterns over
clever one-liners.

## References

- **Layout** — [`${CLAUDE_SKILL_DIR}/references/layout.md`]: Flex shorthand values, grid details (subgrid, implicit
  rows, alignment), layout patterns
- **Modern CSS** — [`${CLAUDE_SKILL_DIR}/references/modern-css.md`]: Extended modern CSS patterns and examples
- **SCSS** — [`${CLAUDE_SKILL_DIR}/references/scss.md`]: `@forward` patterns, module configuration, built-in modules,
  file organization
- **Responsive** — [`${CLAUDE_SKILL_DIR}/references/responsive.md`]: Extended responsive design patterns and examples
- **Methodologies** — [`${CLAUDE_SKILL_DIR}/references/methodologies.md`]: Methodology patterns and architecture details

## Selectors and Specificity

- Single class selectors by default — keep specificity flat at 0-1-0
- Never use ID selectors for styling — IDs are for anchors and JS hooks
- Never qualify classes with elements — `.error` not `div.error`
- Max nesting depth: 3 levels — deeper nesting couples CSS to DOM structure
- Avoid `!important` — use cascade layers or restructure selectors instead; only valid use is in a low-priority reset
  layer for truly essential styles
- Use `:where()` to zero-out specificity when needed — `:where(.card) .title` has 0-0-1 specificity
- Use `:is()` with awareness — it takes the highest specificity of its arguments
- Flatten nested selectors in SCSS — ability to nest does not mean you should

## Layout Systems

### Choosing Flexbox vs Grid

| Use Case                                      | System  |
| --------------------------------------------- | ------- |
| One-dimensional flow (row or column)          | Flexbox |
| Two-dimensional layout (rows AND columns)     | Grid    |
| Content-driven sizing                         | Flexbox |
| Layout-driven sizing                          | Grid    |
| Component internals (nav items, card content) | Flexbox |
| Page-level structure, complex arrangements    | Grid    |
| Items need to wrap naturally                  | Flexbox |
| Precise placement on named lines/areas        | Grid    |

Both work together — a grid item can be a flex container and vice versa.

### Flexbox

- Always use the `flex` shorthand — it sets intelligent defaults. See `${CLAUDE_SKILL_DIR}/references/layout.md` for the
  full shorthand value table
- `flex-flow: row wrap` combines `flex-direction` and `flex-wrap`
- Use `flex-wrap` with a `flex` basis for responsive layouts without media queries: `flex: 1 1 300px` wraps items when
  they can't maintain 300px minimum
- Centering: `display: flex; align-items: center; justify-content: center` or `margin: auto` on a flex child
- `gap` over margin hacks — works in both flexbox and grid
- Avoid `justify-content: space-between` with wrap — causes orphan gaps; prefer `gap` + `flex-wrap`

### CSS Grid

- `repeat(auto-fit, minmax(250px, 1fr))` is the canonical responsive grid — no media queries needed
- Prefer `auto-fit` over `auto-fill` — `auto-fit` expands columns to fill space; `auto-fill` keeps empty tracks
- Use named grid areas for page-level layouts — they auto-create named lines
- Never hardcode `px` widths on grid items — use `fr`, `minmax()`, or `auto`
- `grid-auto-flow: dense` fills visual holes — use carefully, it breaks visual/source order alignment (a11y concern)
- Never use `order` in ways that break logical reading order
- See `${CLAUDE_SKILL_DIR}/references/layout.md` for subgrid, implicit rows, alignment shorthands, and negative line
  numbers

### General Layout Rules

- Never use `float` for layout — floats are for wrapping text around images
- Intrinsic sizing first — use `flex-wrap`, `min()`, `max()`, `clamp()` before reaching for media queries

## CSS Nesting

- Use `&` for pseudo-classes/elements and compound selectors — `&:hover`, `&::before`, `&.active`
- Omit `&` for descendant selectors — `.card { .title {} }` works
- `&` is required when the nested selector starts with a type selector — `& p {}` not `p {}`
- Nesting at-rules (`@media`, `@supports`, `@container`) nest directly inside rules
- Specificity: `:is()` wrapping applies in nesting — be aware that specificity may differ from the equivalent unnested
  selector
- Max depth: 3 levels — same rule as flat CSS

## Cascade Layers (`@layer`)

- Declare all layers at the top of the stylesheet in a single statement:
  `@layer reset, defaults, themes, components, utilities;`
- First declared = lowest priority; un-layered styles always beat layered styles
- `!important` reverses layer order — `!important` in the lowest layer wins over `!important` in higher layers
- Import third-party CSS into sub-layers: `@import url('vendor.css') layer(vendor.bootstrap);`
- Use `revert-layer` to roll back to the previous layer's value
- `!important` in low layers is intentional — it means "this style is essential, don't override"
- Don't create layers per-component — layers manage cascade priority between categories (reset vs component vs utility),
  not scope
- Nested layers: `@layer components { @layer buttons, cards; }` — access via `@layer components.buttons`
- Anonymous layers (`@layer { }`) can't be appended to later

## Container Queries

- Define containment: `container-type: inline-size` on the wrapper
- Name containers for targeting: `container: card / inline-size`
- Query by name: `@container card (width > 400px) { }`
- Unnamed queries hit the nearest ancestor container

### Container Query Units

- `cqw` / `cqh` — 1% of container width / height
- `cqi` / `cqb` — 1% of container inline / block size
- `cqmin` / `cqmax` — smaller / larger of `cqi` or `cqb`

Use `cqi` instead of `vw` for container-scoped fluid values: `font-size: clamp(1rem, 2.5cqi + 0.5rem, 2rem)`

## Responsive Design

### Responsive Hierarchy

Design from the inside out — use the right tool for each level:

- **Content-driven** — Flexbox wrapping, `min()`/`max()`/`clamp()`: always — baseline
- **Container-driven** — Container queries, `cqi`/`cqw` units: component adapts to parent
- **Viewport-driven** — Media queries, `vw`/`vh`/`dvh`: page-level layout changes
- **User preference** — `prefers-*` media queries: color scheme, motion, contrast

### Core Rules

- Mobile-first — default styles for small screens, enhance upward
- Content-driven breakpoints — let content decide, not device sizes
- `rem` for breakpoints: `@media (width >= 45rem)` not `(min-width: 768px)`
- Use modern range syntax: `@media (768px <= width < 1024px)`
- Logical properties for layout: `margin-inline-start` not `margin-left`
- Container queries for component-level adaptation; media queries only for viewport-dependent elements (nav, header)
- Respect user preferences: `prefers-reduced-motion`, `prefers-color-scheme`, `prefers-contrast`
- Single container max-width pattern: `width: min(100% - 2rem, 75rem); margin-inline: auto` — avoid multiple `max-width`
  values at different breakpoints

### Fluid Sizing

- `clamp(min, preferred, max)` for fonts, spacing, and container widths
- Build a fluid type scale with custom properties: `--step-0: clamp(1rem, 0.5rem + 1.5vw, 1.25rem)`
- Never use `vw` alone for font size — it blows up on large screens; always pair with `clamp()` and `rem`
- Use `cqi` instead of `vw` for container-scoped fluid values

### Logical Properties

Use logical properties for layout-sensitive values (margins, padding, borders, text alignment, positioning offsets).
Physical properties are fine for visual effects not affected by writing direction (e.g., box-shadow offsets).

- `left` / `right` → `inline-start` / `inline-end`
- `top` / `bottom` → `block-start` / `block-end`
- `width` / `height` → `inline-size` / `block-size`
- `margin-left` → `margin-inline-start`
- `padding-top` → `padding-block-start`
- `text-align: left` → `text-align: start`

Short