surface-dots

My personal linux dotfiles. Also, please check out my calendar app: Evercal

Screenshots

Desktop Layouts

Cassini Powermenu, Reading Mode, Other system components

Dependencies

Core & System

quickshell
hyprland
hypridle
hyprlock
hyprland-plugins
xdg-utils
xdg-desktop-portal-hyprland
xdg-desktop-portal-kde
xdg-desktop-portal-gtk
polkit-gnome
sddm
pacman-contrib
networkmanager
bluez, blueman
upower
webkit2gtk-4.1

UI & Theming

dunst
awww
rofi
kitty
thunar
firefox
hyprpicker
colorreload-gtk-module
qt6ct
kvantum
papirus-icon-theme
ttf-nerd-fonts-symbols
ttf-cm-unicode
ttf-google-fonts-git

Utilities

grim, slurp, swappy, grimblast
pamixer
pulseaudio-utils
playerctl
brightnessctl
libnotify
wl-clipboard
vdirsyncer
khal
EverCal
xdg-utils
curl, jq
auto-cpufreq (optional)
howdy-git (optional)

Caution

Some layout geometry is still hardcoded for 3:2 high-resolution display. Deviation in aspect ratio or pixel density will result in misalignment or things looking too big or small. Please follow instructions in the FAQs below to reconfigure values accordingl or start an issue if you require further assistance.

Installation

A GUI installer is included for installing surface-dots. Full instructions are in installation.md and if you want to learn more about how the installer was written check installer_readme.md, sources are in .source_codes/installer_src.

git clone https://github.com/snes19xx/surface-dots
cd surface-dots
chmod +x surface-dots-installer
./surface-dots-installer

Note

The installer does not install dependencies, install those yourself first. It's only been tested on Arch. You also need a polkit agent running before you launch it. If it won't start you probably need the WebKitGTK runtime libs, see installation.md for the workaround.

You can always just clone the repo and copy the files around manually if you'd rather not use it.

Hyprland

Keybindings

Apps

SUPER + Q → terminal (kitty)
SUPER + E → file manager (thunar)
SUPER + R → app drawer (works in both layouts now, see the note below)
SUPER + B → firefox
SUPER + S → my custom ocr app (lens)
SUPER + P → color picker (hyprpicker -a)

SUPER + R used to need rewiring if you ran the top bar. It doesn't anymore — the bind goes to the shell either way, and the shell decides what to open: rofi in topbar mode, the wide drawer in taskbar mode. Same key, right launcher.

Shaders

These live in shader.lua, not hyprland.lua:

SUPER + D → reading mode
SUPER + N → night light
ALT + C → CRT mode
SUPER + ALT + S → turn every shader off

Window actions

SUPER + SPACE → toggle hub on or off
SUPER + X → kill active window
SUPER + F → toggle floating (simple)
SUPER + ALT + F → toggle floating and set size 900x600 + center
SUPER + L → float and resize to 1440x1080
SUPER + M → fullscreen
SUPER + UP → togglesplit
SUPER + DOWN → togglesplit

Exit

ALT + F4 → Power menu
SUPER + ALT + F4 → exit Hyprland

Focus (arrow keys)

SUPER + Left/Right → move focus horizontally
SUPER + SHIFT + Up/Down → move focus vertically

Workspaces

SUPER + 1..0 → workspace 1..10
SUPER + SHIFT + 1..0 → move active window to workspace 1..10
SUPER + mouse wheel → next/prev workspace
SUPER + G → toggle group
SUPER+CTRL+LEFT/RIGHT → move across grouped windows

Scratchpad (“special workspace”)

SUPER + H → toggle special workspace magic
SUPER + SHIFT + S → move active window to special:magic

Mouse (window move/resize)

SUPER + LMB → move window
SUPER + RMB → resize window

Screenshots

Print → Screen snip
SUPER + Print → Capture screen
SUPER + SHIFT + Print → Window capture
SUPER + O → Capture monitor

Unbound by default

The shell registers a third global, quickshell:monitorPicker, which opens the Displays panel straight from the desktop. I don't have a key on it because the panel also pops up on its own when you plug a monitor in, but if you want one:

hl.bind(mod .. " + SHIFT + D", hl.dsp.global("quickshell:monitorPicker"))

Shaders

Shaders are integral part of my setup, I find them fun.

All shaders are located at ~/.config/hypr/shaders/
shaders can be accessed and toggled through rofi start menu (only in taskbar mode)

OR:

# activate with:
hyprctl eval 'hl.config({ decoration = { screen_shader = "/<path to shader.glsl>" } })'

# To turn off the screen shader, set the screen_shader value to an empty string.
hyprctl eval 'hl.config({ decoration = { screen_shader = "" } })'

Reading Mode

A shader-based reading mode to mimic an e-ink reader.

Toggle with SUPER + D or ~/.config/hypr/shaders/reading_mode.sh
Automatically disables animations, shadows, and blur
Custom GLSL shader with e-ink-like color reproduction
Warm cream paper tone and soft charcoal blacks for reduced contrast
Fine paper grain -like texture

Other shaders

main.glsl – main shader to improve my display (activates on startup through hyprland exec)
night.glsl – my main night-light mode shader (toggle with SUPER + N)
outdoor.gls – for maximum outdoor useability
cinema.glsl – for media consumption
amano.glsl – simulates Yoshitaka Amano artstyle
art_canvas.glsl – smulates physical canvas geometry and pigment density
dither.glsl – Simulates 4-bit graphics.
fuji_acros.glsl – simulates fujifilm acros
crt_mode.glsl – simulates a crt monitor
vhs.glsl – simulates vhs
gameboy.glsl – simulates a gameboy screen
smart_invert.glsl – eConverts RGB to HSL, inverts the Lightness channel, and converts back
silent_hill.glsl – Pacific Northwest / Silent Hill Shader
greens.glsl – Retains only green hues and desaturates all other colors to grayscale.

Desktop Layouts

Two desktop layouts, depending on where you want the bar. These used to be two separate shells and they aren't anymore -- top-bar/ and task-bar/ were merged into one config. There's a single shell.qml, one set of services, one theme engine, one hub. The layout is now a setting.

So this is the whole launch command, for both:

qs

No more qs -c task-bar. If you're coming from an older copy of these dots, that's the one thing you have to change in your Hyprland config.

Switch layouts in the Hub under Settings -> Taskbar -> Layout, or set barStyle to task or top in lib/usersettings.json.

Both layouts share the same core components but behave differently depending on mode.

Taskbar Mode Behavior

Taskbar mode has additional desktop components and layout changes:

desktop/ScreenBorder.qml
dock/Drawer.qml

Default state (no active windows)

When the session starts or when no windows are open:

ScreenBorders wrap around the display edges.
The taskbar switches to dock mode.
The center of the dock contains a quickshell app drawer: dock/Drawer.qml

When a window becomes active

As soon as a window opens:

ScreenBorders hide
The taskbar switches to workspace mode
- The taskbar in this state behaves similarly to the regular bar used in top-bar mode, except it appears at the bottom of the screen.
- The launcher switches from the dock's app drawer (dock/Drawer.qml) to the workspace app drawer (dock/WideDrawer.qml). This is a custom quickshell app + shader launcher that replaces my rofi setup, toggled with SUPER + R.

Other taskbar-specific changes

The appdrawer menu is wider and contains shaders
The Hub media card derives its background colors from album art palette colors, instead of using blurred album artwork.
Upcoming events are no longer displayed inside hub/CalendarWeatherCard.qml and have a dedicated card hub/Events.qml. By default, the next upcoming event is shown until it ends. Multiple events can be added to the list by increasing the loop count in the file.
Theme switching is the same everywhere now, there are just extra ways to reach it:
- d and l with the hub open, from either layout. This is the one I actually use.
- The theme swatch in Settings → Theme.
- Topbar mode only: right-click the Arch glyph launcher icon.
All of them end up in the same script, which is now one file instead of one per bar:
```
bash ~/.config/quickshell/utils/theme-mode.sh dark|light
```
Styling for both layouts is handled through the dynamic theme system in lib/ThemeEngine.qml, which follows the shared mode state in lib/ThemeState.qml. That singleton is the only thing that owns dark/light now — there used to be three separate file watchers confirming what mode you were in. A few components still define their own colors internally.

Expand for Topbar/Taskbar components

Workspaces

Clicking a workspace pill runs:

hyprctl dispatch workspace <id>

Updates

Updates are hardcoded for archlinux if you are using a different distro please replace. Both bars poll separately, so this is two edits — bars/TaskBar.qml (line 196) and bars/TopBar.qml (line 132):

// replace this snippet
sh(`
            if [ -e /var/lib/pacman/db.lck ]; then
                cat /tmp/qs_updates_count 2>/dev/null || echo 0
                exit 0
            fi
            n=$(checkupdates 2>/dev/null | wc -l)
            echo "$n" | tee /tmp/qs_updates_count
        `)

with a poller for your distro, for example debian:

// replacement snippet:
sh(`
            # apt list --upgradable does not lock the database, so we skip the lock check
            n=$(apt list --upgradable 2>/dev/null | grep -v 'Listing...' | wc -l)
            echo "$n" | tee /tmp/qs_updates_count
        `)

Clicking the updates pill runs:

kitty -e bash -lc "sudo pacman -Syu"

with this line in bars/TaskBar.qml (line 946) and bars/TopBar.qml (line 574):

command: ["kitty", "-e", "bash", "-lc", "sudo pacman -Syu"]

please replace this line with your package manager's update/upgrade command

Date and Clock

Pressing the clock emits a requestHubToggle() signal used to open or close the hub.
Pressing Esc or clicking outside the hub closes it.

WORKFLOW GUIDE

The whole shell is built around one idea: you shouldn't have to aim at anything. SUPER + SPACE opens the hub, and from that point your left hand is already sitting on every control in it. I open the hub, hit a letter, and it's gone again -- most of my interactions with this desktop last under a second and never involve the mouse.

SUPER + SPACE          →   hub opens (or closes)
        ↓
   d / l               →   dark / light
   n                   →   notifications
   s                   →   settings
   w                   →   wallpapers
   m                   →   displays
   b                   →   battery & system stats
   Esc                 →   close everything

Key	Does	Notes
`d`	Dark theme	`d` on an already-dark desktop does nothing
`l`	Light theme	Same, `l` when you're already light does nothing
`n`	Expand / collapse notifications	For when the media card has squashed them
`s`	Settings panel	Swaps in place, press `s` again to come back
`w`	Wallpaper picker	`s` also backs out of this one
`m`	Displays panel	Resolution, refresh rate, scale, multi-monitor layout
`b`	Battery / system stats card	Toggles the card in the column, doesn't replace the hub
`Esc`	Close	One press, from anywhere

The panels are mutually exclusive on purpose. Opening settings closes displays, opening wallpapers closes settings, and so on. Only one thing is ever in that content area, so there's nothing to stack and nothing to back out of.

A few controls are outside this:

ALT + F4 → power menu. It's its own overlay.
SUPER + R → app drawer. Rofi in topbar mode, the wide drawer in taskbar mode.
Right-click the Wi-Fi button → the full network menu.
Right-click the performance button → battery health card (same as b).
Right-click the Arch glyph, topbar mode only → theme toggle.

Quickshell Hub

The main control and notification center, the core of the shell.

Both layouts open the same hub:

Clicking the date/clock module in the bar
SUPER + SPACE, via quickshell:hubToggle

It's a wlr-layershell overlay, namespaced so you can write Hyprland rules against it:

// hub/HubWindow.qml
WlrLayershell.namespace: "snes-hub"

Where it appears depends on the layout. In taskbar mode it's a 520px two-column panel that rises out of the dock. In topbar mode it's a 320px single column that drops from under the bar on the right, which is how the top bar has always worked. Same window, same keys, same services underneath hub/TaskCards.qml and hub/TopCards.qml just lay the cards out differently.

If you want a lightweight fallback, an earlier AGS version is available in .config/ags/.

EXPAND FOR INDIVIDUAL COMPONENTS

Header

Buttons	Does
Stats	Toggles the battery / system card in the column below
Settings	Swaps the settings panel into the hub
Displays	Swaps the displays panel in
Snapshot	Closes the hub, then fires the capture script ~320ms later

The profile picture is profile.jpg next to shell.qml, overridable in Settings; the name comes from PROFILE_NAME in config.js.

Two things that used to be here are gone. The power button opened a grid inside the header that did the same job as the ALT + F4 menu. there's one power menu now and it's outside the hub. The theme toggle moved to d / l and the swatch in Settings.

RAM and CPU readouts aren't in the header anymore. You need to toggle them with B keypress

Settings Panel

hub/SettingsPanel.qml, so you don't have to edit files for everything.

Open it with the settings button or the s key. It swaps the hub content in place, and s again takes you back to the cards.

Appearance (theme + accent/colors)
Weather API key and location
Power menu skin (Living Things or Cassini) and its accent, saved per light/dark
Layout : this is where you switch between topbar and taskbar
Taskbar tweaks (exclusive zone, dock/workspace forcing, custom background)
Screen borders (thickness, color)
Profile picture & events

Settings are written through lib/Configuration.qml into lib/usersettings.json. Not everything is wired through the panel yet, some styling still is in lib/ThemeEngine.qml and theme.js, but it covers most of the common stuff now.

Displays Panel

hub/MonitorsPanel.qml, opened with the m key or the displays button. This one is new and it's in both layouts.

Layout: Extend / Duplicate / Laptop only / External only
Resolution, refresh rate and scale per monitor
Remembers monitors it has seen before, so a setup you plug into every day comes back the way you left it
Prompts on hotplug when it sees something new

Changes go out through hyprctl.

Wallpaper Panel

hub/WallpaperPanel.qml, opened with w or from the settings panel. It's backed by a small rust helper (bin/papel, source in .source_codes/wallpaper_panel/) that generates thumbnails and streams them into the grid over a socket.

Live thumbnail grid of your wallpaper folder
Refresh button re-scans the folder for newly added wallpapers
Pulls a color palette from the selected wallpaper, click a swatch to copy the hex

Buttons and Sliders

Wi-Fi toggle with SSID readout (right-click opens the Wi-Fi menu)
Bluetooth toggle with connected device status (right-click opens blueman)
Performance profile button (cycles Auto → Max → Powersave through auto-cpufreq, right-click toggles the battery health card). Needs a sudoers rule, see below — without one it's inert by design.
DND toggle (dunst)
Volume and brightness sliders (pactl and brightnessctl)

Enabling the performance button (auto-cpufreq)

auto-cpufreq --force=… sets a system-wide CPU policy, so it needs root. The shell runs it as:

sudo -n auto-cpufreq --force=performance|powersave|reset

out of the box the button does nothing To make it work, grant passwordless sudo for those three exact commands:

sudo visudo -f /etc/sudoers.d/auto-cpufreq

yourname ALL=(root) NOPASSWD: /usr/bin/auto-cpufreq --force=performance, \
                              /usr/bin/auto-cpufreq --force=reset, \
                              /usr/bin/auto-cpufreq --force=powersave

[!WARNING] Use visudo -f, not an editor. It validates the file before saving, and a broken sudoers file locks you out of sudo entirely.

List the three commands out in full. NOPASSWD: /usr/bin/auto-cpufreq * looks tidier and is a privilege escalation hole-- the wildcard accepts any argument.

If the call fails the button rolls its own state back, so it won't sit there claiming "Max" when nothing changed. If you don't use auto-cpufreq at all, ignore the button; nothing else in the shell depends on it.

Battery Health

Shows RAM and CPU usage alongside the battery in taskbar mode. Toggle it with b or by right-clicking the performance button.

It finds your battery automatically:

DEV=$(upower -e | grep -m1 -i battery); upower -i "$DEV"

Displayed information:

Health (capacity %)
Current charge %
Charge cycles
Energy (full / design)
Time remaining (when available)
Charging state

Media Card (MPRIS)

Appears only when media is playing
Clicking it launches the external Now Playing widget and closes the hub
Resets its internal state when track metadata changes

Some browser content (like YouTube) can behave inconsistently depending on how the browser exposes MPRIS.

In taskbar mode the media card derives its background from an album art palette. In topbar mode it uses blurred artwork.

Now Playing (Flutter)

A separate Flutter desktop widget managed through Hyprland window rules.

Window resizing is disabled (setResizable(false))
Esc closes the widget
Theme colors are generated from album artwork using palette_generator

NOTE
You may need to make the now_playing binary executable. The path is resolved relative to the shell now, so you shouldn't have to edit it unless you move the binary.

Calendar, Weather and Events

A calendar and weather card, with weather coming from a shell script (lib/weather.sh, OpenWeatherMap). Set the key and coordinates in the settings panel.

The weather glyphs are Nerd Font symbols, not emoji. if you see a tofu box instead of a cloud, you're missing ttf-nerd-fonts-symbols.

Calendar events are synced from Google Calendar using vdirsyncer and khal.

Where events show up differs between the layouts:

Taskbar mode : a dedicated hub/Events.qml card
Topbar mode : inline in the calendar card

The next upcoming event stays visible until it finishes. Show more by increasing the loop count in hub/Events.qml, or maxEvents in the settings.

Google Calendar sync (vdirsyncer + khal)

Recommended installation method (avoids system Python packaging issues):

sudo pacman -S --needed python-pipx

pipx install "vdirsyncer[google]"

If both a system and pipx version of vdirsyncer exist, remove the system package and ensure ~/.local/bin appears earlier in PATH.

Setup

Create the required directories:

mkdir -p ~/.config/vdirsyncer/status ~/.config/vdirsyncer/tokens
mkdir -p ~/.local/share/vdirsyncer/calendars

Example configuration values:

token_file = "~/.config/vdirsyncer/tokens/google_calendar"
type = "google_calendar"
client_id / client_secret

Calendar files are stored in:

~/.local/share/vdirsyncer/calendars/*

Khal reads .ics files from this location.

Notes

The CalDAV API must be enabled in Google Cloud.
If OAuth consent is in testing mode, add yourself as a test user.
If you receive “token obtained but Not Found”, enable calendars at:

https://calendar.google.com/calendar/syncselect

Sync and test

vdirsyncer discover
vdirsyncer sync
khal list now 7d

Notifications

Clicking a notification dismisses it
Uses dunst (dunstctl) as the backend
Collapsed by default when the media card is active
n or the expand button opens them back up

Power menu

wlr-layershell power menu overlay (separate from the hub header menu). Toggled with ALT+F4

It comes in two skins (pick one in the settings panel):

Living Things — the original everforest power menu
Cassini — an editorial black & white look with a random Cassini photograph on the side

Both share the same logic (utils/PowerMenuController.qml), the skins are just presentation.

Run

quickshell -p ~/.config/quickshell/utils/PowerMenu.qml

Wifi menu

Network manager applet at lib/WifiMenu.qml, in both light and dark.

Trigger: right-click the Wi-Fi button in the Hub.
Standalone, if you want it on a key of its own: quickshell -p ~/.config/quickshell/lib/WifiMenu.qml

It runs inside the shell now. It's preloaded and just made visible now, so it's instant. The file still works standalone for anyone who prefers binding it directly.

Warning

You should be able to connect to most enterprise access points now (PEAP/MSCHAPv2 only). That covers most corporate/campus networks (including eduroam), but if you ever hit an enterprise AP that requires EAP-TLS (client certificates) or EAP-TTLS, this menu won't handle it -- you'd need nmcli/nmtui directly for that.

OSDs

Custom on-screen displays for:

Volume
Brightness
Various system modes (Dark, Light, Reading Mode, etc.)

Firefox Customizations

Codex Stellarium

Get it on Firefox

Codex Stellarium is an interactive, customizeable astronomy inspired custom new tab/homepage. Replaces the default new tab with an interactive starfield, planetary system, and comet simulator. Contains:

Canvas Animations: Interactive comets, planetary orbits, and a parallax starfield.
Dynamic Theme: Auto-switches between light and dark modes based on local time or weather conditions.
Live Data: Displays current weather (via Open-Meteo API), lunar phase, and sidereal time.
Shortcuts: Configurable quick links.

Manual Installation

Note

I have a .crx file in the codex-stellarium directory if you want to use it in a chromium-based browser.
I also have other custom home/newtab pages in .config/firefox/custom_homes that can be installed with this method

.config/firefox/codex-stellarium Firefox doesn't really want you to use local html as a new tab page, if you want to isntall codex stellarium manually or use your own html as custom new tab:

Move config/firefox/defaults/pref/autoconfig.js to Firefox defaults/pref/ (e.g. /usr/lib/firefox/defaults/pref/)
Edit config/firefox/mozilla.cfg (repo path: .config/firefox/mozilla.cfg) and set your file path
Move mozilla.cfg to the Firefox install directory root (e.g. /usr/lib/firefox/)

userChrome

/chrome/userChrome.css: A custom stylesheet that overrides the default Firefox interface. (These customizations work in windows or other os as well)

Expand for instructions to install custom usercss:

1. Enable Stylesheets in Firefox

Open Firefox and enter about:config in the URL bar.
Accept the risk warning.
Search for toolkit.legacyUserProfileCustomizations.stylesheets.
Double-click to set the value to true.

2. Locate Your Active Profile

Go to about:profiles.
Find the profile box that states: "This is the profile in use and it cannot be deleted."
Copy the path listed under Root Directory
(e.g., /home/username/.mozilla/firefox/xxxxxxxx.default-release).

3. Install the Files

Copy the userChrome.css into the chrome folder
(create it if it doesn't exist, or move the chrome folder from this repo)

Cursors

`Saturnian` cursor theme:

Custom cursor theme for Surface-dots in two variants - Saturnian-Night for dark desktops Saturnian-Day for light. For more info:Read cursor_readme.md

The installer copies both variants into ~/.local/share/icons as part of the utilities step. If you'd rather do it by hand, or you want them system wide:

Install

./install.sh              # current user  -> ~/.local/share/icons
sudo ./install.sh --system  # all users   -> /usr/share/icons
./install.sh --uninstall

Then, without restarting anything:

hyprctl setcursor Saturnian-Night 32

Themes

GTK:

I use a modified version of Fausto-Korpsvart's Everforest gtk theme. The installer automatically copies it to the required directory for the theme toggle script to use it.

Qt / Kvantum

Kvantum theme files are located in: .config/Kvantum

Additional related configuration files:

.config/qt6ct
.config/color-schemes

Use Kvantum Manager to install and apply the Kvantum theme.

Lockscreens

SDDM

I have two SDDM themes:

Stellarium SDDM theme (Astronomy inspired)
Pixel SDDM theme (Android inspired)

The installer installs the themes and writes to conf.d automatically based on your choice. It will however prompt you for password authorization via pkexec.

For Manual install:
- move the contents of sddm/theme folder to /usr/share/sddm/themes/ (create the dir if it doesn't exist yet) and:
```
sudo mkdir -p /etc/sddm.conf.d
echo -e "[Theme]\nCurrent=stellarium" | sudo tee /etc/sddm.conf.d/theme.conf
```

Hyprlock

I have two hyprlock themes that are designed to look exactly like the SDDM themes above:

Stellarium hyprlock theme (Astronomy inspired)
Pixel hyprlock theme (Android inspired)

Utilities

Utilities include the following:

crt_gen.py a script to add crt like filters to an image (works best with images that aren't too bright or too dark)
figures.py script to generate nice fun mathematical illustrations
SR4.icm Color profile for the display of the Surface Laptop 4. Import it in KDE Plasma to get Windows-like color calibration.
Fonts I like and use often

Credits & Acknowledgements

Everforest-GTK-Theme by Fausto-Korpsvart
Topbar mode Rofi themes loosely based on @adi1090x's type 7
Pixeldots.qml in sddm theme based on @mahaveergurjar's Pixeldots
Colors: Modified from https://github.com/sainnhe/everforest
VScode theme: Modified from Andrei Lucaci's Everforest pro theme
Kvantum theme based on materia-everforest-kvantum
Dave Hoskins for Hash without Sine
Some svgs are from https://www.svgrepo.com/ , I made some myself
Thorium: https://thorium.rocks/ for the background visualizations in firefox custom new tab
My design inspiration comes mainly from : Microsoft design, Material design and calla. The typography and UI design used in the installer are my own original work, which I’ve also used in several of my other projects, including my website and the firefox extension.
Big thanks to u/NoPsychology143 who gave me a giant list of bugs they encountered and I have attempted to resolve them in this update.

Media Sources

Photo by fffunction studio on Unsplash
Photo by Brian McGowan on Unsplash
Photo by Mimicry Hu on Unsplash
Photo by Bailey Zindel on Unsplash
Photo by Jay Yu on Unsplash
Photo by Ben Dutton on Unsplash
Photo by Richard Rhee on Flickr
Photo by Cedric Chambaz on Flickr
Photo by temo Berishvili on Unsplash
Photo by Lucas Pezeta on Unsplash
Photo by Andreas Strandman on Unsplash
All Rofi pictures were pulled from Pinterest; I don’t know the original owners.

[Reuse Note:]

Feel free to copy/steal whatever you want as long as you cite me and more importantly the listed media sources in the credits/references where applicable.

FAQs

Q: Will this run on a distro other than Arch Linux?
A: I'm not sure about the installer but as long as you have the dependencies I don't see why it wouldn't.

Q: Can I use this setup with another compositor or desktop environment?
A: Yes. Most features, including Quickshell, will work correctly (as long as you're on wayland). Shaders are the only exception. However, some features exclusively rely on hyprland's ipcs, for best experience please use with hyprland

Q: Why use Flutter for the "Now Playing" widget?
A: It was one of my first projects while learning Flutter, which explains the older dependencies. Behind the Material Design frontend, it is just a standard MPRIS controller.

Q: How does the face unlock animation work?
A: It assumes the authentication was successful by default. You may need to adjust the timer in main.qml to get the timing right for a realistic effect. It does properly recognize authentication failures and timeouts.

Q: Why are there multiple app drawers (including the top-bar Rofi drawers)?
_A: I am currently experimenting with different designs and layouts. Taskbar mode now has a custom quickshell app + shader drawer (dock/WideDrawer.qml) that replaces rofi, moving forward I will only update this.

Q: I'm updating from an older version and nothing launches. Why?
A: Almost certainly qs -c task-bar still in your Hyprland config. There's no task-bar config to select anymore, it's just qs. Check hyprland.lua, shader.lua and scripts/wallpaper.sh, those are the three places that referenced it.

Q: I picked a layout in settings, do I need to restart the shell?
A: No.

Q: How do I enable or disable screen borders?
A: Settings -> Screen borders, where you can also set thickness and color. They're taskbar mode only. showScreenBorders in lib/usersettings.json if you'd rather not click.

Q: Components are misaligned in the hub. How do I fix them?
A: You can correct alignment by adding padding (left, right, up, down), adjusting spacing, or using the translate function. For example, to move weather in CalendarWeather card to the right:

// Right: Weather
      ColumnLayout {
        Layout.alignment: Qt.AlignTop | Qt.AlignRight
        Layout.preferredWidth: 110

        /* increase to move right, decrease (values can be negatives too) to move to the left */
        transform: Translate { x: 5 }  // <--- add this

Q: The taskbar is covering windows at the bottom of the screen. How do I fix this?
A: Settings -> Taskbar -> Excl. zone, or increase the gaps in your Hyprland config. It's taskbarExclusiveZone in lib/usersettings.json and no longer needs a code edit-- the bars moved to bars/TaskBar.qml and bars/TopBar.qml if you're looking for the old line.

Q: Can I use the top-bar Rofi on the taskbar, or vice versa?
A: SUPER + R goes to the shell now and the shell picks the launcher for the current layout, so you don't have to rewire anything to switch modes. To force one, the branch is in shell.qml under the drawerToggle shortcut, just swap which side calls rofi and which calls wideDrawer.toggle().

Q: The theme switcher is not applying my GTK or Qt themes. How do I fix it?
A: First, make sure the script has executable permissions. Next, verify the theme files exist and match the names referenced in the script. Finally, run the script directly from the terminal to check for specific error messages abd fix them one by one.

Q: The wallpaper panel is empty or won't apply anything. How do I fix it?
A: By default it reads from ~/Pictures/Wallpapers, set PAPEL_DIR if yours live somewhere else. It also needs awww running to actually set the wallpaper, and bin/papel has to be executable. If you just added new wallpapers, hit the refresh button so it re-scans the folder.

Q: How do I switch the power menu skin?
A: Open the settings panel and go to the power menu section, you can pick between Living Things and Cassini there, and set a custom accent for each one. Works from either layout now.

Q: Where did the p power menu in the hub go?
A: Removed. It was a second, worse power menu living in the hub header doing the same job as ALT + F4. There's one now.

Q: The weather is wrong or not showing up. How do I fix it?
A: Set your key and coordinates in the weather section of the settings panel, or edit lib/weather.sh directly. It's OpenWeatherMap, so you need your own free API key from them. You also need curl and jq installed.

Q: The weather text shows but the icon is a blank box.
A: Install ttf-nerd-fonts-symbols. The condition icons are Nerd Font glyphs. Same fix for any other missing glyph in the bars or hub.

Q: The performance button flips back to what it was, or does nothing.
A: Working as intended until you opt in. It runs sudo -n auto-cpufreq --force=…, and -n means sudo won't prompt — so with no sudoers rule the call fails and the button rolls its state back rather than lying to you. Add the drop-in from the perf button section. It's deliberately not a plain sudo: that version fails as an auth failure and feeds pam_faillock, which on Arch is shared with hyprlock and sddm, so enough clicks lock you out of your own screen.

Q: hyprlock is rejecting my correct password.
A: Check faillock --user "$USER". If it lists a pile of sudo entries you've tripped pam_faillock, which system-auth shares between sudo, hyprlock, sddm, su and passwd. faillock --user "$USER" --reset clears it, and the default unlock_time=600 means it also clears itself after 10 minutes. Older copies of these dots caused this through auto-cpufreq; on a current copy, something else on your system is failing auth.

Q: I changed something in the settings panel but it didn't stick. Why?
A: Most settings are saved through lib/Configuration.qml, so make sure it can actually write to its config location. A few components still read their colors from theme.js or define them internally, so those bits still need a manual file edit for now.

Q: How do I add my own shader to the wide app drawer?
A: Drop the .glsl in ~/.config/hypr/shaders/, then add a matching icon in dock/shader-icons/ (and a light-mode version in dock/shader-icons/light/) so it shows up in the drawer's shader tab.

Q: The hub keys don't do anything.
A: The hub has to have focus, which it does when you open it with SUPER + SPACE or by clicking the clock. If you clicked through to a window first, the keystrokes went there.

Q: Can I change the hub keybinds?
A: They're a Keys.onPressed block near the top of hub/HubWindow.qml, one else if per key. Add or swap letters there.

Q: Something's off in only one of the two layouts. Where do I look?
A: If it's a card, it's in hub/top/ for topbar mode or hub/ for taskbar mode. If it's the bar, bars/TopBar.qml or bars/TaskBar.qml. Everything else (services, theme, settings, wifi menu, panels) is shared, so a bug there will show up in both.

If you have any other questions, please start an issue. I'd be more than happy to answer it for you.

Name		Name	Last commit message	Last commit date
.config		.config
.source_codes		.source_codes
cursor		cursor
media		media
sddm/themes		sddm/themes
utilities		utilities
venv311		venv311
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
bash.sh		bash.sh
surface-dots-installer		surface-dots-installer

Latest commit

History

Folders and files

Repository files navigation

surface-dots

Table of contents

Screenshots

Dependencies

Core & System

UI & Theming

Utilities

Installation

Hyprland

Apps

Shaders

Window actions

Exit

Focus (arrow keys)

Workspaces

Scratchpad (“special workspace”)

Mouse (window move/resize)

Screenshots

Unbound by default

Shaders

Reading Mode

Other shaders

Desktop Layouts

Taskbar Mode Behavior

Default state (no active windows)

When a window becomes active

Other taskbar-specific changes

Workspaces

Updates

Date and Clock

WORKFLOW GUIDE

Quickshell Hub

Header

Settings Panel

Displays Panel

Wallpaper Panel

Buttons and Sliders

Enabling the performance button (auto-cpufreq)

Battery Health

Media Card (MPRIS)

Now Playing (Flutter)

Calendar, Weather and Events

Setup

Notes

Sync and test

Notifications

Power menu

Wifi menu

OSDs

Firefox Customizations

Codex Stellarium

Get it on Firefox

Manual Installation

userChrome

1. Enable Stylesheets in Firefox

2. Locate Your Active Profile

3. Install the Files

Cursors

Saturnian cursor theme:

Install

Themes

GTK:

Qt / Kvantum

Lockscreens

SDDM

Hyprlock

Utilities

Credits & Acknowledgements

Media Sources

[Reuse Note:]

FAQs

About

Topics

Resources

Stars

Watchers

`Saturnian` cursor theme: