🌅 Aurora

A macOS-like desktop shell for Linux — the Mac experience without leaving Linux.

---

📖 Contents

Start here

• What is this?
• What works today
• Screenshots
• Installation
• Running
• Starting on every login

Going further

• Roadmap
• Persistent settings

Under the hood

• Design system
• Platform constraints and workarounds
• Directory structure
• Icons
• License

---

🎯 What is this?

For people who dislike how Linux desktops look and want the interface quality of macOS, without switching operating systems.

Aurora is not a distribution or a compositor — it is an interface layer that sits on top of an existing KDE Plasma installation. The underlying system (KWin, Wayland, window management) stays as it is; Aurora only changes the part you see and touch.

The goal is not "similar" but identical: the icon magnification curve, spacing ratios, animation durations and colors are derived from Apple's own measurements. Details are in the design system section below.

---

✨ What works today

🎯 Pixel-accurate dock	macOS's cosine magnification wave, drag-and-drop reordering, context menu, tooltips, bounce animation, running indicators and trash
🧭 All four edges	Bottom, top, left or right — the layout, menus and tooltips all follow
⚙️ Settings app	A separate window in the macOS System Settings layout: traffic lights, rounded corners, shadow, sidebar. Eight Desktop & Dock options
🪟 Window management	The right-click menu lists an app's open windows by title; clicking the icon raises all of them
🧞 Genie minimize	Windows shrink toward their own dock icon — not the cursor. See how this was solved
💾 Everything persists	Icon order, pins, sizes and every toggle survive a reboot

---

📸 Screenshots

Magnification, window switching and the Genie minimize animation:

The magnification wave — icons scale with distance from the pointer, following macOS's cosine curve:

Right-click menu with the application's open windows listed by title. The active window is marked:

System Settings	Vertical dock
The Desktop & Dock panel	The dock works on all four edges

---

📦 Installation

From a release (recommended):

curl -LO https://github.com/azateser/aurora/releases/latest/download/aurora-dock-0.1.0.tar.gz
tar -xzf aurora-dock-0.1.0.tar.gz && cd aurora-dock-0.1.0
./scripts/install.sh

From source:

git clone https://github.com/azateser/aurora.git && cd aurora
./scripts/install.sh

That's the whole setup. Aurora starts by itself on every login from then on — see Starting on every login.

The install script does the following:

• checks dependencies
• builds the helper program (for the minimize animation, optional)
• sets up the Wayland protocol permission and the KWin window rule
• creates an autostart entry so it starts on every login
• hides the Plasma panel (so it does not conflict with Aurora's dock)
• checks for the SF Pro font and reports the fallback to Inter if missing

To uninstall and restore the system to its previous state:

./scripts/uninstall.sh

The Plasma panel comes back, the autostart entry is removed, and the KWin rule is deleted. Your settings are preserved under ~/.config/aurora/.

SF Pro font (optional)

macOS's font cannot be bundled with the package because of Apple's license. If you want to install it on your own machine:

./scripts/install-font.sh

It downloads from Apple (~207 MB) and installs into the user directory. If it is not installed, Aurora uses the openly licensed Inter.

Requirements: quickshell (noctalia-qs on Arch), qt6-tools, KDE Plasma 6 (Wayland). Optional: gcc and wayland-scanner (so the minimize animation targets the dock icon).

▶️ Running

You only need to do this once. The installer already set up autostart, so after a reboot Aurora comes up on its own — nothing to launch, nothing to configure.

To start it right now without rebooting:

./scripts/dock.sh

The settings window opens by right-clicking the settings icon in the dock and choosing Aurora Settings.

Starting on every login

./scripts/install.sh writes ~/.config/autostart/aurora-dock.desktop, which KDE runs after the desktop has loaded (X-KDE-autostart-phase=2). The helper that positions the minimize animation starts alongside the dock.

To check that it is in place:

cat ~/.config/autostart/aurora-dock.desktop

To turn autostart off but keep Aurora installed, delete that file. To remove everything, run ./scripts/uninstall.sh.

Note: the autostart entry points at the folder you installed from. If you move or rename that folder, re-run ./scripts/install.sh so the path is updated.

Development

The full shell (wallpaper + top bar + dock) in an isolated KWin session, with hot reload — this does not touch your running desktop:

./scripts/dev.sh

---

🗺️ Roadmap

Roughly ordered by priority.

Next

• Top bar — currently only a clock. A menu bar, status icons and a control center are needed.
• Minimized window preview — macOS shows an image of the minimized window; we show the application icon. KWin has a ScreenShot2.CaptureWindow method, but it returns raw pixel data over a file descriptor, so a separate helper is required.
• Settings panels — the Appearance, Wallpaper and Displays panels are present in the sidebar but empty.

Later

• Launchpad — the Apps icon currently opens Vicinae; we should have our own launcher.
• Application design system — there are nine controls under Aurora/Controls/ (slider, toggle, popup, checkbox…). They need to be extended for applications like Finder and Terminal.
• Notification center and Spotlight-like search.

Known limitations

• Running application detection looks at the process list; background services without windows can sometimes show up. Since wlr-foreign-toplevel is not supported in KWin, a direct window list cannot be obtained.
• Memory baseline ~110 MB — the Qt/Mesa GPU context. It cannot be reduced without leaving Qt. Since applications added later will run in the same process, this cost is paid once.
• Multiple monitors have not been tested.

---

📁 Directory structure

shell/
  shell.qml              full shell entry point
  dock-only.qml          dock only (on top of the existing desktop)
  Aurora/Design/         design system (Tokens, Config)
  Aurora/Services/       data layer (Apps, Settings, WindowFx, AuroraApps)
  Aurora/Controls/       reusable controls
  modules/               Dock, TopBar, Wallpaper
  components/            ContextMenu, MenuPanel
  apps/settings/         System Settings application
assets/icons/            dock icons (named after the .desktop id)
assets/settings-icons/   settings panel icons (512px)
assets/glyphs/           SF Symbols (check mark, window)
helper/                  Wayland helper program (minimize target)
scripts/                 install, run and development scripts

---

🎨 Design system

All visual values live in shell/Aurora/Design/Tokens.qml. Raw colors or measurements are never written in QML files; every value is read from here. Changing a token propagates through the whole interface.

Measurements

Dock measurements were taken from the reference image published by Apple and scaled proportionally (reference: 110 px icon):

Value	Ratio	Token
Icon size	1.00	dockIcon = 50
Gap between icons	0.327	dockGap = 16
Icon corner radius	0.236	dockIconRadius
Plate corner radius	0.509	dockPlateRadius
Horizontal padding	0.291	dockPadding = 14
Vertical padding	0.309	dockPadY = 15

The vertical padding is equal at the top and the bottom; the indicator dot sits inside the bottom padding and does not require extra height.

Motion

The magnification curve is cosine-based: (1 - cos θ) / 2. This is the curve reverse-engineered from macOS; linear scaling or smoothstep does not give the same feel.

The dockCurve exponent determines how flat the skirts stay. At low values neighboring icons react early; at high values only the icon under the cursor grows.

Color

The light and dark themes share the same token names; changing Tokens.dark switches the entire interface. Glass surfaces are semi-transparent and are tuned to work together with KWin's blur effect — they look more opaque when blur is off.

---

🔧 Platform constraints and workarounds

This section records the constraints encountered during development that shaped the code. The decisions here are not arbitrary; read the reasoning before changing them.

KWin does not support wlr-foreign-toplevel-management

ToplevelManager.toplevels is always empty — this protocol is specific to wlroots and does not exist in KDE. Because of this:

• Running application detection is done from the process list (ps). Since window ownership is unknown, background services can also appear.
• Window operations (focus, close, hide) are done by loading a temporary script into KWin. Killing processes (pkill) cannot be used: the Exec name in the .desktop file often does not match the real process name, the pattern expands and other applications get closed too.

Process name matching is attempted in four ways: the full name, the form truncated to 15 characters by ps, the first segment (helium-browser → helium), and the last segment of the .desktop id (org.kde.konsole → konsole).

KWin does not know the target of the minimize animation

The Genie (magiclamp) effect shrinks the window toward Window.iconGeometry. This value is read-only and is only filled in from the org_kde_plasma_window_management protocol. Without a target, the effect goes to the cursor position.

The protocol is invisible in the Wayland registry — KWin hides it behind a global filter. Its absence from wayland-info output gives the impression that it was "not compiled in", but it can in fact be enabled: add the key

X-KDE-Wayland-Interfaces=org_kde_plasma_window_management

to the application's .desktop file and run kbuildsycoca6. The Exec path must be the real (canonical) path of the binary.

Two more subtleties: set_minimized_geometry requires a surface that KWin recognizes (the helper opens its own layer-shell surface), and KWin drops the geometry when the surface closes (the process must stay running).

helper/README.md covers the build and installation details.

Quickshell's DesktopEntries API returns empty

This API does not work in the package used (noctalia-qs). The application list is built by scanning .desktop files directly.

Region only supports rectangles and ellipses

There is no rounded rectangle for the blur region. It is built by combining two rectangles (horizontal + vertical body) and four corner ellipses. If a plain rectangle is used, square blur spill is visible at the bottom corners.

QML pitfalls

• If scale and transform are defined together, scale is ignored. If both are needed, they must be given in a single transform list.
• Behavior cannot be placed on a readonly property.
• A component cannot be instantiated inside itself; this is why ContextMenu and MenuPanel are in separate files (the submenu uses the same panel a second time).
• The command binding of Process objects may not yet see the object's other properties while it is being constructed; it is assigned explicitly inside Component.onCompleted.
• Changes to JS objects are not reported to QML. For dictionaries such as entries and localIcons, a separate counter (revision) is kept and bindings read that.
• native is a reserved word and cannot be used as a property name.

Layout computation

The dock layout is computed in a single pass and cached in layout. If size and position are read from separate sources (one from the raw index, the other from the sorted index), icons overlap.

There are two indexes and they must not be mixed up:

• raw index — the icon's place in the model; its size is read from this one
• sorted index (order(i)) — the icon's visual slot; its position is read from this one

During dragging, the swap thresholds are taken from the fixed resting positions. If they are bound to live values such as centerOf, dropIndex feeds itself and icons land in the same slot during fast movement.

Performance

Memory usage is ~140 MB (PSS), idle CPU 0.3%. About ~110 MB of that is Qt/Mesa's GPU context — the application code's share is ~20 MB. Shrinking the icons does not change this baseline; this has been verified by measurement.

The process scan runs at 1500 ms intervals when idle, and at 180 ms intervals while an application is opening or closing. The scan result is applied immediately inside Process.onExited; if it is deferred to the next round, the response time doubles.

---

💾 Persistent settings

~/.config/aurora/dock.json

{
  "removed": {},   // applications removed from the dock
  "order":   [],   // the order chosen by the user
  "extra":   []    // applications added that are not in the default list
}

Launching at login works separately: the application's .desktop file is copied under ~/.config/autostart.

---

🖼️ Icons

Files under assets/icons/ take precedence over the system theme. The file name must match the .desktop id:

org.kde.konsole.png      Terminal
aurora.trash.png         Trash (empty)
aurora.trash-full.png    Trash (full)
_blank.png               empty macOS square that theme icons are placed into

Icons are scaled to 256 px; the dock displays at most 93 px.

Icons in macOS format come with their own squircle shapes and are drawn directly. Icons coming from the system theme are placed inside the _blank.png square, so the appearance stays consistent across the dock.

---

⚖️ License

All rights reserved. Aurora can be used free of charge, but redistribution, modification and commercial use are subject to permission. See the LICENSE file for details.

The source code is present in the package because QML is an interpreted language and it is required for the software to run. Its visibility does not change the terms of use.

Assets are also out of scope. The copyright of the icons under assets/ belongs to Apple Inc.

The SF Pro font is not included in the package. If it is installed on your system Aurora uses it, otherwise it falls back to the openly licensed Inter (hasSF in Tokens.qml).

Aurora is not affiliated with Apple Inc.