River component updates

[danielguillan]

Summary

Towards https://github.com/github/brand-marketing-design/issues/2606

Aligns the River component to the 2026 brand refresh.

🔗 Storybook

List of notable changes:

Based on the changes made (renamed bordered-grid to gridline, replaced hasBackground with imageBackgroundColor), here's the updated description:

• Added new EyebrowText component, a simplified text label for use above headings
• Applies backwards compatible updates to the River
• Added new props and variants that can be opted into:
  • Added variant prop with gridline option
  • Added imageBackgroundColor prop on River.Visual for full-bleed container with subtle background
  • Added align prop on River.Content for optional block-end vertical alignment
  • Added support for EyebrowText as a child of River.Content
• Slots for applying dither animations via ref on River.Visual

What should reviewers focus on?

• Review the 'default' River examples, and review whether the changes are in fact backwards compatible
• Review design accuracy of the new River variants (bordered-grid)
• Verify the hasBackground visual treatment at different viewport sizes (mobile, tablet, desktop)

Steps to test:

Contributor checklist:

• All new and existing CI checks pass
• Tests prove that the feature works and covers both happy and unhappy paths
• Any drop in coverage, breaking changes or regressions have been documented above
• UI Changes contain new visual snapshots (generated by adding update snapshots label to the PR)
• All developer debugging and non-functional logging has been removed
• Related issues have been referenced in the PR description

Reviewer checklist:

• Check that pull request and proposed changes adhere to our contribution guidelines and code of conduct
• Check that tests prove the feature works and covers both happy and unhappy paths
• Check that there aren't other open Pull Requests for the same update/change

[changeset-bot]

🦋 Changeset detected

Latest commit: 9d3c0db

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 8 packages

Name	Type
@primer/react-brand	Minor
@primer/brand-primitives	Minor
@primer/brand-docs	Minor
@primer/brand-css	Minor
@primer/brand-e2e	Minor
@primer/brand-fonts	Minor
@primer/brand-config	Minor
@primer/brand-storybook	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🔍 Design token changes found

View CSS variable changes

+ --brand-RiverBreakout-variant-gridline-spacing-contentGap: var(--base-size-16);

+ --brand-RiverBreakout-variant-gridline-spacing-outerInline: var(--base-size-20);

+ --brand-RiverBreakout-variant-gridline-spacing-outerBlockEnd: var(--base-size-40);

+ --brand-RiverBreakout-variant-gridline-spacing-outerBlock: var(--base-size-36);

- --brand-River-spacing-outer: var(--base-size-36);
+ --brand-River-variant-gridline-spacing-outerInline: var(--base-size-20);

+ --brand-River-variant-gridline-spacing-outerBlock: var(--base-size-40);

+ --brand-River-spacing-outerBlock: var(--base-size-36);

- --brand-River-spacing-inner: var(--base-size-24);
+ --brand-River-spacing-inner: var(--base-size-40);

+ --brand-RiverBreakout-variant-gridline-spacing-contentGap: var(--base-size-20);

+ --brand-RiverBreakout-variant-gridline-spacing-outerInline: var(--base-size-36);

+ --brand-RiverBreakout-variant-gridline-spacing-outerBlockEnd: var(--base-size-48);

+ --brand-RiverBreakout-variant-gridline-spacing-outerBlock: var(--base-size-40);

+ --brand-RiverBreakout-variant-gridline-spacing-contentGap: var(--base-size-24);

+ --brand-RiverBreakout-variant-gridline-spacing-outerInline: var(--base-size-64);

+ --brand-RiverBreakout-variant-gridline-spacing-outerBlockEnd: var(--base-size-80);

+ --brand-RiverBreakout-variant-gridline-spacing-outerBlock: var(--base-size-64);

- --brand-River-spacing-outer: var(--base-size-48);
+ --brand-River-variant-gridline-spacing-outerInline: var(--base-size-64);

+ --brand-River-variant-gridline-spacing-outerBlock: var(--base-size-64);

+ --brand-River-spacing-outerBlock: var(--base-size-48);

- --brand-River-spacing-inner: var(--base-size-48);
+ --brand-River-spacing-inner: var(--base-size-24);

[github-actions]

🟢 Unit test coverage changes found

Unit test coverage has been updated through this PR.

Changes: 1 new tests, 0 removed tests, 2 improved, 0 decreased

Component/Hook	Statements	Functions	Branches	Change
EyebrowText	100.0%	100.0%	100.0%	NEW
River	100.0%	100.0%	98.0% 98.4%	+0.4%
RiverBreakout	100.0%	100.0%	76.9% 81.3%	+4.3%

[github-actions]

⚠️ Visual differences found

Our visual comparison tests found UI differences.

Please review the differences by using the test artifacts to ensure that the changes were intentional.

Artifacts can be downloaded and reviewed locally.

Download links are available at the bottom of the workflow summary screen.

Example:

If the changes are expected, please run npm run test:visual:update-snapshots to replace the previous fixtures.

Review visual differences

[Copilot]

Pull request overview

This PR implements the 2026 brand refresh for the River component with backwards-compatible updates and introduces a new EyebrowText component.

Changes:

• Added new EyebrowText component for use as a small text label above headings
• Introduced variant prop to River with new gridline option for bordered grid layouts
• Added imageBackgroundColor prop to River.Visual for background treatments
• Updated River spacing design tokens and added support for new variants

Reviewed changes

Copilot reviewed 10 out of 567 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/react/src/EyebrowText/*	New component files including implementation, tests, stories, and styles
packages/design-tokens/src/tokens/functional/components/river/river.json	Updated spacing tokens and added gridline variant configuration
apps/next-docs/content/components/River/react.mdx	Documentation for new River variants and imageBackgroundColor prop
apps/next-docs/content/components/River/react.tsx	Export new defaultRiverVariant constant
.changeset/wide-seed-sky.md	Release notes describing new features

[simmonsjenna]

@danielguillan These three new variants are now getting affected by too much spacing on the left of the copy (intended left/right padding would be balanced for these):

Storybook link

Storybook link

Storybook link

[danielguillan]

@simmonsjenna the current spacing in these is consistent with the designs in Figma. But I understand why it feels unbalanced. Since these variants are non-blocking, I'm happy to revisit the spacing in a follow-up.

Gridline + background + 50:50 — Storybook - Figma

Gridline + background + 60:40 — Storybook - Figma

Dismissing to unblock release. We'll follow up on final fixes as they only affect grid lines.