Add documentation about floats, and possibly expand method

docs/extensibility/theme-support.md

@@ -45,7 +45,35 @@ Some blocks such as the image block have the possibility to define a "wide" or "
 add_theme_support( 'align-wide' );
 ```
 
-### Block Color Palettes:
+### Wide Alignments and Floats
+
+It can be difficult to create a responsive layout that accommodates wide images, a sidebar, a centered column, and floated elements that stay within that centered column.
+
+Gutenberg adds additional markup to floated images to make styling them easier.
+
+Here's the markup for an `Image` with a caption:
+
+```
+<figure class="wp-block-image">
+	<img src="..." alt="" width="200px">
+	<figcaption>Short image caption.</figcaption>
+</figure>
+```
+
+Here's the markup for a left-floated image:
+
+```
+<div class="wp-block-image">
+	<figure class="alignleft">
+		<img src="..." alt="" width="200px">
+		<figcaption>Short image caption.</figcaption>
+	</figure>
+</div>
+```
+
+Here's an example using the above markup to achieve a responsive layout that features a sidebar, wide images, and floated elements with bounded captions: https://codepen.io/joen/pen/zLWvrW.
+
+### Block Color Palettes
 
 Different blocks have the possibility of customizing colors. Gutenberg provides a default palette, but a theme can overwrite it and provide its own:
 

packages/editor/src/components/default-block-appender/style.scss

@@ -1,14 +1,16 @@
 .editor-default-block-appender {
-	input[type="text"].editor-default-block-appender__content { // needs specificity
+	clear: both; // The appender doesn't scale well to sit next to floats, so clear them.
+
+	input[type="text"].editor-default-block-appender__content { // Needs specificity in order to override input field styles from WP-admin styles.
 		font-family: $editor-font;
-		font-size: $editor-font-size; // It should match the default paragraph size
+		font-size: $editor-font-size; // It should match the default paragraph size.
 		border: none;
 		background: none;
 		box-shadow: none;
 		display: block;
 		margin-left: 0;
 		margin-right: 0;
-		max-width: none; // fixes a bleed issue from the admin
+		max-width: none; // Overrides upstream CSS from the admin.
 		cursor: text;
 		width: 100%;
 		outline: $border-width solid transparent;
@@ -17,9 +19,8 @@
 		// Emulate the dimensions of a paragraph block.
 		padding: 0 #{ $block-padding + $border-width };
 
-		// use opacity to work in various editor styles
+		// Use opacity to work in various editor styles.
 		color: $dark-opacity-300;
-
 		.is-dark-theme & {
 			color: $light-opacity-300;
 		}
@@ -31,9 +32,8 @@
 		transition: opacity 0.2s;
 
 		.components-icon-button:not(:hover) {
-			// use opacity to work in various editor styles
+			// Use opacity to work in various editor styles.
 			color: $dark-opacity-500;
-
 			.is-dark-theme & {
 				color: $light-opacity-500;
 			}
@@ -107,10 +107,9 @@
 		height: $block-side-ui-width;
 		padding: 0;
 
-		// use opacity to work in various editor styles
+		// Use opacity to work in various editor styles.
 		&:not(:hover) {
 			color: $dark-opacity-500;
-
 			.is-dark-theme & {
 				color: $light-opacity-500;
 			}