Merge pull request #200 from AdobeXD/pflynn/panel-docs-updates

XD 21 proposed docs updates

Author: dkstevekwak

CONTRIBUTING.md

@@ -42,7 +42,7 @@ To preview the fully formatted docs as they will appear online, follow these ste
 npm install
 npm run book:install
 
-# Rebuild HTML content (takes 2-3 minutes)
+# Rebuild HTML content (takes 3-5 minutes)
 npm run book:build
 
 # View HTML from a local webserver (using a file:// URL won't work)

SUMMARY.md

@@ -3,13 +3,15 @@
 * [Quick start](./README.md)
   * [Quick start](./tutorials/quick-start/index.md)
   * [Quick start - React](./tutorials/quick-start-react/index.md)
+  * [Quick start - Panel UI](./tutorials/quick-start-panel/index.md)
   * [Debugging plugins](./tutorials/debugging/index.md)
 * [Plugin Development 101](./plugin-development-guidelines/index.md)
   * [Plugin structure](./reference/structure/index.md)
     * [Plugin location](./reference/structure/location.md)
     * [Folder structure](./reference/structure/folder-structure.md)
       * [manifest.json](./reference/structure/manifest.md)
       * [main.js](./reference/structure/handlers.md)
+    * [Menu structure](./reference/structure/menu-structure.md)
   * [JavaScript and XD plugin APIs](./reference/javascript/index.md)
     * [JavaScript support](./reference/javascript/javascript-support.md)
     * [Sync and async](./reference/javascript/sync-async.md)
@@ -55,6 +57,10 @@
       * [Modal dialogs](./reference/ui/dialogs/index.md)
         * [Showing dialogs](./reference/ui/dialogs/showing.md)
         * [Dismissing dialogs](./reference/ui/dialogs/dismissal.md)
+      * [Panels](./reference/ui/panels/index.md)
+        * [show() callback](./reference/ui/panels/show.md)
+        * [hide() callback](./reference/ui/panels/hide.md)
+        * [update() callback](./reference/ui/panels/update.md)
     * [Resources - Sticker Sheet](./plugin-design-guidelines/ui_resources/Sticker_sheet.md)
 * [Step-by-step Tutorials](./tutorials/index.md)
   * [Working with content](./tutorials/content-index.md)
@@ -161,4 +167,7 @@
 * [Joining Our Community](./community.md)
   * [Code of conduct](./CODE_OF_CONDUCT.md)
   * [How to contribute](./CONTRIBUTING.md)
+* [Migrations](./migrations.md)
+  * [UXP 2 to 3](./migrations/uxp-2-to-3.md)
+  * [Porting Modals to Panels](./migrations/how-to-migrate-from-modal-to-panel.md)
 * [Plugin API roadmap](./plugin-api-roadmap.md)

changes.md

@@ -1,5 +1,60 @@
 # Change Log
 
+## XD Release 21.0.12 (July 2019)
+
+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.
+
+### Plugin Panel UI
+
+* Plugins can now display UI persistently in a side panel. More information:
+    * [How to define a panel](./reference/structure/handlers.md#panel)
+    * [Panel overview / reference](./reference/ui/panels/index.md)
+    * [Panel Quick Start tutorial](./tutorials/quick-start-panel/index.md)
+    * [Migrating from dialogs to panels](./migrations/how-to-migrate-from-modal-to-panel.md)
+* A new default stylesheet is provided for plugin UI that renders inside a plugin. This means that UI that renders in one manner in a modal dialog may not render in the same exact manner in a panel.
+
+### UXP 3 HTML/CSS changes
+
+In order to gain access to most of these features, your plugin must _opt-in_ to the UXP 3.1 layout engine by changing the `minVersion` in your `manifest.json`:
+
+```json
+    "host": {
+        "minVersion": "21.0"
+    }
+```
+
+> **NOTE:** Without this change, your plugin will run in [backwards-compatibility mode](./migrations/uxp-2-to-3.md).
+
+* **Layout engine**
+    * **Inline layout** -- You now have the ability to write code like `<p>This is <a href="...">a link</a></p>` and have the link render _inline_ with the rest of the text
+    * **Layout now defaults to inline** (no longer flexbox) -- _This may break existing plugin UI code:_ now `span` elements will render with `inline`, `button`s will render as `inline-block`, etc.
+    * **`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`
+* **SVG UI elements**
+* **New UI controls**
+    * Radio buttons -- `<input type="radio" />`
+    * Progress bars & spinners -- `<progress>`
+* **CSS improvements**
+    * `linear-gradient()`
+    * `outline`
+    * More units! -- UXP now understands `rem`, `em`, `px`, `pt`, `vh`, `vw`, `cm`, `in`, etc. **NOTE:** UXP will now start ignoring values (other than `0`) that don't specify any units, which can break older plugin UI code.
+    * CSS Variables -- easily apply themes and other layout to your plugin.
+    * More pseudo-selectors -- `:lang` and `:focus`
+    * `calc()` -- For example, `width: calc(100% - 9px)`. Note that you can mix units, just like you can on the web.
+    * Inheritance -- The CSS parser now understands `initial`, `unset`, and `inherit`. You can also use `!important` to override styles (although you should use this as a last resort).
+    * Default styles are now easier to override as the specificity in the default stylesheet has been reduced.
+* **Keyboard focus** -- Setting `tab-index` to `0` will now cause any element to be focusable. You can **not** yet control the tab order.
+
+### Known Issues
+
+See the [Known Issues page](./known-issues.md) for a comprehensive list of existing known issues.
+
+
+----
+
 ## XD Release 20.0.12 (June 2019)
 
 ### UI Changes

distribution/packaging.md

@@ -20,7 +20,7 @@ Select all files within your plugin's parent folder. On both macOS and Windows y
 | macOS         | _Right-click > Compress # items_ |
 | Windows       | _Right-click > Send to > Compressed (zipped) folder_ |
 
-If you plan to distribute via the XD plugin manager, your .ZIP file **must be less than 25MB in size**. You'll only be able to submit for review if your file is under the size limit.
+If you plan to distribute via the XD plugin manager, your .ZIP file **must be less than 25MB in size and contain fewer than 3,000 files**. You'll only be able to submit for review if your file is under these limits.
 
 > **Danger**
 >