diff --git a/front/ui-docs/components/ui/alert.md b/front/ui-docs/components/ui/alert.md
index 86cb68ca7..c4e23a0b0 100644
--- a/front/ui-docs/components/ui/alert.md
+++ b/front/ui-docs/components/ui/alert.md
@@ -4,7 +4,7 @@ import Button from "~/components/ui/Button.vue"
 </script>
 
 ```ts
-import Alert from "~/components/ui/Alert.vue"
+import Alert from "~/components/ui/Alert.vue";
 ```
 
 # Alert
@@ -79,10 +79,9 @@ Funkwhale alerts support a range of pastel colors for visual appeal.
 
 ## Alert actions
 
-```vue-html{2-4}
+```vue-html{3-6}
 <Alert blue>
   Awesome artist
-
   <template #actions>
     <Button disabled>Deny</Button>
     <Button>Got it</Button>
diff --git a/front/ui-docs/components/ui/layout/section.md b/front/ui-docs/components/ui/layout/section.md
index e91ae06d8..d91a0c6d2 100644
--- a/front/ui-docs/components/ui/layout/section.md
+++ b/front/ui-docs/components/ui/layout/section.md
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 
 import { type Track, type User } from '~/types'
 
@@ -102,7 +102,7 @@ const user: User = {
 </script>
 
 ```ts
-import Section from "~/components/ui/Section.vue"
+import Section from "~/components/ui/Section.vue";
 ```
 
 # Layout section
@@ -136,10 +136,10 @@ The link or button will be shown on the right side of the header.
 ```vue-html
 <Layout stack gap-64>
   <Spacer />
-  <Section h3="With a link" 
+  <Section h3="With a link"
     :action="{ text:'My library', to:'/' }" />
 
-  <Section h3="With a button" 
+  <Section h3="With a button"
     :action="{ text:'Say hello!', onClick:()=>console.log('Hello') }" />
 </Layout>
 ```
@@ -162,36 +162,29 @@ You can add props to the Link or Button, for example to make them `primary` or a
 <Section solid primary icon="bi-star"
     h3="Example" :action="{ text:'Say hello!', onClick:()=>console.log('Hello') }" />
 
-::: tip Gaps between consecutive sections
+## Set gaps between consecutive sections
 
-Place consecutive sections into a [Layout stack](../layout) width a size of 64px give them a regular vertical rhythm. Use different sizes for very small or very large headings.
-You can add spacers with negative or positive size if you want to manually make a specific distance smaller or larger than the others.
+Place consecutive sections into a [Layout stack](../layout) with a 64px gap (`gap-64`) to give them a regular vertical rhythm. Use different sizes for very small or very large headings.
+
+Note the spacer above the layout. By default, sections begin at the baseline of the heading. This enables us to explicitly define the vertical rhythm, independently of the heading's line height.
 
 ```vue-html
+<Spacer/>
 <Layout stack gap-64>
-  <Spacer />
   <Section h3="Section 1" />
   <Section h3="Section 2" />
 </Layout>
 ```
 
+<Spacer />
 <Layout stack gap-64>
-  <Spacer no-size />
   <Section h3="Section 1" />
   <Section h3="Section 2" />
 </Layout>
 
 <Spacer />
 
-:::
-
-::: tip Let items cover the whole grid width
-
-To prevent items from being put on a grid, add `style="grid-column: 1 / -1"` which means that they span "all existing columns".
-
-:::
-
-## Example
+## Mix sections of different item widths
 
 ```vue-html
 <Layout flex>
@@ -259,9 +252,7 @@ To prevent items from being put on a grid, add `style="grid-column: 1 / -1"` whi
 
 ## Responsivity
 
-- Cards and Activities snap to the grid columns. They have intrinsic widths, expressed in the number of columns they span. For Card, it is 3 and for Activity, it is 4.
-- On a typical laptop screen, you will have 4 albums or 3 activities side-by-side. On a typical mobile screen, you will have 1 medium card or 2 small ones in a row.
+- Cards and Activities snap to the grid columns. They have intrinsic widths, expressed in the number of columns they span. For `Card`, it is `3` and for `Activity`, it is `4`.
+- On a typical laptop screen, you may have 4 album cards or 3 activities side-by-side. On a typical mobile screen, you will have one medium card or two small ones in a row.
 - The remaining space is evenly distributed.
-- Title rows align with the content below them.
-
-Resize the window to observe how the items move.
+- Title rows align with the content below them. The action on the right will always end with the last item in the grid. Resize the window to observe how the items move.