Merge branch 'main' into rezrah/add-native-actionmenu-hero

Author: rezrah

.changeset/clear-pages-compose.md

@@ -7,3 +7,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.
+- Improved guidance on imagery used in `Hero` and `River` components

.changeset/fix-esm-control-color-tokens.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Fixed missing styles for ESM form controls, where the dependent design tokens were missing . Affects `TextInput`, `Textarea`, `Select`, `Checkbox`, `Radio`, and `FormControl`.

.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.

packages/mcp/content/page-design.md

@@ -65,17 +65,39 @@ Resolve exact sizes and weights with `primer_brand_tokens`.
 
 ## Component & element patterns
 
+### Generated dither backgrounds
+
+**Always pair dither with product UI.** Dither is a supporting background texture, never standalone media or content.
+
+- Use two separate layers for every product UI visual: a dither background and a contained product-shot foreground. Keep them as distinct layers, never one flattened image.
+- Treat a solid subtle/gray surround as placeholder-only. Replace the entire surrounding surface with dither.
+- When no screenshot is provided, proactively create one lightweight, representative product UI mockup to show that product imagery matters and that the user should replace it with their own screenshot.
+- When product UI does not fit the brief, use a relevant non-dither wallpaper, approved illustration, or video.
+- Apply dither only as the background of an outer media wrapper.
+- Never pass dither to `Hero.Image`, `Image`, `<img>`, or `<picture>`, or make it the direct image child of `River.Visual`.
+- Layer the product shot above the dither, leaving dither visible around it.
+- In Hero media, make the dither wrapper span the full viewport width.
+- In River media, make the dither wrapper fill the `River.Visual` cell.
+
 ### 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.
+- Every Hero must include relevant visual media and a label unless the brief explicitly requires a text-only Hero.
+- A missing input screenshot is not a reason to omit Hero media.
+- For one non-product media asset, use `Hero.Image` / `Hero.Video`.
+- For product UI, use the two-layer treatment in **Generated dither backgrounds**. Do not render product UI directly through `Hero.Image`.
+- Place a product UI media band immediately after the Hero copy.
+- Constrain only the product-shot foreground to the shared content-grid width; the full-width media band is not permission to make the product shot itself bleed full-width.
+- Use a single flattened, precomposed landscape image only when the brief explicitly requires one.
 - 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.
+- Finish a Hero as text and actions only because the brief did not provide an image.
+- Add irrelevant hero media, or use social or open-graph templates for hero media.
+- Put dither behind the Hero copy, inside `Hero.Image`, inside the content grid, or in a flattened product shot. The dither is the full-bleed media-band background; the product shot is the contained foreground.
 - Let decorative or illustrative Hero media grow arbitrarily tall or bleed outside the shared grid.
 
 ### River
@@ -85,10 +107,15 @@ Resolve exact sizes and weights with `primer_brand_tokens`.
 - 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.
+- When a River explains a product feature, prefer real product UI over a standalone wallpaper.
+- For River product UI, use the two-layer treatment in **Generated dither backgrounds** inside `River.Visual`.
+- Use a standalone non-dither wallpaper only when no meaningful product UI can demonstrate the feature.
 
 **Don't**
 
 - Zigzag gridline Rivers with `align="end"`.
+- Render dither as the direct image child of `River.Visual`; it must cover the full visual cell as the background behind a separate product shot.
+- Use a wallpaper as the only River visual when a product shot would communicate the feature; wallpaper-only product Rivers read as placeholders.
 
 ### Repeated panels
 

packages/mcp/src/review/rules.test.ts

@@ -71,6 +71,102 @@ describe('primer_brand_review rules', () => {
     expect(ruleIds(findings)).not.toContain('balanced-cta-image')
   })
 
+  it('flags a Hero with no visual media', () => {
+    expect(ruleIds(review('<Hero><Hero.Heading>Build</Hero.Heading></Hero>'))).toContain('hero-requires-media')
+  })
+
+  it.each([
+    '<Hero><Hero.Heading>Build</Hero.Heading><Hero.Image src={image} alt="Product UI" /></Hero>',
+    '<Hero><Hero.Heading>Build</Hero.Heading><Hero.Video src={video} /></Hero>',
+    "import heroDither from './dither.png'\nimport heroShot from './shot-checks.png'\n<Hero><Hero.Heading>Build</Hero.Heading></Hero><div style={{backgroundImage: `url(${heroDither})`}}><img src={heroShot} alt=\"Product UI\" /></div>",
+  ])('allows a Hero with visual media: %s', code => {
+    expect(ruleIds(review(code))).not.toContain('hero-requires-media')
+  })
+
+  it('flags product UI rendered directly in Hero.Image without dither', () => {
+    const code =
+      'import securityOverview from "./security-overview.svg"\n<Hero><Hero.Image src={securityOverview} alt="Security dashboard" /></Hero>'
+    expect(ruleIds(review(code))).toContain('product-shot-needs-dither')
+  })
+
+  it('flags product UI rendered directly in River.Visual without dither', () => {
+    const code =
+      'import securityOverview from "./security-overview.svg"\n<River.Visual><img src={securityOverview} alt="Security dashboard" /></River.Visual>'
+    expect(ruleIds(review(code))).toContain('product-shot-needs-dither')
+  })
+
+  it('allows a product shot layered over a dither background', () => {
+    const code =
+      'import securityOverview from "./security-overview.svg"\nimport heroDither from "./hero-dither.png"\n<Hero><Hero.Heading>Security</Hero.Heading></Hero><div style={{backgroundImage: `url(${heroDither})`}}><img src={securityOverview} alt="Security dashboard" /></div>'
+    expect(ruleIds(review(code))).not.toContain('product-shot-needs-dither')
+  })
+
+  it('does not flag decorative media when only an unrelated attribute contains a product word', () => {
+    const code =
+      'import abstractArt from "./abstract.svg"\n<Hero><Hero.Image src={abstractArt} alt="Abstract illustration" className="product-grid" /></Hero>'
+    expect(ruleIds(review(code))).not.toContain('product-shot-needs-dither')
+  })
+
+  it('does not flag a decorative illustration whose filename contains "overview"', () => {
+    const code =
+      'import overviewGraphic from "./overview-illustration.svg"\n<River.Visual><img src={overviewGraphic} alt="Section illustration" /></River.Visual>'
+    expect(ruleIds(review(code))).not.toContain('product-shot-needs-dither')
+  })
+
+  it('flags product UI detected from the src binding name', () => {
+    const code = 'import productShot from "./hero-2.png"\n<Hero><Hero.Image src={productShot} alt="" /></Hero>'
+    expect(ruleIds(review(code))).toContain('product-shot-needs-dither')
+  })
+
+  it('flags the archived Advanced Security Hero product shot (exact source)', () => {
+    const code =
+      'import securityOverview from "./security-overview.svg"\n<Hero.Image src={securityOverview} alt="GitHub security overview showing code scanning alerts, blocked secrets, and autofix acceptance" />'
+    expect(ruleIds(review(code))).toContain('product-shot-needs-dither')
+  })
+
+  it('flags a bare River product shot even when another Hero shot is correctly dithered', () => {
+    const code = [
+      'import heroDither from "./hero-dither.png"',
+      'import securityOverview from "./security-overview.svg"',
+      'import consoleShot from "./console.svg"',
+      '<Hero>',
+      '  <Hero.Heading>Security</Hero.Heading>',
+      '  <div style={{backgroundImage: `url(${heroDither})`}}>',
+      '    <img src={securityOverview} alt="Security overview with code scanning alerts" />',
+      '  </div>',
+      '</Hero>',
+      '<River>',
+      '  <River.Visual>',
+      '    <img src={consoleShot} alt="Console dashboard showing secret scanning" />',
+      '  </River.Visual>',
+      '</River>',
+    ].join('\n')
+    const productShotFindings = review(code).filter(finding => finding.rule === 'product-shot-needs-dither')
+    expect(productShotFindings).toHaveLength(1)
+    expect(productShotFindings[0]?.evidence).toContain('consoleShot')
+  })
+
+  it('treats a CSS Module class that paints dither as a covered background', () => {
+    const code =
+      'import styles from "./Hero.module.css"\nimport productShot from "./dashboard.png"\n<div className={styles.mediaBand}><img src={productShot} alt="Product dashboard" /></div>\n.mediaBand { background-image: url("./hero-dither.png"); }'
+    expect(ruleIds(review(code))).not.toContain('product-shot-needs-dither')
+  })
+
+  it.each([
+    'import heroDither from \'./assets/hero-dither.png\'\n<Hero.Image src={heroDither} alt="" />',
+    'const riverDither = asset\n<River.Visual><img src={riverDither} alt="" /></River.Visual>',
+  ])('flags dither rendered as image content: %s', code => {
+    const findings = review(code)
+    expect(ruleIds(findings)).toContain('dither-as-image')
+    expect(findings.filter(finding => finding.rule === 'dither-as-image')).toHaveLength(1)
+  })
+
+  it('allows dither as a background behind a separate product shot', () => {
+    const code =
+      'import heroDither from \'./assets/hero-dither.png\'\n<div style={{backgroundImage: `url(${heroDither})`}}><img src={productShot} alt="Product UI" /></div>'
+    expect(ruleIds(review(code))).not.toContain('dither-as-image')
+  })
+
   it('accepts valid, on-brand usage with no errors', () => {
     const findings = review('<Hero align="center"><Hero.Heading>Build</Hero.Heading></Hero>')
     expect(errorsOf(findings)).toHaveLength(0)

packages/mcp/src/review/rules.ts

@@ -148,6 +148,141 @@ const balancedCtaRequiresImage: Rule = {
   },
 }
 
+/** Heroes require visual media unless the brief explicitly says otherwise. */
+const heroRequiresMedia: Rule = {
+  id: 'hero-requires-media',
+  requiresAssetGenerator: true,
+  run(code) {
+    const hasLayeredProductMedia =
+      /dither/i.test(code) &&
+      /(?:product[-_ ]?(?:shot|image)|(?:hero|product)Shot|shot[-_])/i.test(code) &&
+      /background(?:-image|Image)/i.test(code)
+    const findings: Finding[] = []
+    for (const match of code.matchAll(/<Hero\b[^>]*>([\s\S]*?)<\/Hero>/g)) {
+      if (/<Hero\.(?:Image|Video)\b/.test(match[1] ?? '') || hasLayeredProductMedia) continue
+      findings.push({
+        severity: 'warning',
+        rule: this.id,
+        message:
+          'This Hero has no visual media. Heroes require `Hero.Image`, `Hero.Video`, or a deliberate full-width dither background with a separate product-shot foreground unless the brief explicitly asks for text only.',
+        evidence: evidence(match[0]),
+      })
+    }
+    return findings
+  },
+}
+
+/** Product-looking media must use the required dither background treatment. */
+const productShotNeedsDither: Rule = {
+  id: 'product-shot-needs-dither',
+  run(code) {
+    // Words that mean "this is real product UI" — layout bits plus GitHub feature names.
+    const productToken =
+      /product[-_ ]?(?:shot|ui|screenshot)|screenshot|dashboard|console|panel|editor|settings|mockup|ui[-_]?shot|app[-_ ]?(?:ui|screenshot)|security|code[-_ ]?scanning|scanning|secrets?|\balerts?\b|autofix|dependabot|codeql|vulnerabilit|pull[-_ ]?request/i
+
+    // ...and the giveaways that it's just decoration. This is what keeps security-overview.svg
+    // (product) apart from overview-illustration.svg (decorative).
+    const decorativeToken =
+      /illustration|illustrative|abstract|wallpaper|pattern|decorative|texture|gradient|\blogo\b|logomark|\bicon\b|avatar|headshot/i
+
+    // Remember each import's path so we can peek at the filename later.
+    const importPath = new Map<string, string>()
+    for (const match of code.matchAll(/import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+)['"]/gi)) {
+      const [, binding, path] = match
+      if (binding && path !== undefined) importPath.set(binding, path)
+    }
+
+    // CSS classes that paint dither, so a CSS Module wrapper counts too — not just inline styles.
+    const ditherClasses = new Set<string>()
+    for (const match of code.matchAll(/\.(-?[A-Za-z_][\w-]*)\s*\{([^}]*)\}/g)) {
+      const [, cls, body] = match
+      if (cls && body && /background/i.test(body) && /dither/i.test(body)) ditherClasses.add(cls)
+    }
+
+    const openTagPaintsDither = (openTag: string): boolean => {
+      if (/background(?:-image|Image)/.test(openTag) && /dither/i.test(openTag)) return true
+      const classMatch = openTag.match(/class(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\})/)
+      const classValue = classMatch?.[1] ?? classMatch?.[2] ?? classMatch?.[3] ?? ''
+      if (!classValue) return false
+      if (/dither/i.test(classValue)) return true
+      return [...ditherClasses].some(cls => new RegExp(`\\b${escapeRegExp(cls)}\\b`).test(classValue))
+    }
+
+    // Walk the tags once and jot down where each dither wrapper starts and ends.
+    const voidElement = /^(?:img|source|br|input|hr|area|col|embed|track|wbr|meta|link)$/i
+    const ditherRanges: Array<[number, number]> = []
+    const openWrappers: Array<{dither: boolean; start: number}> = []
+    for (const match of code.matchAll(/<(\/?)([A-Za-z][\w.]*)\b[^>]*?(\/?)>/g)) {
+      const [, closing, name, selfClose] = match
+      if (selfClose === '/' || (name !== undefined && voidElement.test(name))) continue
+      if (closing === '/') {
+        const opened = openWrappers.pop()
+        if (opened?.dither) ditherRanges.push([opened.start, match.index + match[0].length])
+      } else {
+        openWrappers.push({dither: openTagPaintsDither(match[0]), start: match.index})
+      }
+    }
+    // Never closed? Treat it as covering everything after it.
+    for (const opened of openWrappers) {
+      if (opened.dither) ditherRanges.push([opened.start, code.length])
+    }
+    const insideDitherWrapper = (index: number): boolean =>
+      ditherRanges.some(([start, end]) => index > start && index < end)
+
+    const altText = (tag: string): string => tag.match(/\balt\s*=\s*["']([^"']*)["']/i)?.[1] ?? ''
+    const srcBinding = (tag: string): string => tag.match(/\bsrc\s*=\s*\{([A-Za-z_$][\w$]*)\}/)?.[1] ?? ''
+    const srcLiteral = (tag: string): string => tag.match(/\bsrc\s*=\s*["']([^"']*)["']/i)?.[1] ?? ''
+
+    const findings: Finding[] = []
+    for (const match of code.matchAll(/<(?:Hero\.Image|Image|img|picture)\b[^>]*>/g)) {
+      const tag = match[0]
+      const binding = srcBinding(tag)
+      // Go on what describes the image — alt, src binding, filename — not stray attrs like className.
+      const signals = [altText(tag), binding, importPath.get(binding) ?? '', srcLiteral(tag)]
+      const looksLikeProduct = signals.some(signal => productToken.test(signal))
+      const isDecorative = signals.some(signal => decorativeToken.test(signal))
+      if (!looksLikeProduct || isDecorative) continue
+      if (insideDitherWrapper(match.index)) continue
+      findings.push({
+        severity: 'warning',
+        rule: this.id,
+        message:
+          'Product UI must not use a default/subtle gray media surface. Put the product shot in a contained foreground layer and replace the entire surrounding media background with full-width dither.',
+        evidence: evidence(tag),
+      })
+    }
+    return findings
+  },
+}
+
+/** Dither is supporting background texture, never the image content itself. */
+const ditherAsImage: Rule = {
+  id: 'dither-as-image',
+  run(code) {
+    const ditherBindings = new Set<string>()
+    for (const match of code.matchAll(/import\s+([A-Za-z_$][\w$]*)\s+from\s+['"][^'"]*dither[^'"]*['"]/gi)) {
+      if (match[1]) ditherBindings.add(match[1])
+    }
+
+    const findings: Finding[] = []
+    for (const match of code.matchAll(/<(?:Hero\.Image|Image|img|source)\b[^>]*>/gi)) {
+      const tag = match[0]
+      const usesDitherBinding = [...ditherBindings].some(binding =>
+        new RegExp(`\\b(?:src|srcSet)\\s*=\\s*\\{[^}]*\\b${escapeRegExp(binding)}\\b`).test(tag),
+      )
+      if (!/dither/i.test(tag) && !usesDitherBinding) continue
+      findings.push({
+        severity: 'error',
+        rule: this.id,
+        message:
+          'Dither must never be rendered as image content. Use it only as an edge-to-edge background behind a separate, contained product shot; if no product screenshot is available, omit the dither.',
+        evidence: evidence(tag),
+      })
+    }
+    return findings
+  },
+}
+
 type RawPattern = {
   id: string
   test: RegExp
@@ -325,6 +460,9 @@ export const allRules: Rule[] = [
   invalidPropValue,
   invalidPropCombination,
   balancedCtaRequiresImage,
+  heroRequiresMedia,
+  productShotNeedsDither,
+  ditherAsImage,
   rawHtml,
   hardcodedValues,
   offBrandTells,

packages/mcp/src/review/types.ts

@@ -12,6 +12,8 @@ export type Finding = {
 
 export type Rule = {
   id: string
+  /** When set, the rule only runs if the GitHub Asset Generator MCP tools are available (internal GitHub use). */
+  requiresAssetGenerator?: boolean
   run(code: string, catalog: Catalog): Finding[]
 }
 

packages/mcp/src/server.ts

@@ -19,15 +19,17 @@ Use these tools whenever a project builds marketing/landing pages, or depends on
 This is NOT @primer/react (GitHub's product UI library); if you are building application/product UI,
 use the Primer (product) tools instead.
 
-Typical flow: primer_brand_setup once at the start of a new page or project, primer_brand_examples to start
-from correct patterns, primer_brand_component for exact props, primer_brand_tokens / primer_brand_asset for tokens and
-icons, primer_brand_docs for guidance, and primer_brand_review as the final gate over your complete output (JSX and
+Typical flow: \`primer_brand_setup\` once at the start of a new page or project, \`primer_brand_examples\` to start
+from correct patterns, \`primer_brand_component\` for exact props, \`primer_brand_tokens\` / \`primer_brand_asset\` for tokens and
+icons, \`primer_brand_docs\` for guidance, and \`primer_brand_review\` as the final gate over your complete output (JSX and
 CSS together) before you finish.
 
 ${
   assetGenerator.available
-    ? `Use the GitHub Asset Generator MCP tools (\`asset-generator\`) instead of stock photos or AI art. Use Asset Generator
-for wallpapers, hero or river background images, and product shots.`
+    ? `Use the GitHub Asset Generator MCP tools (\`asset-generator\`) instead of stock photos or AI art. For product UI,
+  call \`create_dither_patterns\` and \`create_full_screen_product_shot\` as a pair, keep the files separate, and render full-width
+  dither behind the contained product shot. Never use dither alone. If no screenshot exists, proactively create one lightweight,
+  representative mockup. Use non-dither media when product UI does not fit. Read \`primer_brand_page_design\` for placement.`
     : ''
 }
 `