Provide expert guidance on scalable CSS architecture using modern features: cascade layers, container queries, CSS nesting, logical properties, custom properties, and the tradeoffs between CSS modules, CSS-in-JS, and utility-first approaches. Focus on maintainability, specificity control, and progressive enhancement.
Key Patterns
Cascade Layers (@layer)
Layers give explicit control over specificity ordering, regardless of selector specificity or source order:
Why layers matter: Without layers, a .btn class with specificity 0-1-0 can be overridden by any element selector in a later stylesheet. With layers, component styles always beat base styles regardless of specificity.
Container Queries
Style children based on parent size, not viewport:
@scope (.card) to (.card-actions) {
/* Styles only apply inside .card but stop before .card-actions */p {
color: var(--color-text-secondary);
line-height: 1.6;
}
a {
color: var(--color-brand-600);
}
}
Choosing a CSS Strategy
Approach
Best For
Tradeoffs
Tailwind CSS
Rapid development, consistent design
Large class strings, learning curve
CSS Modules
Scoped styles, zero runtime, SSR
No dynamic styles, verbose imports
Vanilla CSS (layers)
Full control, modern features
Manual scoping, larger teams need conventions
CSS-in-JS (Panda/Vanilla Extract)
Type-safe styles, design systems
Build complexity, zero-runtime options limited
Recommendation for most projects: Tailwind CSS + CSS Modules for edge cases (third-party styling, complex selectors).
Best Practices
Use cascade layers — Control specificity explicitly rather than fighting it with !important.
Custom properties for theming — Define tokens as CSS custom properties for runtime theming and dark mode.
Container queries for components — Components should respond to their container, not the viewport.
Logical properties — Use block/inline terminology for RTL/LTR support.
clamp() for fluid design — Replace breakpoint-based font/spacing jumps with smooth scaling.
Minimize nesting depth — Keep CSS nesting to 3 levels max for readability.
Prefer :where() for low-specificity defaults — :where(.btn) has zero specificity, easy to override.
Use :is() for grouping — :is(h1, h2, h3) { ... } instead of repeating selectors.
prefers-reduced-motion — Always provide reduced-motion alternatives for animations.
No !important — If you need it, your layer architecture needs fixing.
Common Pitfalls
Pitfall
Problem
Fix
Specificity wars
!important chains, fragile overrides
Use @layer for explicit ordering
Global styles leaking
Components affected by unrelated styles
CSS Modules, @scope, or Tailwind
Fixed viewport breakpoints
Components break when placed in sidebars
Container queries for component styles
Directional properties
Broken in RTL languages
Logical properties (margin-inline-start)
Overusing nesting
Deep selectors, high specificity
Max 3 levels, use flat class names
Forgetting dark mode
Variables reset unexpectedly
Test both themes, use semantic tokens
calc() units mismatch
calc(100% - 16px) mixed units
Consistent units, test edge cases
Missing fallbacks for new features
Broken in older browsers
@supports queries for progressive enhancement
From css-variables
CSS custom properties for design tokens, theming, dynamic styles, dark mode, and runtime theme switching without JavaScript
CSS Variables Specialist
Purpose
CSS custom properties (variables) are the foundation of modern theming, design token systems, and dynamic styling. Unlike preprocessor variables (Sass/Less), CSS variables are live in the browser — they cascade, inherit, can be scoped to any selector, and can be changed at runtime without JavaScript. This skill covers architecture, theming patterns, performance, and integration with frameworks.
Key Concepts
Custom Properties vs Preprocessor Variables
Feature
CSS Custom Properties
Sass Variables
Runtime changes
Yes (live in DOM)
No (compiled away)
Cascade/inheritance
Yes
No
Scoped to selectors
Yes
Scoped to blocks
Media query responsive
Yes
No
JavaScript access
getComputedStyle / setProperty
Not possible
Fallback values
var(--x, fallback)
Default params
The Variable Cascade
/* Variables cascade and inherit just like any CSS property */:root {
--color-primary: #2563eb; /* Global default */
}
.card {
--color-primary: #7c3aed; /* Scoped override — only .card and children */
}
.card.button {
background: var(--color-primary); /* Gets #7c3aed, not #2563eb */
}
Workflow
Step 1: Define Design Token Layers
Organize variables in semantic layers — primitive tokens feed semantic tokens which feed component tokens:
<!-- Anti-FOUC script — place in <head> before any CSS --><script>
(function() {
var t = localStorage.getItem('theme');
if (t === 'dark' || t === 'light') {
document.documentElement.setAttribute('data-theme', t);
}
})();
</script>
Step 4: Dynamic Values at Runtime
// Read a CSS variable valueconst primaryColor = getComputedStyle(document.documentElement)
.getPropertyValue('--color-primary')
.trim();
// Set a CSS variable dynamicallydocument.documentElement.style.setProperty('--color-primary', '#e11d48');
// Scoped to a specific elementconst card = document.querySelector('.card');
card.style.setProperty('--card-bg', 'linear-gradient(135deg, #667eea, #764ba2)');
/* Use dynamic values from JavaScript for animations */.progress-bar {
width: var(--progress, 0%);
transition: width var(--duration-normal) var(--ease-default);
}
CSS Grid layout patterns — grid templates, auto-placement, subgrid, named areas, and responsive grids.
CSS Grid Layout Patterns
Purpose
Provide expert guidance on CSS Grid layout for building complex, responsive page layouts. Covers grid templates, auto-placement, subgrid, named areas, and intrinsic sizing patterns. Focuses on modern CSS Grid (including subgrid) with Tailwind CSS equivalents.
Use auto-fit with minmax() for responsive grids — Eliminates the need for most media queries in card layouts.
Use min(100%, Xrem) inside minmax() — Prevents items from overflowing on very narrow containers.
Use named grid areas for page layouts — More readable than line-number placement for complex layouts.
Use subgrid for aligned card content — Ensures titles, descriptions, and CTAs align across cards in a row.
Prefer gap over margins — Grid gap only applies between items, not at edges. Simpler than managing margins.
Use dvh for full-height layouts — 100dvh accounts for mobile browser chrome, unlike 100vh.
Combine Grid and Flexbox — Use Grid for 2D layouts, Flexbox for 1D alignment within grid items.
Use fr units, not percentages — fr respects gap automatically; percentages don't.
Set min-width: 0 on grid children when needed — Grid items default to min-width: auto, which can cause overflow with long text.
Test with Grid DevTools — Firefox and Chrome both have Grid overlay inspectors that show tracks and gaps.
Common Pitfalls
Pitfall
Problem
Fix
minmax(200px, 1fr) overflow
On screens < 200px, items overflow
Use minmax(min(100%, 200px), 1fr)
Percentage gaps
Gaps calculated from container, not track
Use rem or px for gap values
auto vs 1fr confusion
auto sizes to content; 1fr shares remaining space
Use 1fr when columns should be equal
Missing min-width: 0
Long words or images overflow grid cells
Add min-width: 0 or overflow: hidden to children
Subgrid without span
Child grid doesn't span enough parent rows
Set grid-row: span N to match subgrid row count
auto-fill when wanting stretch
Items don't fill container width
Use auto-fit to collapse empty tracks
Fixed column count on mobile
Grid doesn't adapt to small screens
Use auto-fit/auto-fill or responsive breakpoints
Forgetting grid-template-rows
Only columns defined, rows auto-sized unexpectedly
Define explicit row templates for complex layouts
From dark-mode
Dark mode implementation with CSS custom properties, prefers-color-scheme, Tailwind dark variant, theme persistence in localStorage, class vs media strategy, and smooth transitions
Dark Mode Skill
Purpose
Implement a flicker-free, accessible dark mode that respects user system preferences, persists choice across sessions, and transitions smoothly between themes.
Inject an inline <script> in <head> before the body renders. This prevents a white flash
when a dark-mode user loads the page. Use React's dangerouslySetInnerHTML on a <script> tag
inside app/layout.tsx:
// Inline script content (runs before paint):
(function() {
try {
var t = localStorage.getItem("theme");
if (t === "dark" || (t !== "light" && matchMedia("(prefers-color-scheme:dark)").matches)) {
document.documentElement.classList.add("dark");
}
} catch(e) {}
})()
Add suppressHydrationWarning on the <html> element to avoid React hydration mismatches
caused by the class being added before hydration.
{/* Tailwind dark: prefix applies when .dark class is on <html> */}
<div className="bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-50">
<pclassName="text-gray-600 dark:text-gray-400">Adapts to theme</p>
</div>
Best Practices
Inline the anti-flash script: Must run before first paint. Never load it as an external file.
Use suppressHydrationWarning: On <html> to prevent React hydration mismatch from the class.
Respect system preference: Default to system, then allow manual override.
Use HSL tokens: Store colors as HSL channels so opacity modifiers work: bg-background/50.
Test both modes: Every page, every component. Dark mode is not an afterthought.
Accessible contrast: Verify WCAG AA (4.5:1 text, 3:1 UI) in both themes.
Common Pitfalls
Pitfall
Fix
White flash on dark-mode page load
Add inline script to <head> before body renders
Hydration mismatch warning
Add suppressHydrationWarning to <html>
Images look wrong in dark mode
Use dark:invert or provide dark variants
Hardcoded colors ignore theme
Use CSS variables or Tailwind dark: prefix everywhere
Transition flicker on first load
Only add transition class during intentional toggles
From responsive-design
Responsive design — fluid typography, container queries, aspect ratios, mobile-first CSS, clamp(), modern layout patterns, and accessibility across viewports
Responsive Design Skill
Purpose
Responsive design ensures interfaces work across all viewport sizes. Modern CSS provides powerful tools (clamp, container queries, fluid grids) that replace brittle breakpoint-only approaches. This skill covers fluid typography, container queries, modern layout patterns, responsive images, and mobile-first architecture.
/* Cards automatically wrap based on available space */.auto-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
gap: var(--space-md);
}
/* min(100%, 18rem) prevents overflow on small screens */
Sidebar Layout (Responsive Without Media Query)
.sidebar-layout {
display: grid;
grid-template-columns: fit-content(20rem) minmax(0, 1fr);
gap: var(--space-lg);
}
/* On narrow viewports, stack with a media query */@media (max-width: 48rem) {
.sidebar-layout {
grid-template-columns: 1fr;
}
}
Holy Grail Layout
.page {
display: grid;
grid-template-rows: auto 1fr auto;
min-height: 100dvh; /* dvh = dynamic viewport height (accounts for mobile browser chrome) */
}
.page-content {
display: grid;
grid-template-columns: minmax(0, 1fr);
width: min(100% - 2rem, 75rem); /* Max-width with padding, no media query */margin-inline: auto;
}
Flexible Spacing with margin-inline: auto
/* Content wrapper that centers and constrains width */.content-wrapper {
width: min(100% - var(--space-md) * 2, 75rem);
margin-inline: auto;
}
/* This single rule replaces: max-width + padding-left + padding-right + margin auto */
Step 4: Responsive Images
<!-- srcset + sizes: browser picks the best image --><imgsrc="/images/hero-800.jpg"srcset="
/images/hero-400.jpg 400w,
/images/hero-800.jpg 800w,
/images/hero-1200.jpg 1200w,
/images/hero-1600.jpg 1600w
"sizes="(max-width: 640px) 100vw, (max-width: 1024px) 80vw, 1200px"alt="Hero image"loading="lazy"decoding="async"fetchpriority="high"
/><!-- <picture> for art direction (different crops per viewport) --><picture><sourcemedia="(max-width: 640px)"srcset="/images/hero-mobile.jpg" /><sourcemedia="(max-width: 1024px)"srcset="/images/hero-tablet.jpg" /><imgsrc="/images/hero-desktop.jpg"alt="Hero image" /></picture>
/* Modern viewport units account for mobile browser chrome (address bar, toolbar) */.full-height {
height: 100dvh; /* dvh = dynamic viewport height (changes as chrome shows/hides) */
}
.hero-section {
min-height: 100svh; /* svh = small viewport height (chrome visible — safe minimum) */
}
.modal-overlay {
height: 100lvh; /* lvh = large viewport height (chrome hidden — maximum) */
}
/*
dvh: Changes dynamically as mobile browser chrome appears/disappears
svh: Smallest possible viewport (when address bar is showing)
lvh: Largest possible viewport (when address bar is hidden)
For most cases, use dvh. For hero sections, use svh (prevents content jump).
*/
Step 7: Responsive Text Truncation
/* Single line truncation */.truncate {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
/* Multi-line truncation (works in all modern browsers) */.line-clamp-2 {
display: -webkit-box;
-webkit-line-clamp: 2;
-webkit-box-orient: vertical;
overflow: hidden;
}
.line-clamp-3 {
display: -webkit-box;
-webkit-line-clamp: 3;
-webkit-box-orient: vertical;
overflow: hidden;
}
Step 8: Touch Target Sizing
/* WCAG 2.2 requires 24x24px minimum, recommends 44x44px */.touch-target {
min-height: 2.75rem; /* 44px — Apple HIG recommendation */min-width: 2.75rem;
padding: 0.75rem1rem;
}
/* Invisible touch area expansion */.icon-button {
position: relative;
width: 1.5rem;
height: 1.5rem;
}
.icon-button::before {
content: '';
position: absolute;
inset: -0.5rem; /* Expand touch area by 8px in each direction */
}
Common Pitfalls
Using px for breakpoints and font sizes — Use rem. Users who increase their browser's base font size get properly scaled text and breakpoints.
Forgetting min-width: 0 in flex/grid children — Flex and grid children have an implicit min-width: auto, causing overflow. Add min-width: 0 or overflow: hidden to prevent horizontal scroll.
Using 100vh on mobile — The address bar causes 100vh to be taller than the visible viewport. Use 100dvh or 100svh instead.
Media queries only — Over-relying on breakpoints instead of intrinsic sizing (min(), clamp(), auto-fit). Modern CSS can handle most responsive behavior without breakpoints.
Not testing with real content — Designs that work with "Lorem ipsum" break with real variable-length content. Test with short and long content.
Ignoring landscape orientation — Mobile landscape creates a wide, short viewport. Test with @media (orientation: landscape) and (max-height: 500px).
Fixed-width elements — Any width: 500px without max-width: 100% will overflow on mobile. Always use relative or constrained widths.
Provide expert guidance on frontend animation implementation using Framer Motion, CSS animations, GSAP, and native scroll-driven animations. Focus on performant, accessible motion that enhances user experience without degrading performance or excluding users who prefer reduced motion.
Core Principles
Purpose over decoration — Every animation should serve a purpose: guide attention, provide feedback, show relationships, or smooth transitions.
60fps or nothing — Animate only transform and opacity for GPU-accelerated performance. Avoid animating width, height, top, left, margin, or padding.
Respect user preferences — Always implement prefers-reduced-motion alternatives.
Duration guidelines — Micro-interactions: 100-200ms. Transitions: 200-400ms. Complex sequences: 400-800ms. Never exceed 1s for UI animations.
Production-ready animation library for React. Declarative API with spring physics, layout animations, gesture support, and scroll-driven effects. Pairs with React's component model for composable, performant motion.
When to Use
Adding enter/exit/layout transitions to React components
Use motion.div, motion.span, etc. — drop-in replacements that accept animation props.
Animate Prop & Variants
Define initial, animate, and exit states inline or via named variants for reuse across children.
AnimatePresence
Wrap conditional elements to animate mount/unmount. Use mode="wait" for sequential transitions and always provide a unique key.
Layout Animations
Add layout prop for automatic size/position transitions. Use layoutId for shared-element animations across components.
Gesture Animations
whileHover, whileTap, whileFocus, whileDrag — declarative gesture states. Combine drag with dragConstraints and dragElastic.
Scroll-Triggered Animations
useScroll() returns scrollYProgress. Pair with useTransform or useMotionValueEvent to drive animations from scroll position.
Spring Physics
Default transition uses springs. Tune with type: "spring", stiffness, damping, mass. Use type: "tween" with duration for linear/eased motion.
Stagger Children
In parent variants, set transition: { staggerChildren: 0.05 }. Children inherit variant names and animate in sequence.
useAnimate (Imperative)
const [scope, animate] = useAnimate() — run sequenced or conditional animations outside the declarative model. Useful for complex orchestration.
Anti-Patterns
Animating layout-triggering properties (width, height) without layout prop — causes jank; use layout or transform-based animations instead.
Missing key on AnimatePresence children — exit animations silently break.
Over-stiff springs — stiffness > 500 without proportional damping causes oscillation. Test with damping: 2 * Math.sqrt(stiffness) for critical damping.
Animating unmeasured elements — layout requires the element to be in the DOM before measuring; avoid combining with display: none.
Ignoring prefers-reduced-motion — wrap animations with useReducedMotion() and provide static fallbacks.
Re-creating variants on every render — define variants outside the component or memoize them.
Provide expert guidance on CSS animations using Tailwind CSS and the tailwindcss-animate plugin, including enter/exit animations, looping animations, staggered sequences, and accessibility-compliant motion patterns.
The plugin provides animate-in and animate-out base classes combined with directional modifiers:
// Fade in
<div className="animate-in fade-in duration-200">
Fadesin
</div>
// Slide in from bottom with fade<divclassName="animate-in fade-in slide-in-from-bottom-4 duration-300">
Slides up and fades in
</div>// Slide in from left<divclassName="animate-in fade-in slide-in-from-left-8 duration-300">
Slides from left
</div>// Scale in (zoom)<divclassName="animate-in fade-in zoom-in-95 duration-200">
Scales up from 95% with fade
</div>// Exit animations<divclassName="animate-out fade-out slide-out-to-bottom-4 duration-200">
Slides down and fades out
</div>// Spin out<divclassName="animate-out fade-out spin-out-180 duration-300">
Spins and fades out
</div>// Combine with fill-mode to persist end state<divclassName="animate-in fade-in duration-300 fill-mode-forwards">
Stays visible after animation
</div>
