docs: add important info around global styles

docs/02-app/01-building-your-application/05-styling/01-css-modules.mdx → docs/02-app/01-building-your-application/05-styling/01-stylesheets.mdx

@@ -1,6 +1,6 @@
 ---
-title: CSS Modules and Global Styles
-nav_title: CSS Modules
+title: Stylesheets
+nav_title: Stylesheets
 description: Style your Next.js Application with CSS Modules, Global Styles, and external stylesheets.
 ---
 
@@ -29,7 +29,7 @@ Next.js has built-in support for CSS Modules using the `.module.css` extension.
 
 CSS Modules locally scope CSS by automatically creating a unique class name. This allows you to use the same class name in different files without worrying about collisions. This behavior makes CSS Modules the ideal way to include component-level CSS.
 
-## Example
+### Example
 
 <AppOnly>
 CSS Modules can be imported into any file inside the `app` directory:
@@ -110,7 +110,10 @@ These `.css` files represent hot execution paths in your application, ensuring t
 <AppOnly>
 Global styles can be imported into any layout, page, or component inside the `app` directory.
 
-> **Good to know**: This is different from the `pages` directory, where you can only import global styles inside the `_app.js` file.
+> **Good to know**:
+>
+> - This is different from the `pages` directory, where you can only import global styles inside the `_app.js` file.
+> - Next.js does not support usage of global styles unless they are actually global, meaning they can apply to all pages and can live for the lifetime of the application. This is because Next.js uses React's built-in support for stylesheets to integrate with Suspense. This built-in support currently does not remove stylesheets as you navigate from Page A to Page B. Because of this, we recommend using CSS Modules over global styles.
 
 For example, consider a stylesheet named `app/global.css`:
 
@@ -300,7 +303,7 @@ function ExampleDialog(props) {
 
 ## Ordering and Merging
 
-Next.js optimizes CSS during production builds by automatically chunking (merging) stylesheets. The CSS order is determined by the order in which you import the stylesheets into your application code.
+Next.js optimizes CSS during production builds by automatically chunking (merging) stylesheets. The CSS order is _determined by the order in which you import the stylesheets into your application code_.
 
 For example, `base-button.module.css` will be ordered before `page.module.css` since `<BaseButton>` is imported first in `<Page>`:
 
@@ -346,6 +349,7 @@ To maintain a predictable order, we recommend the following:
   - Use a consistent naming convention for your CSS modules. For example, using `<name>.module.css` over `<name>.tsx`.
 - Extract shared styles into a separate shared component.
 - If using [Tailwind](/docs/app/building-your-application/styling/tailwind-css), import the stylesheet at the top of the file, preferably in the [Root Layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required).
+- Turn off any linters/formatters (e.g., ESLint's [`sort-import`](https://eslint.org/docs/latest/rules/sort-imports)) that automatically sort your imports. This can inadvertently affect your CSS since CSS import order _matters_.
 
 > **Good to know:**
 >

docs/02-app/01-building-your-application/05-styling/02-tailwind-css.mdx

@@ -55,7 +55,7 @@ You do not need to modify `postcss.config.js`.
 
 ## 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-modules#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/building-your-application/styling/stylesheets#global-styles) in your application, for example:
 
 ```css filename="app/globals.css"
 @tailwind base;

docs/02-app/01-building-your-application/05-styling/04-css-in-js.mdx

@@ -33,7 +33,7 @@ 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-modules) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css).
+If you want to style Server Components, we recommend using [CSS Modules](/docs/app/building-your-application/styling/stylesheets) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css).
 
 ## Configuring CSS-in-JS in `app`
 

docs/02-app/01-building-your-application/05-styling/index.mdx

@@ -7,8 +7,8 @@ description: Learn the different ways you can style your Next.js application.
 
 Next.js supports different ways of styling your application, including:
 
-- **Global CSS**: Simple to use and familiar for those experienced with traditional CSS, but can lead to larger CSS bundles and difficulty managing styles as the application grows.
 - **CSS Modules**: Create locally scoped CSS classes to avoid naming conflicts and improve maintainability.
+- **Global CSS**: Simple to use and familiar for those experienced with traditional CSS, but can lead to larger CSS bundles and difficulty managing styles as the application grows.
 - **Tailwind CSS**: A utility-first CSS framework that allows for rapid custom designs by composing utility classes.
 - **Sass**: A popular CSS preprocessor that extends CSS with features like variables, nested rules, and mixins.
 - **CSS-in-JS**: Embed CSS directly in your JavaScript components, enabling dynamic and scoped styling.

docs/02-app/01-building-your-application/06-optimizing/01-images.mdx

@@ -229,7 +229,7 @@ If none of the suggested methods works for sizing your images, the `next/image`
 Styling the Image component is similar to styling a normal `<img>` element, but there are a few guidelines to keep in mind:
 
 - Use `className` or `style`, not `styled-jsx`.
-  - In most cases, we recommend using the `className` prop. This can be an imported [CSS Module](/docs/app/building-your-application/styling/css-modules), a [global stylesheet](/docs/app/building-your-application/styling/css-modules#global-styles), etc.
+  - In most cases, we recommend using the `className` prop. This can be an imported [CSS Module](/docs/app/building-your-application/styling/stylesheets), a [global stylesheet](/docs/app/building-your-application/styling/stylesheets#global-styles), etc.
   - You can also use the `style` prop to assign inline styles.
   - You cannot use [styled-jsx](/docs/app/building-your-application/styling/css-in-js) because it's scoped to the current component (unless you mark the style as `global`).
 - When using `fill`, the parent element must have `position: relative`

docs/02-app/01-building-your-application/11-upgrading/04-app-router-migration.mdx

@@ -876,11 +876,11 @@ export async function GET(request) {}
 
 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-modules)
+- [CSS Modules](/docs/app/building-your-application/styling/stylesheets)
 - [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css)
-- [Global Styles](/docs/app/building-your-application/styling/css-modules#global-styles)
+- [Global Styles](/docs/app/building-your-application/styling/stylesheets#global-styles)
 - [CSS-in-JS](/docs/app/building-your-application/styling/css-in-js)
-- [External Stylesheets](/docs/app/building-your-application/styling/css-modules#external-stylesheets)
+- [External Stylesheets](/docs/app/building-your-application/styling/stylesheets#external-stylesheets)
 - [Sass](/docs/app/building-your-application/styling/sass)
 
 #### Tailwind CSS

docs/02-app/01-building-your-application/11-upgrading/06-from-create-react-app.mdx

@@ -313,7 +313,7 @@ With the above changes, you shifted from declaring everything in your `index.htm
 
 ### Step 6: Styles
 
-Like Create React App, Next.js has built-in support for [CSS Modules](/docs/app/building-your-application/styling/css-modules).
+Like Create React App, Next.js has built-in support for [CSS Modules](/docs/app/building-your-application/styling/stylesheets).
 
 If you're using a global CSS file, import it into your `app/layout.tsx` file:
 

docs/02-app/02-api-reference/04-functions/generate-metadata.mdx

@@ -1017,7 +1017,7 @@ The following metadata types do not currently have built-in support. However, th
 | `<meta http-equiv="...">`     | Use appropriate HTTP Headers via [`redirect()`](/docs/app/api-reference/functions/redirect), [Middleware](/docs/app/building-your-application/routing/middleware#nextresponse), [Security Headers](/docs/app/api-reference/next-config-js/headers) |
 | `<base>`                      | Render the tag in the layout or page itself.                                                                                                                                                                                                       |
 | `<noscript>`                  | Render the tag in the layout or page itself.                                                                                                                                                                                                       |
-| `<style>`                     | Learn more about [styling in Next.js](/docs/app/building-your-application/styling/css-modules).                                                                                                                                                    |
+| `<style>`                     | Learn more about [styling in Next.js](/docs/app/building-your-application/styling/stylesheets).                                                                                                                                                    |
 | `<script>`                    | Learn more about [using scripts](/docs/app/building-your-application/optimizing/scripts).                                                                                                                                                          |
 | `<link rel="stylesheet" />`   | `import` stylesheets directly in the layout or page itself.                                                                                                                                                                                        |
 | `<link rel="preload />`       | Use [ReactDOM preload method](#link-relpreload)                                                                                                                                                                                                    |

docs/02-app/02-api-reference/05-next-config-js/webpack.mdx

@@ -13,7 +13,7 @@ Before continuing to add custom webpack configuration to your application make s
 <AppOnly>
 
 - [CSS imports](/docs/app/building-your-application/styling)
-- [CSS modules](/docs/app/building-your-application/styling/css-modules)
+- [CSS modules](/docs/app/building-your-application/styling/stylesheets)
 - [Sass/SCSS imports](/docs/app/building-your-application/styling/sass)
 - [Sass/SCSS modules](/docs/app/building-your-application/styling/sass)
 

docs/03-pages/01-building-your-application/04-styling/01-css-modules.mdx

@@ -1,7 +1,7 @@
 ---
 title: CSS Modules
 description: Style your Next.js Application using CSS Modules.
-source: app/building-your-application/styling/css-modules
+source: app/building-your-application/styling/stylesheets
 ---
 
 {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}