Document animation configuration and desktop comparisons

README.md

@@ -30,6 +30,28 @@ Ferese combines a window manager and desktop shell with one configuration.
 - A built-in lock screen and authentication dialogs
 - Settings and Control Center with Wi-Fi, Bluetooth and audio controls
 
+## How Ferese compares
+
+Ferese combines scrolling and tree layouts with its own desktop controls. The table
+compares current upstream features and names separate tools where they are needed.
+
+| Feature | Ferese | [Hyprland](https://github.com/hyprwm/Hyprland) | [niri](https://github.com/niri-wm/niri) |
+| --- | --- | --- | --- |
+| Tiling layouts | Scrolling columns and tree tiling; switch per workspace | [Scrolling, dwindle, master and monocle; per-workspace layouts](https://github.com/hyprwm/Hyprland#features) | Scrolling columns |
+| Floating windows | Built in | Built in | Built in |
+| Workspace overview | Built in | Plugins such as [HyprExpo](https://github.com/sandwichfarm/hyprexpo) | Built in |
+| Animations | Spring and easing animations | Bézier and spring curves | [Spring and easing animations; custom shaders](https://niri-wm.github.io/niri/Configuration:-Animations.html) |
+| Live configuration reload | Yes | Yes | Yes |
+| Monitor mirroring | Built in | [Built in](https://wiki.hypr.land/configuring/core/monitors/) | Separate tool, such as [wl-mirror](https://niri-wm.github.io/niri/Screencasting.html#screen-mirroring) |
+| Desktop controls | Included Settings and Control Center | [Separate utilities](https://wiki.hypr.land/hypr-ecosystem/) or a desktop shell | [Separate desktop shell or tools](https://niri-wm.github.io/niri/Integrating-niri.html#desktop-components) |
+| Notifications | Included in ferese-shell | [Separate notification daemon](https://wiki.hypr.land/Useful-Utilities/Must-have/) | [Separate notification daemon or shell](https://niri-wm.github.io/niri/Integrating-niri.html) |
+| Lock screen | Included ferese-lock | Separate [hyprlock](https://wiki.hypr.land/Hypr-Ecosystem/hyprlock/) | Separate locker, such as [swaylock or hyprlock](https://niri-wm.github.io/niri/Integrating-niri.html) |
+| Screen-sharing backend | xdg-desktop-portal-ferese | [xdg-desktop-portal-hyprland](https://wiki.hypr.land/Hypr-Ecosystem/xdg-desktop-portal-hyprland/) | [xdg-desktop-portal-gnome](https://niri-wm.github.io/niri/Screencasting.html#overview) |
+
+Ferese's shell, Settings, lock screen and dialogs use a shared theme. Other desktop
+shells, including [DankMaterialShell and Noctalia](https://niri-wm.github.io/niri/Integrating-niri.html#desktop-components),
+also include desktop controls; their features depend on the shell and tools you install.
+
 ## Install
 
 Start with the [dependencies](docs/installation.md#requirements), then clone Ferese and

docs/configuration.md

@@ -112,7 +112,34 @@ the focused column. `paged` packs columns into viewport-sized pages: halves form
 form triples; mixed widths and client minimum sizes determine actual boundaries.
 Changing default width preserves manually resized columns.
 
-## Motion
+## Animations
+
+Set animation speed in Settings → Motion or edit the `animations` block in
+`~/.config/ferese/config.kdl`. Changes apply live. Start with `speed` if you only
+want faster or slower transitions; you do not need to change the springs.
+
+```kdl
+animations {
+    enabled #true
+    reduced-motion #false
+    speed 1.0
+
+    spring {
+        mass 1.0
+        stiffness 700.0
+        damping 53.0
+    }
+
+    viewport-spring {
+        mass 1.0
+        stiffness 320.0
+        damping-ratio 1.0
+    }
+}
+```
+
+This example uses the built-in defaults. The packaged config sets `speed 0.9`.
+You can omit either spring block to keep its defaults.
 
 | Section / key | Type | Default | Meaning |
 | --- | --- | --- | --- |
@@ -126,6 +153,47 @@ Changing default width preserves manually resized columns.
 | `animations.viewport-spring.stiffness` | number > 0 | `320` | Scrolling stiffness |
 | `animations.viewport-spring.damping-ratio` | number > 0 | `1` | `1` is critically damped |
 
+### Speed and reduced motion
+
+`speed` changes window motion, scrolling, workspace transitions, overview,
+theme transitions and shell popup, notification and hover transitions. `0.5`
+gives an animation twice as much time; `2.0` gives it half as much. Overview
+uses 60% of this speed when opening or closing, including when selecting a
+window. There is no separate overview-speed setting.
+
+Set `reduced-motion #true` or `enabled #false` to make these transitions
+immediate. Reduced motion takes precedence over `enabled #true`; setting
+`speed 0` is invalid. These settings control Ferese's animations, not animations
+inside other applications.
+
+### Spring tuning
+
+`spring` controls window position and size motion, fullscreen/maximize zoom and
+overview entrance motion. `viewport-spring` controls the scrolling viewport and
+the column-width animation that runs with it. Shell popups and theme fades use
+timed transitions, so the spring parameters do not change their curves.
+
+Spring motion has no fixed duration. Its settling time depends on the distance
+to the target, current velocity and the spring parameters. The `animations`
+block has no settings for per-animation durations, custom curves or animation
+shaders.
+
+With the other parameters unchanged, higher stiffness makes motion faster and
+higher mass makes it slower. Damping controls how quickly velocity dies away.
+The default window spring is slightly overdamped, close to critical damping;
+the viewport spring is critically damped.
+
+For `viewport-spring`, `damping-ratio 1.0` is critical damping, values below `1`
+are underdamped and values above `1` are overdamped. The window spring uses a
+damping coefficient instead: critical damping is
+`damping = 2 * sqrt(stiffness * mass)`. Ferese stops spring animations
+at their first target crossing, so lowering damping does not make them bounce
+past the target.
+
+Mass, stiffness, damping ratio and speed must be finite and greater than zero.
+The window spring's damping coefficient may also be zero. Invalid edits leave
+the last accepted configuration active.
+
 ## Appearance
 
 Settings → Appearance offers six paired themes: **Ferese Blue** (default),