Skip to content

Remove all deprecated recipes + update MCP tool guidance #1400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rezrah merged 5 commits into from
Jul 21, 2026
Merged

Remove all deprecated recipes + update MCP tool guidance #1400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3baa870
update primer_brand_review guardrails
rezrah Jul 15, 2026
414f152
update annotation
rezrah Jul 15, 2026
02f8c6a
Merge branch 'main' of github.com:primer/brand into rezrah/update-mcp…
rezrah Jul 20, 2026
5e07adb
remove all non-flex-suite recipes
rezrah Jul 20, 2026
d77bae6
add more evals guidance
rezrah Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/clear-pages-compose.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
19 changes: 4 additions & 15 deletions apps/next-docs/content/components/River/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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.

Expand Down Expand Up @@ -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

Expand Down
4 changes: 1 addition & 3 deletions packages/e2e/scripts/playwright/axe-clean.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,6 @@ const testsToSkip = [
'components-videoplayer-features--with-poster', // video makes this too flakey
'components-videoplayer-features--without-branding', // video makes this too flakey
'components-videoplayer--playground', // video makes this too flakey
'recipes-feature-previews-level-1--level-one-side-by-side-enterprise', // video makes this too flakey
'recipes-feature-previews-level-1--level-one-side-by-side', // custom, unrelated background image
'components-eyebrowbanner-features--on-custom-background-dark', // custom, unrelated background image
'components-eyebrowbanner-features--on-custom-background-light', // custom, unrelated background image
'components-subdomainnavbar--skip-to-main-tag', // contains main tag which is in conflict with the default role="main" element
Expand All @@ -60,7 +58,7 @@ const testsToSkip = [

const ignoreViolations = {
'landmark-one-main': {except: []}, // on most of the stories we don't have a main landmark
'page-has-heading-one': {except: ['components-hero', 'recipes-feature-previews']}, // on some stories we dont have a heading,
'page-has-heading-one': {except: ['components-hero']}, // on some stories we dont have a heading,
region: {except: []}, // on most of the stories we don't have a region landmark
}

Expand Down
34 changes: 0 additions & 34 deletions packages/e2e/scripts/playwright/playwright.generate-tests.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,41 +65,11 @@ const waitForTimeoutLookup = {
'components-box-features--animation': 6000, // for the animation
'components-ide--playground': 2000, // for the animation
'components-ide--default': 2000, // for the animation
'recipes-seo-article-page--playground': 5000, // for the animation
'recipes-seo-article-page--all-headings': 5000, // for the animation
'recipes-seo-article-page--ai-theme': 5000, // for the animation
'recipes-seo-article-page--collaboration-theme': 5000, // for the animation
'recipes-seo-article-page--enterprise-theme': 5000, // for the animation
'recipes-seo-article-page--security-theme': 5000, // for the animation
'recipes-seo-article-page--productivity-theme': 5000, // for the animation
'recipes-seo-article-page--light-hero-image': 5000, // for the animation
'recipes-seo-article-page--dark-hero-image': 5000, // for the animation
'recipes-solutions-categorypage--light': 4000, // for the animation
'recipes-solutions-categorypage--dark': 4000, // for the animation
'recipes-solutions-solution-industry--maximum': 3500, // for the animation
'recipes-solutions-solution-industry--maximum-dark': 3500, // for the animation
'recipes-solutions-solution-industry--minimum': 3500, // for the animation
'recipes-solutions-solution-industry--minimum-dark': 3500, // for the animation
'recipes-solutions-solution-org-size--maximum': 3500, // for the animation
'recipes-solutions-solution-org-size--maximum-dark': 3500, // for the animation
'recipes-solutions-solution-org-size--minimum': 3500, // for the animation
'recipes-solutions-solution-org-size--minimum-dark': 3500, // for the animation
'recipes-solutions-solution-use-case--minimum': 2000, // for the footer logos
'recipes-solutions-solution-use-case--minimum-dark': 2000, // for the footer logos
'recipes-solutions-solution-use-case--maximum-dark': 2000, // for the footer logos
'recipes-solutions-solution-use-case--maximum': 2000, // for the footer logos
'recipes-solutions-overview--light': 3500, // for the animation
'recipes-solutions-overview--dark': 3500, // for the animation
'components-riverstoryscroll--default': 3500, // for the animation
'components-riverstoryscroll-features--with-timeline': 3500, // for the animation
'components-riverstoryscroll-features--with-timeline-narrow': 3500, // for the animation
'components-riverstoryscroll-features--enterprise-example': 3500, // for the animation
'components-riverstoryscroll-features--enterprise-example-narrow': 3500, // for the animation
'recipes-feature-previews-level-2--level-two-playground': 4000, // for the animation
'recipes-feature-previews-level-2--level-two-point-one': 4000, // for the animation
'recipes-feature-previews-level-2--level-two-point-two': 4000, // for the animation
'recipes-feature-previews-level-2--level-two-point-three': 4000, // for the animation
'recipes-feature-previews-level-2--level-two-point-four': 4000, // for the animation
'components-textrevealanimation--playground': 3000, // for the animation
'components-textrevealanimation-examples--with-large-testimonial': 3000, // for the animation
'components-textrevealanimation-examples--with-hero': 3000, // for the animation
Expand Down Expand Up @@ -131,9 +101,7 @@ const waitForTimeoutLookup = {
'components-videoplayer-features--tooltip-visible-on-focus': 5000, // for video metadata to load
'components-hero-features-images-and-videos--with-video-block-end-default': 5000, // for video metadata to load
'components-hero-features-images-and-videos--with-video-inline-end': 5000, // for video metadata to load
'recipes-flextemplate-flextemplate--default': 4000, // for video metadata to load
'components-textcursoranimation--playground': 4000, // for the animation to complete
'recipes-flextemplate-flexsection--default': 1000, // longer load time
'components-subnav-features--delayed-active-link': 2000, // because the story sets an initial delay,
'components-logosuite-features--grid-line-expressive-kitchen-sink': 3000, // for the animation to complete
'components-logosuite-features--takeover-button': 3000, // for the animation to complete
Expand Down Expand Up @@ -177,7 +145,6 @@ const skipTestLookup = [
'components-logosuite-features--mixed-width', // animation only
'components-logosuite-features--following-hero', // animation only
'components-logosuite-features--stacked', // animation only
'recipes-feature-previews-level-1--level-one-side-by-side-enterprise', // video makes this too flakey
'components-subdomainnavbar--overflow-menu-open', // flakey despite timeout
'components-ide-features--editor-only', // animation too long
'components-ide-features--editor-no-replay-button', // animation too long
Expand All @@ -187,7 +154,6 @@ const skipTestLookup = [
'components-ide-features--perspective-example-light', // animation too long
'components-ide-features--all-glass', // animation too long
'components-ide-features--editor-custom-icons', // animation too long
'recipes-seo-category-page--default', // template contains randomisation
'components-statistic-features--animations', // animation only
'components-riverstoryscroll-features--video-narrow', // video makes this too flakey
'components-riverstoryscroll-features--video', // video makes this too flakey
Expand Down
Loading
Loading