Wrap diagrams and transparent images with background (#11891)

By adding a `.diagram-wrap` CSS class that can be added to images as
needed.

To improve legibility in dark mode and visual separation in light mode.

Contributes to #11883

Author: parlough

src/_sass/components/_content.scss

@@ -19,6 +19,18 @@
 
     img {
       object-fit: contain;
+
+      &.diagram-wrap {
+        background-color: #f8f9fa;
+        padding: 1rem;
+        border-radius: 1rem;
+      }
+
+      &.small-diagram-wrap {
+        background-color: #f8f9fa;
+        padding: 0.5rem;
+        border-radius: 0.5rem;
+      }
     }
 
     > img {

src/content/assets/images/docs/PlatformChannels.png

@@ -20,7 +20,7 @@ it. Flutter is fast enough to do that, even on every frame if needed.
 Flutter is _declarative_. This means that Flutter builds its user interface to
 reflect the current state of your app:
 
-<img src='/assets/images/docs/development/data-and-backend/state-mgmt/ui-equals-function-of-state.png' width="100%" alt="A mathematical formula of UI = f(state). 'UI' is the layout on the screen. 'f' is your build methods. 'state' is the application state.">
+<img src='/assets/images/docs/development/data-and-backend/state-mgmt/ui-equals-function-of-state.png' width="100%" class="diagram-wrap" alt="A mathematical formula of UI = f(state). 'UI' is the layout on the screen. 'f' is your build methods. 'state' is the application state.">
 
 {% comment %}
 Source drawing for the png above: : https://docs.google.com/drawings/d/1RDcR5LyFtzhpmiT5-UupXBeos2Ban5cUTU0-JujS3Os/edit?usp=sharing

src/content/assets/images/docs/arch-overview/web-framework-diagram.png

@@ -122,7 +122,7 @@ it might need to be moved to app state.
 
 For that reason, take the following diagram with a large grain of salt:
 
-<img src='/assets/images/docs/development/data-and-backend/state-mgmt/ephemeral-vs-app-state.png' width="100%" alt="A flow chart. Start with 'Data'. 'Who needs it?'. Three options: 'Most widgets', 'Some widgets' and 'Single widget'. The first two options both lead to 'App state'. The 'Single widget' option leads to 'Ephemeral state'.">
+<img src='/assets/images/docs/development/data-and-backend/state-mgmt/ephemeral-vs-app-state.png' width="100%" class="diagram-wrap" alt="A flow chart. Start with 'Data'. 'Who needs it?'. Three options: 'Most widgets', 'Some widgets' and 'Single widget'. The first two options both lead to 'App state'. The 'Single widget' option leads to 'Ephemeral state'.">
 
 {% comment %}
 Source drawing for the png above: : https://docs.google.com/drawings/d/1p5Bvuagin9DZH8bNrpGfpQQvKwLartYhIvD0WKGa64k/edit?usp=sharing

src/content/data-and-backend/state-mgmt/declarative.md

@@ -28,7 +28,7 @@ you can find packages and tutorials listed on the [options page][].
 
 ## Our example 
 
-<img src='/assets/images/docs/development/data-and-backend/state-mgmt/model-shopper-screencast.webp' alt='An animated gif showing a Flutter app in use. It starts with the user on a login screen. They log in and are taken to the catalog screen, with a list of items. The click on several items, and as they do so, the items are marked as "added". The user clicks on a button and gets taken to the cart view. They see the items there. They go back to the catalog, and the items they bought still show "added". End of animation.' class='site-image-right'>
+<img src='/assets/images/docs/development/data-and-backend/state-mgmt/model-shopper-screencast.webp' alt='An animated gif showing a Flutter app in use. It starts with the user on a login screen. They log in and are taken to the catalog screen, with a list of items. The click on several items, and as they do so, the items are marked as "added". The user clicks on a button and gets taken to the cart view. They see the items there. They go back to the catalog, and the items they bought still show "added". End of animation.' class='site-image-right' style="max-height: 24rem;">
 
 For illustration, consider the following simple app.
 
@@ -43,7 +43,7 @@ and a scrolling view of many list items (`MyListItems`).
 
 Here's the app visualized as a widget tree.
 
-<img src='/assets/images/docs/development/data-and-backend/state-mgmt/simple-widget-tree.png' width="100%" alt="A widget tree with MyApp at the top, and  MyCatalog and MyCart below it. MyCart area leaf nodes, but MyCatalog have two children: MyAppBar and a list of MyListItems.">
+<img src='/assets/images/docs/development/data-and-backend/state-mgmt/simple-widget-tree.png' width="100%" class="diagram-wrap" alt="A widget tree with MyApp at the top, and  MyCatalog and MyCart below it. MyCart area leaf nodes, but MyCatalog have two children: MyAppBar and a list of MyListItems.">
 
 {% comment %}
   Source drawing for the png above: https://docs.google.com/drawings/d/1KXxAl_Ctxc-avhR4uE58BXBM6Tyhy0pQMCsSMFHVL_0/edit?zx=y4m1lzbhsrvx
@@ -135,7 +135,7 @@ it rebuilds `MyCart` from above (more on that later). Because of this,
 what to show for any given `contents`. When that changes, the old
 `MyCart` widget disappears and is completely replaced by the new one.
 
-<img src='/assets/images/docs/development/data-and-backend/state-mgmt/simple-widget-tree-with-cart.png' width="100%" alt="Same widget tree as above, but now we show a small 'cart' badge next to MyApp, and there are two arrows here. One comes from one of the MyListItems to the 'cart', and another one goes from the 'cart' to the MyCart widget.">
+<img src='/assets/images/docs/development/data-and-backend/state-mgmt/simple-widget-tree-with-cart.png' width="100%" class="diagram-wrap" alt="Same widget tree as above, but now we show a small 'cart' badge next to MyApp, and there are two arrows here. One comes from one of the MyListItems to the 'cart', and another one goes from the 'cart' to the MyCart widget.">
 
 {% comment %}
   Source drawing for the png above: https://docs.google.com/drawings/d/1ErMyaX4fwfbIW9ABuPAlHELLGMsU6cdxPDFz_elsS9k/edit?zx=j42inp8903pt

src/content/data-and-backend/state-mgmt/ephemeral-vs-app.md

@@ -37,7 +37,7 @@ to painting a frame on the screen.
 The following figure shows an example event queue
 with 3 events waiting to be processed.
 
-![The main isolate diagram](/assets/images/docs/development/concurrency/basics-main-isolate.png){:width="50%"}
+![The main isolate diagram](/assets/images/docs/development/concurrency/basics-main-isolate.png){:width="50%" .diagram-wrap}
 
 For smooth rendering,
 Flutter adds a "paint frame" event to the event queue
@@ -47,7 +47,7 @@ the application experiences UI jank,
 or worse,
 become unresponsive altogether.
 
-![Event jank diagram](/assets/images/docs/development/concurrency/event-jank.png){:width="50%"}
+![Event jank diagram](/assets/images/docs/development/concurrency/event-jank.png){:width="60%" .diagram-wrap}
 
 Whenever a process can't be completed in a frame gap,
 the time between two frames,
@@ -74,7 +74,7 @@ to experience UI jank.
 This jank happens when there is any computation that takes longer than
 Flutter's frame gap.
 
-![Event jank diagram](/assets/images/docs/development/concurrency/event-jank.png){:width="50%"}
+![Event jank diagram](/assets/images/docs/development/concurrency/event-jank.png){:width="60%" .diagram-wrap}
 
 Any process _could_ take longer to complete,
 depending on the implementation
@@ -141,7 +141,7 @@ and then shuts the isolate down when the computation is complete.
 This all happens concurrently with the main isolate,
 and doesn't block it.
 
-![Isolate diagram](/assets/images/docs/development/concurrency/isolate-bg-worker.png){:width="50%"}
+![Isolate diagram](/assets/images/docs/development/concurrency/isolate-bg-worker.png){:width="70%" .diagram-wrap}
 
 The `Isolate.run` method requires a single argument,
 a callback function,

src/content/data-and-backend/state-mgmt/simple.md

@@ -489,7 +489,7 @@ You can use `InheritedWidget` to create a state widget
 that wraps a common ancestor in the
 widget tree, as shown in this example:
 
-![Inherited widgets](/assets/images/docs/arch-overview/inherited-widget.png){:width="50%"}
+![Inherited widgets](/assets/images/docs/arch-overview/inherited-widget.png){:width="50%" .diagram-wrap}
 
 [`InheritedWidget`]: {{site.api}}/flutter/widgets/InheritedWidget-class.html
 
@@ -602,8 +602,7 @@ rendering pipeline is that **simple is fast**.
 Flutter has a straightforward pipeline for how data flows to
 the system, as shown in the following sequencing diagram:
 
-![Render pipeline sequencing
-diagram](/assets/images/docs/arch-overview/render-pipeline.png){:width="100%"}
+![Render pipeline sequencing diagram](/assets/images/docs/arch-overview/render-pipeline.png){:width="100%" .diagram-wrap}
 
 Let's take a look at some of these phases in greater detail.
 
@@ -648,8 +647,7 @@ as `RawImage` and `RichText` during the build process. The eventual widget
 hierarchy might therefore be deeper than what the code represents,
 as in this case[^2]:
 
-![Render pipeline sequencing
-diagram](/assets/images/docs/arch-overview/widgets.png){:width="35%"}
+![Render pipeline sequencing diagram](/assets/images/docs/arch-overview/widgets.png){:width="40%" .diagram-wrap}
 
 This explains why, when you examine the tree through
 a debug tool such as the
@@ -667,8 +665,7 @@ hierarchy. There are two basic types of elements:
 - `RenderObjectElement`, an element that participates in the layout or paint
   phases.
 
-![Render pipeline sequencing
-diagram](/assets/images/docs/arch-overview/widget-element.png){:width="85%"}
+![Render pipeline sequencing diagram](/assets/images/docs/arch-overview/widget-element.png){:width="85%" .diagram-wrap}
 
 `RenderObjectElement`s are an intermediary between their widget analog and the
 underlying `RenderObject`, which we'll come to later.
@@ -715,8 +712,7 @@ an image, and
 [`RenderTransform`]({{site.api}}/flutter/rendering/RenderTransform-class.html)
 applies a transformation before painting its child.
 
-![Differences between the widgets hierarchy and the element and render
-trees](/assets/images/docs/arch-overview/trees.png){:width="100%"}
+![Differences between the widgets hierarchy and the element and render trees](/assets/images/docs/arch-overview/trees.png){:width="100%" .diagram-wrap}
 
 Most Flutter widgets are rendered by an object that inherits from the
 `RenderBox` subclass, which represents a `RenderObject` of fixed size in a 2D
@@ -730,8 +726,7 @@ the child _must_ respect the constraints given to it by its parent. Children
 respond by **passing up a size** to their parent object within the constraints
 the parent established.
 
-![Constraints go down, sizes go
-up](/assets/images/docs/arch-overview/constraints-sizes.png){:width="80%"}
+![Constraints go down, sizes go up](/assets/images/docs/arch-overview/constraints-sizes.png){:width="70%" .diagram-wrap}
 
 At the end of this single walk through the tree, every object has a defined size
 within its parent's constraints and is ready to be painted by calling the
@@ -853,8 +848,7 @@ Swift. Data is serialized from a Dart type like `Map` into a standard format,
 and then deserialized into an equivalent representation in Kotlin (such as
 `HashMap`) or Swift (such as `Dictionary`).
 
-![How platform channels allow Flutter to communicate with host
-code](/assets/images/docs/arch-overview/platform-channels.png){:width="70%"}
+![How platform channels allow Flutter to communicate with host code](/assets/images/docs/arch-overview/platform-channels.png){:width="65%" .diagram-wrap}
 
 The following is a short platform channel example of a Dart call to a receiving
 event handler in Kotlin (Android) or Swift (iOS):
@@ -1100,6 +1094,7 @@ Flutter offers two _build_ modes:
 <td>`--wasm`</td>
 <td>Skwasm (preferred), CanvasKit (fallback)</td>
 </tr>
+</table>
 
 
 The default mode makes only CanvasKit renderer available.
@@ -1112,7 +1107,7 @@ and falls back to CanvasKit otherwise.
 The draw.io source for the following image is in /diagrams/resources
 {% endcomment %}
 
-![Flutter web architecture](/assets/images/docs/arch-overview/web-framework-diagram.png)
+![Flutter web architecture](/assets/images/docs/arch-overview/web-framework-diagram.png){:width="80%" .diagram-wrap}
 
 Perhaps the most notable difference compared to other
 platforms on which Flutter runs is that there is no need

src/content/perf/isolates.md

@@ -29,7 +29,7 @@ contexts. An [`Action`][] can be a simple callback (as in the case of
 the [`CallbackAction`][]) or something more complex that integrates with entire
 undo/redo architectures (for example) or other logic.
 
-![Using Shortcuts Diagram][]{:width="100%"}
+![Using Shortcuts Diagram][]{:width="100%" .diagram-wrap}
 
 [`Shortcuts`][] are key bindings that activate by pressing a key or combination
 of keys. The key combinations reside in a table with their bound intent. When

src/content/resources/architectural-overview.md

@@ -33,7 +33,7 @@ replacing the solid star with an outline and
 decreasing the count. Tapping again favorites the lake,
 drawing a solid star and increasing the count.
 
-{% render docs/app-figure.md, image:"ui/favorited-not-favorited.png", alt:"The custom widget you'll create" %}
+{% render docs/app-figure.md, image:"ui/favorited-not-favorited.png", alt:"The custom widget you'll create", img-class:"diagram-wrap" %}
 
 To accomplish this, you'll create a single custom widget
 that includes both the star and the count,

src/content/ui/interactivity/actions-and-shortcuts.md

@@ -49,7 +49,7 @@ can see the visual layout.
 Here's a diagram of the widget tree for the previous
 example:
 
-<img src='/assets/images/docs/ui/layout/sample-flutter-layout.png' class="text-center" alt="Node tree">
+<img src='/assets/images/docs/ui/layout/sample-flutter-layout.png' class="text-center diagram-wrap" alt="Node tree">
 
 Most of this should look as you might expect, but you might be wondering
 about the containers (shown in pink). [`Container`][] is a widget class
@@ -361,11 +361,11 @@ columns inside of rows or columns.
 This layout is organized as a `Row`. The row contains two children:
 a column on the left, and an image on the right:
 
-<img src='/assets/images/docs/ui/layout/pavlova-diagram.png' alt="Screenshot with callouts showing the row containing two children">
+<img src='/assets/images/docs/ui/layout/pavlova-diagram.png' class="diagram-wrap" alt="Screenshot with callouts showing the row containing two children">
 
 The left column's widget tree nests rows and columns.
 
-<img src='/assets/images/docs/ui/layout/pavlova-left-column-diagram.png' alt="Diagram showing a left column broken down to its sub-rows and sub-columns">
+<img src='/assets/images/docs/ui/layout/pavlova-left-column-diagram.png' class="diagram-wrap" alt="Diagram showing a left column broken down to its sub-rows and sub-columns">
 
 You'll implement some of Pavlova's layout code in
 [Nesting rows and columns](#nesting-rows-and-columns).
@@ -399,10 +399,10 @@ axis runs horizontally.
 
 <div class="side-by-side">
   <div class="centered-rows">
-    <img src='/assets/images/docs/ui/layout/row-diagram.png' alt="Diagram showing the main axis and cross axis for a row">
+    <img src='/assets/images/docs/ui/layout/row-diagram.png' class="diagram-wrap" alt="Diagram showing the main axis and cross axis for a row">
   </div>
   <div class="centered-rows">
-    <img src='/assets/images/docs/ui/layout/column-diagram.png' alt="Diagram showing the main axis and cross axis for a column">
+    <img src='/assets/images/docs/ui/layout/column-diagram.png' class="diagram-wrap" alt="Diagram showing the main axis and cross axis for a column">
   </div>
 </div>
 
@@ -442,7 +442,7 @@ space evenly between, before, and after each image.
 
 </div>
 <div>
-  <img src='/assets/images/docs/ui/layout/row-spaceevenly-visual.png' alt="Row with 3 evenly spaced images">
+  <img src='/assets/images/docs/ui/layout/row-spaceevenly-visual.png' class="small-diagram-wrap" alt="Row with 3 evenly spaced images">
 
   **App source:** [row_column]({{examples}}/layout/row_column)
 </div>
@@ -471,7 +471,7 @@ space evenly between, above, and below each image.
 
 </div>
 <div class="text-center">
-  <img src='/assets/images/docs/ui/layout/column-visual.png' height="250px" alt="Column showing 3 images spaced evenly">
+  <img src='/assets/images/docs/ui/layout/column-visual.png' height="250px" class="small-diagram-wrap" alt="Column showing 3 images spaced evenly">
 
   **App source:** [row_column]({{examples}}/layout/row_column)
 </div>
@@ -487,7 +487,7 @@ When a layout is too large to fit a device, a yellow
 and black striped pattern appears along the affected edge.
 Here is an [example][sizing] of a row that is too wide:
 
-<img src='/assets/images/docs/ui/layout/layout-too-large.png' class="text-center" alt="Overly-wide row">
+<img src='/assets/images/docs/ui/layout/layout-too-large.png' class="text-center" style="max-height: 15rem;" alt="Overly-wide row">
 
 Widgets can be sized to fit within a row or column by using the
 [`Expanded`][] widget. To fix the previous example where the
@@ -511,7 +511,7 @@ wrap each image with an `Expanded` widget.
 
 </div>
 <div>
-  <img src='/assets/images/docs/ui/layout/row-expanded-2-visual.png' alt="Row of 3 images that are too wide, but each is constrained to take only 1/3 of the space">
+  <img src='/assets/images/docs/ui/layout/row-expanded-2-visual.png' class="small-diagram-wrap" alt="Row of 3 images that are too wide, but each is constrained to take only 1/3 of the space">
 
   **App source:** [sizing]({{examples}}/layout/sizing)
 </div>
@@ -540,7 +540,7 @@ the flex factor of the middle image to 2:
 
 </div>
 <div>
-  <img src='/assets/images/docs/ui/layout/row-expanded-visual.png' alt="Row of 3 images with the middle image twice as wide as the others">
+  <img src='/assets/images/docs/ui/layout/row-expanded-visual.png' class="small-diagram-wrap" alt="Row of 3 images with the middle image twice as wide as the others">
 
   **App source:** [sizing]({{examples}}/layout/sizing)
 </div>
@@ -575,7 +575,7 @@ uses this property to pack the star icons together.
 
 </div>
 <div>
-  <img src='/assets/images/docs/ui/layout/packed.png' class="simple-border" alt="Row of 5 stars, packed together in the middle of the row">
+  <img src='/assets/images/docs/ui/layout/packed.png' class="small-diagram-wrap" alt="Row of 5 stars, packed together in the middle of the row">
 
   **App source:** [pavlova]({{examples}}/layout/pavlova)
 </div>
@@ -596,7 +596,7 @@ columns of icons and text.
 
 The widget tree for the ratings row:
 
-<img src='/assets/images/docs/ui/layout/widget-tree-pavlova-rating-row.png' class="text-center" alt="Ratings row widget tree">
+<img src='/assets/images/docs/ui/layout/widget-tree-pavlova-rating-row.png' class="text-center diagram-wrap" alt="Ratings row widget tree">
 
 The `ratings` variable creates a row containing a smaller row
 of 5-star icons, and text:
@@ -645,7 +645,7 @@ The icons row, below the ratings row, contains 3 columns;
 each column contains an icon and two lines of text,
 as you can see in its widget tree:
 
-<img src='/assets/images/docs/ui/layout/widget-tree-pavlova-icon-row.png' class="text-center" alt="Icon widget tree">
+<img src='/assets/images/docs/ui/layout/widget-tree-pavlova-icon-row.png' class="text-center diagram-wrap" alt="Icon widget tree">
 
 The `iconList` variable defines the icons row:
 
@@ -848,7 +848,7 @@ color or image.
 
 </div>
 <div class="text-center">
-  <img src='/assets/images/docs/ui/layout/margin-padding-border.png' alt="Diagram showing: margin, border, padding, and content">
+  <img src='/assets/images/docs/ui/layout/margin-padding-border.png' class="diagram-wrap" alt="Diagram showing: margin, border, padding, and content">
 </div>
 </div>