diff --git a/Sources/SwiftDocC/Semantics/Metadata/PageImage.swift b/Sources/SwiftDocC/Semantics/Metadata/PageImage.swift
index aae9c3d91..88451fdec 100644
--- a/Sources/SwiftDocC/Semantics/Metadata/PageImage.swift
+++ b/Sources/SwiftDocC/Semantics/Metadata/PageImage.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2022-2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2025 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -14,9 +14,19 @@ public import Markdown
 /// Associates an image with a page.
 ///
 /// You can use this directive to set the image used when rendering a user-interface element representing the page.
-/// For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,
-/// or the card image used to represent this page when using the ``Links`` directive and the ``Links/VisualStyle/detailedGrid``
-/// visual style.
+///
+/// Use the "icon" purpose to customize the icon that DocC uses to represent this page in the navigation sidebar.
+/// For article pages, DocC also uses this icon to represent the article in topics sections and in ``Links`` directives that use the `list` visual style.
+///
+/// > Tip: Page images with the "icon" purpose work best when they're square and when they have good visual clarity at small sizes (less than 20×20 points).
+///
+/// Use the "card" purpose to customize the image that DocC uses to represent this page inside ``Links`` directives that use the either the `detailedGrid` or the `compactGrid` visual style.
+/// For article pages, DocC also incorporates a partially faded out version of the card image in the background of the page itself.
+///
+/// > Tip: Page images with the "card" purpose work best when they have a 16:9 aspect ratio. Currently, the largest size that DocC displays a card image is 640×360 points.
+///
+/// If you specify an "icon" page image without specifying a "card" page image, DocC will use the icon as a fallback in places where the card image is preferred.
+/// To avoid upscaled pixelated icons in these places, either configure a "card" page image as well or use a scalable vector image asset for the "icon" page image.
 public final class PageImage: Semantic, AutomaticDirectiveConvertible {
     public static let introducedVersion = "5.8"
     public let originalMarkup: BlockDirective
diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json
index 8469494a8..ef6eaf073 100644
--- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json
+++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json
@@ -4167,13 +4167,43 @@
             "text" : "You can use this directive to set the image used when rendering a user-interface element representing the page."
           },
           {
-            "text" : "For example, use the page image directive to customize the icon used to represent this page in the navigation sidebar,"
+            "text" : ""
+          },
+          {
+            "text" : "Use the \"icon\" purpose to customize the icon that DocC uses to represent this page in the navigation sidebar."
+          },
+          {
+            "text" : "For article pages, DocC also uses this icon to represent the article in topics sections and in ``Links`` directives that use the `list` visual style."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "> Tip: Page images with the \"icon\" purpose work best when they're square and when they have good visual clarity at small sizes (less than 20×20 points)."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "Use the \"card\" purpose to customize the image that DocC uses to represent this page inside ``Links`` directives that use the either the `detailedGrid` or the `compactGrid` visual style."
+          },
+          {
+            "text" : "For article pages, DocC also incorporates a partially faded out version of the card image in the background of the page itself."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "> Tip: Page images with the \"card\" purpose work best when they have a 16:9 aspect ratio. Currently, the largest size that DocC displays a card image is 640×360 points."
+          },
+          {
+            "text" : ""
           },
           {
-            "text" : "or the card image used to represent this page when using the ``Links`` directive and the ``Links\/VisualStyle\/detailedGrid``"
+            "text" : "If you specify an \"icon\" page image without specifying a \"card\" page image, DocC will use the icon as a fallback in places where the card image is preferred."
           },
           {
-            "text" : "visual style."
+            "text" : "To avoid upscaled pixelated icons in these places, either configure a \"card\" page image as well or use a scalable vector image asset for the \"icon\" page image."
           },
           {
             "text" : "- Parameters:"