css

# 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` Shorthands: `margin-block: 1rem 2rem` (block-start, block-end); `margin-inline: auto` (both inline directions). ### User Preference Queries - Color scheme: declare `color-scheme: light dark` on `:root` and use `@media (prefers-color-scheme: dark)` for overrides - Reduced motion: either remove motion in `prefers-reduced-motion: reduce` or add motion only in `prefers-reduced-motion: no-preference` (progressive enhancement approach) - High contrast: `@media (prefers-contrast: more)` - Interaction: `@media (hover: hover)` for hover effects on capable devices; `@media (pointer: coarse)` for touch targets (min 44px) ### Responsive Images - `img { max-width: 100%; height: auto; display: block; }` - Use `aspect-ratio` + `object-fit: cover` for hero images ## The `:has()` Selector Select elements based on descendants or siblings — the "parent selector." - Anchor to specific elements, not `body`, `:root`, or `*` — broad anchors force expensive re-evaluation on every DOM change - Use direct child (`>`) or sibling (`+`, `~`) combinators inside `:has()` to limit traversal scope - Cannot nest `:has()` inside `:has()` - Pseudo-elements are not valid inside `:has()` - `.layout:has(> .sidebar-open)` (good) not `body:has(.sidebar-open)` (bad) ## Custom Properties - Define design tokens on `:root` — scope overrides to components - Semantic naming: `--color-text-primary` not `--dark-gray` - Use kebab-case; prefix with category: `--color-`, `--spacing-`, `--font-` - Provide fallbacks for component-level variables: `var(--button-bg, var(--color-primary))` - Custom properties are case-sensitive — `--my-color` differs from `--My-Color` - Custom properties inherit by default (unlike most CSS properties) - Use `@property` for typed, animatable custom properties — enables type checking (invalid values fall back to `initial-value`), controlled inheritance (`inherits: false`), and transitions on custom properties ## View Transitions - `view-transition-name` must be unique per page at transition time - Keep transitions short — 200-400ms for UI, longer for page-level - Always respect `prefers-reduced-motion: reduce` for view transitions - Same-document (SPA): `document.startViewTransition(() => { /* update DOM */ })` - Cross-document (MPA): `@view-transition { navigation: auto; }` - Named transitions target specific elements via `::view-transition-group(name)` ## Box Model and Sizing - Always set `box-sizing: border-box` globally via reset - `rem` for font sizes and breakpoints — respects user preferences - `em` for component-relative spacing (padding that scales with font size) - Fluid sizing with `clamp()` — replace manual breakpoint ladders - `aspect-ratio` over padding hacks for maintaining proportions - No units on zero values — `margin: 0` not `margin: 0px` (except where required: `flex: 0 0 0px`) - Leading zero on decimals: `opacity: 0.5` not `opacity: .5` - Shorthand hex where possible: `#ebc` not `#eebbcc` ## SCSS / Dart Sass ### Module System - `@use` and `@forward` only — `@import` is deprecated (Dart Sass 1.80.0), removed in 3.0.0 - `@use` must appear before any rules except `@forward` - Namespace defaults to the last component of the URL (without extension) - Members are scoped to the loading file — not globally available - Each module loaded exactly once — no duplicate CSS output - Namespace access: `variables.$primary` not global `$primary` - No-namespace `@use 'variables' as *` — use sparingly, only for own files - `math.div()` for division — the `/` operator is deprecated - Prefix private members with `-` or `_` - Prefer mixins over `@extend` — more predictable output; `@extend` produces unexpected selectors and doesn't work across media queries - Max nesting: 3 levels `@forward` re-exports modules, supports prefixing and visibility control. Module configuration uses `!default` variables and `@use ... with ()`. See `${CLAUDE_SKILL_DIR}/references/scss.md` for `@forward` patterns, configuration passthrough, built-in module usage, and file organization conventions. ### Migration Use the official migrator: `sass-migrator module --migrate-deps entrypoint.scss`. For built-in functions only: `sass-migrator module --built-in-only entrypoint.scss`. ## CSS Methodologies ### BEM (Block Element Modifier) - Blocks are standalone components: `.card`, `.nav`, `.form` - Elements are parts of a block (double underscore): `.card__title`, `.card__image` - Modifiers are variations (double hyphen): `.card--featured`, `.card__title--bold` - Never nest elements: `.card__header__title` is wrong — flatten to `.card__title` or create a new block - Modifiers don't exist alone — always pair with base class: `class="card card--featured"` - Use BEM in team projects, large codebases, projects without scoped styles - Skip BEM when using CSS Modules, utility-first CSS, or small projects ### CSS Modules - Use simple, descriptive class names — scoping eliminates conflict risk - One module per component - Compose shared styles: `composes: resetButton from './shared.module.css'` - Global escape hatch: `:global(.utility-class)` when needed - Pair with custom properties for theming (variables aren't scoped) ### Architecture (ITCSS) Organize styles by specificity, low to high: Settings → Tools → Generic → Elements → Objects → Components → Utilities. Maps naturally to cascade layers: `@layer settings, generic, elements, objects, components, utilities;` ## Formatting - 2-space indentation, no tabs - One declaration per line - Semicolon after every declaration including the last - Space after colon: `color: red` not `color:red` - Opening brace on same line as selector - Blank line between rules - Lowercase everything (selectors, properties, values, hex colors) - Single quotes for attribute selectors and font names - Group declarations by category: layout → box model → typography → visual → interaction ## Application When **writing** CSS: - Apply all conventions silently — don't narrate each rule being followed. - Use intrinsic sizing and fluid techniques before media queries. - If an existing codebase contradicts a convention, follow the codebase and flag the divergence once. When **reviewing** CSS: - Cite the specific violation and show the fix inline. - Don't lecture or quote the rule — state what's wrong and how to fix it. ``` Bad review comment: "According to CSS best practices, you should avoid using ID selectors for styling because they have high specificity." Good review comment: "`#header` -> `.header` -- IDs create specificity 1-0-0, difficult to override." ``` ## Integration The coding skill governs workflow; this skill governs CSS implementation choices. For SCSS, this single skill covers both CSS and SCSS conventions.