Global CSS Import Flow in Next.js:

Pages Router:
  pages/_app.js → imports global.css → applies to ALL pages

App Router:
  app/layout.tsx → imports globals.css → applies to ALL routes

Both:
  Components → import CSS Modules → scoped to component only
  Components → CANNOT import global CSS (Next.js throws error)

flowchart TD
    subgraph "Pages Router"
        A[_app.tsx] --> B[import 'globals.css']
        B --> C[Page 1: index.tsx]
        B --> D[Page 2: about.tsx]
        B --> E[Page 3: contact.tsx]
    end

    subgraph "App Router"
        F[layout.tsx] --> G[import 'app/globals.css']
        G --> H[Home Page]
        G --> I[About Page]
        G --> J[Blog Page]
    end

    K[Component] --> L[import styles from './Comp.module.css']

    style A fill:#7c3aed,color:#fff
    style F fill:#7c3aed,color:#fff
    style B fill:#22c55e,color:#fff
    style G fill:#22c55e,color:#fff
    style K fill:#f59e0b,color:#000

sequenceDiagram
    participant Dev as Developer
    participant Next as Next.js Compiler
    participant CSS as CSS Processor
    participant SWC as SWC Bundler
    participant Browser

    Dev->>Next: Import globals.css in _app.tsx
    Next->>Next: Verify allowed entry point ✓
    Next->>CSS: Parse and process CSS
    CSS->>CSS: Resolve @import and @tailwind directives
    CSS->>SWC: Add to dependency graph
    SWC->>SWC: Build CSS bundle
    SWC->>Browser: Inject <style> or <link>
    Browser->>Browser: Apply global styles to all pages

Entry Point (_app.tsx / layout.tsx)
├── CSS Reset (normalize.css or custom)
│   └── Removes browser inconsistencies
├── Base Typography
│   └── html, body, headings, paragraphs
├── CSS Custom Properties
│   └── --color-primary, --spacing-md, --font-sans
├── Utility Classes
│   └── .container, .sr-only, .text-center
├── Third-party CSS
│   └── Library stylesheets
└── Print Styles
    └── @media print rules

flowchart LR
    A[Global CSS] --> B[CSS Reset]
    A --> C[Typography]
    A --> D[Custom Properties]
    A --> E[Utilities]

    F[Component Styles] --> G[CSS Modules]
    F --> H[CSS-in-JS]
    F --> I[Inline Styles]

    B & C & D & E --> J[Browser Cascade]
    G & H & I --> J

    J --> K[Fully Styled Page]

    style A fill:#7c3aed,color:#fff
    style F fill:#4f46e5,color:#fff
    style J fill:#22c55e,color:#fff

flowchart TD
    A[Create styles/globals.css] --> B[Write CSS reset]
    B --> C[Define custom properties]
    C --> D[Set typography]
    D --> E[Import in _app.tsx]
    E --> F[Run dev server]
    F --> G{Check all pages}
    G -->|Styles apply everywhere| H[✓ Success]
    G -->|Styles missing| I[Check import path]
    I --> E

/* styles/globals.css — Global styles for entire application */

/* 1. CSS Reset */
*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

/* 2. Base Typography */
html {
  font-size: 16px;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
    Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
  line-height: 1.6;
  color: #1a202c;
  background-color: #ffffff;
}

/* 3. CSS Custom Properties (Design Tokens) */
:root {
  /* Colors */
  --color-primary: #0070f3;
  --color-primary-dark: #0051a2;
  --color-secondary: #7928ca;
  --color-accent: #ff0080;
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-background: #ffffff;
  --color-surface: #f7fafc;
  --color-text: #1a202c;
  --color-text-muted: #718096;

  /* Spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-2xl: 3rem;

  /* Typography */
  --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --font-mono: 'SF Mono', 'Fira Code', 'Fira Mono', 'Roboto Mono', monospace;
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-size-3xl: 1.875rem;
  --font-size-4xl: 2.25rem;

  /* Borders */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

  /* Transitions */
  --transition-fast: 150ms ease;
  --transition-base: 200ms ease;
  --transition-slow: 300ms ease;

  /* Breakpoints (for reference, not usable in CSS) */
  /* --bp-sm: 640px; */
  /* --bp-md: 768px; */
  /* --bp-lg: 1024px; */
  /* --bp-xl: 1280px; */
}

/* 4. Utility Classes */
.container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 var(--spacing-md);
}

.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;
}

.text-center {
  text-align: center;
}

/* 5. Focus styles for accessibility */
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

/* 6. Link styles */
a {
  color: var(--color-primary);
  text-decoration: none;
  transition: color var(--transition-fast);
}

a:hover {
  color: var(--color-primary-dark);
  text-decoration: underline;
}

/* 7. Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --color-background: #0f172a;
    --color-surface: #1e293b;
    --color-text: #f1f5f9;
    --color-text-muted: #94a3b8;
  }

  body {
    color: var(--color-text);
    background-color: var(--color-background);
  }
}

// pages/_app.tsx — Pages Router: Import global CSS here
import type { AppProps } from 'next/app'
import '../styles/globals.css'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

// app/layout.tsx — App Router: Import global CSS here
import type { Metadata } from 'next'
import './globals.css'

export const metadata: Metadata = {
  title: 'My App',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

// app/layout.tsx — App Router with multiple imports
import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import './globals.css'

const inter = Inter({ subsets: ['latin'] })

export const metadata: Metadata = {
  title: 'My SaaS App',
  description: 'A full-stack SaaS application',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <header style={{ height: 'var(--header-height)' }}>
          {/* Navigation */}
        </header>
        <main>{children}</main>
      </body>
    </html>
  )
}

// components/ThemeToggle.tsx — Using CSS custom properties for theming
'use client'

import { useEffect, useState } from 'react'

type Theme = 'light' | 'dark' | 'system'

export default function ThemeToggle() {
  const [theme, setTheme] = useState<Theme>('system')

  useEffect(() => {
    const stored = localStorage.getItem('theme') as Theme | null
    if (stored) {
      setTheme(stored)
      document.documentElement.setAttribute('data-theme', stored === 'system'
        ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
        : stored
      )
    }
  }, [])

  const handleChange = (newTheme: Theme) => {
    setTheme(newTheme)
    localStorage.setItem('theme', newTheme)

    if (newTheme === 'system') {
      const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches
      document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light')
    } else {
      document.documentElement.setAttribute('data-theme', newTheme)
    }
  }

  return (
    <div className="theme-toggle">
      <button onClick={() => handleChange('light')} data-active={theme === 'light'}>
        ☀️ Light
      </button>
      <button onClick={() => handleChange('dark')} data-active={theme === 'dark'}>
        🌙 Dark
      </button>
      <button onClick={() => handleChange('system')} data-active={theme === 'system'}>
        💻 System
      </button>
    </div>
  )
}

/* styles/globals.css — Production-grade global styles */

/* Vendors — Third-party CSS */
@import 'react-toastify/dist/ReactToastify.css';
@import 'swiper/css';

/* Base — Foundation layers */
@import './base/reset.css';
@import './base/typography.css';
@import './base/tokens.css';

/* Layout — Structural styles */
@import './layout/grid.css';
@import './layout/header.css';
@import './layout/footer.css';

/* Utilities — Helper classes */
@import './utilities/accessibility.css';
@import './utilities/animations.css';
@import './utilities/spacing.css';

/* Critical performance: Load critical CSS inline, defer non-critical */
@media print {
  @import './print.css';
}

/* Motion preference: Reduce animations for accessibility */
@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;
  }
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  :root {
    --text-primary: #000000;
    --text-secondary: #1a1a1a;
    --border-light: #666666;
  }
}

// pages/_app.tsx — Organized imports
import type { AppProps } from 'next/app'
import { Analytics } from '@vercel/analytics/react'

// Global styles — MUST be imported here
import '@/styles/globals.css'

// Fonts — Google Fonts via next/font
import { Inter } from 'next/font/google'
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',  // Use as CSS variable
})

// SEO metadata
import { DefaultSeo } from 'next-seo'
import SEO from '../next-seo.config'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <DefaultSeo {...SEO} />
      <div className={inter.variable}>
        <Component {...pageProps} />
      </div>
      <Analytics />
    </>
  )
}

// components/GlobalStyleProvider.tsx — Optional wrapper for App Router
'use client'

import { useEffect } from 'react'

export default function GlobalStyleProvider({
  children,
}: {
  children: React.ReactNode
}) {
  useEffect(() => {
    // Apply saved theme on mount
    const theme = localStorage.getItem('theme') || 'system'
    document.documentElement.setAttribute('data-theme', theme)

    // Listen for system theme changes
    const mq = window.matchMedia('(prefers-color-scheme: dark)')
    const handler = (e: MediaQueryListEvent) => {
      if (localStorage.getItem('theme') === 'system') {
        document.documentElement.setAttribute('data-theme', e.matches ? 'dark' : 'light')
      }
    }
    mq.addEventListener('change', handler)
    return () => mq.removeEventListener('change', handler)
  }, [])

  return <>{children}</>
}

styles/
├── globals.css              # Main entry point — imports all partials
├── base/
│   ├── reset.css            # CSS reset/normalize
│   ├── typography.css       # Font families, headings, paragraphs
│   └── tokens.css           # CSS custom properties (design tokens)
├── layout/
│   ├── grid.css             # Grid system
│   ├── header.css           # Header/ Nav styles
│   └── footer.css           # Footer styles
├── components/
│   ├── buttons.css          # Global button styles (overridable by modules)
│   ├── forms.css            # Form element styles
│   └── cards.css            # Card layout styles
├── utilities/
│   ├── accessibility.css    # .sr-only, focus styles, reduced motion
│   ├── animations.css       # Shared @keyframes definitions
│   └── spacing.css          # Margin/padding utility classes
├── vendors/
│   └── third-party.css      # Third-party library overrides
└── print.css                # Print-specific styles

// components/Header.tsx — This file has a bug
import '../styles/globals.css'  // Bug: importing global CSS in a component

export default function Header() {
  return (
    <header className="header">
      <h1>My App</h1>
    </header>
  )
}

// middleware.ts — Set tenant theme based on subdomain
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const hostname = request.headers.get('host') || ''
  const subdomain = hostname.split('.')[0]

  // Map subdomain to theme
  const themes: Record<string, Record<string, string>> = {
    acme: {
      primary: '#2563eb',
      secondary: '#3b82f6',
      accent: '#60a5fa',
    },
    globex: {
      primary: '#059669',
      secondary: '#10b981',
      accent: '#34d399',
    },
  }

  const theme = themes[subdomain] || themes.acme

  // Set theme via response header
  const response = NextResponse.next()
  Object.entries(theme).forEach(([key, value]) => {
    response.headers.set(`X-Theme-${key}`, value)
  })

  return response
}

'use client'

import { useEffect, useState } from 'react'

type Theme = 'light' | 'dark' | 'solarized'

export default function useTheme() {
  const [theme, setTheme] = useState<Theme>('light')

  useEffect(() => {
    const saved = localStorage.getItem('app-theme') as Theme | null
    if (saved) {
      setTheme(saved)
      document.documentElement.setAttribute('data-theme', saved)
    }
  }, [])

  const changeTheme = (newTheme: Theme) => {
    setTheme(newTheme)
    localStorage.setItem('app-theme', newTheme)
    document.documentElement.setAttribute('data-theme', newTheme)
  }

  return { theme, changeTheme }
}

/* Global CSS — Only importable in _app.tsx or layout.tsx */

/* Design Tokens */
:root {
  --color-primary: #0070f3;
  --spacing-md: 1rem;
}

/* Dark Mode */
@media (prefers-color-scheme: dark) {
  :root { --bg: #0f172a; }
}

/* Theme Toggle */
[data-theme='dark'] { --bg: #0f172a; }

/* Accessibility */
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; }
}

/* Utility Classes */
.sr-only { /* Screen reader only */ }
.container { /* Max-width centering */ }

// ✅ Correct: Import in _app.tsx
import '../styles/globals.css'

// ❌ Wrong: Import in component
// import '../styles/globals.css'  // ERROR!