diff --git a/front/ui-docs/using-color.md b/front/ui-docs/using-color.md
index a8375a697..a0a1d8da1 100644
--- a/front/ui-docs/using-color.md
+++ b/front/ui-docs/using-color.md
@@ -2,10 +2,17 @@
 import { color } from "~/composables/colors.ts"
 import Button from "~/components/ui/Button.vue"
 import Card from "~/components/ui/Card.vue"
+import Link from "~/components/ui/Link.vue"
 import Layout from "~/components/ui/Layout.vue"
+import Alert from "~/components/ui/Alert.vue"
 import Spacer from "~/components/ui/layout/Spacer.vue"
 </script>
 
+<Link disabled to="#theme-color-definitions">Want to fix colors?</Link>
+<Link solid primary to="#change-a-color-value">Change a color value</Link>
+<Link solid primary to="#alter-the-shade-of-a-color">Alter the shade of a color</Link>
+<Link solid primary to="#choose-a-different-style-for-a-specific-variant">Modify a specific variant</Link>
+
 # Using Color
 
 ## Add color via props
@@ -498,6 +505,70 @@ For each semantic color, we set a foreground and a background. In addition, we n
 
 [-> Example: #interactive-and-or-raised](#interactive-and-or-raised)
 
+## Theme color definitions
+
+All colors are defined in `front/src/style/colors.scss`.
+
+Its structure is as follows:
+
+<Layout stack style="--width:100%; background:#0002;">
+
+<Card solid purple title="(1) Palette">
+
+Defining [all funkwhale color values](#palette)
+
+</Card>
+
+<Card solid blue title="(2) Choosing the semantic colors from the palette">
+
+both for light and dark theme, and both normal and raised:
+
+- default
+- secondary
+- primary
+- destructive
+- blue
+- red
+- purple
+- green
+- yellow
+
+</Card>
+
+<Card solid green title="(3) Applying colors">
+
+(for all elements not managed by vitepress)
+
+- (a) Applying colors to things with no explicit Variant props, such as headings and paragraphs, simple links, focusable elements
+- (b) Applying colors to things with explicit Variant props: - solid (and default buttons) - ghost - outline
+  </Card>
+
+</Layout>
+
+## Change a color value
+
+For example, you want to make all blue hues more cyan-ish or mute all reds.
+
+- Find the color value you want to change in **section 1 (Palette)**
+- Change it
+- Keep this page open and check under [Palette](#palette) if the colors are still in harmony with each other. Also make sure all recommended color combinations still meet the relevant WCGA2 recommendations for contrast
+
+## Alter the shade of a color
+
+In funkwhale components, we use semantic color names such as `primary`, `destructive`, `default` (neutral). Now, you find, for example, that a secondary button has low contrast in light mode, and you decide to alter the text color.
+
+- Find the relevant section in **section 2 (hoosing the semantic colors from the palette)**. In our example, it's `.secondary` under `theme-light`.
+- You see that the values are `--color: var(--fw-gray-700);` and `--background-color: var(--fw-gray-200);`, and you change `--color` to `var(--fw-gray-900)`.
+- Test your changes. If nothing changes, then there is a Css rule with higher precedence. Find and eliminate these sorts of competing rules.
+
+## Choose a different style for a specific variant
+
+For example, you want to add visible lines around ghost links and buttons when the user hovers over them.
+
+- Find the variant class in **section 3 (Applying colors)**. In our example, it is `.ghost`.
+- In our example, we would add the line `border-color: var(--hover-border-color);` under `&:hover` to make the outline on interactive items visible on hover.
+- Make sure to test all affected components before committing and merging the changes
+
 <style module>
     .swatch {
       transition:all .15s, filter 0s;