docs: Physical layout docs improvements (#2533)

* docs: Added layout configuration reference page
* docs: Refactored and revamped physical layout creation information
* docs: Added note in studio features page
* docs: added studio_unlock note in features section
---------

Co-authored-by: Cem Aksoylar <[email protected]>
Co-authored-by: Joel Spadin <[email protected]>
Co-authored-by: Peter Johanson <[email protected]>

9 files changed, 882 insertions, 342 deletions

diff --git a/docs/docs/assets/hardware-integration/numpad.svg b/docs/docs/assets/hardware-integration/numpad.svg
new file mode 100644
index 0000000000..073f286478
--- /dev/null
+++ b/docs/docs/assets/hardware-integration/numpad.svg
@@ -0,0 +1,182 @@
+<svg width="610" height="362" viewBox="0 0 610 362" class="keymap" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<style>
+/* font and background color specifications */
+svg.keymap {
+    font-family: sans-serif;
+    font-size: 14px;
+    font-kerning: normal;
+    text-rendering: optimizeLegibility;
+    fill: #24292e;
+}
+
+/* default key styling */
+rect.key {
+    fill: #f6f8fa;
+    stroke: #c9cccf;
+    stroke-width: 1;
+}
+
+text {
+    text-anchor: middle;
+    dominant-baseline: middle;
+}
+
+@media (prefers-color-scheme: dark) {
+    svg.keymap { fill: #d1d6db; }
+    rect.key { fill: #3f4750; stroke: #60666c; }
+}
+</style>
+<g transform="translate(30, 0)" class="layer- ">
+<text x="0" y="28" class="label" id="x_x"> </text>
+<g transform="translate(0, 56)">
+<g transform="translate(25, 25)" class="key keypos-0">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">0</text>
+</g>
+<g transform="translate(75, 25)" class="key keypos-1">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">1</text>
+</g>
+<g transform="translate(125, 25)" class="key keypos-2">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">2</text>
+</g>
+<g transform="translate(175, 25)" class="key keypos-3">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">3</text>
+</g>
+<g transform="translate(25, 75)" class="key keypos-4">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">4</text>
+</g>
+<g transform="translate(75, 75)" class="key keypos-5">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">5</text>
+</g>
+<g transform="translate(125, 75)" class="key keypos-6">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">6</text>
+</g>
+<g transform="translate(175, 75)" class="key keypos-7">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">7</text>
+</g>
+<g transform="translate(25, 125)" class="key keypos-8">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">8</text>
+</g>
+<g transform="translate(75, 125)" class="key keypos-9">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">9</text>
+</g>
+<g transform="translate(125, 125)" class="key keypos-10">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">10</text>
+</g>
+<g transform="translate(175, 125)" class="key keypos-11">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">11</text>
+</g>
+<g transform="translate(25, 175)" class="key keypos-12">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">12</text>
+</g>
+<g transform="translate(75, 175)" class="key keypos-13">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">13</text>
+</g>
+<g transform="translate(125, 175)" class="key keypos-14">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">14</text>
+</g>
+<g transform="translate(175, 175)" class="key keypos-15">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">15</text>
+</g>
+<g transform="translate(25, 225)" class="key keypos-16">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">16</text>
+</g>
+<g transform="translate(75, 225)" class="key keypos-17">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">17</text>
+</g>
+<g transform="translate(125, 225)" class="key keypos-18">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">18</text>
+</g>
+<g transform="translate(175, 225)" class="key keypos-19">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">19</text>
+</g>
+<g transform="translate(375, 25)" class="key keypos-20">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">0</text>
+</g>
+<g transform="translate(425, 25)" class="key keypos-21">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">1</text>
+</g>
+<g transform="translate(475, 25)" class="key keypos-22">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">2</text>
+</g>
+<g transform="translate(525, 25)" class="key keypos-23">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">3</text>
+</g>
+<g transform="translate(375, 75)" class="key keypos-24">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">4</text>
+</g>
+<g transform="translate(425, 75)" class="key keypos-25">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">5</text>
+</g>
+<g transform="translate(475, 75)" class="key keypos-26">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">6</text>
+</g>
+<g transform="translate(525, 100)" class="key keypos-27">
+<rect rx="6" ry="6" x="-23" y="-48" width="46" height="96" class="key"/>
+<text x="0" y="0" class="key tap">7</text>
+</g>
+<g transform="translate(375, 125)" class="key keypos-28">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">8</text>
+</g>
+<g transform="translate(425, 125)" class="key keypos-29">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">9</text>
+</g>
+<g transform="translate(475, 125)" class="key keypos-30">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">10</text>
+</g>
+<g transform="translate(375, 175)" class="key keypos-31">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">11</text>
+</g>
+<g transform="translate(425, 175)" class="key keypos-32">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">12</text>
+</g>
+<g transform="translate(475, 175)" class="key keypos-33">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">13</text>
+</g>
+<g transform="translate(525, 200)" class="key keypos-34">
+<rect rx="6" ry="6" x="-23" y="-48" width="46" height="96" class="key"/>
+<text x="0" y="0" class="key tap">14</text>
+</g>
+<g transform="translate(400, 225)" class="key keypos-35">
+<rect rx="6" ry="6" x="-48" y="-23" width="96" height="46" class="key"/>
+<text x="0" y="0" class="key tap">15</text>
+</g>
+<g transform="translate(475, 225)" class="key keypos-36">
+<rect rx="6" ry="6" x="-23" y="-23" width="46" height="46" class="key"/>
+<text x="0" y="0" class="key tap">16</text>
+</g>
+</g>
+</g>
+</svg>
diff --git a/docs/docs/config/kscan.md b/docs/docs/config/kscan.md
index b4dd992519..dfe22bf49d 100644
--- a/docs/docs/config/kscan.md
+++ b/docs/docs/config/kscan.md
@@ -335,170 +335,3 @@ Definition file: [zmk/app/dts/bindings/zmk,kscan-mock.yaml](https://github.com/z
 | `exit-after`   | bool  | Exit the program after running all events     | false   |
 
 The `events` array should be defined using the macros from [app/module/include/dt-bindings/zmk/kscan_mock.h](https://github.com/zmkfirmware/zmk/blob/main/app/module/include/dt-bindings/zmk/kscan_mock.h).
-
-## Matrix Transform
-
-Defines a mapping from keymap logical positions to physical matrix positions.
-
-Transforms should be used any time the physical layout of a keyboard's keys does not match the layout of its electrical matrix and/or when not all positions in the matrix are used. This applies to most non-ortholinear boards.
-
-Transforms can also be used for keyboards with multiple layouts. You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps.
-
-See the [new shield guide](../development/hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform.
-
-### Devicetree
-
-Applies to: `compatible = "zmk,matrix-transform"`
-
-Definition file: [zmk/app/dts/bindings/zmk,matrix-transform.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cmatrix-transform.yaml)
-
-| Property     | Type  | Description                                                           | Default |
-| ------------ | ----- | --------------------------------------------------------------------- | ------- |
-| `rows`       | int   | Number of rows in the transformed matrix                              |         |
-| `columns`    | int   | Number of columns in the transformed matrix                           |         |
-| `row-offset` | int   | Adds an offset to all rows before looking them up in the transform    | 0       |
-| `col-offset` | int   | Adds an offset to all columns before looking them up in the transform | 0       |
-| `map`        | array | A list of position transforms                                         |         |
-
-The `map` array should be defined using the `RC()` macro from [dt-bindings/zmk/matrix_transform.h](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/matrix_transform.h). It should have one item per logical position in the keymap. Each item should list the physical row and column that should trigger the key in that position.
-
-### Example: Skipping Unused Positions
-
-Any keyboard which is not a grid of 1 unit keys will likely have some unused positions in the matrix. A matrix transform can be used to skip the unused positions so users don't have to set them to `&none` in keymaps.
-
-```dts
-// numpad.overlay
-/ {
-    chosen {
-        zmk,kscan = &kscan0;
-        zmk,matrix-transform = &default_transform;
-    };
-
-    kscan0: kscan {
-        compatible = "zmk,kscan-gpio-matrix";
-        // define row-gpios with 5 elements and col-gpios with 4...
-    };
-
-    default_transform: matrix_transform {
-        compatible = "zmk,matrix-transform";
-        rows = <5>;
-        columns = <4>;
-        // ┌───┬───┬───┬───┐
-        // │NUM│ / │ * │ - │
-        // ├───┼───┼───┼───┤
-        // │ 7 │ 8 │ 9 │ + │
-        // ├───┼───┼───┤   │
-        // │ 4 │ 5 │ 6 │   │
-        // ├───┼───┼───┼───┤
-        // │ 1 │ 2 │ 3 │RET│
-        // ├───┴───┼───┤   │
-        // │ 0     │ . │   │
-        // └───────┴───┴───┘
-        map = <
-            RC(0,0) RC(0,1) RC(0,2) RC(0,3)
-            RC(1,0) RC(1,1) RC(1,2) RC(1,3)
-            RC(2,0) RC(2,1) RC(2,2)
-            RC(3,0) RC(3,1) RC(3,2) RC(3,3)
-            RC(4,0)         RC(4,1)
-        >;
-    };
-};
-```
-
-```dts
-// numpad.keymap
-/ {
-    keymap {
-        compatible = "zmk,keymap";
-        default {
-            bindings = <
-                &kp KP_NUM &kp KP_DIV &kp KP_MULT &kp KP_MINUS
-                &kp KP_N7  &kp KP_N8  &kp KP_N9   &kp KP_PLUS
-                &kp KP_N4  &kp KP_N5  &kp KP_N6
-                &kp KP_N1  &kp KP_N2  &kp KP_N3   &kp KP_ENTER
-                &kp KP_N0             &kp KP_DOT
-            >;
-        };
-    }
-};
-```
-
-### Example: Non-standard Matrix
-
-Consider a keyboard with a [duplex matrix](https://wiki.ai03.com/books/pcb-design/page/matrices-and-duplex-matrix), where the matrix has twice as many rows and half as many columns as the keyboard has keys. A matrix transform can be used to correct for this so that keymaps can match the layout of the keys, not the layout of the matrix.
-
-```dts
-/ {
-    chosen {
-        zmk,kscan = &kscan0;
-        zmk,matrix-transform = &default_transform;
-    };
-
-    kscan0: kscan {
-        compatible = "zmk,kscan-gpio-matrix";
-        // define row-gpios with 12 elements and col-gpios with 8...
-    };
-
-    default_transform: matrix_transform {
-        compatible = "zmk,matrix-transform";
-        rows = <6>;
-        columns = <16>;
-        // ESC F1 F2 F3   ...
-        // `   1  2  3    ...
-        // Tab  Q  W  E   ...
-        // Caps  A  S  D  ...
-        // Shift  Z  X  C ...
-        // Ctrl Alt       ...
-        map = <
-            RC(0,0) RC(1,0) RC(0,1) RC(1,1)       // ...
-            RC(2,0) RC(3,0) RC(2,1) RC(3,1)       // ...
-            RC(4,0)   RC(5,0) RC(4,1) RC(5,1)     // ...
-            RC(6,0)     RC(7,0) RC(6,1) RC(7,1)   // ...
-            RC(8,0)       RC(9,0) RC(8,1) RC(9,1) // ...
-            RC(10,0) RC(11,0)                     // ...
-        >;
-    };
-};
-```
-
-### Example: Charlieplex
-
-Since a charlieplex driver will never align with a keyboard directly due to the un-addressable positions, a matrix transform should be used to map the pairs to the layout of the keys.
-Note that the entire addressable space does not need to be mapped.
-
-```devicetree
-/ {
-    chosen {
-        zmk,kscan = &kscan0;
-        zmk,matrix-transform = &default_transform;
-    };
-
-    kscan0: kscan {
-        compatible = "zmk,kscan-gpio-charlieplex";
-        wakeup-source;
-
-        interrupt-gpios = <&pro_micro 21 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) >;
-        gpios
-          = <&pro_micro 16 GPIO_ACTIVE_HIGH>
-          , <&pro_micro 17 GPIO_ACTIVE_HIGH>
-          , <&pro_micro 18 GPIO_ACTIVE_HIGH>
-          , <&pro_micro 19 GPIO_ACTIVE_HIGH>
-          , <&pro_micro 20 GPIO_ACTIVE_HIGH>
-          ; // addressable space is 5x5, (minus paired values)
-    };
-
-    default_transform: matrix_transform {
-        compatible = "zmk,matrix-transform";
-        rows = <3>;
-        columns = <5>;
-        //  Q  W  E  R
-        //   A  S  D  F
-        //    Z  X  C  V
-        map = <
-            RC(0,1) RC(0,2) RC(0,3) RC(0,4)
-              RC(1,0) RC(1,2) RC(1,3) RC(1,4)
-                RC(2,0) RC(2,1) RC(2,3) RC(2,4)
-        >;
-    };
-};
-```
diff --git a/docs/docs/config/layout.md b/docs/docs/config/layout.md
new file mode 100644
index 0000000000..385d60c3b4
--- /dev/null
+++ b/docs/docs/config/layout.md
@@ -0,0 +1,225 @@
+---
+title: Layout Configuration
+sidebar_label: Layout
+---
+
+See [Configuration Overview](index.md) for instructions on how to change these settings.
+
+## Matrix Transform
+
+Defines a mapping from keymap logical positions to physical [kscan](./kscan.md) positions.
+
+You can define multiple matrix transform nodes, one for each layout, and users can select which one they want from the `/chosen` node in their keymaps.
+
+See the [new shield guide](../development/hardware-integration/new-shield.mdx#matrix-transform) for more documentation on how to define a matrix transform.
+
+### Devicetree
+
+Applies to: `compatible = "zmk,matrix-transform"`
+
+Definition file: [zmk/app/dts/bindings/zmk,matrix-transform.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cmatrix-transform.yaml)
+
+| Property     | Type  | Description                                                           | Default |
+| ------------ | ----- | --------------------------------------------------------------------- | ------- |
+| `rows`       | int   | Number of rows in the transformed matrix                              |         |
+| `columns`    | int   | Number of columns in the transformed matrix                           |         |
+| `row-offset` | int   | Adds an offset to all rows before looking them up in the transform    | 0       |
+| `col-offset` | int   | Adds an offset to all columns before looking them up in the transform | 0       |
+| `map`        | array | A list of position transforms                                         |         |
+
+The `map` array should be defined using the `RC()` macro from [dt-bindings/zmk/matrix_transform.h](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/matrix_transform.h). It should have one item per logical position in the keymap. Each item should list the physical row and column that should trigger the key in that position.
+
+### Example: Skipping Unused Positions
+
+Any keyboard which is not a grid of 1 unit keys will likely have some unused positions in the matrix. A matrix transform can be used to skip the unused positions so users don't have to set them to `&none` in keymaps.
+
+```dts
+// numpad.overlay
+/ {
+    chosen {
+        zmk,kscan = &kscan0;
+        zmk,matrix-transform = &default_transform;
+    };
+
+    kscan0: kscan {
+        compatible = "zmk,kscan-gpio-matrix";
+        // define row-gpios with 5 elements and col-gpios with 4...
+    };
+
+    default_transform: matrix_transform {
+        compatible = "zmk,matrix-transform";
+        rows = <5>;
+        columns = <4>;
+        // ┌───┬───┬───┬───┐
+        // │NUM│ / │ * │ - │
+        // ├───┼───┼───┼───┤
+        // │ 7 │ 8 │ 9 │ + │
+        // ├───┼───┼───┤   │
+        // │ 4 │ 5 │ 6 │   │
+        // ├───┼───┼───┼───┤
+        // │ 1 │ 2 │ 3 │RET│
+        // ├───┴───┼───┤   │
+        // │ 0     │ . │   │
+        // └───────┴───┴───┘
+        map = <
+            RC(0,0) RC(0,1) RC(0,2) RC(0,3)
+            RC(1,0) RC(1,1) RC(1,2) RC(1,3)
+            RC(2,0) RC(2,1) RC(2,2)
+            RC(3,0) RC(3,1) RC(3,2) RC(3,3)
+            RC(4,0)         RC(4,1)
+        >;
+    };
+};
+```
+
+```dts
+// numpad.keymap
+/ {
+    keymap {
+        compatible = "zmk,keymap";
+        default {
+            bindings = <
+                &kp KP_NUM &kp KP_DIV &kp KP_MULT &kp KP_MINUS
+                &kp KP_N7  &kp KP_N8  &kp KP_N9   &kp KP_PLUS
+                &kp KP_N4  &kp KP_N5  &kp KP_N6
+                &kp KP_N1  &kp KP_N2  &kp KP_N3   &kp KP_ENTER
+                &kp KP_N0             &kp KP_DOT
+            >;
+        };
+    }
+};
+```
+
+### Example: Non-standard Matrix
+
+Consider a keyboard with a [duplex matrix](https://wiki.ai03.com/books/pcb-design/page/matrices-and-duplex-matrix), where the matrix has twice as many rows and half as many columns as the keyboard has keys. A matrix transform can be used to correct for this so that keymaps can match the layout of the keys, not the layout of the matrix.
+
+```dts
+/ {
+    chosen {
+        zmk,kscan = &kscan0;
+        zmk,matrix-transform = &default_transform;
+    };
+
+    kscan0: kscan {
+        compatible = "zmk,kscan-gpio-matrix";
+        // define row-gpios with 12 elements and col-gpios with 8...
+    };
+
+    default_transform: matrix_transform {
+        compatible = "zmk,matrix-transform";
+        rows = <6>;
+        columns = <16>;
+        // ESC F1 F2 F3   ...
+        // `   1  2  3    ...
+        // Tab  Q  W  E   ...
+        // Caps  A  S  D  ...
+        // Shift  Z  X  C ...
+        // Ctrl Alt       ...
+        map = <
+            RC(0,0) RC(1,0) RC(0,1) RC(1,1)       // ...
+            RC(2,0) RC(3,0) RC(2,1) RC(3,1)       // ...
+            RC(4,0)   RC(5,0) RC(4,1) RC(5,1)     // ...
+            RC(6,0)     RC(7,0) RC(6,1) RC(7,1)   // ...
+            RC(8,0)       RC(9,0) RC(8,1) RC(9,1) // ...
+            RC(10,0) RC(11,0)                     // ...
+        >;
+    };
+};
+```
+
+### Example: Charlieplex
+
+Since a charlieplex driver will never align with a keyboard directly due to the un-addressable positions, a matrix transform should be used to map the pairs to the layout of the keys.
+Note that the entire addressable space does not need to be mapped.
+
+```devicetree
+/ {
+    chosen {
+        zmk,kscan = &kscan0;
+        zmk,matrix-transform = &default_transform;
+    };
+
+    kscan0: kscan {
+        compatible = "zmk,kscan-gpio-charlieplex";
+        wakeup-source;
+
+        interrupt-gpios = <&pro_micro 21 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) >;
+        gpios
+          = <&pro_micro 16 GPIO_ACTIVE_HIGH>
+          , <&pro_micro 17 GPIO_ACTIVE_HIGH>
+          , <&pro_micro 18 GPIO_ACTIVE_HIGH>
+          , <&pro_micro 19 GPIO_ACTIVE_HIGH>
+          , <&pro_micro 20 GPIO_ACTIVE_HIGH>
+          ; // addressable space is 5x5, (minus paired values)
+    };
+
+    default_transform: matrix_transform {
+        compatible = "zmk,matrix-transform";
+        rows = <3>;
+        columns = <5>;
+        //  Q  W  E  R
+        //   A  S  D  F
+        //    Z  X  C  V
+        map = <
+            RC(0,1) RC(0,2) RC(0,3) RC(0,4)
+              RC(1,0) RC(1,2) RC(1,3) RC(1,4)
+                RC(2,0) RC(2,1) RC(2,3) RC(2,4)
+        >;
+    };
+};
+```
+
+## Physical Layout
+
+Defines a keyboard layout by joining together a [matrix transform](#matrix-transform), a [keyboard scan](./kscan.md), and a list of physical key properties.
+Multiple physical layouts can be defined for keyboards with multiple physical key layouts.
+Read through the [page on physical layouts](../development/hardware-integration/physical-layouts.md) for more information.
+
+### Devicetree
+
+Applies to: `compatible = zmk,physical-layout`
+
+Definition file: [zmk/app/dts/bindings/zmk,physical-layout.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cphysical-layout.yaml)
+
+| Property       | Type          | Description                                                                                                            | Default |
+| -------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
+| `display-name` | string        | The name of this layout, for display purposes                                                                          |         |
+| `transform`    | phandle       | The matrix transform to use along with this layout                                                                     |         |
+| `kscan`        | phandle       | The kscan to use along with this layout. The `zmk,kscan` chosen will be used as a fallback if this property is omitted |         |
+| `keys`         | phandle-array | Array of key physical attributes.                                                                                      |         |
+
+Each element of the `keys` array has the shape `<&key_physical_attrs w h x y r rx ry>`, with the following properties:
+
+| Property   | Type     | Description                          | Unit                                                    |
+| ---------- | -------- | ------------------------------------ | ------------------------------------------------------- |
+| Width      | int (>0) | Key(cap) width                       | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Height     | int (>0) | Key(cap) height                      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| X          | uint     | Key X position (top-left point)      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Y          | uint     | Key Y position (top-left point)      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Rotation   | int      | Key rotation (positive => clockwise) | [centi-](https://en.wikipedia.org/wiki/Centi-)degree    |
+| Rotation X | int      | Rotation origin X position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Rotation Y | int      | Rotation origin Y position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+
+The `key_physical_attrs` node is defined in [`dts/physical_layouts.dtsi`](https://github.com/zmkfirmware/zmk/blob/main/app/dts/physical_layouts.dtsi) and is mandatory.
+
+## Physical Layout Position Map
+
+Defines a mapping between [physical layouts](#physical-layout), allowing key mappings to be preserved in the same locations as previously when using [ZMK Studio](../features/studio.md). Read through the [page on physical layouts](../development/hardware-integration/physical-layouts.md) for more information.
+
+### Devicetree
+
+Applies to: `compatible = zmk,physical-layout-position-map`
+
+Definition file: [zmk/app/dts/bindings/zmk,physical-layout-position-map.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Cphysical-layout-position-map.yaml)
+
+| Property   | Type    | Description                                                                                      | Default |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------ | ------- |
+| `complete` | boolean | If the mapping complete describes the key mapping, and no position based mapping should be used. |         |
+
+The `zmk,physical-layout-position-map` node should have one child node per physical layout. Each child node should have the following properties:
+
+| Property          | Type    | Description                                                                       | Default |
+| ----------------- | ------- | --------------------------------------------------------------------------------- | ------- |
+| `physical-layout` | phandle | The physical layout that corresponds to this mapping entry                        |         |
+| `positions`       | array   | Array of key positions that match the same array entry in the other sibling nodes |         |
diff --git a/docs/docs/development/hardware-integration/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx
index f2be494638..18ce3adea6 100644
--- a/docs/docs/development/hardware-integration/new-shield.mdx
+++ b/docs/docs/development/hardware-integration/new-shield.mdx
@@ -442,33 +442,15 @@ The matrix transform is also used to "correct" pin orderings into something that
 
 See the [in-tree keyboards](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) that ZMK defines for examples of more complex matrix transformations.
 
-Also see the [matrix transform section](../../config/kscan.md#matrix-transform) in the Keyboard Scan configuration documentation for further details and examples of matrix transforms.
+Also see the [matrix transform section](../../config/layout.md#matrix-transform) in the Keyboard Scan configuration documentation for further details and examples of matrix transforms.
 
 ### Physical Layout
 
-The physical layout is the top level entity that aggregates all details about a certain possible layout:
+Your keyboard will need to have a physical layout defined.
+Read through our [dedicated page on physical layouts](./physical-layouts.md) for information on how to define a physical layout.
+Physical layouts should be placed in the same file as the matrix transform, i.e. `my_keyboard.overlay` for unibodies and `my_keyboard.dtsi` for split keyboards.
 
-- Your keyboard scan (kscan) driver
-- Your matrix transform
-- (Optional) Physical key positions
-
-The physical layout should be placed in the same file as the matrix transform, i.e. `my_keyboard.overlay` for unibodies and `my_keyboard.dtsi` for split keyboards.
-
-A physical layout is very basic, e.g.:
-
-```dts
-/ {
-    default_layout: default_layout {
-        compatible = "zmk,physical-layout";
-        display-name = "Default Layout";
-        transform = <&default_transform>;
-        kscan = <&kscan0>;
-    };
-};
-```
-
-If a keyboard has multiple possible layouts (ex. you can snap off an outer column), then you should define multiple matrix transformations and multiple physical layouts.
-If necessary, you can also define multiple kscan instances.
+A very basic physical layout looks like this:
 
 ```dts
 / {
@@ -478,18 +460,9 @@ If necessary, you can also define multiple kscan instances.
         transform = <&default_transform>;
         kscan = <&kscan0>;
     };
-
-    alt_layout: alt_layout {
-        compatible = "zmk,physical-layout";
-        display-name = "Alternate Layout";
-        transform = <&alt_transform>;
-        kscan = <&alt_kscan0>;
-    };
 };
 ```
 
-See [ZMK Studio Setup](./studio-setup.md) for information on defining the `keys` property for physical key positions that lets you enable [ZMK Studio](../../features/studio.md) for your keyboard.
-
 ### Chosen Node
 
 Set the `chosen` node to a defined "default" physical layout. This should also be placed in the same file as the physical layout, i.e. `my_keyboard.overlay` for unibodies and `my_keyboard.dtsi` for split keyboards.
@@ -503,7 +476,7 @@ Set the `chosen` node to a defined "default" physical layout. This should also b
 };
 ```
 
-If you define multiple physical layouts, users can select a different layout by overriding the `zmk,physical-layout` chosen node in their keymap file.
+If you define multiple physical layouts, users can select a different layout by overriding the `zmk,physical-layout` chosen node in their keymap file or by using [ZMK Studio](../../features/studio.md) if your board is compatible with it.
 
 :::note
 If all of your physical layouts use the same `kscan` node under the hood, you can skip setting the `kscan` property on each layout and instead assign the `zmk,kscan` chosen node to your single kscan instance:
@@ -550,6 +523,7 @@ Here is an example simple keymap for a 3x3 macropad, with only one layer:
 
 The keymap should match the order of the keys in the [matrix transform](#matrix-transform) exactly, left to right, top to bottom (they are both 1 dimensional arrays rearranged with newline characters for better legibility).
 See [Keymaps](../../keymaps/index.mdx) for information on defining keymaps in ZMK.
+If you wish to use [ZMK Studio](../../features/studio.md) with your keyboard, make sure to assign the [ZMK Studio unlocking behavior](../../keymaps/behaviors/studio-unlock.md) to a key in your keymap.
 
 ## Metadata
 
diff --git a/docs/docs/development/hardware-integration/physical-layouts.md b/docs/docs/development/hardware-integration/physical-layouts.md
new file mode 100644
index 0000000000..873bc714a8
--- /dev/null
+++ b/docs/docs/development/hardware-integration/physical-layouts.md
@@ -0,0 +1,452 @@
+---
+title: Physical Layouts
+toc_max_heading_level: 4
+---
+
+A physical layout is a devicetree entity that aggregates all details about a certain possible keyboard layout.
+It contains:
+
+- A [keyboard scan (kscan) driver](../../config/kscan.md)
+- A [matrix transform](../../config/layout.md#matrix-transform)
+- (Optional) [Physical key positions](#physical-layout-positions)
+
+## Basic Physical Layout
+
+A basic physical layout without the `keys` property looks like this:
+
+```dts
+/ {
+    default_layout: default_layout {
+        compatible = "zmk,physical-layout";
+        display-name = "Default Layout";
+        transform = <&default_transform>;
+        kscan = <&kscan0>;
+    };
+};
+```
+
+It is given a name, a matrix transform, and a kscan. If all of your physical layouts share the same kscan, then the `kscan` property can be omitted - in this case it needs to be set in the [`chosen` node](./new-shield.mdx#chosen-node). See the [configuration section on physical layouts](../../config/index.md) for reference.
+
+## (Optional) Keys Property
+
+:::warning[Alpha Feature]
+
+[ZMK Studio](../../features/studio.md) support is in alpha. Although best efforts are being made, backwards compatibility during active development is not guaranteed.
+
+:::
+
+The `keys` property is required for [ZMK Studio](../../features/studio.md) support. It is used to describe the physical attributes of each key position present in that layout. If this property is used, then you should define the physical layouts and any [position maps](#position-map) in a file called `<your keyboard>-layouts.dtsi`. This file should then be imported by the appropriate file, such as an `.overlay`, `.dts`, or a `.dtsi` (last of which is itself imported by one of the previous).
+
+To pull in the necessary definition for creating physical layouts with the `keys` property, a new include should be added to the top of the devicetree file:
+
+```
+#include <physical_layouts.dtsi>
+```
+
+Assigned to the `keys` property is an array of key descriptions listed in the same order as keymap bindings, matrix transforms, etc.
+A key description has the shape `<&key_physical_attrs w h x y r rx ry>` with the following properties:
+
+| Property   | Type     | Description                          | Unit                                                    |
+| ---------- | -------- | ------------------------------------ | ------------------------------------------------------- |
+| Width      | int (>0) | Key(cap) width                       | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Height     | int (>0) | Key(cap) height                      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| X          | uint     | Key X position (top-left point)      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Y          | uint     | Key Y position (top-left point)      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Rotation   | int      | Key rotation (positive => clockwise) | [centi-](https://en.wikipedia.org/wiki/Centi-)degree    |
+| Rotation X | int      | Rotation origin X position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+| Rotation Y | int      | Rotation origin Y position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
+
+:::tip
+You can specify negative values in devicetree using parentheses around it, e.g. `(-3000)` for a 30 degree counterclockwise rotation.
+:::
+
+### Physical Layout with Keys Example
+
+Here is an example of a physical layout for a 2x2 macropad:
+
+```dts
+#include <physical_layouts.dtsi>
+
+/ {
+    macropad_physical_layout: macropad_physical_layout {
+        compatible = "zmk,physical-layout";
+        display-name = "Macro Pad";
+        transform = <&default_transform>;
+        kscan = <&kscan0>;
+        keys  //                     w   h    x    y     rot    rx    ry
+            = <&key_physical_attrs 100 100    0    0       0     0     0>
+            , <&key_physical_attrs 100 100  100    0       0     0     0>
+            , <&key_physical_attrs 100 100    0  100       0     0     0>
+            , <&key_physical_attrs 100 100  100  100       0     0     0>
+            ;
+    };
+};
+```
+
+## Using Predefined Layouts
+
+ZMK defines a number of popular physical layouts in-tree at [`app/dts/layouts`](https://github.com/zmkfirmware/zmk/tree/main/app/dts/layouts).
+To use such layouts, import them and assign their `transform` and (optionally) `kscan` properties.
+
+Here is an example of using the predefined physical layouts for a keyboard with the same layout as the "ferris":
+
+```dts
+#include <layouts/cuddlykeyboards/ferris.dtsi>
+
+// Assigning suitable kscan and matrix transforms
+&cuddlykeyboards_ferris_layout {
+    transform = <&default_transform>;
+    kscan = <&kscan0>;
+};
+```
+
+Shared physical layouts found in the same folder are defined such that they can be used together, to define [multiple physical layout](#multiple-physical-layouts) options. See below for more information on multiple physical layouts.
+
+Here is an example of using the predefined physical layouts for a 60% keyboard:
+
+```dts
+#include <layouts/common/60percent/all1u.dtsi>
+#include <layouts/common/60percent/ansi.dtsi>
+#include <layouts/common/60percent/hhkb.dtsi>
+#include <layouts/common/60percent/iso.dtsi>
+
+
+// Assigning suitable kscan and matrix transforms
+&layout_60_ansi {
+    transform = <&ansi_transform>;
+    kscan = <&ansi_kscan>;
+};
+
+&layout_60_iso {
+    transform = <&iso_transform>;
+    kscan = <&iso_kscan>;
+};
+
+&layout_60_all1u {
+    transform = <&all_1u_transform>;
+    kscan = <&all_1u_kscan>;
+};
+
+&layout_60_hhkb {
+    transform = <&hhkb_transform>;
+    kscan = <&hhkb_kscan>;
+};
+```
+
+## Multiple Physical Layouts
+
+If a keyboard has multiple possible layouts (e.g. you can snap off an outer column), then you should define multiple matrix transformations and multiple physical layouts, one for each possible layout.
+If necessary, you can also define multiple kscan instances.
+
+```dts
+// Needed if and only if keys property is used
+#include <physical_layouts.dtsi>
+
+/ {
+    default_layout: default_layout {
+        compatible = "zmk,physical-layout";
+        display-name = "Default Layout";
+        transform = <&default_transform>;
+        kscan = <&kscan0>;
+        keys = <...>; // List of key positions, optional
+    };
+
+    alt_layout: alt_layout {
+        compatible = "zmk,physical-layout";
+        display-name = "Alternate Layout";
+        transform = <&alt_transform>;
+        kscan = <&alt_kscan0>;
+        keys = <...>; // List of key positions, optional
+    };
+};
+```
+
+### Position Map
+
+When switching between layouts using [ZMK Studio](../../features/studio.md), an attempt is made to automatically infer bindings for the keys in the new layout from the old layout. Keys with the same physical key properties are given the same binding. This approach has some limitations, so for more accurate transference of bindings a position map is used.
+
+A position map looks something like this:
+
+```dts
+/ {
+    position_map {
+        compatible = "zmk,physical-layout-position-map";
+        complete; // Optional, see 'Example non-complete position map'
+        layout1: layout1 {
+            physical-layout = <&physical_layout1>;
+            positions = <...>; // List of positions to map
+        };
+        layout2: layout2 {
+            physical-layout = <&physical_layout2>;
+            positions = <...>; // List of positions to map
+        };
+        // Additional layout child nodes
+    };
+};
+```
+
+A child node is defined for every layout the keyboard can have. The `positions` properties each contain an array of indices, which are used to refer to keys in the `keys` array of their corresponding physical layout. A `0` in the `positions` property refers to the first key in the `keys` array, a `1` refers to the second, and so on.
+
+When switching from one layout to another, say from layout 1 to layout 2, the _orderings_ found in the `positions` arrays are used. The first key in the `positions` array of layout 2 is given the binding assigned to the first key in the `positions` array of layout 1, the second key in the `positions` array of layout 2 is given the binding assigned to the second key in the `positions` array of layout 1, and so on.
+
+The position map should be marked as `complete` if all desired binding transfers are defined within it. Otherwise, [ZMK Studio](../../features/studio.md) will continue to automatically determine assignments for keys not listed in the position map. See [this example non-complete position map](#example-non-complete-position-map) for why this could be useful.
+
+See also the [configuration section on position maps](../../config/layout.md#physical-layout-position-map).
+
+#### Writing a position map
+
+Start by creating the parent node defining the position map:
+
+```dts
+/ {
+    keypad_position_map {
+        compatible = "zmk,physical-layout-position-map";
+        complete; // Optional, see 'Example non-complete position map'
+
+        // Child node 1 here
+
+        // Child node 2 here
+
+        // ...
+    };
+};
+```
+
+It is easiest to write the position map by considering one layout to be the "reference" layout, and defining all other position maps with respect to it. The reference layout should usually be the one with the most keys, as that creates a position map where no key bindings are lost when switching to a layout with fewer keys and back.
+
+Create the child node for the reference layout, and fill the `positions` array by counting upwards, giving it the same order and number of keys as the `keys` property of its physical layout. For a 2x2 macropad the child node would be
+
+```dts
+/ {
+    keypad_position_map {
+        // Other properties
+
+        macropad_map: macropad {
+            physical-layout = <&macropad_layout>;
+            positions // This is equivalent to `positions = <0 1 2 3>;`, reshaped for readability
+                = < 0  1 >
+                , < 2  3 >;
+        };
+    };
+};
+```
+
+Next write the child nodes for every other layout with respect to the reference. For keys present in the reference which aren't present in the layout you're writing the child node for, count backwards: The first key that isn't present is given the highest number found in the `positions` array of the reference, the second key that isn't present is given the second highest number, and so on. The below examples show this process more clearly.
+
+#### Example larger position map
+
+Consider the following macropad/numpad with two physical layouts:
+
+![A 4x5 numpad/macropad](../../assets/hardware-integration/numpad.svg)
+
+Let us first consider each side individually. The "reference" position map of the left side would look like this:
+
+```dts
+/ {
+    keypad_position_map {
+        // Other properties
+
+        macropad_map: macropad {
+            physical-layout = <&macropad_layout>;
+            positions
+                = < 0  1  2  3>
+                , < 4  5  6  7>
+                , < 8  9 10 11>
+                , <12 13 14 15>
+                , <16 17 18 19>;
+        };
+    };
+};
+```
+
+Meanwhile, the "reference" position map of the right side with fewer keys would look like this:
+
+```dts
+/ {
+    keypad_position_map {
+        // Other properties
+
+        numpad_map: numpad {
+            physical-layout = <&numpad_layout>;
+            positions
+                = < 0  1  2  3>
+                , < 4  5  6  7>
+                , < 8  9 10   >
+                , <11 12 13 14>
+                , <15    16   >;
+        };
+    };
+};
+```
+
+As a reminder, the `positions` property is a one-dimensional array like the `keys` property, formatted nicely through the use of whitespace and angle bracket groupings.
+
+If the left side with more keys was used as the reference layout, then the overall position map of the keyboard would look like this:
+
+```dts
+/ {
+    keypad_lossless_position_map {
+        compatible = "zmk,physical-layout-position-map";
+        complete;
+
+        macropad_map: macropad {
+            physical-layout = <&macropad_layout>;
+            positions
+                = < 0  1  2  3>
+                , < 4  5  6  7>
+                , < 8  9 10 11>
+                , <12 13 14 15>
+                , <16 17 18 19>;
+        };
+
+        numpad_map: numpad {
+            physical-layout = <&numpad_layout>;
+            positions
+                = < 0  1  2  3>
+                , < 4  5  6  7>
+                , < 8  9 10 19>
+                , <11 12 13 14>
+                , <15 18 16 17>;
+        };
+    };
+};
+```
+
+The "missing" positions are filled with the "spare" numbers of the layout with more keys. The order in which the spare keys are used is arbitrary and counting backwards is a convenient way to assign them.
+
+If the right side with fewer keys were used as a reference instead, then the overall position map would look like this:
+
+```dts
+/ {
+    keypad_lossy_position_map {
+        compatible = "zmk,physical-layout-position-map";
+        complete;
+
+        macropad_map: macropad {
+            physical-layout = <&macropad_layout>;
+            positions
+                = < 0  1  2  3>
+                , < 4  5  6  7>
+                , < 8  9 10   >
+                , <12 13 14 15>
+                , <16    18   >;
+        };
+
+        numpad_map: numpad {
+            physical-layout = <&numpad_layout>;
+            positions
+                = < 0  1  2  3>
+                , < 4  5  6  7>
+                , < 8  9 10   >
+                , <11 12 13 14>
+                , <15    16   >;
+        };
+    };
+};
+```
+
+The above example is "lossy" because (unlike the previous "lossless" example) if a user switches from the macropad layout to the numpad layout _and then_ switches from the numpad layout back to the macropad layout, the assignments to the keys present but not listed in the macropad's map are lost.
+
+#### Example non-`complete` position map
+
+Consider the above device again -- most of the positions have identical `keys` properties. For example, the macropad's `12` key and the numpad's `11` key would have the same physical property, and be mapped to each other automatically. The keys whose mappings are unable to be determined automatically are those with different physical characteristics: the 2u high and 2u wide keys, and their corresponding 1u counterparts.
+
+A non-`complete` position map can be used to assign mappings to only these particular keys:
+
+```dts
+/ {
+    keypad_lossy_position_map {
+        compatible = "zmk,physical-layout-position-map";
+
+        macropad_map: macropad {
+            physical-layout = <&macropad_layout>;
+            positions = <7 15 16>;
+        };
+
+        numpad_map: numpad {
+            physical-layout = <&numpad_layout>;
+            positions = <7 14 15>;
+        };
+    };
+};
+```
+
+This is noticably simpler to write, and can be a useful way of saving flash space for memory-constrained devices. The above is a "lossy" mapping, though. While "lossless" non-`complete` mappings are possible, they can be counter-intuitive enough that it may be easier to write the full position map instead.
+
+For completeness, the equivalent "lossless" non-`complete` position map is shown below:
+
+```dts
+/ {
+    keypad_lossy_position_map {
+        compatible = "zmk,physical-layout-position-map";
+
+        macropad_map: macropad {
+            physical-layout = <&macropad_layout>;
+            positions = <7 11 15 19 16 17>;
+        };
+
+        numpad_map: numpad {
+            physical-layout = <&numpad_layout>;
+            positions = <7 19 14 18 15 17>;
+        };
+    };
+};
+```
+
+#### Additional example: corne
+
+The following is an example of a "lossless" position map which maps the 5-column and 6-column Corne keymap layouts. The 6 column layout is the reference layout.
+
+```dts
+    foostan_corne_lossless_position_map {
+        compatible = "zmk,physical-layout-position-map";
+
+        complete;
+
+        twelve_map: twelve {
+            physical-layout = <&foostan_corne_6col_layout>;
+            positions
+                = < 0  1  2  3  4  5  6  7  8  9 10 11>
+                , <12 13 14 15 16 17 18 19 20 21 22 23>
+                , <24 25 26 27 28 29 30 31 32 33 34 35>
+                , <         36 37 38 39 40 41         >;
+        };
+
+        ten_map: ten {
+            physical-layout = <&foostan_corne_5col_layout>;
+            positions
+                = <41  0  1  2  3  4  5  6  7  8  9 40>
+                , <39 10 11 12 13 14 15 16 17 18 19 38>
+                , <37 20 21 22 23 24 25 26 27 28 29 36>
+                , <         30 31 32 33 34 35         >;
+        };
+    };
+```
+
+Meanwhile, the "lossy" version of the same position map with the 5 column version as reference looks like this:
+
+```dts
+    foostan_corne_lossy_position_map {
+        compatible = "zmk,physical-layout-position-map";
+
+        complete;
+
+        twelve_map: twelve {
+            physical-layout = <&foostan_corne_6col_layout>;
+            positions
+                = < 1  2  3  4  5  6  7  8  9 10>
+                , <13 14 15 16 17 18 19 20 21 22>
+                , <25 26 27 28 29 30 31 32 33 34>
+                , <      36 37 38 39 40 41      >;
+        };
+
+        ten_map: ten {
+            physical-layout = <&foostan_corne_5col_layout>;
+            positions
+                = < 0  1  2  3  4  5  6  7  8  9>
+                , <10 11 12 13 14 15 16 17 18 19>
+                , <20 21 22 23 24 25 26 27 28 29>
+                , <      30 31 32 33 34 35      >;
+        };
+    };
+```
diff --git a/docs/docs/development/hardware-integration/studio-setup.md b/docs/docs/development/hardware-integration/studio-setup.md
deleted file mode 100644
index dfa8002037..0000000000
--- a/docs/docs/development/hardware-integration/studio-setup.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-title: ZMK Studio Setup
----
-
-:::warning[Alpha Feature]
-
-ZMK Studio support is in alpha. Although best efforts are being made, backwards compatibility during active development is not guaranteed.
-
-:::
-
-This guide will walk you through enabling ZMK Studio support for a keyboard.
-
-The main additional pieces needed for ZMK Studio support involve additional metadata needed in order
-to properly to display the physical layouts available for the particular keyboard.
-
-# Physical Layout Positions
-
-Physical layouts are described as part of the [new shield guide](./new-shield.mdx#physical-layout) with the exception of the `keys` property that is required for ZMK Studio support. This is used to describe the physical attributes of each key position present in that layout and its items are listed in the same order as keymap bindings, matrix transforms, etc. The properties available are:
-
-| Property   | Type     | Description                          | Unit                                                    |
-| ---------- | -------- | ------------------------------------ | ------------------------------------------------------- |
-| Width      | int (>0) | Key(cap) width                       | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
-| Height     | int (>0) | Key(cap) height                      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
-| X          | uint     | Key X position (top-left point)      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
-| Y          | uint     | Key Y position (top-left point)      | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
-| Rotation   | int      | Key rotation (positive => clockwise) | [centi-](https://en.wikipedia.org/wiki/Centi-)degree    |
-| Rotation X | int      | Rotation origin X position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
-| Rotation Y | int      | Rotation origin Y position           | [centi-](https://en.wikipedia.org/wiki/Centi-)"keyunit" |
-
-:::note
-You can specify negative values in devicetree using parentheses around it, e.g. `(-3000)` for a 30 degree counterclockwise rotation.
-:::
-
-## Header Include
-
-To pull in the necessary definition for creating physical layouts, a new include should be added to the top of the devicetree file:
-
-```
-#include <physical_layouts.dtsi>
-```
-
-## Example
-
-Here is an example physical layout for a 2x2 macropad:
-
-```dts
-    macropad_physical_layout: macropad_physical_layout {
-        compatible = "zmk,physical-layout";
-        display-name = "Macro Pad";
-
-        keys  //                     w   h    x    y     rot    rx    ry
-            = <&key_physical_attrs 100 100    0    0       0     0     0>
-            , <&key_physical_attrs 100 100  100    0       0     0     0>
-            , <&key_physical_attrs 100 100    0  100       0     0     0>
-            , <&key_physical_attrs 100 100  100  100       0     0     0>
-            ;
-    };
-```
-
-# Position Map
-
-When switching between layouts with ZMK Studio, the keymap of the previously selected layout is used to populate the keymap in the new layout. To determine which keymap entry maps to which entry in the new layout, keys between the two layouts that share the exact same physical attributes are matched.
-
-However, keys between layouts might not be in exactly the same positions, in which case a position map can be used. The position map includes a sequence for every relevant layout, and the corresponding entries in `positions` property will be used to determine the mapping between layouts. By default, the physical attribute matching behavior will be used as a fallback for positions not specified in the map, but the `complete` property can be added to the map to specify that no matching fallback should occur.
-
-:::info
-
-Key positions in the maps are numbered like the keys in your keymap, starting at 0. So the first position in the layout is position `0`, the next key position is `1`, etc.
-
-:::
-
-## Examples
-
-### Basic Map
-
-For example, the following position map correctly maps the 5-column and 6-column Corne keymap layouts.
-
-```dts
-    foostan_corne_position_map {
-        compatible = "zmk,physical-layout-position-map";
-
-        complete;
-
-        twelve {
-            physical-layout = <&foostan_corne_6col_layout>;
-            positions
-                = < 1  2  3  4  5  6  7  8  9 10>
-                , <13 14 15 16 17 18 19 20 21 22>
-                , <25 26 27 28 29 30 31 32 33 34>
-                , <      36 37 38 39 40 41      >;
-        };
-
-        ten {
-            physical-layout = <&foostan_corne_5col_layout>;
-            positions
-                = < 0  1  2  3  4  5  6  7  8  9>
-                , <10 11 12 13 14 15 16 17 18 19>
-                , <20 21 22 23 24 25 26 27 28 29>
-                , <      30 31 32 33 34 35      >;
-        };
-    };
-```
-
-The first entries in the two mappings have values `1` and `0` respectively, which means that position `1` in the 6-column layout will map to position `0` in the 5-column layout, the second entries show that position `2` in the 6-column layout corresponds to position `1` in the 5-column layout, etc.
-
-### Full Preserving Map
-
-The above basic example has one major downside. Because the keys on the outer columns of the 6-column layout aren't mapped into any locations in the 5-column layout, when a user switches to the 5-column layout and then back to the 6-column layout, the bindings for those outer columns will have been lost/dropped at the first step.
-
-In order to preserve those bindings that are in "missing" keys in other layouts, we can include those locations in the map, but map them "off the end" of the smaller layout key positions.
-
-Here is a fixed up Corne mapping:
-
-```dts
-    foostan_corne_position_map {
-        compatible = "zmk,physical-layout-position-map";
-
-        complete;
-
-        twelve {
-            physical-layout = <&foostan_corne_6col_layout>;
-            positions
-                = < 0  1  2  3  4  5  6  7  8  9 10 11>
-                , <12 13 14 15 16 17 18 19 20 21 22 23>
-                , <24 25 26 27 28 29 30 31 32 33 34 35>
-                , <         36 37 38 39 40 41         >;
-        };
-
-        ten {
-            physical-layout = <&foostan_corne_5col_layout>;
-            positions
-                = <36  0  1  2  3  4  5  6  7  8  9 37>
-                , <38 10 11 12 13 14 15 16 17 18 19 39>
-                , <40 20 21 22 23 24 25 26 27 28 29 41>
-                , <         30 31 32 33 34 35         >;
-        };
-    };
-```
-
-Notice how the outer column positions in the 6-column layout are mapped to positions 36, 37, etc. in the 5-column layout. The 5-column layout only uses key positions up to 35, so those bindings in the outer columns will get migrated into the "extra space" that is ignored by the smaller layout, preserved to get mapped back in place when the user switches back.
diff --git a/docs/docs/features/studio.md b/docs/docs/features/studio.md
index f8d4059b95..4053d3d9a1 100644
--- a/docs/docs/features/studio.md
+++ b/docs/docs/features/studio.md
@@ -10,6 +10,10 @@ ZMK Studio support is in alpha. Although best efforts are being made, keeping co
 
 ZMK Studio provides runtime update functionality to ZMK powered devices, allowing users to change their keymap layers without flashing new firmware to their keyboards. Studio is still under active development, and is not yet ready for casual end user use.
 
+## Keymap Changes
+
+To unlock your keyboard to allow ZMK Studio to make changes, you'll need to add a [`&studio_unlock`](../keymaps/behaviors/studio-unlock.md) binding to the keymap.
+
 ## Building
 
 Building for ZMK Studio involves two main additional items.
@@ -109,3 +113,11 @@ By default, a build with ZMK Studio enabled will only allow as many layers as ar
 ```
 
 The reserved layers will be ignored during regular ZMK builds but will become available for ZMK Studio enabled builds.
+
+## Adding ZMK Studio Support to a Keyboard
+
+To allow ZMK Studio to be used with a keyboard, the keyboard will need to have a physical layout with the `keys` property defined. Relevant information can be found in:
+
+- The [dedicated page on physical layouts](../development/hardware-integration/physical-layouts.md), informing you how to define one
+- The [new shield guide](../development/hardware-integration/new-shield.mdx), informing you how to select a physical layout once defined
+- The corresponding [configuration page](../config/layout.md#physical-layout), for reference
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 9f67147149..4c278d4bbe 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -110,6 +110,7 @@ module.exports = {
         "config/displays",
         "config/encoders",
         "config/keymap",
+        "config/layout",
         "config/kscan",
         "config/power",
         "config/underglow",
@@ -125,9 +126,9 @@ module.exports = {
           collapsed: true,
           items: [
             "development/hardware-integration/new-shield",
+            "development/hardware-integration/physical-layouts",
             "development/hardware-integration/hardware-metadata-files",
             "development/hardware-integration/boards-shields-keymaps",
-            "development/hardware-integration/studio-setup",
             "development/hardware-integration/shift-registers",
             "development/hardware-integration/encoders",
           ],
diff --git a/docs/static/_redirects b/docs/static/_redirects
index f5e8da2602..de769e94b6 100644
--- a/docs/static/_redirects
+++ b/docs/static/_redirects
@@ -17,4 +17,5 @@
 /docs/development/posix-board /docs/development/local-toolchain/posix-board 301
 /docs/development/pre-commit /docs/development/local-toolchain/pre-commit 301
 /docs/development/tests /docs/development/local-toolchain/tests 301
-/docs/development/guides/new-behavior /docs/development/new-behavior 301
\ No newline at end of file
+/docs/development/guides/new-behavior /docs/development/new-behavior 301
+/docs/development/hardware-integration/studio-setup /docs/development/hardware-integration/physical-layouts 301