Bundle docs in the package and clean up private files

.changeset/bundle-version-pinned-docs.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Version-pinned documentation is now bundled in `@primer/react-brand`. Each release now ships Markdown documentation at parity with primer.style/brand under `docs/`, plus an `llms.txt` index. This is to help agents reference documentation that matches their installed version instead relying on the latest version of documentation published to primer.style/brand, which may be ahead of what's locally installed.

.changeset/exclude-internal-type-declarations.md

@@ -0,0 +1,11 @@
+---
+'@primer/react-brand': minor
+---
+
+⚠️ Changes to the files listed in the package: `lib/` (UMD) and `esm/` (ESM) bundles now ship a clean, filtered list of React modules and type declarations (everything exported from `index.ts`). Internal-only modules that were never intended for the package like `recipes/` and Storybook test `fixtures/` — are no longer included:
+
+```diff
+- @primer/react-brand/esm/recipes/**
+- @primer/react-brand/{lib,esm}/**/fixtures/**
+- @primer/react-brand/{lib,esm}/**/*.fixtures.d.ts
+```

.github/workflows/ci.yml

@@ -49,3 +49,6 @@ jobs:
 
       - name: Run unit tests
         run: npm run test
+
+      - name: Verify docs bundle
+        run: npm run bundle:docs:verify --workspace=packages/react

apps/next-docs/content/components/Section/react.mdx

@@ -136,6 +136,6 @@ The default `Section` wraps its content in a semantic `<section>` element and pr
 | `backgroundImageSrc`      | `string` \| `string[]` `ResponsiveMap` |             | `false`  | Add one or more background images.                                                                                                                            |
 | `backgroundImageSize`     | `string` \| `string[]` `ResponsiveMap` | `'cover'`   | `false`  | Control the size of the background image(s). This accepts all CSS `background-size` supported values, including keywords like `contain`.                      |
 | `backgroundImagePosition` | `string` \| `string[]` `ResponsiveMap` | `'50%'`     | `false`  | Control the position of the background image(s). This accepts all CSS `background-position` supported values, including keywords like `top` and edge offsets. |
-| `rounded`                 | `boolean`                              | `false`     | `false`  | Adds rounded conterns to the top of the section.                                                                                                              |
+| `rounded`                 | `boolean`                              | `false`     | `false`  | Adds rounded corners to the top of the section.                                                                                                               |
 | `fullWidth`               | `boolean`                              | `false`     | `false`  | Makes the container fill the entire width of the section.                                                                                                     |
-| `as`                      | `section'`, `'div'`                    | `'section'` | `false`  | Applies the underlying HTML element.                                                                                                                          |
+| `as`                      | `'section'` \| `'div'`                 | `'section'` | `false`  | Applies the underlying HTML element.                                                                                                                          |

apps/next-docs/content/components/SubdomainNavBar/index.mdx

@@ -119,16 +119,16 @@ Use the `onNarrowMenuToggle` prop to detect when the mobile menu is opened or cl
 
 ### SubdomainNavBar <Label>Required</Label>
 
-| Name                 | Type                            |       Default       | Description                                                                                                                            |
-| :------------------- | :------------------------------ | :-----------------: | :------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`           | <SubdomainNavBarChildrenProp /> |                     | Valid child nodes                                                                                                                      |
-| `className`          | `string`                        |                     | Sets a custom class                                                                                                                    |
-| `id`                 | `string`                        |                     | Sets a custom id                                                                                                                       |
-| `logoHref`           | `string`                        | `https//github.com` | Optionally change the URL of the logo                                                                                                  |
-| `title`              | `string`                        |                     | The title or name of the subdomain. Appears adjacent to the logo and is required for communicating content to assisitive technologies. |
-| `titleHref`          | `string`                        |         `/`         | The URL for the site. Typically used to link the title prop value to the site root.                                                    |
-| `ref`                | `React.RefObject`               |                     | Forward a Ref to the underlying DOM node                                                                                               |
-| `onNarrowMenuToggle` | `(isOpen: boolean) => void`     |                     | When the mobile menu is opened or closed, this callback is called with the new open state.                                             |
+| Name                 | Type                            |       Default        | Description                                                                                                                            |
+| :------------------- | :------------------------------ | :------------------: | :------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`           | <SubdomainNavBarChildrenProp /> |                      | Valid child nodes                                                                                                                      |
+| `className`          | `string`                        |                      | Sets a custom class                                                                                                                    |
+| `id`                 | `string`                        |                      | Sets a custom id                                                                                                                       |
+| `logoHref`           | `string`                        | `https://github.com` | Optionally change the URL of the logo                                                                                                  |
+| `title`              | `string`                        |                      | The title or name of the subdomain. Appears adjacent to the logo and is required for communicating content to assisitive technologies. |
+| `titleHref`          | `string`                        |         `/`          | The URL for the site. Typically used to link the title prop value to the site root.                                                    |
+| `ref`                | `React.RefObject`               |                      | Forward a Ref to the underlying DOM node                                                                                               |
+| `onNarrowMenuToggle` | `(isOpen: boolean) => void`     |                      | When the mobile menu is opened or closed, this callback is called with the new open state.                                             |
 
 <h3 id="SubdomainNavBar-link">
   SubdomainNavBar.Link <Label>Required</Label>

apps/next-docs/content/components/Tooltip/index.mdx

@@ -63,4 +63,5 @@ Use this with caution. It is generally better to use a visible label for better
 
 ## Related components
 
-- [Button](/components/Button): Often used in conjunction with tooltips.
+- [Popover](/components/Popover): For displaying more complex interactive content that appears when triggered
+- [Button](/components/Button): Often used in conjunction with tooltips

apps/next-docs/content/forms/TextArea/index.mdx

@@ -4,13 +4,13 @@ description: Use the textarea component for multi-line text input form fields.
 keywords: ['input', 'form']
 show-tabs: false
 source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Textarea/Textarea.tsx
-storybook: '/react/storybook?path=/story/components-forms-textarea--default'
+storybook: '/brand/storybook/?path=/story/components-forms-textarea--default'
 ---
 
 import {TextAreaSizeProp, TextAreaValidationStatusProp, TextAreaResizeProp} from './react'
 
 ```js
-import {Textarea} from '@primer/react'
+import {Textarea} from '@primer/react-brand'
 ```
 
 ## Examples

apps/next-docs/content/layout/Stack/react.mdx

@@ -5,8 +5,8 @@ keywords: ['layout']
 show-tabs: true
 tab-label: React
 ready: true
-source: https://github.com/primer/brand/blob/main/packages/react/src/Box/Box.tsx
-storybook: '/brand/storybook/?path=/story/components-box--default'
+source: https://github.com/primer/brand/blob/main/packages/react/src/Stack/Stack.tsx
+storybook: '/brand/storybook/?path=/story/components-stack--default'
 ---
 
 import {

packages/react/.gitignore

@@ -1,2 +1,4 @@
 fonts/
-esm/
+esm/
+docs/
+llms.txt

packages/react/.prettierignore

@@ -2,5 +2,7 @@ src/**/*.css.d.ts
 coverage/
 lib/
 esm/
+docs/
+llms.txt
 src/tokens
 .changeset

packages/react/README.md

@@ -0,0 +1,19 @@
+# @primer/react-brand
+
+GitHub's design system for building React-based marketing websites and brand-led digital experiences.
+
+> **Are you an AI agent or tool?** Version-matched documentation is bundled with this package. Start at `node_modules/@primer/react-brand/llms.txt`. Prefer bundled documentation over the website linked below, which tracks the latest release only, and could describe unreleased features, or omit ones that were retired in the version you have installed.
+
+## Installation
+
+```bash
+npm install @primer/react-brand
+```
+
+## Documentation
+
+We publish our docs in two ways:
+
+1. Bundled and matched to your installed version: This is recommended for agents and humans using older versions of the library. Start with [`llms.txt`](./llms.txt) at the package root, which indexes every component and links into [`docs/`](./docs/).
+
+2. Latest docs at [primer.style/brand](https://primer.style/brand), which is the latest version of our docs, and may show unreleased features.

packages/react/eslint.config.mjs

@@ -2,6 +2,9 @@ import rootConfig from '../../eslint.config.mjs'
 
 export default [
   ...rootConfig,
+  {
+    ignores: ['docs/**'], // docs generated and bundled in the package, not published docs
+  },
   {
     languageOptions: {
       parserOptions: {

packages/react/package.json

@@ -46,24 +46,29 @@
   "files": [
     "lib",
     "esm",
-    "fonts"
+    "fonts",
+    "docs",
+    "llms.txt"
   ],
   "scripts": {
     "build": "npm run clean && npm run build:css-types && npm run build:umd && npm run build:esm && scripts/postbuild",
-    "build:umd": "webpack",
+    "build:umd": "webpack && tsc --project tsconfig.umd.json",
     "build:esm": "vite build --config vite.esm.config.ts && tsc --project tsconfig.esm.json",
     "build:css-types": "tcm -p 'src/**/*.css' .",
     "build:types": "tsc --project tsconfig.build.json",
+    "bundle:docs": "node scripts/bundle-docs.mjs",
     "check": "tsc --noEmit",
-    "clean": "rm -rf lib && rm -rf esm && rm -rf fonts",
+    "clean": "rm -rf lib && rm -rf esm && rm -rf fonts && rm -rf docs && rm -f llms.txt",
     "format": "prettier --check '**/*.{js,jsx,ts,tsx,md,mdx,css,json}'",
     "format:fix": "prettier --write '**/*.{js,jsx,ts,tsx,md,mdx,css,json}'",
     "lint": "eslint '**/*.{js,ts,tsx,md,mdx}' --max-warnings=0",
     "lint:fix": "npm run lint -- --fix",
+    "prepack": "npm run bundle:docs",
     "release": "npm run build && changeset publish",
     "start": "npm run start:css-types",
     "start:css-types": "tcm -w -p 'src/**/*.css' .",
-    "test": "jest"
+    "test": "jest",
+    "bundle:docs:verify": "node scripts/verify-docs-bundle.mjs"
   },
   "dependencies": {
     "@oddbird/popover-polyfill": "0.5.2",
@@ -94,15 +99,22 @@
     "identity-obj-proxy": "^3.0.0",
     "jest-axe": "10.0.0",
     "jest-environment-jsdom": "^30.3.0",
+    "mdast-util-to-string": "^4.0.0",
     "mini-css-extract-plugin": "2.10.2",
     "postcss": "8.5.10",
     "postcss-loader": "8.2.1",
     "postcss-preset-env": "11.2.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
     "storybook": "^10.3.4",
     "style-dictionary": "^3.8.0",
     "style-loader": "4.0.0",
     "ts-loader": "^9.5.7",
     "typed-css-modules": "0.9.1",
+    "unified": "^11.0.5",
     "vite": "^8.0.3",
     "vite-plugin-lib-inject-css": "^2.2.2",
     "typescript-plugin-css-modules": "5.2.0",