@primer/react-brand 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.11ae3568

package/docs/components/MediaPlaylist/index.md

@@ -0,0 +1,133 @@
+---
+title: Media playlist
+description: Use MediaPlaylist to pair thumbnail-backed media items with a shared playback or media area.
+keywords: ['media', 'playlist', 'tabs', 'video', 'youtube']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/MediaPlaylist/MediaPlaylist.tsx
+storybook: '/brand/storybook/?path=/story/components-mediaplaylist--default'
+---
+
+```js
+import {MediaPlaylist} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<MediaPlaylist>
+  <MediaPlaylist.Heading>Latest videos</MediaPlaylist.Heading>
+
+  <MediaPlaylist.Item thumbnail={<img src="https://i.ytimg.com/vi/ITxzBiTBZW0/hqdefault.jpg" alt="" loading="lazy" />}>
+    <MediaPlaylist.ItemHeading title="Getting More from Every Copilot Interaction" description="10:57" />
+    <MediaPlaylist.ItemContent>
+      <Text as="p" variant="muted">
+        See workflows for scoping context, choosing the right mode, and getting more focused Copilot answers.
+      </Text>
+    </MediaPlaylist.ItemContent>
+    <MediaPlaylist.ItemMedia>
+      <iframe
+        src="https://www.youtube-nocookie.com/embed/ITxzBiTBZW0"
+        title="Getting More from Every Copilot Interaction"
+        loading="lazy"
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+        allowFullScreen
+      />
+    </MediaPlaylist.ItemMedia>
+  </MediaPlaylist.Item>
+
+  <MediaPlaylist.Item thumbnail={<img src="https://i.ytimg.com/vi/CIgdAO8mbw0/hqdefault.jpg" alt="" loading="lazy" />}>
+    <MediaPlaylist.ItemHeading title="How to plan projects with GitHub Copilot CLI" description="08:35" />
+    <MediaPlaylist.ItemContent>
+      <Text as="p" variant="muted">
+        Use GitHub Copilot CLI planning to clarify goals, map an approach, and prepare implementation work.
+      </Text>
+    </MediaPlaylist.ItemContent>
+    <MediaPlaylist.ItemMedia>
+      <iframe
+        src="https://www.youtube-nocookie.com/embed/CIgdAO8mbw0"
+        title="How to plan projects with GitHub Copilot CLI"
+        loading="lazy"
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+        allowFullScreen
+      />
+    </MediaPlaylist.ItemMedia>
+  </MediaPlaylist.Item>
+
+  <MediaPlaylist.Item thumbnail={<img src="https://i.ytimg.com/vi/wS8CV85RTO8/hqdefault.jpg" alt="" loading="lazy" />}>
+    <MediaPlaylist.ItemHeading title="What is TanStack AI? The new open source toolkit" description="12:04" />
+    <MediaPlaylist.ItemContent>
+      <Text as="p" variant="muted">
+        Get a quick look at TanStack AI and its open source approach to framework-agnostic AI tooling.
+      </Text>
+    </MediaPlaylist.ItemContent>
+    <MediaPlaylist.ItemMedia>
+      <iframe
+        src="https://www.youtube-nocookie.com/embed/wS8CV85RTO8"
+        title="What is TanStack AI? The new open source toolkit"
+        loading="lazy"
+        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+        allowFullScreen
+      />
+    </MediaPlaylist.ItemMedia>
+  </MediaPlaylist.Item>
+</MediaPlaylist>
+```
+
+## Component props
+
+### MediaPlaylist `Required`
+
+| Name                   | Type                              | Default | Description                                                         |
+| :--------------------- | :-------------------------------- | :-----: | :------------------------------------------------------------------ |
+| `children`             | `ReactNode`                       |         | Includes one required `MediaPlaylist.Heading` and one or more items |
+| `defaultSelectedIndex` | `number`                          |   `0`   | Default selected index for uncontrolled mode                        |
+| `selectedIndex`        | `number`                          |         | Selected index for controlled mode                                  |
+| `onChange`             | `(selectedIndex: number) => void` |         | Callback called when selected index changes                         |
+
+`MediaPlaylist` extends the HTML `div` element and supports all `div` props.
+
+### MediaPlaylist.Heading `Required`
+
+| Name       | Type                                   | Default | Description                                                            |
+| :--------- | :------------------------------------- | :-----: | :--------------------------------------------------------------------- |
+| `children` | `ReactNode`                            |         | Visible playlist heading and accessible label for the playlist items   |
+| `as`       | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` |  `'h3'` | Semantic heading level                                                 |
+| `id`       | `string`                               |         | Optional custom ID used for the tablist `aria-labelledby` relationship |
+
+`MediaPlaylist.Heading` renders a visible heading and active item counter.
+
+### MediaPlaylist.Item `Required`
+
+| Name        | Type                   | Default | Description                                           |
+| :---------- | :--------------------- | :-----: | :---------------------------------------------------- |
+| `children`  | `React.ReactElement[]` |         | Must include ItemHeading, ItemContent, and ItemMedia  |
+| `thumbnail` | `ReactNode`            |         | Thumbnail media displayed in the playlist item button |
+| `className` | `string`               |         | Optional custom class                                 |
+
+### MediaPlaylist.ItemHeading `Required`
+
+| Name          | Type        | Default | Description                                                           |
+| :------------ | :---------- | :-----: | :-------------------------------------------------------------------- |
+| `title`       | `ReactNode` |         | Item title text                                                       |
+| `description` | `ReactNode` |         | Optional metadata rendered under the title, such as a video duration  |
+| `children`    | `ReactNode` |         | Custom item heading content when title/description props are not used |
+
+`MediaPlaylist.ItemHeading` renders as a `span` and extends the [`Text`](../../typography/Text/index.md) component, excluding the `as` prop.
+
+### MediaPlaylist.ItemContent `Required`
+
+| Name       | Type        | Default | Description       |
+| :--------- | :---------- | :-----: | :---------------- |
+| `children` | `ReactNode` |         | Item body content |
+
+`MediaPlaylist.ItemContent` extends the HTML `div` element and supports all `div` props.
+
+### MediaPlaylist.ItemMedia `Required`
+
+| Name       | Type                 | Default | Description |
+| :--------- | :------------------- | :-----: | :---------- |
+| `children` | `React.ReactElement` |         | Item media  |
+
+`MediaPlaylist.ItemMedia` extends the HTML `div` element and supports all `div` props.

package/docs/components/MinimalFooter/index.md

@@ -0,0 +1,94 @@
+---
+title: Minimal footer
+description: Use the minimal footer component to provide a global footer featuring legal links, GitHub logomarks and footnotes.
+keywords: ['legal', 'copyright', 'social', 'links', 'footnotes']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/MinimalFooter/MinimalFooter.tsx
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=4686%3A30927&t=QKh20cPDVIFtBCHj-0
+storybook: '/brand/storybook/?path=/story/components-minimalfooter--playground'
+---
+
+```js
+import {MinimalFooter} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<MinimalFooter />
+```
+
+### Footer links
+
+```jsx
+<MinimalFooter>
+  <MinimalFooter.Link href="https://github.com/organizations/enterprise_plan">Try GitHub for free</MinimalFooter.Link>
+  <MinimalFooter.Link href="https://github.com/enterprise">Enterprise</MinimalFooter.Link>
+  <MinimalFooter.Link href="https://github.com/enterprise/contact">Email us</MinimalFooter.Link>
+</MinimalFooter>
+```
+
+### Footnotes
+
+```jsx
+<MinimalFooter>
+  <MinimalFooter.Footnotes>
+    <Text>
+      <sup>1</sup>By signing up, GitHub may use your information to personalize and measure the effectiveness of
+      enterprise business ads, including those you see off of GitHub, promotional communications or marketing you
+      receive related to the Enterprise Marketing Pages. We will send you relevant emails and promotional information
+      based on your GitHub profile and any additional information provided in the sign-up form. If you change your mind,
+      you can unsubscribe at any time (an unsubscribe link is provided in every email). For more information on how
+      GitHub uses your personal information, please see the{' '}
+      <InlineLink
+        href="https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement"
+        target="_blank"
+      >
+        GitHub Privacy Statement
+      </InlineLink>
+      .
+    </Text>
+  </MinimalFooter.Footnotes>
+</MinimalFooter>
+```
+
+### Footer social links
+
+`MinimalFooter` will render all supported social links by default. Social links can be removed however, by passing `socialLinks={false}`. Alteratively, pass an array of valid social links to filter the default list.
+
+```jsx
+<Stack>
+  Hide all social links:
+  <MinimalFooter socialLinks={false} />
+  <br />
+  Only show GitHub social link:
+  <MinimalFooter socialLinks={['github']} />
+</Stack>
+```
+
+## Component props
+
+### MinimalFooter
+
+| Name                 | Type                                                                                             |                                        Default                                        | Description                                            |
+| :------------------- | :----------------------------------------------------------------------------------------------- | :-----------------------------------------------------------------------------------: | :----------------------------------------------------- |
+| `className`          | `string`                                                                                         |                                                                                       | Sets a custom class on the root element                |
+| `children`           | `'MinimalFooter.Link' \| 'MinimalFooter.Footnotes'`                                              |                                      `undefined`                                      | Valid child components                                 |
+| `copyrightStatement` | `string` \| `ReactElement`                                                                       |                                                                                       | The copyright statement to be displayed in the footer. |
+| `logoHref`           | `string`                                                                                         |                                 `'https://github.com'`                                | The href for the GitHub logo.                          |
+| `socialLinks`        | `['x', 'github', 'linkedin', 'youtube', 'facebook', 'twitch', 'tiktok', 'instagram']` \| `false` | `['x', 'github', 'linkedin', 'youtube', 'facebook', 'twitch', 'tiktok', 'instagram']` | Array of valid strings or `false` to hide all links    |
+
+### MinimalFooter.Link
+
+| Name       | Type              |   Default   | Description                         |
+| :--------- | :---------------- | :---------: | :---------------------------------- |
+| `as`       | `'a'`, `'button'` |    `'a'`    | Applies the underlying HTML element |
+| `children` | `string`          | `undefined` | Link label text                     |
+
+### MinimalFooter.Footnotes
+
+| Name       | Type         |   Default   | Description                                                           |
+| :--------- | :----------- | :---------: | :-------------------------------------------------------------------- |
+| `children` | ReactElement | `undefined` | Use Primer Brand `Text` components to benefit from inherited styling. |

package/docs/components/NavList/index.md

@@ -0,0 +1,210 @@
+---
+title: NavList
+description: Use NavList to render vertical navigation with optional expandable groups.
+keywords: ['navigation', 'vertical navigation', 'sidebar', 'nested navigation']
+ready: true
+source: https://github.com/primer/brand/tree/main/packages/react/src/NavList/NavList.tsx
+storybook: '/brand/storybook/?path=/story/components-navlist--playground'
+---
+
+```js
+import {NavList} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<NavList aria-label="Docs navigation">
+  <NavList.Item href="#" aria-current="page">
+    Overview
+  </NavList.Item>
+  <NavList.Item href="#">Quickstart</NavList.Item>
+  <NavList.Item href="#">Install GitHub Copilot</NavList.Item>
+  <NavList.Item href="#">Configure your editor</NavList.Item>
+  <NavList.Item href="#">Manage policies</NavList.Item>
+  <NavList.Item href="#">Troubleshooting</NavList.Item>
+</NavList>
+```
+
+### Groups
+
+Use `NavList.Group` to organize related navigation items into labelled groups.
+
+```jsx
+<NavList aria-label="Section navigation">
+  <NavList.Group title="Products">
+    <NavList.Item href="#" aria-current="page">
+      Copilot
+    </NavList.Item>
+    <NavList.Item href="#">Codespaces</NavList.Item>
+    <NavList.Item href="#">Actions</NavList.Item>
+    <NavList.Item href="#">Packages</NavList.Item>
+  </NavList.Group>
+  <NavList.Group title="Collaboration">
+    <NavList.Item href="#">Pull requests</NavList.Item>
+    <NavList.Item href="#">Issues</NavList.Item>
+    <NavList.Item href="#">Discussions</NavList.Item>
+  </NavList.Group>
+  <NavList.Group title="Security">
+    <NavList.Item href="#">Overview</NavList.Item>
+    <NavList.Item href="#">Secret scanning</NavList.Item>
+    <NavList.Item href="#">Code scanning</NavList.Item>
+  </NavList.Group>
+</NavList>
+```
+
+### Nested disclosure
+
+Add `NavList.SubNav` to a `NavList.Item` when an item needs to expand and collapse nested navigation links.
+
+```jsx
+<NavList aria-label="Nested navigation">
+  <NavList.Group title="Collaboration">
+    <NavList.Item defaultExpanded>
+      Pull requests
+      <NavList.SubNav>
+        <NavList.Item href="#" aria-current="page">
+          Review pull requests
+        </NavList.Item>
+        <NavList.Item href="#">Use suggested changes</NavList.Item>
+        <NavList.Item href="#">Configure rulesets</NavList.Item>
+      </NavList.SubNav>
+    </NavList.Item>
+    <NavList.Item>
+      Branches
+      <NavList.SubNav>
+        <NavList.Item href="#">Overview</NavList.Item>
+        <NavList.Item href="#">Protection rules</NavList.Item>
+      </NavList.SubNav>
+    </NavList.Item>
+  </NavList.Group>
+</NavList>
+```
+
+### Up to five navigation levels
+
+`NavList` can include up to five levels when a page hierarchy requires it. Use the fewest levels needed; levels one through four can optionally expand or collapse, and level five is reserved for leaf article links.
+
+```jsx
+<NavList aria-label="Five-level navigation">
+  <NavList.Item defaultExpanded>
+    GitHub Copilot
+    <NavList.SubNav>
+      <NavList.Item defaultExpanded>
+        Guides
+        <NavList.SubNav>
+          <NavList.Item defaultExpanded>
+            Agents
+            <NavList.SubNav>
+              <NavList.Item defaultExpanded>
+                Build an agent
+                <NavList.SubNav>
+                  <NavList.Item href="#" aria-current="page">
+                    Create a tool
+                  </NavList.Item>
+                  <NavList.Item href="#">Add memory</NavList.Item>
+                  <NavList.Item href="#">Debug prompts</NavList.Item>
+                  <NavList.Item href="#">Deploy safely</NavList.Item>
+                </NavList.SubNav>
+              </NavList.Item>
+              <NavList.Item href="#">Customize an agent</NavList.Item>
+              <NavList.Item href="#">Debug an agent</NavList.Item>
+            </NavList.SubNav>
+          </NavList.Item>
+          <NavList.Item>
+            Extensions
+            <NavList.SubNav>
+              <NavList.Item href="#">Install an extension</NavList.Item>
+              <NavList.Item href="#">Publish an extension</NavList.Item>
+              <NavList.Item href="#">Manage permissions</NavList.Item>
+            </NavList.SubNav>
+          </NavList.Item>
+        </NavList.SubNav>
+      </NavList.Item>
+      <NavList.Item>
+        Administration
+        <NavList.SubNav>
+          <NavList.Item href="#">Overview</NavList.Item>
+          <NavList.Item href="#">Policies</NavList.Item>
+          <NavList.Item href="#">Audit log</NavList.Item>
+        </NavList.SubNav>
+      </NavList.Item>
+    </NavList.SubNav>
+  </NavList.Item>
+  <NavList.Item>
+    Code review
+    <NavList.SubNav>
+      <NavList.Item href="#">Overview</NavList.Item>
+      <NavList.Item href="#">Review pull requests</NavList.Item>
+      <NavList.Item href="#">Use suggested changes</NavList.Item>
+    </NavList.SubNav>
+  </NavList.Item>
+</NavList>
+```
+
+### With visuals
+
+Use `leadingVisual` and `trailingVisual` to add icons to the label area. Visuals are additive: they do not replace disclosure triangles, change item sizing, or move the active and inactive row alignment.
+
+```jsx
+<NavList aria-label="Visual navigation">
+  <NavList.Item href="#" aria-current="page" leadingVisual={BookIcon} trailingVisual={<KebabHorizontalIcon />}>
+    GitHub Copilot
+  </NavList.Item>
+</NavList>
+```
+
+## Accessibility
+
+Give each `NavList` a clear `aria-label`, especially when the page includes more than one navigation landmark.
+
+Use `aria-current="page"` on the link for the current page. Only apply `aria-current` to leaf items that navigate somewhere, not to disclosure rows with nested items.
+
+Keep group titles and disclosure labels short and descriptive. Items with `NavList.SubNav` must include visible label text so people can understand what will expand.
+
+## Component props
+
+### NavList `Required`
+
+| name              | type        | default | required | description                                           |
+| ----------------- | ----------- | ------- | -------- | ----------------------------------------------------- |
+| `children`        | `ReactNode` |         | `true`   | `NavList.Item` and `NavList.Group` nodes              |
+| `aria-label`      | `string`    |         | `true`   | Accessible label for the navigation landmark          |
+| `aria-labelledby` | `string`    |         | `false`  | ID of the element that labels the navigation landmark |
+| `className`       | `string`    |         | `false`  | Sets a custom class on the `nav` element              |
+
+Forwards all standard HTML attributes for `<nav>` elements.
+
+### NavList.Item `Required`
+
+| name               | type                                                                      | default | required | description                                                                                |
+| ------------------ | ------------------------------------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
+| `as`               | `'a' \| 'button'`                                                         | `'a'`   | `false`  | Element used for leaf items                                                                |
+| `children`         | `ReactNode`                                                               |         | `true`   | Item label and optional `NavList.SubNav` for nested disclosure                             |
+| `href`             | `string`                                                                  |         | `false`  | URL for leaf items when rendering as an anchor                                             |
+| `aria-current`     | `'page' \| 'step' \| 'location' \| 'date' \| 'time' \| 'true' \| 'false'` |         | `false`  | Marks a leaf item as current                                                               |
+| `defaultExpanded`  | `boolean`                                                                 | `false` | `false`  | Opens nested `NavList.SubNav` by default                                                   |
+| `expanded`         | `boolean`                                                                 |         | `false`  | Controls the nested `NavList.SubNav` expanded state                                        |
+| `onExpandedChange` | `(expanded) => void`                                                      |         | `false`  | Called when the nested `NavList.SubNav` expanded state changes                             |
+| `leadingVisual`    | `ReactElement \| Icon`                                                    |         | `false`  | Visual rendered before the label                                                           |
+| `trailingVisual`   | `ReactElement \| Icon`                                                    |         | `false`  | Visual rendered after the label                                                            |
+| `disabled`         | `boolean`                                                                 | `false` | `false`  | Disables the item. Leaf links receive `aria-disabled`; disclosure buttons receive disabled |
+
+Forwards props to the rendered leaf link or disclosure button.
+
+### NavList.Group
+
+| name        | type        | default | required | description                                |
+| ----------- | ----------- | ------- | -------- | ------------------------------------------ |
+| `title`     | `ReactNode` |         | `false`  | Heading text for the group                 |
+| `children`  | `ReactNode` |         | `true`   | `NavList.Item` nodes                       |
+| `className` | `string`    |         | `false`  | Sets a custom class on the group list item |
+
+### NavList.SubNav
+
+| name        | type        | default | required | description                            |
+| ----------- | ----------- | ------- | -------- | -------------------------------------- |
+| `children`  | `ReactNode` |         | `true`   | Nested `NavList.Item` nodes            |
+| `className` | `string`    |         | `false`  | Sets a custom class on the nested `ul` |

package/docs/components/OrderedList/index.md

@@ -0,0 +1,55 @@
+---
+title: Ordered list
+description: Use the ordered list component to display a list of numbered items.
+keywords: ['numbered list', 'sequence']
+---
+
+## Anatomy
+
+![Ordered list renders as a numbered list of items](https://github.com/primer/brand/assets/912236/5cda0c94-c120-4fc6-8306-8b55012dee0a)
+
+## Usage
+
+Use an ordered list to represent a list of items in a numerical order.
+
+A number indicating the items relative position in the sequence will be prepended to each item in the list.
+
+The ordered list is commonly used when presenting sequential or step-by-step information. It is suitable for instructions, procedures, tutorials, or any content that follows a specific order. Ensure that the items in the ordered list are logically organized and follow a clear progression. This helps readers understand the sequence of information and makes it easier to follow.
+
+Avoid overusing ordered lists. Reserve them for situations where the order of items is genuinely meaningful or where a clear sequence needs to be conveyed. For
+lists that don't require a specific order, consider using an [unordered list](../UnorderedList/index.md) instead.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/40022d10-248f-45d5-acce-2917a72d7b12)
+
+_Use an ordered list to present a sequence of steps._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/e9dd1ee2-cfa7-40d4-a8b6-2416cf99cdae)
+
+_Don't use an ordered list to present a list of items that don't require a specific order. Use an unordered list
+instead._
+
+The ordered list should have concise and short items. Avoid using long sentences or paragraphs as they can be difficult to scan and comprehend. If you need to include a long item or even headings and links, consider using a [pillar](../Pillar/index.md), a [card](../Card/index.md) or a [river](../River/index.md) instead.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/181f1cb9-05bc-4010-a80b-a978b7ffbe56)
+
+_Use an ordered list for short and concise content items._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/28950f6a-d7f0-4d9d-bb70-02c062d309f3)
+
+_Don't use an ordered list for long and rich sentences, paragraphs, headings or links. Use a pillar, card or river
+components instead._
+
+## Related components
+
+- [Unordered list](../UnorderedList/index.md): to display a list of plain content items.
+- [Pillar](../Pillar/index.md): To display related content with less visual emphasis.
+- [Card](../Card/index.md): to display navigational related content with higher visual weight.
+- [River](../River/index.md): To display a list of content items with a visual asset.

package/docs/components/OrderedList/react.md

@@ -0,0 +1,41 @@
+---
+title: Ordered list
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/branch/NzBMPIfPrFU9I87d3k7KVq/Primer-Brand?node-id=4045%3A17560&t=W8B9ArDngbzJCC2m-0
+source: https://github.com/primer/brand/blob/main/packages/react/src/list/OrderedList/OrderedList.tsx
+storybook: '/brand/storybook/?path=/story/components-orderedlist--playground'
+description: Use the ordered list component to display a list of numbered items.
+---
+
+```js
+import {OrderedList} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<OrderedList>
+  <OrderedList.Item>Automatic security and version updates</OrderedList.Item>
+  <OrderedList.Item>GitHub Security Advisories</OrderedList.Item>
+  <OrderedList.Item>Code and secret scanning</OrderedList.Item>
+  <OrderedList.Item>Dependency review</OrderedList.Item>
+  <OrderedList.Item>Automated authentication and identity management</OrderedList.Item>
+</OrderedList>
+```
+
+## Component props
+
+### OrderedList
+
+| Name        | Type                                   |  Default  | Description                                              |
+| :---------- | :------------------------------------- | :-------: | :------------------------------------------------------- |
+| `className` | `string`                               |           | Sets a custom class on the root element                  |
+| `children`  | `React.ReactNode`, `React.ReactNode[]` | `default` | Content to be displayed within the OrderedList component |
+
+### OrderedList.Item
+
+| Name        | Type                                   |  Default  | Description                                              |
+| :---------- | :------------------------------------- | :-------: | :------------------------------------------------------- |
+| `className` | `string`                               |           | Sets a custom class on the root element                  |
+| `children`  | `React.ReactNode`, `React.ReactNode[]` | `default` | Content to be displayed within the OrderedList component |

package/docs/components/Pagination/index.md

@@ -0,0 +1,80 @@
+---
+title: Pagination
+description: Use Pagination to display a sequence of links that allow navigation to discrete, related pages.
+keywords: ['page numbers', 'page navigation']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Pagination/Pagination.tsx
+storybook: '/brand/storybook/?path=/story/components-pagination--playground'
+---
+
+```js
+import {Pagination} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx filename="noinline"
+const App = () => {
+  const [currentPage, setCurrentPage] = React.useState(5)
+  const totalPages = 10
+
+  const handlePageChange = (e, pageNumber) => {
+    if (pageNumber === currentPage + 1 && currentPage < totalPages) {
+      // Next page handler
+      setCurrentPage(currentPage + 1)
+    } else if (pageNumber === currentPage - 1 && currentPage > 1) {
+      // Previous page handler
+      setCurrentPage(currentPage - 1)
+    } else if (pageNumber >= 1 && pageNumber <= totalPages) {
+      setCurrentPage(pageNumber)
+    }
+  }
+
+  return <Pagination pageCount={10} currentPage={currentPage} onPageChange={handlePageChange} />
+}
+
+render(<App />)
+```
+
+### Hide page numbers
+
+```jsx
+<Pagination pageCount={15} currentPage={5} showPages={false} />
+```
+
+### Custom href
+
+```jsx
+<Pagination pageCount={3} currentPage={1} hrefBuilder={n => `https://primer.style/brand/page/${n}`} />
+```
+
+### Custom data attributes
+
+```jsx
+<Pagination
+  pageCount={3}
+  currentPage={1}
+  pageAttributesBuilder={n => {
+    return {
+      'data-custom-attribute': `custom-attribute-${n}`,
+    }
+  }}
+/>
+```
+
+## Component props
+
+### Pagination `Required`
+
+| name                    | type                                                                         | default | required | description                                                                                                             |
+| ----------------------- | ---------------------------------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `pageCount`             | `number`                                                                     |         | `true`   | The total number of pages                                                                                               |
+| `currentPage`           | `number`                                                                     |         | `true`   | The current page number                                                                                                 |
+| `onPageChange`          | `(e: React.MouseEvent, n: number) => void`                                   |         | `false`  | Callback function for when the page changes                                                                             |
+| `hrefBuilder`           | `(n: number) => string`                                                      |         | `false`  | Function to build the href for each page                                                                                |
+| `pageAttributesBuilder` | `(n: number, page: PaginationPageType) => {[attributeName: string]: string}` |         | `false`  | Forward custom attributes to pagination items.                                                                          |
+| `marginPageCount`       | `number`                                                                     |         | `false`  | Defines how many pages are to be displayed on the left and right of the component. Will be reduced on narrow viewports. |
+| `showPages`             | `boolean`                                                                    |         | `false`  | Whether to show the page numbers                                                                                        |
+| `surroundingPageCount`  | `number`                                                                     |         | `false`  | The number of pages to show on each side of the current page. Will be hidden on narrow viewports.                       |