From 0cfac5066936e3783f23733903be7ab4f62efbc8 Mon Sep 17 00:00:00 2001
From: upsiflu <upsiflu@gmail.com>
Date: Mon, 6 Jan 2025 20:56:03 +0100
Subject: [PATCH] chore(ui-docs): document `aria-pressed` and toggle-switch vs.
 toggle-button

---
 front/ui-docs/components/ui/button.md | 31 ++++++++++++++++++++++-----
 front/ui-docs/components/ui/toggle.md |  2 +-
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/front/ui-docs/components/ui/button.md b/front/ui-docs/components/ui/button.md
index 49d7363c4..91b05c8d3 100644
--- a/front/ui-docs/components/ui/button.md
+++ b/front/ui-docs/components/ui/button.md
@@ -237,13 +237,34 @@ Round buttons have fully rounded edges.
 
 ## Button states
 
-You can pass a state to indicate whether a user can interact with a button.
-
 ### On/Off
 
 You can force an active state by passing an `aria-pressed` prop.
 
-This can be useful for toggle buttons (if you don't want to use a [Toggle component](toggle))
+::: tip When do I use a Toggle vs. a Button?
+
+**Use a Button with an `aria-pressed` prop**
+
+- if the semantics of the option change depending whether it's on or off
+- to perform asynchronous, stateful and fallible actions
+
+**Examples:**
+
+- Toggle a remote property
+- Open/close a section in the Ui
+- Toolbar buttons that toggle through many options such as "Paragraph/Heading/List"
+
+**Use the [Toggle component](toggle) (a.k.a. switch)**
+
+- for options that don't cause side-effects and never change the Toggle label content based on the Toggle state (think of the traditional checkbox).
+- for options that don't have any intermediary state besides "on" and "off"
+
+**Examples:**
+
+- A checkbox in the User settings
+- A checkbox in a form that the user submits later
+
+:::
 
 ```vue-html
 <Button>
@@ -291,9 +312,9 @@ This can be useful for toggle buttons (if you don't want to use a [Toggle compo
 
 ### Disabled
 
-Disabled buttons are non-interactive and inherit a less bold color than the one provided. You can apply a disabled state by passing a `disabled` prop.
+Disabled buttons are non-interactive and inherit a less bold color than the one provided.
 
-::: tip When should I use `disabled`?
+::: tip When do I use `disabled`?
 
 Use the `disabled` property for buttons that the user expects at a certain position, for example in a toolbar or in a row of action buttons.
 
diff --git a/front/ui-docs/components/ui/toggle.md b/front/ui-docs/components/ui/toggle.md
index 7f453d171..3e4760521 100644
--- a/front/ui-docs/components/ui/toggle.md
+++ b/front/ui-docs/components/ui/toggle.md
@@ -10,7 +10,7 @@ const toggle = ref(false)
 
 # Toggle
 
-Toggles are basic form inputs that visually represent a boolean value. Toggles can be **on** (`true`) or **off** (`false`).
+Toggles are basic form inputs that visually represent a boolean value. Toggles can be **on** (`true`) or **off** (`false`). For actions with more than 2 states or delayed, fallible, or effectful actions, [consider using a Button with `aria-pressed` logic instead](button#on-off).
 
 | Prop            | Data type | Required? | Description                              |
 | --------------- | --------- | --------- | ---------------------------------------- |