Add interface guidelines for Breadcrumbs component (#915)

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:
+
+- Are missing section-level navigation elements E.g. [SubNav](/components/SubNav)
+- Need to surface contextually-relevant content through its parent page(s)
+
+### 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,22 @@ Ensure that the text of each individual Breadcrumb item fits entirely within a 3
   </Dont>
 </DoDontContainer>
 
-## Component props
+## Options
+
+### Variants
+
+The breadcrumbs component is available in two variants:
 
-### Breadcrumbs <Label>Required</Label>
+- The default variant uses the standard text color, positioning the navigation as a secondary element on the page. This is suitable for most scenarios.  
+- The accent variant emphasizes parent links with an accent color. This variant should 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,59 @@
+---
+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: Breadcrumbs display the current page within the site's hierarchy, allowing users to easily navigate to a different level.
+---
+
+import ComponentLayout from '../../../src/layouts/component-layout'
+
+import {Label} from '@primer/react'
+import {BreadcrumbVariants} from '@primer/react-brand'
+import {PropTableValues} from '../../../src/components'
+
+export default ComponentLayout
+
+```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    |