Merge main into SubdomainNavBar refactor

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 406505eb-bef7-46a4-be1a-599ec848f243

Author: danielguillan

.changeset/clear-pages-compose.md

@@ -0,0 +1,9 @@
+---
+'@primer/brand-mcp': patch
+---
+
+Improves guidance and examples delivered through the Primer Brand MCP tools:
+
+- Improves guidance delivered through the `primer_brand_review` tool.
+- Cleaner output from the `primer_brand_examples` tool.
+- Add new page design guidance advising that `River` descriptions are limited to 160 characters and the default `50:50` image-to-text ratio is preferred.

.changeset/fix-action-menu-split-button-click.md

@@ -0,0 +1,10 @@
+---
+'@primer/react-brand': minor
+---
+
+Multiple `ActionMenu` component updates:
+
+- Calls consumer-provided `onClick` handlers in default and split-button modes.
+- ⚠️ Breaking change to `ActionMenu.Button` in split-button mode. Custom HTML attributes are now correctly forwarded to the primary action instead of the menu toggle. This was the originally intended behavior.
+- Forwards the `variant` prop in `default` mode correctly. `ActionMenu` can now render in all available `Button` variants.
+- Forwards the `leadingVisual` prop in `default` mode.

.changeset/fuzzy-years-smile.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Fixed the `Hero` image border radius when rendering a `picture` element.

.changeset/neat-lists-align.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Fixed `NavList` indentation across grouped nested disclosure levels.

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

@@ -19,6 +19,7 @@ import {
   ActionMenuMenuAlignmentProp,
   ActionMenuMenuSideProp,
   ActionMenuModeProp,
+  ActionMenuButtonVariantsProp,
 } from './react'
 
 ```js
@@ -77,11 +78,6 @@ render(<App />)
 
 In this `mode`, the `ActionMenu` can be shown as a split button with an action (left) and dropdown button (right) with an additional list of actions.
 
-<Note>
-  In split-button mode, each action must be rendered as a link element using the as="a" prop, including the main button
-  and all menu items.
-</Note>
-
 ```jsx live
 <ActionMenu mode="split-button">
   <ActionMenu.Button variant="subtle" as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
@@ -144,11 +140,14 @@ In this `mode`, the `ActionMenu` can be shown as a split button with an action (
 
 ### ActionMenu.Button <Label>Required</Label>
 
-| name        | type           | default | required | description                        |
-| ----------- | -------------- | ------- | -------- | ---------------------------------- |
-| `className` | `string`       |         |          | Sets a custom class on the element |
-| `children`  | `ReactElement` |         |          |
-| `id`        | `string`       |         |          | Sets a custom `id`                 |
+| name            | type                             | default     | required | description                                      |
+| --------------- | -------------------------------- | ----------- | -------- | ------------------------------------------------ |
+| `className`     | `string`                         |             |          | Sets a custom class on the element               |
+| `children`      | `ReactElement`                   |             |          |                                                  |
+| `id`            | `string`                         |             |          | Sets a custom `id`                               |
+| `variant`       | <ActionMenuButtonVariantsProp /> |             | `false`  | Sets the button styling variation                |
+| `onClick`       | `(event: MouseEvent) => void`    | `undefined` | `false`  | Handles activation of the button                 |
+| `leadingVisual` | `ReactElement`                   | `undefined` | `false`  | Renders a leading visual before the button label |
 
 ### ActionMenu.Overlay <Label>Required</Label>
 

apps/next-docs/content/components/ActionMenu/react.tsx

@@ -6,6 +6,9 @@ import {ActionMenuButtonModes} from '../../../../../packages/react/src/ActionMen
 export const ActionMenuSizesProp = () => <PropTableValues values={['small', 'medium']} commaSeparated />
 export const ActionMenuSelectionVariantProp = () => <PropTableValues values={['single', 'none']} commaSeparated />
 export const ActionMenuMenuAlignmentProp = () => <PropTableValues values={['start', 'end']} commaSeparated />
+export const ActionMenuButtonVariantsProp = () => (
+  <PropTableValues values={['primary', 'secondary', 'subtle']} commaSeparated />
+)
 
 export const ActionMenuMenuSideProp = () => (
   <PropTableValues

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

@@ -19,7 +19,7 @@ import dontVisuals from './images/dont-visuals-size.png'
 
 Use rivers to showcase features and introduce topics. Rivers are composed of images or videos paired alongside text content like headings, paragraphs, and links.
 
-A river’s content should be short and concise, no longer than 3 or 4 sentences and in a single paragraph when possible.
+A river’s content should be short and concise, no longer than 160 characters, and contained in a single paragraph when possible.
 
 <DoDontContainer>
   <Do>
@@ -34,20 +34,9 @@ A river’s content should be short and concise, no longer than 3 or 4 sentences
 
 ### Stacked
 
-Two or more rivers can be stacked to guide the user through a set of features. When stacking rivers, alternate between left and right alignments to create a more dynamic reading flow. When alternating alignments, use a `40:60` image to text ratio, otherwise keep the ratio to `50:50`.
+Two or more rivers can be stacked to guide the user through a set of features. Keep rivers in a stack consistently aligned to create a predictable reading flow. For gridline rivers, always use start alignment. Don't use zig-zag layouts.
 
-It is possible to use 2 or more following left or right river to create a simple alignment promoting easy scroll scan.
-
-<DoDontContainer>
-  <Do>
-    <img alt="" src="https://github.com/primer/brand/assets/912236/a7f8bca8-78e6-4e29-a44b-5a305ffeeeae" />
-    <Caption>Alternate rivers with left and right alignments.</Caption>
-  </Do>
-  <Dont>
-    <img alt="" src="https://github.com/primer/brand/assets/6951037/169d5c19-67f4-4f15-8e3b-80c877b34af1" />
-    <Caption>Don't break the flow in a stack of rivers that would otherwise stay aligned.</Caption>
-  </Dont>
-</DoDontContainer>
+Prefer the default 50:50 image-to-text ratio where possible. Use 60:40 only when the visual needs more space or emphasis.
 
 Note that too many rivers can make the design feel repetitive. In that situation, consider introducing a breakout section or break the content with a different component, such as [pillar](/components/Pillar) or [card](/components/Card) to provide a better visual hierarchy and experience. For example, use the river for the top features you want to highlight and then use pillars to showcase the rest.
 
@@ -179,7 +168,7 @@ The image is automatically styled to fit the width of the parent container. If y
 
 - We recommend using a river left as the first river of the flow to start with a visual and avoid stacking text with above section on mobile
 - River components stacks create a unit, the set should be considered to be the main parent section. The parent section should be spaced as a regular section with the largest spacing while internal elements should use smaller spacing
-- If the image is critical for the user to understand the message, default to right aligned. If the text is critical for the user to understand the image, choose left aligned.
+- For a standalone river, choose its alignment based on whether the visual or text needs emphasis. Keep every river in a stack consistently aligned.
 
 ### Link