diff --git a/front/ui-docs/.vitepress/theme/Theme.vue b/front/ui-docs/.vitepress/theme/Theme.vue
index b7b451a60..1b7dfa857 100644
--- a/front/ui-docs/.vitepress/theme/Theme.vue
+++ b/front/ui-docs/.vitepress/theme/Theme.vue
@@ -35,6 +35,8 @@ const { Theme } = DefaultTheme
   padding: 16px 0;
   flex-grow: 1;
   border-radius: 8px;
+  justify-content: center;
+  --vp-code-block-bg: transparent;
 
   &:not(.transparent){
     background-color:var(--background-color);
diff --git a/front/ui-docs/components/ui/button.md b/front/ui-docs/components/ui/button.md
index 4a09d6853..39b03665a 100644
--- a/front/ui-docs/components/ui/button.md
+++ b/front/ui-docs/components/ui/button.md
@@ -41,7 +41,9 @@ Find [a complete overview of recommended styles on the color page](../../using-c
 
 ### Default
 
-<Layout flex>
+<Layout grid class="preview transparent">
+
+<div style="grid-column: span 3">
 
 ```vue-html
 <Button>
@@ -49,17 +51,21 @@ Find [a complete overview of recommended styles on the color page](../../using-c
 </Button>
 ```
 
-<Layout class="preview">
-  <Button>
-    Default button
-  </Button>
-</Layout>
+</div>
+
+<Button>
+  Default button
+</Button>
 
 </Layout>
 
 ### Primary
 
-Primary buttons represent **positive** actions such as uploading, confirming, and accepting changes.
+The primary button represents the **single positive** action on a page or modal, such as uploading, confirming, and accepting changes.
+
+<Layout grid class="preview">
+
+<div style="grid-column: span 3">
 
 ```vue-html
 <Button primary>
@@ -67,38 +73,60 @@ Primary buttons represent **positive** actions such as uploading, confirming, an
 </Button>
 ```
 
+</div>
+
 <Button primary>
   Primary button
 </Button>
 
+</Layout>
+
 ### Secondary
 
 Secondary buttons represent **neutral** actions such as cancelling a change or dismissing a notification.
 
+<Layout grid class="preview secondary">
+
+<div style="grid-column: span 3">
+
 ```vue-html
-<Button secondary>
+<Button secondary raised>
   Secondary button
 </Button>
 ```
 
-<Button secondary>
+</div>
+
+<Button secondary raised>
   Secondary button
 </Button>
 
+</Layout>
+
+Note that on a secondary background, the button needs to be `raised` to make it stand out.
+
 ### Destructive
 
 Desctrutive buttons represent **dangerous** actions including deleting items or purging domain information.
 
+<Layout grid class="preview">
+
+<div style="grid-column: span 3">
+
 ```vue-html
 <Button destructive>
   Destructive button
 </Button>
 ```
 
+</div>
+
 <Button destructive>
   Destructive button
 </Button>
 
+</Layout>
+
 ## Button variants
 
 Buttons come in different styles that you can use depending on the location of the button.
@@ -225,7 +253,7 @@ This can be useful for toggle buttons (if you don't want to use a [Toggle compo
 </Button>
 ```
 
-**Secondary (default):**
+**Default:**
 
 <Button>
   Inactive button
@@ -237,6 +265,18 @@ This can be useful for toggle buttons (if you don't want to use a [Toggle compo
 
 ---
 
+**Secondary:**
+
+<Button secondary>
+  Inactive button
+</Button>
+
+<Button secondary aria-pressed>
+  Active button
+</Button>
+
+---
+
 **Primary:**
 
 <Button primary>
@@ -275,6 +315,10 @@ If a user can't interact with a button until something has finished loading, you
   Loading button
 </Button>
 
+<Button primary is-loading>
+  Loading button
+</Button>
+
 ### Promise handling in `@click`
 
 When a function passed to `@click` returns a promise, the button automatically toggles a loading state on click. When the promise resolves or is rejected, the loading state turns off.
diff --git a/front/ui-docs/using-color.md b/front/ui-docs/using-color.md
index b5ed0dfe3..49c036879 100644
--- a/front/ui-docs/using-color.md
+++ b/front/ui-docs/using-color.md
@@ -22,8 +22,8 @@ Want to fix colors?
 <Link solid primary to="#choose-a-different-style-for-a-specific-variant">Modify a specific variant</Link>
 </Layout>
 </Alert>
-
 <Spacer />
+
 # Using Color
 
 ## Add color via props
@@ -445,40 +445,6 @@ Many browsers automatically turn on "night mode" to lower the light emission of
 
 In both "dark mode" and "light mode", the colors must provide adequate contrast and consistency.
 
-All colors added through the `color` or the `propsToColor` function in `composable/colors.ts` respect this setting. If you need to define new colors, use the following syntax in your `scss`:
-
-```scss
-@include light-theme {
-  --my-new-color: var(--fw-blue-400);
-}
-@include dark-theme {
-  --my-new-color: var(--fw-blue-800);
-}
-```
-
-It's good practice to limit the scope of a variable to the module that needs it:
-
-```vue
-<template>
-  <div :class="$style.newColor" />
-</template>
-
-<style module lang="scss">
-@include light-theme {
-  --foreground-color: var(--fw-blue-400);
-  --background-color: var(--fw-beige-100);
-}
-@include dark-theme {
-  --foreground-color: var(--fw-pastel-blue-1);
-  --background-color: var(--fw-gray-960);
-}
-.new-color {
-  color: var(--foreground-color);
-  background-color: var(--background-color);
-}
-</style>
-```
-
 Read more about [style modules in the corresponding vue docs](https://vuejs.org/api/sfc-css-features.html#css-modules).
 
 For testing purposes and side-by-side comparisons, you can add the classes `force-dark-theme` and `force-light-theme`.
@@ -650,7 +616,7 @@ Here is the meaning the styles should convey:
 <Button ghost> Button ghost </Button>
 <Button outline> Button outline </Button>
 <Button solid> Button solid </Button>
-<Button solid aria-pressed="true"> Button active </Button>
+<Button solid aria-pressed > Button active </Button>
 <Button disabled> Button disabled </Button>
 <Button primary> Button primary </Button>
 
@@ -692,7 +658,7 @@ Here is the meaning the styles should convey:
 <Button ghost> Button ghost </Button>
 <Button outline> Button outline </Button>
 <Button solid> Button solid </Button>
-<Button aria-pressed="true"> Button active </Button>
+<Button aria-pressed > Button active </Button>
 <Button disabled> Button disabled </Button>
 <Button primary> Button primary </Button>
 
@@ -734,7 +700,7 @@ Here is the meaning the styles should convey:
 <Button ghost> Button ghost </Button>
 <Button outline> Button outline </Button>
 <Button solid> Button solid </Button>
-<Button aria-pressed="true"> Button active </Button>
+<Button aria-pressed > Button active </Button>
 <Button disabled> Button disabled </Button>
 <Button primary> Button primary </Button>
 
@@ -776,7 +742,7 @@ Here is the meaning the styles should convey:
 <Button ghost> Button ghost </Button>
 <Button outline> Button outline </Button>
 <Button solid> Button solid </Button>
-<Button solid aria-pressed="true"> Button active </Button>
+<Button solid aria-pressed > Button active </Button>
 <Button disabled> Button disabled </Button>
 <Button primary> Button primary </Button>
 
@@ -786,7 +752,7 @@ Here is the meaning the styles should convey:
 <Button raised ghost> Button raised ghost </Button>
 <Button raised outline> Button raised outline </Button>
 <Button raised solid> Button raised solid </Button>
-<Button raised aria-pressed="true"> Button active </Button>
+<Button raised aria-pressed > Button active </Button>
 <Button raised disabled> Button raised disabled </Button>
 </Card>