Quick fixes to docs

Author: kerrishotts

changes.md

@@ -4,7 +4,11 @@
 
 XD 21 adds major updates: the ability to **show panel UI**, and the much-improved **UXP 3 CSS & layout engine**.
 
-_The new layout engine likely constitutes a **breaking change** for any plugin with UI_ -- read below for details.
+> **Danger**
+>
+> _The new layout engine likely constitutes a **breaking change** for any plugin with UI_ -- read below for details.
+
+Also note that this release has an issue where transactions being wrapped by `editDocument` is _not_ enforced. This will be fixed in an upcoming patch version, so you will want to continue wrapping scenegraph changes from panels in `editDocument` so that your plugin isn't broken when we release the fix.
 
 ### Plugin Panel UI
 
@@ -33,6 +37,8 @@ In order to gain access to most of these features, your plugin must _opt-in_ to
     * **`overflow` defaults to `visible`** (no longer `hidden`), per the web specification -- _This may break existing plugin UI code._
     * `object-fit` -- to control the size of images
     * `z-index`
+    * Improvements to `position`, including correct `absolute` semantics.
+      * **WARNING**: Technically `position: fixed` is supported. However, _you should not use it_ in your plugin panels because there are some bugs that will be fixed in a future update that will break if your plugin uses `position: fixed`.
 * **SVG UI elements**
 * **New UI controls**
     * Radio buttons -- `<input type="radio" />`

known-issues.md

@@ -49,6 +49,8 @@
 - `<label for="id"/>` is not supported. Wrap `<label>` around the control instead.
 - `<input type="file" />` is not supported.
 - `<input type="color" />` is not supported.
+- Using unitless values in `width` and `height` attributes are not supported in UXP 3.1. Use `px`, or CSS styles.
+- `<label>` uses `inline-flex` layout semantics in UXP 3.1 mode, with `flex-wrap: wrap` enabled. If you need to prevent wrapping, use `flex-wrap: nowrap` on these elements. Note that the default layout behavior is now _horizontal_ not _vertical_.
 
 ### Layout
 
@@ -75,6 +77,7 @@
 - The bottom border may not always render with the same width as the other borders.
 - Underlines may render very thin.
 - `calc` only works for length properties. Using `calc` for a color will not work.
+- If you need to override an anchor link color, use `a[href]` as the selector to override it.
 
 ### DOM
 

migrations/uxp-2-to-3.md

@@ -227,7 +227,10 @@ The default stylesheet in UXP 3 is different from that provided by UXP 2 and bac
 _Most_ of the differences in the default stylesheet are due to the presence of the panel insertion point for your plugins. Modal dialogs styling is generally the same. However, there are a few differences that might cause changes in your layout:
 
 * `<label>` is now rendered using `display: inline-flex` by default. This means form elements without a `row` or `column` class will render with the label to the left of the element instead of the label above the element.
+  * `<label>` will also _wrap_ if the width of the parent is too narrow. If you want to restrict this wrapping, you can apply `flex-wrap: nowrap` to the element. In the future, `<label>` will more closely match the web standard.
+  * `<label>` no longer needs the `row` class to lay out horizontally.
 * Styles are applied with _less_ specificity. This means it is easier to override the styling of an `<h2>`, for example.
+    * One place this may cause issues is that anchor colors are applied to anchors only with `href` attributes. If you need to override this color, use `a[href]` as the selector.
 
 ## Quick Feature Summary