From 4276a45e9fb559a62a11ae30e9613348e0dc16ff Mon Sep 17 00:00:00 2001 From: Samuel Onoja Date: Sun, 27 Sep 2026 14:02:37 +0100 Subject: [PATCH] docs: explain Ferese integration model --- README.md | 1 + docs/why-ferese.md | 74 +++++++++++++++++++++++++++++++++++++++++++ scripts/build-site.py | 1 + site/README.md | 3 +- site/content/index.md | 2 ++ site/index.html | 2 +- 6 files changed, 81 insertions(+), 2 deletions(-) create mode 100644 docs/why-ferese.md diff --git a/README.md b/README.md index 06b369e..6ed3f1d 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ Settings → Shortcuts** to change them or assign gestures to other actions. ## Documentation +- [Why Ferese](docs/why-ferese.md) - [Installation and recovery](docs/installation.md) - [Configuration reference](docs/configuration.md) - [Desktop widgets](docs/desktop-widgets.md) diff --git a/docs/why-ferese.md b/docs/why-ferese.md new file mode 100644 index 0000000..7ce8b28 --- /dev/null +++ b/docs/why-ferese.md @@ -0,0 +1,74 @@ +# Why Ferese + +Omarchy and Ferese come from two different ideas about how a desktop should be +built. Omarchy brings existing Linux tools together and configures them as one +environment, which gives it access to mature components that already do their +jobs well. + +A setup like that might combine: + +```text +Hyprland + bar + launcher + notifications + lock screen + theme scripts +``` + +There is nothing wrong with this approach, and being able to replace each part +is useful, but those parts still have their own configuration, state, rendering, +and lifecycle. Matching their themes can make them look related, while keeping +their behavior in sync remains an ongoing part of maintaining the desktop. + +With Ferese, we are building the compositor and shell together, so workspaces, +layout, focus, outputs, input, and materials all come from the same desktop +state. The shell and Settings use first-party interfaces to work with that state +instead of reading separate versions of it from several external tools. + +This does not mean every Ferese component has to run in one process. It means +that the components share the same concepts, configuration, and protocols, so a +workspace or surface means the same thing everywhere it appears. + +## What this means in practice + +You can see the difference in something as simple as corner radius. Ferese has a +shared setting for shell surfaces: + +```kdl +theme { + geometry { + shell-radius 16 + } +} +``` + +Changing that value updates the bar, Control Center, popovers, notifications, +widgets, and native lock screen together. Managed windows have their own radius +because they are a different kind of surface, but each value still has one clear +meaning wherever it is used. + +In an assembled desktop, making the same visual change may mean editing the +window manager, bar CSS, launcher theme, notification daemon, and lock screen +config separately, then keeping those values aligned as the setup changes. + +The same difference shows up in how the desktop behaves. Ferese implements +scrolling as part of its workspace model, renders blur behind shell surfaces in +the compositor, and builds the overview from the real window scene. Focus, +fullscreen, workspace geometry, and input all work from the same state rather +than waiting for separate tools to catch up with one another. + +When a window opens, Ferese can handle the result as one transition: + +```text +window opens → layout updates → viewport moves → input follows +``` + +An assembled environment may need to publish a window-manager event, pass it +through IPC, run a script, update the bar, and start another animation before +the rest of the desktop reflects the change. Each step can be fast, but it is +still another boundary that has to be maintained. + +## The tradeoff we are making + +Building more of the desktop ourselves gives Ferese tighter control over how its +parts work together, but it also leaves us responsible for more code. Omarchy +can rely on mature components from across the Linux desktop ecosystem, while +Ferese has to build that same level of maturity over time, and that is a tradeoff +we are willing to make to keep the desktop consistent in both behavior and +configuration. diff --git a/scripts/build-site.py b/scripts/build-site.py index 9278497..eba40e9 100644 --- a/scripts/build-site.py +++ b/scripts/build-site.py @@ -13,6 +13,7 @@ OUTPUT = ROOT / 'build' / 'site' REPO = 'https://github.com/ferese-wm/ferese' PAGES = [ ('index', 'Introduction', ROOT / 'site/content/index.md'), + ('why-ferese', 'Why Ferese', ROOT / 'docs/why-ferese.md'), ('installation', 'Installation', ROOT / 'docs/installation.md'), ('configuration', 'Configuration', ROOT / 'docs/configuration.md'), ('desktop-widgets', 'Desktop widgets', ROOT / 'docs/desktop-widgets.md'), diff --git a/site/README.md b/site/README.md index e4ebeb1..f3002d0 100644 --- a/site/README.md +++ b/site/README.md @@ -18,7 +18,8 @@ site sources or Markdown guides, then refresh the browser. - `site/index.html` and `site/styles.css`: homepage and shared visual design. - `site/content/index.md`: handbook introduction. -- `docs/{installation,configuration,desktop-widgets,notifications}.md`: source guides. +- `docs/{why-ferese,installation,configuration,desktop-widgets,notifications,locking}.md`: + source guides. - `scripts/build-site.py`: renders Markdown, resolves links, generates section navigation, previous/next links, and the search index. - `site/app.js`: handbook search and code copying. Reading and navigation work diff --git a/site/content/index.md b/site/content/index.md index d84ac73..b9e56eb 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -4,6 +4,8 @@ Ferese is a complete Wayland desktop built around personalization. Its custom sh This handbook covers installing Ferese, finding your way around, and making the desktop your own. +[Why Ferese](why-ferese.md) explains why the desktop is designed as one integrated system rather than assembled from separately configured tools. + ## Start with your first session 1. Read [Installation](installation.md) for dependencies, building, login-manager or TTY startup, and recovery. diff --git a/site/index.html b/site/index.html index 8b3d79b..68cdf92 100644 --- a/site/index.html +++ b/site/index.html @@ -93,7 +93,7 @@ A menu bar, Control Center, Settings, notifications, and desktop widgets, designed to work together.

- Explore the handbook → + Why integration matters →

Make it yours