[Docs] Add Figma images support

[danielguillan]

Summary

Resolves https://github.com/github/brand-experience/issues/428

Adds support for embedding Figma frames in Primer Brand docs pages and thumbnails, with generated images committed to the repository.

This ports the existing Primer Docs workflow and adapts it with stricter discovery and validation for Brand content.

Authors reference a Figma frame through <FigmaImage> or page frontmatter. The generation script discovers and downloads those frames, while CI verifies that the URLs and committed assets remain in sync without requiring Figma access during a docs build.

List of notable changes:

• added local generation, a manual workflow that opens a draft image update PR, and an update figma images label workflow that regenerates previews and commits them to the current PR branch
• restricted image sources to the Brand Interface Guidelines Figma file
• added token-free CI validation for invalid URLs, missing images or dimensions, and stale generated files
• added light and dark mode sources with fallbacks and mode-aware “Edit in Figma” links
• added AST-based MDX and YAML discovery instead of regular expressions, avoiding matches in code examples or unrelated content
  • Note that the required packages were already in the lockfile: remark-frontmatter, unist-util-visit, and yaml through nextra; and unified, remark-parse, remark-mdx, and unist-util-visit through @mdx-js/mdx.

What should reviewers focus on?

• Review the Figma URL discovery and validation rules.
• Verify light and dark previews, fallbacks, captions, and edit links in the docs preview.

Steps to test:

1. Open the CTA Banner docs page in the CI preview and switch between light and dark modes.
2. Run npm run figma-images:validate --workspace=apps/next-docs.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 761aabb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[github-actions]

🟢 No design token changes found

[github-actions]

🟢 Bundle size report

Check	Main	Branch	Change
UMD — full bundle (JS)	101.39 kB	101.39 kB	🟢 No change
UMD — full bundle (CSS)	66.98 kB	66.98 kB	🟢 No change
ESM — full bundle (JS + CSS)	1.52 MB	1.52 MB	🟢 No change
ESM — tree-shaken simple (Button)	70.28 kB	70.28 kB	🟢 No change
ESM — tree-shaken complex (ActionMenu)	79.17 kB	79.17 kB	🟢 No change

[github-actions]

🟢 No visual differences found

Our visual comparison tests did not find any differences in the UI.

[Copilot]

Pull request overview

Adds first-class support for embedding and validating Figma frame previews in the Primer Brand docs app (apps/next-docs), including a generator/validator workflow and updated docs pages that adopt the new FigmaImage component.

Changes:

• Introduces a FigmaImage MDX component (with light/dark sources, captions, and “Edit in Figma” links) plus server-side resolution of committed preview assets.
• Adds AST-based MDX/YAML discovery + URL validation + asset verification scripts, with a local generate command and token-free CI validation.
• Adds GitHub Actions workflows to generate/update committed Figma previews (manual and “update figma images” label driven), and documents the workflow in contributor docs.

Show a summary per file

File	Description
package-lock.json	Updates workspace versions and adds dependencies required for MDX parsing/validation and @primer/figma-images.
CONTRIBUTING.md	Documents how to reference Figma frames and update/validate generated assets.
apps/next-docs/src/components/FigmaImage/FigmaImagePreview.tsx	Client-side preview rendering with missing-preview fallback UI and dimension handling.
apps/next-docs/src/components/FigmaImage/FigmaImageEditLink.tsx	Client-side “Edit in Figma” link tied to the active (light/dark) source.
apps/next-docs/src/components/FigmaImage/FigmaImage.utils.ts	Shared utilities for choosing active sources/edit URLs and preserving aspect ratios.
apps/next-docs/src/components/FigmaImage/FigmaImage.types.ts	Defines the resolved source shape passed between server/client components.
apps/next-docs/src/components/FigmaImage/FigmaImage.tsx	Main MDX component composing preview + edit link + caption, with alt/presentation rules.
apps/next-docs/src/components/FigmaImage/FigmaImage.server.mjs	Resolves Figma URLs to committed local assets and maps pageMap thumbnails accordingly.
apps/next-docs/src/components/FigmaImage/FigmaImage.module.css	Styling for previews, captions, missing states, and the hover/focus edit link affordance.
apps/next-docs/scripts/figma-images.test.mjs	Node-test coverage for discovery, validation, generation/asset verification, and key utilities.
apps/next-docs/scripts/figma-images.mjs	Implements MDX/YAML AST discovery, URL validation rules, and asset verification + generate/validate CLI.
apps/next-docs/public/images/figma/images.json	Adds the generated manifest mapping node basenames to filenames/dimensions.
apps/next-docs/package.json	Wires up generate/validate scripts, runs validation in check, and adds a workspace test script.
apps/next-docs/mdx-components.js	Registers FigmaImage for MDX pages.
apps/next-docs/content/components/CTABanner/index.mdx	Switches an anatomy image to use <FigmaImage> with light/dark sources and caption.
apps/next-docs/content/components/Card/index.mdx	Switches thumbnails to Figma-backed URLs (light/dark) for generation/validation.
apps/next-docs/app/layout.tsx	Maps Figma-backed thumbnails in the doctocat page map to committed asset URLs.
.github/workflows/update_figma_images.yml	Adds a manual workflow to regenerate previews on main and open a draft PR if assets change.
.github/workflows/update_figma_images_on_label.yml	Adds a pull_request_target workflow to regenerate previews and commit them back to the PR branch when labeled.
.github/copilot-instructions.md	Adds repo guidance that Figma images are generated artifacts and must be regenerated, not edited manually.

Review details

• Files reviewed: 19/24 changed files
• Comments generated: 3
• Review effort level: Low

[Copilot]

Review details

Comments suppressed due to low confidence (2)

apps/next-docs/src/components/FigmaImage/FigmaImage.server.mjs:49

• In both the “missing generated preview” and “success” branches, editUrl is set to the raw url input. If an author passes a relative or protocol-relative URL, the rendered “Edit in Figma” link can point to the docs site (or an unexpected host) instead of Figma. Using the normalized URL here keeps the link consistent with the URL parsing logic used to resolve the asset.

      return {
        editUrl: url,
        width: manifestEntry?.width,
        height: manifestEntry?.height,
        missingReason: 'The generated preview image is missing for this Figma frame.',

apps/next-docs/src/components/FigmaImage/FigmaImage.server.mjs:63

• In the catch fallback, editUrl is returned as the original url input. Since this value is used as an anchor href, a malformed/non-Figma URL can become a clickable link. Use a safe default (or omit the edit link) when URL normalization/parsing throws.

    return {
      editUrl: url,
      missingReason: 'The selected Figma frame URL could not be parsed.',
    }

• Files reviewed: 19/24 changed files
• Comments generated: 2
• Review effort level: Low