diff --git a/docs/features/macros.md b/docs/features/macros.md
index ddeb112d6..58e4c095e 100644
--- a/docs/features/macros.md
+++ b/docs/features/macros.md
@@ -99,7 +99,7 @@ The following button types are supported:
 !!! warning
     Some GPIO pins can prevent the ESP from booting when they are held LOW or HIGH. Check the hardware requirements for your board before you use a GPIO pin as a switch input.
 
-For a momentary button, WLED detects the action _after you release_ the button. This delay lets WLED distinguish short, long, and double presses.
+For a momentary button, WLED detects short and double presses _after you release_ the button. This delay lets WLED distinguish short, long, and double presses.
 
 Set the same preset for short, long, and double press to run that preset _directly_ when the button is pressed.
 
@@ -108,6 +108,31 @@ Button 0 has two built-in functions:
 * Hold for more than 5 seconds to open the WLED-AP access point (default password `wled1234`).
 * Hold for more than 10 seconds to erase flash memory and perform a factory reset.
 
+### Button Timing
+
+_(available since 17.0.0)_
+
+You can change how WLED times button presses. This helps with buttons that are hard to press quickly, like buttons with long travel or stiff springs.
+
+Open **Config** > **LED Preferences**, go to **Buttons** and tick **Show Advanced Button Settings**.
+
+| Setting name | Value Range | Default | Description |
+| --- | --- | --- | --- |
+| Debounce time | 0–100 ms | 50 | Ignores button input shorter than this. This filters out contact noise |
+| Long-press time | 200–4000 ms | 600 | How long you hold a button before the long-press action runs |
+| Double-press time | 100–1000 ms | 350 | The longest gap between two presses that still counts as a double press |
+| Long-press repeat delay | 100–4000 ms | 600 | The pause after the first long-press action before it starts to repeat |
+| Long-press repeat interval | 100–4000 ms | 200 | The time between repeats while you keep holding the button |
+
+On buttons with a double-press action, WLED waits for the double-press time before it runs a short press. A longer double-press time makes short presses feel slower.
+
+If you keep holding a button (except button 0), the long-press action repeats. It runs once after the long-press time, again after the repeat delay, and then once every repeat interval. With the defaults, that's a 0.6 second pause, then a repeat every 0.2 seconds. This is how holding a button dims the lights, and how a long-press preset can step through a playlist.
+
+The repeat delay can't be shorter than the repeat interval. If you try, the settings page marks the delay in red and won't save until you fix it.
+
+!!! info
+    The long-press time doesn't change button 0's hold times. Opening the access point still takes 5 seconds, and a factory reset still takes 10 seconds.
+
 ### Example
 
 The simplest macro preset example is getting a button to do your bidding.  
diff --git a/docs/features/settings.md b/docs/features/settings.md
index 8d2545c50..63b71c06f 100644
--- a/docs/features/settings.md
+++ b/docs/features/settings.md
@@ -111,7 +111,7 @@ CCT blending | -100–100 % | 0 | Positive values blend the warm and cold white
 
 The lower part of the page configures the other hardware attached to your controller. Each is covered on its own page:
 
-- **Buttons**: add button GPIOs and pick their type (pushbutton, switch, PIR sensor, touch, analog). What a button does is set up under [Macros](/features/macros).
+- **Buttons**: add button GPIOs and pick their type (pushbutton, switch, PIR sensor, touch, analog). What a button does is set up under [Macros](/features/macros). To change the button timing (debounce, long-press, double-press and repeat times), tick **Show Advanced Button Settings**, see [Button Timing](/features/macros#button-timing).
 - **IR Remote**: the IR receiver GPIO and remote type, see [Infrared](/interfaces/infrared).
 - **Relay**: the relay GPIO and its invert / open drain options, see [Control a Relay](/features/relay-control).