# Modern CSS Implementation Guide

## Overview
This document provides comprehensive implementation guidelines for modern CSS techniques in the ThrillWiki frontend redesign, including CSS Grid, Flexbox, custom properties, and advanced CSS features for optimal performance and maintainability.

## CSS Architecture

### Layer-Based Organization
```css
/* CSS Cascade Layers for better control */
@layer reset, tokens, base, components, utilities, overrides;

@layer reset {
  /* Modern CSS Reset */
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }
  
  * {
    margin: 0;
  }
  
  body {
    line-height: 1.5;
    -webkit-font-smoothing: antialiased;
  }
  
  img,
  picture,
  video,
  canvas,
  svg {
    display: block;
    max-width: 100%;
  }
  
  input,
  button,
  textarea,
  select {
    font: inherit;
  }
  
  p,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    overflow-wrap: break-word;
  }
  
  #root,
  #__next {
    isolation: isolate;
  }
}

@layer tokens {
  /* Design tokens from design-tokens.md */
  :root {
    /* Import all design tokens here */
  }
}

@layer base {
  /* Base element styles */
  html {
    scroll-behavior: smooth;
  }
  
  @media (prefers-reduced-motion: reduce) {
    html {
      scroll-behavior: auto;
    }
  }
  
  body {
    font-family: var(--font-family-base);
    font-size: var(--text-base);
    line-height: var(--leading-normal);
    color: var(--text-primary);
    background-color: var(--bg-primary);
    transition: background-color var(--transition-base), color var(--transition-base);
  }
}

@layer components {
  /* Component styles */
}

@layer utilities {
  /* Utility classes */
}

@layer overrides {
  /* Framework overrides and specificity fixes */
}
```

## CSS Custom Properties Implementation

### Dynamic Theme System
```css
:root {
  /* Light theme (default) */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #3b82f6;
  --color-primary-900: #1e3a8a;
  
  /* Semantic color mappings */
  --bg-primary: var(--color-neutral-50);
  --bg-secondary: var(--color-neutral-100);
  --text-primary: var(--color-neutral-900);
  --text-secondary: var(--color-neutral-600);
}

[data-theme="dark"] {
  /* Dark theme overrides */
  --bg-primary: var(--color-neutral-900);
  --bg-secondary: var(--color-neutral-800);
  --text-primary: var(--color-neutral-50);
  --text-secondary: var(--color-neutral-300);
}

/* System preference detection */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --bg-primary: var(--color-neutral-900);
    --bg-secondary: var(--color-neutral-800);
    --text-primary: var(--color-neutral-50);
    --text-secondary: var(--color-neutral-300);
  }
}
```

### Contextual Custom Properties
```css
/* Component-scoped custom properties */
.card {
  --card-padding: var(--spacing-component-lg);
  --card-radius: var(--radius-lg);
  --card-shadow: var(--shadow-md);
  
  padding: var(--card-padding);
  border-radius: var(--card-radius);
  box-shadow: var(--card-shadow);
  background: var(--bg-elevated);
}

.card--compact {
  --card-padding: var(--spacing-component-md);
  --card-radius: var(--radius-md);
  --card-shadow: var(--shadow-sm);
}

.card--featured {
  --card-padding: var(--spacing-component-xl);
  --card-shadow: var(--shadow-lg);
}
```

## CSS Grid Implementation

### Advanced Grid Patterns
```css
/* Intrinsic Web Design Grid */
.auto-grid {
  --min-column-width: 250px;
  --grid-gap: var(--spacing-layout-md);
  
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(var(--min-column-width), 100%), 1fr));
  gap: var(--grid-gap);
}

/* Named Grid Lines */
.page-grid {
  display: grid;
  grid-template-columns: 
    [full-start] minmax(var(--spacing-layout-md), 1fr)
    [content-start] min(65ch, calc(100% - 2 * var(--spacing-layout-md)))
    [content-end] minmax(var(--spacing-layout-md), 1fr)
    [full-end];
  grid-template-rows: auto 1fr auto;
}

.page-header {
  grid-column: full;
  background: var(--bg-elevated);
}

.page-content {
  grid-column: content;
}

.page-footer {
  grid-column: full;
  background: var(--bg-secondary);
}

/* Subgrid Implementation (when supported) */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: var(--spacing-layout-md);
}

.card {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 3;
}

/* Fallback for browsers without subgrid */
@supports not (grid-template-rows: subgrid) {
  .card {
    display: flex;
    flex-direction: column;
  }
  
  .card-content {
    flex: 1;
  }
}
```

### Grid Areas and Template Areas
```css
/* Complex Layout with Grid Areas */
.dashboard {
  display: grid;
  grid-template-areas:
    "header header header"
    "sidebar main aside"
    "footer footer footer";
  grid-template-columns: 250px 1fr 300px;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
  gap: var(--spacing-layout-md);
}

.dashboard-header { grid-area: header; }
.dashboard-sidebar { grid-area: sidebar; }
.dashboard-main { grid-area: main; }
.dashboard-aside { grid-area: aside; }
.dashboard-footer { grid-area: footer; }

/* Responsive Grid Areas */
@media (max-width: 1024px) {
  .dashboard {
    grid-template-areas:
      "header"
      "main"
      "aside"
      "footer";
    grid-template-columns: 1fr;
  }
  
  .dashboard-sidebar {
    display: none;
  }
}
```

## Flexbox Implementation

### Advanced Flexbox Patterns
```css
/* Holy Grail Layout with Flexbox */
.holy-grail {
  display: flex;
  flex-direction: column;
  min-height: 100vh;
}

.holy-grail-body {
  display: flex;
  flex: 1;
}

.holy-grail-content {
  flex: 1;
  padding: var(--spacing-layout-md);
}

.holy-grail-nav,
.holy-grail-ads {
  flex: 0 0 200px;
  padding: var(--spacing-layout-sm);
}

.holy-grail-nav {
  order: -1;
}

/* Flexible Card Layout */
.card-flex {
  display: flex;
  flex-direction: column;
  height: 100%;
}

.card-header,
.card-footer {
  flex-shrink: 0;
}

.card-body {
  flex: 1;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
}

/* Centering Patterns */
.center-flex {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 50vh;
}

.center-flex-column {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  text-align: center;
  gap: var(--spacing-component-lg);
}
```

### Flexible Navigation Patterns
```css
/* Responsive Navigation */
.nav-flex {
  display: flex;
  align-items: center;
  justify-content: space-between;
  flex-wrap: wrap;
  gap: var(--spacing-component-md);
}

.nav-brand {
  flex-shrink: 0;
}

.nav-links {
  display: flex;
  align-items: center;
  gap: var(--spacing-component-md);
  flex-wrap: wrap;
}

.nav-actions {
  display: flex;
  align-items: center;
  gap: var(--spacing-component-sm);
  margin-left: auto;
}

/* Breadcrumb Navigation */
.breadcrumb {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: var(--spacing-component-xs);
}

.breadcrumb-item {
  display: flex;
  align-items: center;
  gap: var(--spacing-component-xs);
}

.breadcrumb-item:not(:last-child)::after {
  content: '/';
  color: var(--text-tertiary);
}
```

## Container Queries

### Component-Based Responsive Design
```css
/* Container Query Setup */
.card-container {
  container-type: inline-size;
  container-name: card;
}

.sidebar-container {
  container-type: inline-size;
  container-name: sidebar;
}

/* Container Query Rules */
@container card (min-width: 300px) {
  .card {
    display: flex;
    flex-direction: row;
    align-items: flex-start;
  }
  
  .card-image {
    flex: 0 0 40%;
  }
  
  .card-content {
    flex: 1;
    padding: var(--spacing-component-lg);
  }
}

@container card (min-width: 500px) {
  .card-title {
    font-size: var(--text-xl);
  }
  
  .card-content {
    padding: var(--spacing-component-xl);
  }
}

@container sidebar (max-width: 200px) {
  .sidebar-nav-text {
    display: none;
  }
  
  .sidebar-nav-icon {
    margin: 0 auto;
  }
}
```

## Advanced CSS Features

### CSS Logical Properties
```css
/* Logical properties for internationalization */
.content {
  padding-inline: var(--spacing-layout-md);
  padding-block: var(--spacing-layout-sm);
  margin-block-end: var(--spacing-layout-lg);
  border-inline-start: 3px solid var(--color-primary-500);
}

.card {
  inline-size: 100%;
  max-inline-size: 400px;
  block-size: auto;
  min-block-size: 200px;
}

/* Text alignment */
.text-start { text-align: start; }
.text-end { text-align: end; }
```

### CSS Nesting (when supported)
```css
/* CSS Nesting for better organization */
.card {
  background: var(--bg-elevated);
  border-radius: var(--radius-lg);
  padding: var(--spacing-component-lg);
  
  & .card-title {
    font-size: var(--text-lg);
    font-weight: var(--font-weight-semibold);
    margin-block-end: var(--spacing-component-sm);
    
    & a {
      color: inherit;
      text-decoration: none;
      
      &:hover {
        color: var(--color-primary-600);
        text-decoration: underline;
      }
    }
  }
  
  & .card-content {
    color: var(--text-secondary);
    line-height: var(--leading-relaxed);
  }
  
  &:hover {
    box-shadow: var(--shadow-lg);
    transform: translateY(-2px);
  }
}
```

### CSS Scroll Snap
```css
/* Scroll snap for carousels and galleries */
.carousel {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
  scroll-behavior: smooth;
  gap: var(--spacing-component-md);
  padding: var(--spacing-component-md);
}

.carousel-item {
  flex: 0 0 300px;
  scroll-snap-align: start;
  scroll-snap-stop: always;
}

/* Vertical scroll snap for sections */
.page-sections {
  height: 100vh;
  overflow-y: auto;
  scroll-snap-type: y mandatory;
}

.page-section {
  height: 100vh;
  scroll-snap-align: start;
  display: flex;
  align-items: center;
  justify-content: center;
}
```

### CSS Aspect Ratio
```css
/* Modern aspect ratio control */
.aspect-square {
  aspect-ratio: 1 / 1;
}

.aspect-video {
  aspect-ratio: 16 / 9;
}

.aspect-photo {
  aspect-ratio: 4 / 3;
}

.aspect-golden {
  aspect-ratio: 1.618 / 1;
}

/* Responsive aspect ratios */
.hero-image {
  aspect-ratio: 21 / 9;
  object-fit: cover;
  width: 100%;
}

@media (max-width: 768px) {
  .hero-image {
    aspect-ratio: 16 / 9;
  }
}

@media (max-width: 480px) {
  .hero-image {
    aspect-ratio: 4 / 3;
  }
}
```

## Performance Optimizations

### CSS Containment
```css
/* Layout containment for performance */
.card {
  contain: layout style paint;
}

.sidebar {
  contain: layout;
}

.carousel-item {
  contain: layout style paint;
}

/* Size containment for fixed-size components */
.avatar {
  contain: size layout style paint;
  width: 40px;
  height: 40px;
}
```

### CSS Transform Optimizations
```css
/* Use transform for animations instead of layout properties */
.slide-in {
  transform: translateX(-100%);
  transition: transform var(--duration-300) var(--ease-out);
}

.slide-in.is-visible {
  transform: translateX(0);
}

/* Use will-change sparingly */
.will-animate {
  will-change: transform;
}

.animation-complete {
  will-change: auto;
}

/* GPU acceleration for smooth animations */
.smooth-transform {
  transform: translateZ(0);
  backface-visibility: hidden;
  perspective: 1000px;
}
```

### Critical CSS Patterns
```css
/* Above-the-fold critical styles */
.critical {
  /* Essential layout and typography */
  font-family: var(--font-family-base);
  line-height: var(--leading-normal);
  color: var(--text-primary);
  background-color: var(--bg-primary);
}

.critical-layout {
  display: grid;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
}

/* Defer non-critical styles */
@media print, (min-width: 0) {
  .non-critical {
    /* Decorative styles, animations, etc. */
  }
}
```

## Accessibility Enhancements

### Focus Management
```css
/* Enhanced focus indicators */
.focus-visible {
  outline: 2px solid var(--color-primary-500);
  outline-offset: 2px;
  border-radius: var(--radius-sm);
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  .card {
    border: 1px solid;
  }
  
  .btn {
    border: 2px solid;
  }
}

/* Reduced motion support */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}
```

### Screen Reader Optimizations
```css
/* Screen reader only content */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

.sr-only-focusable:focus {
  position: static;
  width: auto;
  height: auto;
  padding: inherit;
  margin: inherit;
  overflow: visible;
  clip: auto;
  white-space: normal;
}

/* Skip links */
.skip-link {
  position: absolute;
  top: -40px;
  left: 6px;
  background: var(--bg-elevated);
  color: var(--text-primary);
  padding: 8px;
  text-decoration: none;
  border-radius: var(--radius-md);
  z-index: 1000;
  transition: top var(--duration-200) var(--ease-out);
}

.skip-link:focus {
  top: 6px;
}
```

## CSS Debugging and Development

### Debug Utilities
```css
/* Debug mode for development */
[data-debug="true"] * {
  outline: 1px solid red;
}

[data-debug="true"] *:hover {
  outline: 2px solid blue;
}

/* Grid debugging */
.debug-grid {
  background-image: 
    linear-gradient(rgba(255, 0, 0, 0.1) 1px, transparent 1px),
    linear-gradient(90deg, rgba(255, 0, 0, 0.1) 1px, transparent 1px);
  background-size: 20px 20px;
}

/* Flexbox debugging */
.debug-flex > * {
  outline: 1px solid rgba(0, 255, 0, 0.5);
}
```

### CSS Custom Properties for Debugging
```css
:root {
  --debug-color: red;
  --debug-opacity: 0.1;
}

.debug-outline {
  outline: 1px solid var(--debug-color);
  background: rgba(255, 0, 0, var(--debug-opacity));
}
```

## Browser Support and Fallbacks

### Progressive Enhancement
```css
/* Flexbox fallback for CSS Grid */
.grid-fallback {
  display: flex;
  flex-wrap: wrap;
  margin: calc(var(--spacing-layout-md) * -0.5);
}

.grid-fallback > * {
  flex: 1 1 300px;
  margin: calc(var(--spacing-layout-md) * 0.5);
}

@supports (display: grid) {
  .grid-fallback {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: var(--spacing-layout-md);
    margin: 0;
  }
  
  .grid-fallback > * {
    margin: 0;
  }
}

/* Custom properties fallback */
.fallback-colors {
  background-color: #ffffff; /* fallback */
  background-color: var(--bg-primary, #ffffff);
  color: #333333; /* fallback */
  color: var(--text-primary, #333333);
}
```

### Feature Detection
```css
/* Container queries fallback */
@supports not (container-type: inline-size) {
  .card-responsive {
    /* Media query fallback */
  }
}

/* Aspect ratio fallback */
@supports not (aspect-ratio: 1 / 1) {
  .aspect-square {
    width: 100%;
    height: 0;
    padding-bottom: 100%;
    position: relative;
  }
  
  .aspect-square > * {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
}
```

## CSS Organization Best Practices

### File Structure
```
styles/
├── 01-settings/
│   ├── _tokens.css
│   └── _config.css
├── 02-tools/
│   ├── _mixins.css
│   └── _functions.css
├── 03-generic/
│   ├── _reset.css
│   └── _normalize.css
├── 04-elements/
│   ├── _typography.css
│   └── _forms.css
├── 05-objects/
│   ├── _layout.css
│   └── _grid.css
├── 06-components/
│   ├── _buttons.css
│   ├── _cards.css
│   └── _navigation.css
├── 07-utilities/
│   ├── _spacing.css
│   └── _display.css
└── main.css
```

### Naming Conventions
```css
/* BEM methodology with modern enhancements */
.block {}
.block__element {}
.block--modifier {}
.block__element--modifier {}

/* Utility classes with responsive prefixes */
.u-margin-top-sm {}
.u-text-center {}
.u-display-none {}

@media (min-width: 768px) {
  .u-md-display-block {}
  .u-md-text-left {}
}

/* Component states */
.is-active {}
.is-loading {}
.is-disabled {}
.has-error {}
```

This modern CSS implementation guide provides a comprehensive foundation for building performant, maintainable, and accessible stylesheets using the latest CSS features while ensuring broad browser compatibility through progressive enhancement.