docs(react-icons): promote headless API from preview to stable

- move docs/preview-features/headless.md -> docs/headless.md (fix relative links)
- drop the alpha/prerelease banners from the headless doc and README section
- remove headless from the preview-features index (SVG sprites stays alpha)
- publish docs/headless.md via package.json files
- update docsite UserGuidance note to stable wording

SVG sprites remain alpha and are intentionally left unchanged.

Author: Hotell

packages/docsite/stories/Icons/UserGuidance.mdx

@@ -23,7 +23,7 @@ import { Meta } from '@storybook/addon-docs/blocks';
 | **Loading**             | Bundled with JS — no flash                      | FOIT / FOUT risk during font load                           | One request per sprite group; webpack plugin can merge into a single request         |
 | **Setup**               | None (default)                                  | Webpack subsetting plugin, static assets hosting (font)     | Webpack subsetting plugin, static assets hosting (sprite), same-origin proxy for CDN |
 
-> **Note:** A **headless** rendering mode (vanilla CSS, no Griffel runtime) is available as an alpha opt-in via `/headless/*` imports (e.g. `@fluentui/react-icons/headless/svg/access-time`). With CSS extraction it reduces JS bundle sizes significantly — up to −70% for font icons, −56% for SVG sprites, −14% for inline SVG. This table will be updated once the headless API ships in stable.
+> **Note:** A **headless** rendering mode (vanilla CSS, no Griffel runtime) is available via `/headless/*` imports (e.g. `@fluentui/react-icons/headless/svg/access-time`). With CSS extraction it reduces JS bundle sizes significantly — up to −70% for font icons, −56% for SVG sprites, −14% for inline SVG. See the [Headless API documentation](https://github.com/microsoft/fluentui-system-icons/blob/main/packages/react-icons/docs/headless.md) for details.
 
 ### When to use inline SVG (default)
 

packages/react-icons/README.md

@@ -348,13 +348,11 @@ SVG sprites offer smaller bundles, faster renders, and zero runtime overhead.
 
 👉 **[Full documentation →](./docs/preview-features/svg-sprites.md)**
 
-## Headless API — ⚠️ Alpha
-
-> **This feature is available as an alpha prerelease only.** Install via `npm i @fluentui/react-icons@alpha`
+## Headless API
 
 A drop-in replacement for the standard API that removes the CSS-in-JS runtime — provides data-attribute selectors for styling behaviour with opt-in pre-defined vanilla CSS.
 
-👉 **[Full documentation →](./docs/preview-features/headless.md)**
+👉 **[Full documentation →](./docs/headless.md)**
 
 ## Viewing Icons
 

…-icons/docs/preview-features/headless.md packages/react-icons/docs/headless.mdpackages/react-icons/docs/preview-features/headless.md renamed to packages/react-icons/docs/headless.md packages/react-icons/docs/preview-features/headless.md renamed to packages/react-icons/docs/headless.md

@@ -1,9 +1,5 @@
 # Headless API
 
-> **⚠️ Alpha** — this feature is available as an alpha prerelease only.
->
-> Install via `npm i @fluentui/react-icons@prerelease`
-
 The Headless API is a drop-in replacement for the standard icon API that removes the CSS-in-JS runtime dependency. It provides `data-*` attribute selectors for styling behaviour with opt-in pre-defined vanilla CSS — making it suitable for any React setup, including those without a CSS-in-JS runtime.
 
 ## Benefits
@@ -93,7 +89,7 @@ function MyComponent() {
 }
 ```
 
-> **Same-origin requirement:** Sprite files must be served from the same origin as your application. See the [SVG Sprites same-origin section](./svg-sprites.md#same-origin-requirement) for details.
+> **Same-origin requirement:** Sprite files must be served from the same origin as your application. See the [SVG Sprites same-origin section](./preview-features/svg-sprites.md#same-origin-requirement) for details.
 
 ### Font Icons
 
@@ -181,4 +177,4 @@ Use `headless/svg` as the target path (or `headless/svg-sprite` for sprites, `he
 
 > **Note:** You still need to manually add the CSS import (`import '@fluentui/react-icons/headless/styles.css'`) to your application entry point — build transforms only rewrite component imports.
 
-👉 **[Build-Time Transform setup (Babel & SWC) →](../build-transforms.md)**
+👉 **[Build-Time Transform setup (Babel & SWC) →](./build-transforms.md)**

packages/react-icons/docs/preview-features/README.md

@@ -7,7 +7,3 @@
 ## [Atomic API (SVG Sprites)](./svg-sprites.md)
 
 SVG sprites offer smaller bundles, faster renders, and zero runtime overhead.
-
-## [Headless API](./headless.md)
-
-A drop-in replacement for the standard API that removes the CSS-in-JS runtime — provides data-attribute selectors for styling behaviour with opt-in pre-defined vanilla CSS.

packages/react-icons/package.json

@@ -64,6 +64,7 @@
   "files": [
     "docs/preview-features/*.md",
     "docs/build-transforms.md",
+    "docs/headless.md",
     "lib/",
     "lib-cjs/"
   ],