frontend-css

What this skill does

<!-- upstream: paulirish/dotfiles - agents/skills/modern-css/SKILL.md -->

# Modern CSS

This skill provides a reference for writing modern, robust, and efficient CSS.

---

## References Library

For deeper coverage of specific topics, consult the files under `references/`:

| File | Topic |
|------|-------|
| `typography.md` | Vertical rhythm, modular scales, font selection, web font loading, fluid type, OpenType features |
| `color-and-contrast.md` | OKLCH color spaces, tinted neutrals, palette structure, WCAG, dark mode, theming |
| `motion-design.md` | Duration rules, easing curves, premium motion materials, reduced motion, perceived performance |
| `heuristics-scoring.md` | Nielsen's 10 heuristics with 0-4 scoring rubric and P0-P3 severity |
| `cognitive-load.md` | Intrinsic/extraneous/germane load, working memory rule, 8 common violations |
| `personas.md` | 5 design-critique archetypes (Alex/Jordan/Sam/Riley/Casey) |
| `css-patterns.md` | Container queries, color manipulation, SASS, BEM, CSS Modules, focus, vendor prefixes, responsive images, plus a **Responsive Design Foundations** section (mobile-first, breakpoints, pointer detection, safe areas) |
| `layout-patterns.md` | Holy Grail, Split, Bento, Editorial Asymmetry, Masonry, Card Grid recipes, plus a **Spatial Design Principles** section (4pt spacing, hierarchy, container queries, optical adjustments) |
| `ui-pattern-guide.md` | Cards/list/table/gallery decisions, navigation, pagination, modals, blank slate, plus an **Interaction Design** section (8 states, focus rings, Popover API, anchor positioning, keyboard nav) |
| `ux-patterns.md` | Onboarding, trust/social proof, persuasion, paywalls, chunking, plus a **UX Writing** section (button labels, error messages, voice/tone, i18n, terminology) |
| `visual-intensity.md` | Amplify (bolder) vs restrain (quieter) on one axis: scale/weight/color/space moves, anti-AI-slop "bold", easing rules |
| `delight-and-microinteractions.md` | Where/when delight is earned, micro-interactions, copy personality, loading-state copy (anti-slop), celebrations, easter eggs, libraries |
| `production-hardening.md` | Edge-case resilience: text overflow, i18n/RTL logical properties, error/empty/loading states, validation, a11y and performance resilience |
| `flow-patterns.md` | User flow recipes |
| `argyle-cacadia-2025-deck.md` | Adam Argyle CSS Wrapped 2025 deck (offline copy) |
| `token-architecture.md` | Three-layer token system (primitive -> semantic -> component), naming convention, file organization, W3C DTCG alignment |
| `primitive-tokens.md` | Layer 1 reference: raw color scales (gray/blue/status), 4px spacing scale, type scale, radius, shadow, motion, z-index |
| `semantic-tokens.md` | Layer 2 reference: purpose-based aliases (background/foreground, primary/secondary/muted/accent/destructive, status, border/ring), dark-mode overrides |
| `component-tokens.md` | Layer 3 reference: component-scoped tokens (button, input, card, badge, alert, dialog, table) referencing the semantic layer |
| `component-specs.md` | Component spec tables (button, input, card, badge, alert, dialog, table) with variants, sizes, states, anatomy |
| `states-and-variants.md` | Interactive states (default/hover/focus/active/disabled/loading), state priority, transitions, focus rings, error states, variant patterns, ARIA |
| `tailwind-integration.md` | CSS variables + Tailwind config recipe, HSL opacity format, component classes, shadcn/ui alignment |

Several references and merged sections are derived from `pbakaus/impeccable` (Apache-2.0) and `nextlevelbuilder/ui-ux-pro-max-skill` (MIT); see attribution headers inside each file.

---

## Layout & Responsive Design

### Container Queries
```css
.card {
  container: --my-card / inline-size;
}

@container --my-card (width < 40ch) {
  /* Component-based responsive design */
}

@container (20ch < width < 50ch) {
  /* Range syntax */
}
```

**Container units:** `cqi`, `cqb`, `cqw`, `cqh` - size relative to container dimensions

**Anchored container queries:** Style an anchored element (and its descendants) based on which `position-try` fallback is currently active
```css
/* Anchored container queries (newest container-type, 2026) */
.tooltip {
  position: absolute;
  position-anchor: --trigger;
  position-try-fallbacks: flip-inline; /* flip side if it overflows */
  container-type: anchored;
}

/* When the inline-flip fallback is in use, flip the caret to match */
@container anchored(fallback: flip-inline) {
  .tooltip__caret { translate: 100%; }
}

.trigger {
  anchor-name: --trigger;
}
```

### Media Query Range Syntax
```css
@media (width <= 1024px) { }
@media (360px < width < 1024px) { }
```


### Grid Enhancements
- **Subgrid:** Inherit parent grid lines for nested layouts
- **Masonry:** Pinterest-style layouts via `display: grid-lanes` (CSS Grid Level 3), which packs items into the shortest lane while keeping logical tab order. This is the resolved syntax (previously proposed as `grid-template-rows: masonry`). Safari 26 ships it; Chrome and Firefox keep it behind a flag, so gate with `@supports` for progressive enhancement.

---

## Color & Theming

### Color Scheme & Light-Dark Function
```css
:root {
  color-scheme: light dark;
  --surface-1: light-dark(white, #222);
  --text-1: light-dark(#222, #fff);
}
```

### Modern Color Spaces
```css
/* OKLCH: uniform brightness, P3+ colors */
.vibrant {
  background: oklch(72% 75% 330);
}

/* Display-P3 for HDR displays */
@media (dynamic-range: high) {
  .neon {
    --neon-red: color(display-p3 1 0 0);
  }
}

/* Better gradients with in oklch */
.gradient {
  background: linear-gradient(
    to right in oklch,
    color(display-p3 1 0 .5),
    color(display-p3 0 1 1)
  );
}
```

### Color Manipulation
```css
/* color-mix() */
.lighten {
  background: color-mix(in oklab, var(--brand), white);
}

/* Relative color syntax */
.lighter {
  background: oklch(from blue calc(l + .25) c h);
  background: oklch(from blue 75% c h); /* Set to specific lightness */
}

.semi-transparent {
  background: oklch(from var(--color) l c h / 50%);
}

.complementary {
  background: hsl(from blue calc(h + 180) s l);
}
```

### Accent Color
```css
:root {
  accent-color: hotpink; /* Tints checkboxes, radios, range inputs */
}
```

---

## Typography

### Text Wrapping
```css
h1 {
  text-wrap: balance; /* Balanced multi-line headings */
  max-inline-size: 25ch;
}

p {
  text-wrap: pretty; /* No orphans */
  max-inline-size: 50ch;
}
```

### Text Box Trim
```css
h1, p, button {
  text-box: trim-both cap alphabetic; /* Optical vertical centering */
}
```

### Fluid Typography
```css
.heading {
  font-size: clamp(1rem, 1rem + 0.5vw, 2rem); /* Respects user preferences */
}
```

### Dynamic Viewport Units
- `dvh` / `dvw` - Dynamic (accounts for mobile browser UI)
- `svh` / `svw` - Small (smallest possible viewport)
- `lvh` / `lvw` - Large (largest possible viewport)

---

## Animations & Motion

### Scroll-Driven Animation
```css
/* Animate on scroll position */
.parallax {
  animation: slide-up linear both;
  animation-timeline: scroll();
}

/* Animate on viewport intersection */
.fade-in {
  animation: fade linear both;
  animation-timeline: view();
  animation-range: cover -75cqi contain 20cqi;
}
```

### View Transitions
**Status:** Baseline Newly Available (Same-document).
Cross-document transitions are in Limited Availability (Chrome/Safari 18.2+).

```css
@view-transition {
  navigation: auto; /* Automatically animate page transitions (MPAs) */
}

nav {
  view-transition-name: --persist-nav; /* Persist specific elements */
  view-transition-class: --site-header; /* Group transitions with classes */
}

/* Style the active transition */
html:active-view-transition {
  overflow: hidden;
}
```

**Nested View Transition Groups:** Preserve 3D transforms and clipping during transitions.

### Advanced Easing with linear()
```css
.springy {
  --spring: linear(
    0, 0.14 4%, 0.94 17%, 1.15 24% 30%, 1.02 43%, 0.98 5