src/
├── styles/
│   ├── base/
│   │   └── global.css       # Global styles and CSS resets
│   ├── components/          # Component-specific styles
│   ├── responsive/
│   │   ├── breakpoints.css  # Media query breakpoints
│   │   ├── container-queries.css # Container query utilities
│   │   ├── utilities.css    # Responsive utility classes
│   │   └── index.css        # Main responsive styles entry point
│   └── theme/               # Theme variables and theming logic
└── components/              # Component files

/* src/styles/responsive/breakpoints.css */
:root {
  /* Mobile-first breakpoints */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
  
  /* Container query breakpoints */
  --container-sm: 640px;
  --container-md: 768px;
  --container-lg: 1024px;
  --container-xl: 1280px;
  --container-2xl: 1536px;
}

/* Example component using media queries */
.component {
  /* Mobile styles (default) */
  padding: 1rem;
  font-size: 1rem;

  /* Small screens and up */
  @media (min-width: 640px) {
    padding: 1.5rem;
  }

  /* Medium screens and up */
  @media (min-width: 768px) {
    padding: 2rem;
    font-size: 1.125rem;
  }
}

/* src/styles/responsive/container-queries.css */
.container {
  container-type: inline-size;
  container-name: component;
  width: 100%;
}

/* Basic container query */
@container component (min-width: 400px) {
  .card {
    grid-template-columns: 1fr 2fr;
  }
}

<!-- Example component using container queries -->
<div class="container">
  <div class="card">
    <img src="image.jpg" alt="Example" />
    <div class="content">
      <h3>Card Title</h3>
      <p>This card will adapt based on its container size.</p>
    </div>
  </div>
</div>

/* Bad - Desktop-first approach */
.component {
  width: 50%;
  @media (max-width: 768px) {
    width: 100%;
  }
}

/* Good - Mobile-first approach */
.component {
  width: 100%;
  @media (min-width: 768px) {
    width: 50%;
  }
}

/* Container query for a card component */
.card {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}

@container (min-width: 480px) {
  .card {
    flex-direction: row;
    align-items: center;
  }
  
  .card img {
    width: 150px;
    height: 150px;
    object-fit: cover;
  }
}

/* Base styles */
.hero {
  padding: 2rem 1rem;
  text-align: center;
}

/* Container query for component-level adjustments */
@container component (min-width: 600px) {
  .hero {
    text-align: left;
    display: grid;
    grid-template-columns: 1fr 1fr;
    align-items: center;
    gap: 2rem;
  }
}

/* Media query for viewport-specific adjustments */
@media (min-width: 1024px) {
  .hero {
    padding: 4rem 2rem;
    max-width: 1280px;
    margin: 0 auto;
  }
}

<!-- HTML -->
<nav class="nav container">
  <a href="/" class="nav__logo">Logo</a>
  <button class="nav__toggle" aria-expanded="false" aria-controls="nav-menu">
    <span class="sr-only">Menu</span>
  </button>
  <div class="nav__menu" id="nav-menu">
    <ul class="nav__list">
      <li><a href="/about">About</a></li>
      <li><a href="/services">Services</a></li>
      <li><a href="/contact">Contact</a></li>
    </ul>
  </div>
</nav>

/* CSS with container queries */
.nav {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  padding: 1rem;
  gap: 1rem;
}

.nav__toggle {
  margin-left: auto;
  display: block;
}

.nav__menu {
  width: 100%;
  max-height: 0;
  overflow: hidden;
  transition: max-height 0.3s ease-in-out;
}

.nav__menu[data-visible="true"] {
  max-height: 100vh;
}

/* Container query for navigation */
@container (min-width: 768px) {
  .nav__toggle {
    display: none;
  }
  
  .nav__menu {
    width: auto;
    max-height: none;
    display: block;
    margin-left: auto;
  }
  
  .nav__list {
    display: flex;
    gap: 2rem;
  }
}

### Astro Configuration for Tailwind v4

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

// src/types/tailwind.d.ts
declare global {
  namespace CSS {
    interface AtRules {
      theme: string;
    }
  }
}

export interface ThemeColors {
  primary: {
    50: string;
    100: string;
    // ... color scale definitions
  };
  // ... additional color groups
}

/* Dark mode color scale inversion example */
.theme-default[data-mode="dark"] {
  /* Inverted color scales for proper contrast */
  --color-secondary-50: #0f172a;  /* Was light, now dark */
  --color-secondary-100: #1e293b;
  --color-secondary-200: #334155;
  --color-secondary-800: #f1f5f9;  /* Was dark, now light */
  --color-secondary-900: #f8fafc;  /* Was darkest, now lightest */
}

// Enhanced type definitions
export type ThemeMode = 'light' | 'dark';
export type ThemeVariant = 'default' | 'water';
export type ColorScale = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | '950';

// Key test categories covered:
- Constructor initialization with default and stored themes
- setTheme() method with valid/invalid themes and DOM manipulation
- toggleTheme() method with proper state transitions
- getCurrentTheme() method with DOM state detection
- Storage integration with localStorage persistence
- DOM manipulation with classList and attribute management
- Event dispatching with custom theme-change events
- Server-side rendering compatibility

// Comprehensive coverage for:
- Mode initialization and storage retrieval
- setMode() and toggleMode() functionality
- DOM class and attribute management
- localStorage persistence
- Error handling for invalid modes

// Theme and mode combination testing:
- All theme/mode combinations (default+light, default+dark, water+light, water+dark)
- State persistence across browser sessions
- Independent and simultaneous toggling operations
- DOM state validation and cleanup
- Event dispatching coordination
- Server-side rendering compatibility
- CSS variable integration verification

const createStatefulDOMElement = () => {
  const classes = new Set();
  const attributes = new Map();
  
  return {
    classList: {
      add: vi.fn((...classNames) => {
        classNames.forEach(className => classes.add(className));
      }),
      remove: vi.fn((...classNames) => {
        classNames.forEach(className => classes.delete(className));
      }),
      contains: vi.fn((className) => {
        return classes.has(className);
      })
    }
    // ... additional DOM methods
  };
};

beforeEach(() => {
  // Reset DOM state using global reset function
  global.resetDOMState();
  // Reset localStorage
  window.localStorage.clear();
  // Create fresh instances
  switcher = new ThemeSwitcher();
});

toggleTheme() {
  const currentTheme = this.getCurrentTheme();
  const newTheme = currentTheme === 'water' ? 'default' : 'water';
  
  // Update internal state - CRITICAL FIX
  this.currentTheme = newTheme;
  this.applyTheme(newTheme);
  this.storeTheme(newTheme);
  
  return newTheme;
}