diff --git a/docs/widget-layouts.md b/docs/widget-layouts.md
new file mode 100644
index 0000000000..e49f2a2e60
--- /dev/null
+++ b/docs/widget-layouts.md
@@ -0,0 +1,61 @@
+# Widget layout support
+
+Rooms can have a default widget layout to auto-pin certain widgets, make the container different
+sizes, etc. These are defined through the `io.element.widgets.layout` state event (empty state key).
+
+Full example content:
+```json5
+{
+  "widgets": {
+    "first-widget-id": {
+      "container": "top",
+      "index": 0,
+      "width": 60,
+      "height": 40
+    },
+    "second-widget-id": {
+      "container": "right"
+    }
+  }
+}
+```
+
+As shown, there are two containers possible for widgets. These containers have different behaviour
+and interpret the other options differently. 
+
+## `top` container
+
+This is the "App Drawer" or any pinned widgets in a room. This is by far the most versatile container
+though does introduce potential usability issues upon members of the room (widgets take up space and
+therefore less messages can be shown).
+
+The `index` for a widget determines which order the widgets show up in from left to right. Widgets
+without an `index` will show up as the rightmost widgets. Tiebreaks (same `index` or multiple defined
+without an `index`) are resolved by comparing widget IDs. A maximum of 3 widgets can be in the top
+container - any which exceed this will be ignored. Smaller numbers represent leftmost widgets.
+
+The `width` is relative width within the container in percentage points. This will be clamped to a
+range of 0-100 (inclusive). The rightmost widget will have its percentage adjusted to fill the 
+container appropriately, shrinking and growing if required. For example, if three widgets are in the
+top container at 40% width each then the 3rd widget will be shrunk to 20% because 120% > 100%.
+Similarly, if all three widgets were set to 10% width each then the 3rd widget would grow to be 80%.
+
+Note that the client may impose minimum widths on the widgets, such as a 10% minimum to avoid pinning
+hidden widgets. In general, widgets defined in the 30-70% range each will be free of these restrictions.
+
+The `height` is not in fact applied per-widget but is recorded per-widget for potential future 
+capabilities in future containers. The top container will take the tallest `height` and use that for
+the height of the whole container, and thus all widgets in that container. The `height` is relative
+to the container, like with `width`, meaning that 100% will consume as much space as the client is
+willing to sacrifice to the widget container. Like with `width`, the client may impose minimums to avoid
+the container being uselessly small. Heights in the 30-100% range are generally acceptable. The height
+is also clamped to be within 0-100, inclusive.
+
+## `right` container
+
+This is the default container and has no special configuration. Widgets which overflow from the top
+container will be put in this container instead. Putting a widget in the right container does not
+automatically show it - it only mentions that widgets should not be in another container.
+
+The behaviour of this container may change in the future.
+