add more evals guidance

Author: rezrah

.changeset/clear-pages-compose.md

@@ -6,3 +6,4 @@ 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.

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
 

packages/mcp/content/page-design.md

@@ -65,33 +65,123 @@ Resolve exact sizes and weights with `primer_brand_tokens`.
 
 ## Component & element patterns
 
-### Do
-
-- **Heroes** — include relevant media and a label. Prefer a real product shot via `Hero.Image` / `Hero.Video`; use Asset Generator `create_product_landscape` when generating one, or `create_wallpaper` when a product shot does not fit. Keep decorative or illustrative media inside the shared grid with a stable aspect ratio and a token-backed maximum height so it cannot dominate the page or bleed full-width. If needed, place custom media after `Hero`; use `trailingComponent` only when it must live inside the Hero composition.
-- **Rivers** — use `<River variant="gridline" align="start">` throughout a page; omitting `align` also means start.
-- **Repeated panels** — place `Card`, `Pillar`, `Box`, or custom items in a square frame using `<Grid columnGap="none" rowGap="none" enableGutters={false}>`. Draw shared dividers on custom frame/cell wrappers and use `border-radius: 0` there; do not override `Card` or `Pillar` internals. `Pillar` has no grid variant.
-- **CTAs without media** — use the default `CTABanner` with `align="center"` and `hasGridLines`.
-- **CTAs with media** — use `<CTABanner variant="balanced" hasGridLines>` with a direct `CTABanner.Image`. Use Octovisuals for artwork; reserve `CTABanner.Logo` for genuine logos.
-- **Forms** — use a square, zero-gap `Grid` with connected benefits beside a subtle form surface. Use responsive token gutters, Primer Brand form controls, and an enabled `<Button variant="primary" type="submit">`.
-- **FAQs** — use `FAQGroup` navigation for multiple meaningful categories and one `FAQ` directly for a single category.
-- **Section backgrounds** — keep one default background across sections. Use `backgroundColor="subtle"` only to clarify a functional region.
-- **Labels** — use `Hero.Label`, `SectionIntro.Label`, or `EyebrowText`; keep labels intrinsic-width and aligned with their section.
-- **Lists** — use dot bullets without decorative dividers between items.
-- **Buttons** — show enabled controls with a clear primary/secondary hierarchy.
-- **Icons** — keep Octicons at the default green in `Card.Icon`, `Pillar.Icon`, and `Icon` unless there is a deliberate exception.
-
-### Don't
+### Hero
+
+**Do**
+
+- Include relevant media and a label. Prefer a real product shot via `Hero.Image` / `Hero.Video`; use Asset Generator `create_product_landscape` when generating one, or `create_wallpaper` when a product shot does not fit.
+- Keep decorative or illustrative media inside the shared grid with a stable aspect ratio and a token-backed maximum height so it cannot dominate the page or bleed full-width.
+- If needed, place custom media after `Hero`; use `trailingComponent` only when it must live inside the Hero composition.
+
+**Don't**
 
 - Add irrelevant hero media or use social templates such as `create_social_square` or `create_landscape` for hero media.
 - Let decorative or illustrative Hero media grow arbitrarily tall or bleed outside the shared grid.
+
+### River
+
+**Do**
+
+- Use `<River variant="gridline" align="start">` throughout a page; omitting `align` also means start.
+- Keep River descriptions to a maximum of 160 characters.
+- Prefer the default `50:50` image-to-text ratio where possible; set `imageTextRatio="60:40"` only when the visual needs more space or emphasis.
+
+**Don't**
+
 - Zigzag gridline Rivers with `align="end"`.
-- Render repeated panels as separate rounded cards, double their shared borders, override `Card` / `Pillar` radius, or invent a grid variant for `Pillar`.
+
+### Repeated panels
+
+**Do**
+
+- Place `Card`, `Pillar`, `Box`, or custom items in a square frame using `<Grid columnGap="none" rowGap="none" enableGutters={false}>`.
+- Draw shared dividers on custom frame/cell wrappers and use `border-radius: 0` there.
+
+**Don't**
+
+- Render repeated panels as separate rounded cards, double their shared borders, or override `Card` / `Pillar` internals.
+- `Pillar` has no grid variant; don't invent one.
+
+### CTABanner
+
+**Do**
+
+- Without media, use the default `CTABanner` with `align="center"` and `hasGridLines`.
+- With media, use `<CTABanner variant="balanced" hasGridLines>` with a direct `CTABanner.Image`. Use Octovisuals for artwork; reserve `CTABanner.Logo` for genuine logos.
+
+**Don't**
+
 - Use `CTABanner variant="balanced"` without a direct `CTABanner.Image`, or use `CTABanner.Logo` for decorative artwork.
+
+### Forms
+
+**Do**
+
+- Use a square, zero-gap `Grid` with connected benefits beside a subtle form surface. Use responsive token gutters, Primer Brand form controls, and an enabled `<Button variant="primary" type="submit">`.
+
+**Don't**
+
 - Use raw form controls or put the form section in a floating rounded panel.
+
+### FAQs
+
+**Do**
+
+- Use `FAQGroup` navigation for multiple meaningful categories and one `FAQ` directly for a single category.
+
+**Don't**
+
 - Show `FAQGroup` navigation for a single category.
+
+### Section backgrounds
+
+**Do**
+
+- Keep one default background across sections. Use `backgroundColor="subtle"` only to clarify a functional region.
+
+**Don't**
+
 - Alternate section background colors merely for decoration.
-- Stretch Label components full-width or hand-style replacements for the label components. Labels should preserve their auto width, don't let the parent stretch them.
-- Use dashes as bullets, make normal controls look disabled, or tint default-green Octicons without a deliberate reason. `Pillar.Icon` has no `color` prop.
+
+### Labels
+
+**Do**
+
+- Use `Hero.Label`, `SectionIntro.Label`, or `EyebrowText`; keep labels intrinsic-width and aligned with their section.
+
+**Don't**
+
+- Stretch Label components full-width or hand-style replacements for the label components. Labels should preserve their auto width; don't let the parent stretch them.
+
+### Lists
+
+**Do**
+
+- Use dot bullets without decorative dividers between items.
+
+**Don't**
+
+- Use dashes as bullets.
+
+### Buttons
+
+**Do**
+
+- Show enabled controls with a clear primary/secondary hierarchy.
+
+**Don't**
+
+- Make normal controls look disabled.
+
+### Icons
+
+**Do**
+
+- Keep Octicons at the default green in `Card.Icon`, `Pillar.Icon`, and `Icon` unless there is a deliberate exception.
+
+**Don't**
+
+- Tint default-green Octicons without a deliberate reason. `Pillar.Icon` has no `color` prop.
 
 ## Visual verification
 

packages/mcp/src/tools/primer-brand-page-design/primer-brand-page-design.test.ts

@@ -9,10 +9,15 @@ describe('primer_brand_page_design', () => {
     expect(result.text).toContain('gridline')
     expect(result.text).toContain('FlexSuiteAIOverview')
     expect(result.text).toContain('<River variant="gridline" align="start">')
+    expect(result.text).toContain('Keep River descriptions to a maximum of 160 characters')
+    expect(result.text).toContain('Prefer the default `50:50` image-to-text ratio')
+    expect(result.text).toContain('imageTextRatio="60:40"')
     expect(result.text).toContain('`Pillar` has no grid variant')
-    expect(result.text).toContain('### Do')
-    expect(result.text).toContain("### Don't")
-    expect(result.text).toContain('**Repeated panels**')
+    expect(result.text).toContain('### Hero')
+    expect(result.text).toContain('### River')
+    expect(result.text).toContain('**Do**')
+    expect(result.text).toContain("**Don't**")
+    expect(result.text).toContain('### Repeated panels')
     expect(result.text).toContain('`Card`, `Pillar`, `Box`, or custom items')
     expect(result.text).toContain('border-radius: 0')
     expect(result.text).toContain('<CTABanner variant="balanced" hasGridLines>')