Add interface guidelines for Breadcrumbs component

apps/docs/content/components/Breadcrumbs/index.mdx

@@ -1,46 +1,40 @@
 ---
 title: Breadcrumbs
-source: https://github.com/primer/brand/tree/main/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
-storybook: '/brand/storybook/?path=/story/components-breadcrumbs--playground'
-description: Use breadcrumbs to enable wayfinding through navigational links
+description: Breadcrumbs display the current page within the site's hierarchy, allowing users to easily navigate to a different level.
 ---
 
-import {Label} from '@primer/react'
-import {BreadcrumbVariants} from '@primer/react-brand'
-import {PropTableValues} from '../../../src/components'
+import ComponentLayout from '../../../src/layouts/component-layout'
 
+import anatomy from './images/anatomy.png'
+import variants from './images/variants.png'
 import doOverflow from './images/do-overflow.png'
 import dontOverflow from './images/dont-overflow.png'
 
-```js
-import {Breadcrumbs} from '@primer/react-brand'
-```
+export default ComponentLayout
 
-## Examples
+## Anatomy
 
-### Default
+<img
+  src={anatomy}
+  alt="Breadcrumbs with location-based annotations for parent-level links, divider, and current page."
+/>
 
-```jsx live
-<Breadcrumbs>
-  <Breadcrumbs.Item href="/">Resources</Breadcrumbs.Item>
-  <Breadcrumbs.Item href="/copilot">GitHub Copilot</Breadcrumbs.Item>
-  <Breadcrumbs.Item href="/copilot/chat" selected>
-    Chat
-  </Breadcrumbs.Item>
-</Breadcrumbs>
-```
+## Usage
 
-### Accent
+Use breadcrumbs to display a user's path within a site's hierarchy, helping them understand their location and easily navigate back to higher-level pages, especially on sites with deep structures.
 
-```jsx live
-<Breadcrumbs variant="accent">
-  <Breadcrumbs.Item href="/">Resources</Breadcrumbs.Item>
-  <Breadcrumbs.Item href="/copilot">GitHub Copilot</Breadcrumbs.Item>
-  <Breadcrumbs.Item href="/copilot/chat" selected>
-    Chat
-  </Breadcrumbs.Item>
-</Breadcrumbs>
-```
+Breadcrumbs are most appropriate on pages that:
+
+- Do not have a section-level navigation
+- May need the ability to quickly go back to the previous (parent) page
+
+### Placement
+
+Place breadcrumbs at the top of the page, below the header and any navigation bar, to ensure they are immediately visible and accessible to users as they begin navigating the page.
+
+Align breadcrumbs with the main content area to maintain a consistent and orderly layout, helping users easily associate the breadcrumbs with the content they are navigating.
+
+Use consistent placement across all pages of the site so that users can rely on breadcrumbs as a stable navigation tool.
 
 ## Accessibility
 
@@ -63,17 +57,19 @@ Ensure that the text of each individual Breadcrumb item fits entirely within a 3
   </Dont>
 </DoDontContainer>
 
-## Component props
+## Options
+
+### Variants
 
-### Breadcrumbs <Label>Required</Label>
+The breadcrumbs component is available in two variants: a default variant, where links use the standard text color, positioning the navigation as a secondary element on the page, and an accent variant, which emphasizes parent links with an accent color. The default variant is suitable for most scenarios, while the accent variant should be reserved for pages where the breadcrumbs are essential for navigation.
 
-| name      | type                                                          | default | required | description                               |
-| --------- | ------------------------------------------------------------- | ------- | -------- | ----------------------------------------- |
-| `variant` | <PropTableValues values={BreadcrumbVariants} addLineBreaks /> |         | `false`  | Specify alternative breadcrumb appearance |
+<img
+  src={variants}
+  alt="The two breadcrumbs variants available: default and accent"
+/>
 
-### Breadcrumbs.Item <Label>Required</Label>
+## Related components
 
-| name       | type      | default | required | description                         |
-| ---------- | --------- | ------- | -------- | ----------------------------------- |
-| `selected` | `boolean` |         | `false`  | Used for indicating the active link |
-| `href`     | `string`  |         | `true`   | URL of the page the link goes to    |
+- [Anchor nav](/components/AnchorNav): To display navigation for different sections of a page.
+- [Pagination](/components/Pagination): To display navigation for content that is split into sequential pages.
+- [Sub nav](/components/SubNav): To display the secondary navigation of a site.

apps/docs/content/components/Breadcrumbs/react.mdx

@@ -0,0 +1,55 @@
+---
+title: Breadcrumbs
+source: https://github.com/primer/brand/tree/main/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
+storybook: '/brand/storybook/?path=/story/components-breadcrumbs--playground'
+description: Use breadcrumbs to enable wayfinding through navigational links
+---
+
+import {Label} from '@primer/react'
+import {BreadcrumbVariants} from '@primer/react-brand'
+import {PropTableValues} from '../../../src/components'
+
+```js
+import {Breadcrumbs} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx live
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Resources</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/copilot">GitHub Copilot</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/copilot/chat" selected>
+    Chat
+  </Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+### Accent
+
+```jsx live
+<Breadcrumbs variant="accent">
+  <Breadcrumbs.Item href="/">Resources</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/copilot">GitHub Copilot</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/copilot/chat" selected>
+    Chat
+  </Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+## Component props
+
+### Breadcrumbs <Label>Required</Label>
+
+| name      | type                                                          | default | required | description                               |
+| --------- | ------------------------------------------------------------- | ------- | -------- | ----------------------------------------- |
+| `variant` | <PropTableValues values={BreadcrumbVariants} addLineBreaks /> |         | `false`  | Specify alternative breadcrumb appearance |
+
+### Breadcrumbs.Item <Label>Required</Label>
+
+| name       | type      | default | required | description                         |
+| ---------- | --------- | ------- | -------- | ----------------------------------- |
+| `selected` | `boolean` |         | `false`  | Used for indicating the active link |
+| `href`     | `string`  |         | `true`   | URL of the page the link goes to    |