docs: Merge CSS pages (vercel#78996)

Closes: https://linear.app/vercel/issue/DOC-4648/css
Redirects: vercel/front#45417

- Improves the CSS content for clarity and brevity. 
- Adds Pages Router examples.

---------

Co-authored-by: Lee Robinson <lee@leerob.com>

Author: delbaoliveira

docs/01-app/01-getting-started/06-css.mdx

@@ -24,6 +24,8 @@ Next.js provides several ways to use CSS in your application, including:
 
 CSS Modules locally scope CSS by generating unique class names. This allows you to use the same class in different files without worrying about naming collisions.
 
+<AppOnly>
+
 To start using CSS Modules, create a new file with the extension `.module.css` and import it into any component inside the `app` directory:
 
 ```css filename="app/blog/styles.module.css"
@@ -33,26 +35,58 @@ To start using CSS Modules, create a new file with the extension `.module.css` a
 ```
 
 ```tsx filename="app/blog/page.tsx" switcher
-import styles from './styles.module.css'
+import styles from './blog.module.css'
 
-export default function Page({ children }: { children: React.ReactNode }) {
-  return <main className={styles.blog}>{children}</main>
+export default function Page() {
+  return <main className={styles.blog}></main>
 }
 ```
 
 ```jsx filename="app/blog/page.js" switcher
-import styles from './styles.module.css'
+import styles from './blog.module.css'
+
+export default function Layout() {
+  return <main className={styles.blog}></main>
+}
+```
+
+</AppOnly>
+
+<PagesOnly>
+
+To start using CSS Modules, create a new file with the extension `.module.css` and import it into any component inside the `pages` directory:
+
+```css filename="/styles/blog.module.css"
+.blog {
+  padding: 24px;
+}
+```
 
-export default function Page({ children }) {
-  return <main className={styles.blog}>{children}</main>
+```tsx filename="pages/blog/index.tsx" switcher
+import styles from './blog.module.css'
+
+export default function Page() {
+  return <main className={styles.blog}></main>
 }
 ```
 
+```jsx filename="pages/blog/index.js" switcher
+import styles from './blog.module.css'
+
+export default function Page() {
+  return <main className={styles.blog}></main>
+}
+```
+
+</PagesOnly>
+
 ## Global CSS
 
 You can use global CSS to apply styles across your application.
 
-To use global styles, create a `app/global.css` file and import it in the root layout to apply the styles to **every route** in your application:
+<AppOnly>
+
+Create a `app/global.css` file and import it in the root layout to apply the styles to **every route** in your application:
 
 ```css filename="app/global.css"
 body {
@@ -94,8 +128,28 @@ export default function RootLayout({ children }) {
 
 > **Good to know:** Global styles can be imported into any layout, page, or component inside the `app` directory. However, since Next.js uses React's built-in support for stylesheets to integrate with Suspense, this currently does not remove stylesheets as you navigate between routes which can lead to conflicts. We recommend using global styles for _truly_ global CSS, and [CSS Modules](#css-modules) for scoped CSS.
 
+</AppOnly>
+
+<PagesOnly>
+
+Import the stylesheet in the `pages/_app.js` file to apply the styles to **every route** in your application:
+
+```tsx filename="pages/_app.js"
+import '@/styles/global.css'
+
+export default function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}
+```
+
+Due to the global nature of stylesheets, and to avoid conflicts, you should import them inside [`pages/_app.js`](/docs/pages/building-your-application/routing/custom-app).
+
+</PagesOnly>
+
 ## External stylesheets
 
+<AppOnly>
+
 Stylesheets published by external packages can be imported anywhere in the `app` directory, including colocated components:
 
 ```tsx filename="app/layout.tsx" switcher
@@ -126,4 +180,113 @@ export default function RootLayout({ children }) {
 }
 ```
 
-External stylesheets must be directly imported from an npm package or downloaded and colocated with your codebase. You cannot use `<link rel="stylesheet" />`.
+> **Good to know:** In React 19, `<link rel="stylesheet" href="..." />` can also be used. See the [React `link` documentation](https://react.dev/reference/react-dom/components/link) for more information.
+
+</AppOnly>
+
+<PagesOnly>
+
+Next.js allows you to import CSS files from a JavaScript file.
+This is possible because Next.js extends the concept of [`import`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/import) beyond JavaScript.
+
+### Import styles from `node_modules`
+
+Since Next.js **9.5.4**, importing a CSS file from `node_modules` is permitted anywhere in your application.
+
+For global stylesheets, like `bootstrap` or `nprogress`, you should import the file inside `pages/_app.js`. For example:
+
+```jsx filename="pages/_app.js"
+import 'bootstrap/dist/css/bootstrap.css'
+
+export default function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}
+```
+
+To import CSS required by a third-party component, you can do so in your component. For example:
+
+```jsx filename="components/example-dialog.js"
+import { useState } from 'react'
+import { Dialog } from '@reach/dialog'
+import VisuallyHidden from '@reach/visually-hidden'
+import '@reach/dialog/styles.css'
+
+function ExampleDialog(props) {
+  const [showDialog, setShowDialog] = useState(false)
+  const open = () => setShowDialog(true)
+  const close = () => setShowDialog(false)
+
+  return (
+    <div>
+      <button onClick={open}>Open Dialog</button>
+      <Dialog isOpen={showDialog} onDismiss={close}>
+        <button className="close-button" onClick={close}>
+          <VisuallyHidden>Close</VisuallyHidden>
+          <span aria-hidden>×</span>
+        </button>
+        <p>Hello there. I am a dialog</p>
+      </Dialog>
+    </div>
+  )
+}
+```
+
+</PagesOnly>
+## Ordering and Merging
+
+Next.js optimizes CSS during production builds by automatically chunking (merging) stylesheets. The **order of your CSS** depends on the **order you import styles in your code**.
+
+For example, `base-button.module.css` will be ordered before `page.module.css` since `<BaseButton>` is imported before `page.module.css`:
+
+```tsx filename="page.ts" switcher
+import { BaseButton } from './base-button'
+import styles from './page.module.css'
+
+export default function Page() {
+  return <BaseButton className={styles.primary} />
+}
+```
+
+```jsx filename="page.js" switcher
+import { BaseButton } from './base-button'
+import styles from './page.module.css'
+
+export default function Page() {
+  return <BaseButton className={styles.primary} />
+}
+```
+
+```tsx filename="base-button.tsx" switcher
+import styles from './base-button.module.css'
+
+export function BaseButton() {
+  return <button className={styles.primary} />
+}
+```
+
+```jsx filename="base-button.js" switcher
+import styles from './base-button.module.css'
+
+export function BaseButton() {
+  return <button className={styles.primary} />
+}
+```
+
+### Recommendations
+
+To keep CSS ordering predictable:
+
+- Try to contain CSS imports to a single JavaScript or TypeScript entry file
+- Import global styles and Tailwind stylesheets in the root of your application.
+- Use CSS Modules instead of global styles for nested components.
+- Use a consistent naming convention for your CSS modules. For example, using `<name>.module.css` over `<name>.tsx`.
+- Extract shared styles into shared components to avoid duplicate imports.
+- Turn off linters or formatters that auto-sort imports like ESLint’s [`sort-imports`](https://eslint.org/docs/latest/rules/sort-imports).
+- You can use the [`cssChunking`](/docs/app/api-reference/config/next-config-js/cssChunking) option in `next.config.js` to control how CSS is chunked.
+
+## Development vs Production
+
+- In development (`next dev`), CSS updates apply instantly with [Fast Refresh](/docs/architecture/fast-refresh).
+- In production (`next build`), all CSS files are automatically concatenated into **many minified and code-split** `.css` files, ensuring the minimal amount of CSS is loaded for a route.
+- CSS still loads with JavaScript disabled in production, but JavaScript is required in development for Fast Refresh.
+- CSS ordering can behave differently in development, always ensure to check the build (`next build`) to verify the final CSS order.

docs/01-app/02-guides/css-in-js.mdx

@@ -32,8 +32,6 @@ The following are currently working on support:
 
 > **Good to know**: We're testing out different CSS-in-JS libraries and we'll be adding more examples for libraries that support React 18 features and/or the `app` directory.
 
-If you want to style Server Components, we recommend using [CSS Modules](/docs/app/building-your-application/styling/css) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/guides/tailwind-css).
-
 ## Configuring CSS-in-JS in `app`
 
 Configuring CSS-in-JS is a three-step opt-in process that involves:

docs/01-app/02-guides/migrating/app-router-migration.mdx

@@ -886,11 +886,11 @@ If you are also migrating to Next.js from a Single-Page Application (SPA) at the
 
 In the `pages` directory, global stylesheets are restricted to only `pages/_app.js`. With the `app` directory, this restriction has been lifted. Global styles can be added to any layout, page, or component.
 
-- [CSS Modules](/docs/app/building-your-application/styling/css#css-modules)
+- [CSS Modules](/docs/app/getting-started/css#css-modules)
 - [Tailwind CSS](/docs/app/guides/tailwind-css)
-- [Global Styles](/docs/app/building-your-application/styling/css#global-styles)
+- [Global Styles](/docs/app/getting-started/css#global-css)
 - [CSS-in-JS](/docs/app/guides/css-in-js)
-- [External Stylesheets](/docs/app/building-your-application/styling/css#external-stylesheets)
+- [External Stylesheets](/docs/app/getting-started/css#external-stylesheets)
 - [Sass](/docs/app/guides/sass)
 
 #### Tailwind CSS

docs/01-app/02-guides/migrating/from-create-react-app.mdx

@@ -273,7 +273,7 @@ With the above changes, you shifted from declaring everything in your `index.htm
 
 ### Step 5: Styles
 
-Like CRA, Next.js supports [CSS Modules](/docs/app/building-your-application/styling/css#css-modules) out of the box. It also supports [global CSS imports](/docs/app/building-your-application/styling/css#global-styles).
+Like CRA, Next.js supports [CSS Modules](/docs/app/getting-started/css#css-modules) out of the box. It also supports [global CSS imports](/docs/app/getting-started/css#global-css).
 
 If you have a global CSS file, import it into your `app/layout.tsx`:
 

docs/01-app/02-guides/tailwind-css.mdx

@@ -39,7 +39,7 @@ There is also an [upgrade CLI](https://tailwindcss.com/docs/upgrade-guide) and [
 
 ## Importing Styles
 
-Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-directives#directives) that Tailwind will use to inject its generated styles to a [Global Stylesheet](/docs/app/building-your-application/styling/css#global-styles) in your application, for example:
+Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-directives#directives) that Tailwind will use to inject its generated styles to a [Global Stylesheet](/docs/app/getting-started/css#global-css) in your application, for example:
 
 ```css filename="app/globals.css"
 @import 'tailwindcss';
@@ -111,7 +111,7 @@ export default function Page() {
 
 ## Importing Styles
 
-Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-directives#directives) that Tailwind will use to inject its generated styles to a [Global Stylesheet](/docs/pages/building-your-application/styling/css#global-styles) in your application, for example:
+Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-directives#directives) that Tailwind will use to inject its generated styles to a [Global Stylesheet](/docs/app/getting-started/css#global-css) in your application, for example:
 
 ```css filename="styles/globals.css"
 @import 'tailwindcss';