Docs

How Lucid works.

The README, laid out to read. The search at the top of the rail finds any part of it, the way Settings finds an option.

Install

Lucid needs Arch Linux and Hyprland 0.55 or newer (the installer brings Hyprland if it is missing), and installs to ~/.config/quickshell:

git clone https://github.com/Sn3akyy1/lucid.git
cd lucid
./install.sh

In a Wayland session that opens the installer in a window, with a tour of Lucid playing while it works: pick what comes with it with switches, enter your password once, and answer anything it asks with buttons. Start Lucid at the end puts the new binds live and starts the shell. Without a Wayland session, with any option on the command line, or with --terminal, it runs in the terminal instead. Set a wallpaper from Settings → General on first run; that is what your colours come from.

What the installer does
  1. Checks your system and refuses to start anything it cannot finish, rather than leaving you half-installed.
  2. Installs dependencies through paru or yay when there is one, pacman otherwise. It lists everything and asks first; say no and it carries on, naming the features that won't work. This includes the apps the dock ships pinned, several GB and mostly from the AUR (--no-apps skips them).
  3. Copies the shell to ~/.config/quickshell, moving an existing one to ~/.config/quickshell.backup-<timestamp> first, and carries your settings, pins, reminders and keys forward. Lumen and Lens come with it: Lumen opens folders, SUPER+E and every app's open and save dialog, and Lens opens pictures.
  4. Sets up Hyprland: hyprland.lua and its modules, the keybinds, window and layer rules, blur, animations and an autostart. A config of your own is backed up and you are asked first (--no-hypr keeps it untouched, and it still gets the one module Lumen's dialogs need). On a re-run every module is checked against the one in place: new and updated ones are named, and so is one you edited, with your version in the backup.
  5. Sets up theming: the palettes, the wallpaper hook and the matugen templates. An existing matugen/config.toml is appended to, never replaced.
  6. Applies the look: kitty's colours, opacity and fish, the starship prompt, a fastfetch config (only where you have none), the VSCodium theme, and GTK as adw-gtk3-dark with the FairyWren icons, in gsettings and both settings.ini. --no-look skips it.
  7. Builds the tilting cursor, a Hyprland plugin compiled against your own Hyprland and rebuilt by itself after an update (--no-plugins skips it).
  8. Offers the login screen when SDDM is there, or to make SDDM the login screen, and pins the dock with the apps you actually have.
Installer options
FlagWhat it does
--guiThe installer window, its switches set from the other options given. The default in a Wayland session
--terminalStays in the terminal
--no-themingSkips the palette layer and leaves ~/.config/lucid and ~/.config/matugen alone
--no-hyprKeeps your Hyprland config. Lucid's binds, rules, blur and autostart are not installed
--with-hyprReinstalls Lucid's Hyprland config even when one is in place
--no-appsDoesn't install the apps the dock ships pinned (Zen, VSCodium, Spotify, Vesktop, Steam, Proton VPN)
--no-lookLeaves kitty, starship, fastfetch, your shell rc files, VSCode and GTK alone
--no-wallpapersDoesn't copy the bundled wallpapers (about 1.3 GB, live ones included)
--no-pluginsDoesn't build the tilting-cursor plugin
--no-sddmLeaves the login screen theme out
--login-screenMakes Lucid's theme the one the login screen shows (Current=lucid, backed up first)
--skip-depsNever installs packages, only reports what is missing
-y, --yesAccepts every prompt

Updating

From v1.21 on, Settings → About has an Update button whenever a new release is out (the notification that announces it has one too): a warning, your password once, then a pop-up with a progress bar that also asks anything the installer would ask in a terminal. It runs that release's own installer and offers to restart Lucid at the end. The password goes to sudo once and is never stored. Only a published release counts, unless you turn on Beta updates, which offers the newest commit on main and warns that beta builds are untested. By hand it is the same as installing:

git pull
./install.sh
How the update check works, and older versions

Once a day Lucid asks GitHub's public API for the newest release, a plain curl for api.github.com/repos/Sn3akyy1/lucid/releases/latest that carries nothing about you, and posts one notification per version. Settings → About shows what it found and turns it off.

qs ipc call updates status   # what it knows
qs ipc call updates check    # ask now
qs ipc call updates update   # install the new release (warning first)

Older versions stay on the releases page and as tags: git clone --branch v1.20.1 https://github.com/Sn3akyy1/lucid.git.

Uninstall
./uninstall.sh

It moves ~/.config/quickshell aside rather than deleting it, so your settings survive, and leaves the packages alone. The installer notes how things stood before it first changed them, and the uninstaller offers to put those back: the login screen, the GTK theme, icons and dark mode, and your own Hyprland config (or Hyprland's default). It ends by naming the desktop to log back into, and lists what else it left in place, each with a timestamped backup beside it.

What's in it

Every surface is themed from the same palette and moves the same way. Click a part to open it.

The bar

Islands, notches or one full strip, along the top or the bottom

Eleven modules, each a pill that opens into a panel: Workspaces, Media, Tray, Clock, Notifications, System, Privacy, Power, the window title, Start and Apps. Three shapes: islands (floating pills), notches (flush with the edge, blending into it) and the full bar (one strip across the screen, hanging into its corners). Position puts it on the top or the bottom edge, and it slides over to the new one.

  • Panels open as one shape with the bar. On a full bar and with notches an open panel grows out of the bar with no seam, panels side by side merge, and a module at either end can meet the screen's side and curve into it.
  • Joins. In edit mode the link between two neighbours joins them into one island or one notch, and a join holds across a module that has emptied out.
  • Workspaces with live window previews, a run of dots per display, and the scratchpad's apps as glyphs while it is open.
  • Media as a turning disc, a still cover, bars, a progress pill or with previous, play and next; its panel side by side, with a large cover, as a turning record, over the blurred cover, or mini. Lyrics are a click away.
  • Tray, rebuilt: each app in a slot of its own, or three stacked with a count. A click opens the tray, where each app is a row with its real name and its menu opens right in the row.
  • Clock with the date, the time on an accent chip, and behind it today, the month with reminders, timers and a pomodoro, a stopwatch and world clocks.
  • System: whichever of Wi-Fi, Bluetooth, the volume and its level, the microphone and the battery you pick, opening onto the control centre.
  • Start opens the launcher, drawn as the dock's launcher button, Lucid's mark, your distro's logo, your picture or the word Start. Apps puts the dock's apps on the bar, with dots, names, menus and drag to reorder.
  • On the bottom edge the dock steps aside, and on a full bar the launcher rises out of the bar itself, one piece of glass with it.
  • Open on hover, Auto-hide, a bar on every display, and Content size, which scales what is in the bar from 80 to 140% without changing its height.

Control centre

Quick settings on a grid you lay out yourself
The control centre's editor

The System pill opens the control centre: brightness and volume with their devices behind them, Wi-Fi and Bluetooth with full panels, tiles, what is playing, and gauges for the CPU, memory, disk and battery. Untouched it is one column; the pencil opens its editor, lifted off the bar to the middle of the display. Drag blocks in from the library on the left (sliders lying or standing, big tiles and small ones, media, gauges, the weather, the network, power profiles and what is up next), stretch them by any edge, and pick each one's look on the right, or start from a layout. Undo, a right-click menu, keys for everything, and tiles of your own that run your commands. qs ipc call controlcentre toggle opens it from a keybind.

Dock and launcher

A dock that grows into the launcher, with eight modes in one field

A floating toolbar with your pinned apps and running windows, drag to reorder, optional magnification, and auto-hide that can be Dynamic: tucked away only while a window is in the way. Three styles: island, notch (with edge blends) and split, the launcher, the pins and the running apps as three islands that fuse when the launcher opens and spring apart again. Pull a pin up onto the desktop for a shortcut there. With the dock hidden the launcher opens as a notch from the bottom edge.

The launcher is one search field over eight modes, each reachable by a pill, Ctrl and its number, Tab, or a prefix:

ModePrefixWhat it does
AppsFuzzy search over your apps, their own actions and open windows; vsc finds Visual Studio Code
Commands>The shell's commands, power actions included
Emoji:The emoji picker's list; Return copies one
Web?Searches your engine, or opens what you typed if it is an address
Run$Runs a command, in the background or in a terminal that stays open
Theme>themeSwitches palettes
Wallpaper>wallpaperYour wallpapers as a strip, pills, tiles or a bento grid, live ones beside them
Clipboard>clipWhat you copied, images included

Type a sum for a calculator. Wallpapers change with a transition you pick (fade, wipe, wave, grow and the rest of what awww does), and live wallpapers play videos behind the desktop, holding still under a fullscreen window.

Desktop widgets

Twenty-five kinds, close to ninety looks, placed on the wallpaper

Open the widget panel (edit mode, the desktop's right-click menu or the launcher's Widgets pill) and drag a widget out, or click it to drop it in the first free spot. Each one has a sheet with every look drawn live, its colour, size and own options, and snaps to the edges, the centre lines and the others.

WidgetLooks
ClockDigital, stacked, analog, inside an expressive shape, minimal, world clocks, a band across a round face, a scalloped dial, or the hour over the minute as a poster on the bare wallpaper
CalendarThe month, this week, today, or your next reminders
ProgressHow much of the day, week, month and year has gone, as a wavy ring, bars or dots
SystemRings, meters, a graph, tiles or network throughput
Quick togglesRound switches that turn into shapes, a pill of buttons, or Quick Settings tiles
BatteryA ring, a cell, full detail, or every wireless device that reports a charge
MediaEight looks, from an artwork card to a cover cut to a shape that morphs with every track
LyricsWord by word, karaoke, or the whole song scrolling by
VisualiserBars, mirrored bands or a wave, sized by dragging any edge
Weather and SunNow, a forecast, a curve of the next hours, sunrise and sunset
Notes and To-doA sticky note, a ruled sheet, one line; a checklist or just the next thing
TimerCountdown, pomodoro or stopwatch
At a GlanceThe date, the weather and the one thing worth knowing now
And morePhoto, Fetch, Thermals, Network, Games, Shortcuts, Search, GitHub, Palette, Phone

Desktop icons

Your Desktop folder on the wallpaper, the way a real desktop has it

Turned on in Settings → General → Desktop icons. Icons from your icon theme (or Lucid's own), thumbnails, the Trash and your drives; click, Ctrl- or Shift-click or draw a box, drag into folders, the Trash, a drive or another app. Right-click for Cut, Copy, Rename and Delete along the top, Open With, Quick Look (Space), Get Info, Compress and Extract, Send To (folders and phones), tags and more; right-click the desktop for New Item, View and Arrange By. Everything can be undone, and every key can be changed on the Keybinds page. Widgets keep their space: icons step aside together and come back after.

Edit mode

Arrange the bar, the dock and the widgets where they stand
Edit mode with the widget panel

Pick Edit Desktop from the desktop's right-click menu, or right-click any bar module, and the wallpaper shades over. Drag a bar module along the bar, into another group, or down off it; join neighbours into one island; drag the dock's handle up to float it or down into the edge to make it a notch. Right-click a module or the dock for a sheet of its options beside it. The toolbar opens the bar, dock, widgets and wallpaper; Undo (Ctrl+Z) and Revert take changes back, and Done or Escape leaves.

Lumen

A file manager of Lucid's own, and every app's file dialog
Lumen

SUPER+E, the dock or any folder opens it, and every app's Open and Save dialog is a Lumen window, with filters and an overwrite check. Tabs you can pin, colour and drag out into a window of their own; bookmarks with names and colours (Ctrl+D); Recent, Trash and your drives; a grid or a list from 24 to 256 pixels and a preview pane. Network drives: Connect to server (Ctrl+K) opens smb://, sftp://, ftp:// or a Windows \\server\share, signs in as a user or a guest with the password in your keyring, and shows the computers nearby. Copies and moves run in the background, and Lumen waits for them before it quits.

Lens

Pictures and videos, with an editor that never loses the original

Open a picture and its whole folder comes along: arrow keys, swipes and a filmstrip, All pictures (G) to search the folder, zoom and pan with a map. Edit (E) crops, turns, straightens, adjusts light and colour or applies one of twelve looks; Draw (D) adds pens, arrows, shapes, words and pixelation. Saving over a picture keeps its original for good, to bring back whenever you like. Videos play in place with a waving time line, speed, frames to save and Trim. Details, slideshow, full screen, and sending to your phone.

LucidShot

Screenshots, recordings, text and colours from one toolbar
LucidShot

Print freezes the screen under a toolbar: Screenshot, Record, Text or Colour, of a region, a window or the whole screen. A magnifier, edges that snap to windows, Shift for a square, Space to move. The capture flies into a card to open in Lens, mark up, pin over your windows, read the text off or drag into an app. Text reads the words in any part of the screen (tesseract, emoji and QR codes included) and pastes paragraphs as paragraphs; Colour copies HEX, RGB or HSL and collects palettes; Record takes what is playing and the microphone, with a countdown, a pill in the bar, and a GIF from the card.

Music

Lyrics, covers, song identification and a visualiser
The media panel's Lyrics page

The media panel's Lyrics page scrolls with the song: the line being sung springs up and fills with colour letter by letter, and a click on a line seeks there. The Lyrics widget sings along on the desktop word by word, as karaoke, or as the whole song scrolling by. Words come from lrclib.net, looked up only while something shows them and kept on disk. Identify names the song playing around you (songrec), and cava draws the visualiser, resting while nothing plays.

Lock, login and session

A lock screen, a matching login screen, and the session screen
  • Lock screen: a real session lock checked through PAM, with an oversized clock in the wallpaper's colour, the weather, battery, network and Bluetooth at a glance, what is playing, notifications and a power bar. It counts your tries against faillock, warns about Caps Lock, plays a live wallpaper behind its blur, and takes a fingerprint (with fprintd) as well as the password.
  • Login screen: the lock ported to SDDM, painted from the shell's own colours, each account with its own wallpaper and palette, live wallpapers included, and fingerprint login if you want it.
  • Session screen (SUPER+Esc): lock, sleep, log out, restart and shut down on expressive shapes; the ones that cost you work ask twice.
  • Authentication: Lucid is the session's polkit agent, so every administrator prompt comes up in its own dialog.

Notifications, OSD and sounds

Grouped notifications, a notch OSD, toasts and Lucid's own sounds

Notifications are grouped by app with inline reply and progress bars, the newest growing out of the bell; do-not-disturb has quiet hours and a rule for fullscreen windows. The OSD shows volume, brightness, the microphone, Caps Lock and Num Lock as a card or as a notch rising out of the bottom edge, and with the dock a notch too, the dock itself turns into it. Toasts say small things under the bar, and any script can raise one (qs ipc call -- toast show game "Game Mode On"). Sounds: eight notification sounds and the system's own, synthesised for Lucid, each with a switch.

Settings

The whole desktop, without a config file

A searchable app (Ctrl+F, or just type) with a page for every part of the system, a reset arrow on anything you changed, and a What's new sheet after each update. Among the pages:

  • General with Interface size (75 to 125%), Corner rounding and Motion
  • Bar, Dock, Launcher, Widgets and Workspaces
  • Theme, Colours, Palettes and Glass
  • Windows (gaps, borders, corners, shadows, tiling, focus) and Input (layouts, repeat, mouse, touchpad, swipes), live through Hyprland
  • Displays: resolution, refresh, scale, rotation, arrangement and mirroring
  • Network, Bluetooth (files both ways) and Phone, a full KDE Connect client with files, notifications, a media remote and a touchpad
  • Sound, every device, socket and profile, a slider per app, and outputs played together
  • Notifications, Idle (hypridle with sliders), Storage (what fills the disk, as a map), Date & Time (location, weather, units, time zone)
  • Environment: cursor, icons, GTK and Qt themes and fonts, set everywhere at once, Lucid's own pointer included
  • Startup: apps at login, system autostart and environment variables
  • Keybinds, Users and Accounts, Screenshots and About

Special workspaces

Scratchpads for music, chats, to-dos and the system monitor
KeysWorkspaceOpens
SUPER + SHIFT + SScratchpadSomewhere to park windows
SUPER + SHIFT + MMusicSpotify, Feishin, Cider, YouTube Music, TIDAL…
SUPER + SHIFT + DCommsDiscord, Vesktop, Telegram, Signal, Element, Slack…
SUPER + SHIFT + RTo-doTodoist, Planify, Errands, Obsidian…
CTRL + SHIFT + EscSystembtop, Mission Center, Resources…

A key starts its app if needed and slides the workspace over the one you are on; the same key hides it. SUPER+ALT+S stashes a window in the scratchpad. Settings → Workspaces picks the apps, the dimming and blur, and makes workspaces of your own.

Look and motion

Springs, Lucid's own icons and Lucid's own pointer
  • Jelly motion. Panels, pills, menus, the dock, the OSD and widgets settle on a spring with a little wobble. Settings → General → Motion sets how much, or turns it off.
  • Icons. Folders, files, places, drives and many apps share one tonal set drawn from your palette, in Lumen, on the desktop, in the dock and the launcher. An app the set doesn't know keeps its own icon.
  • Pointer. Bibata Modern's shapes in your palette's colours (Dark, Light or Accent), fading along when the palette changes, drawn on your machine from Bibata's source. A tilting cursor leans the arrows and hands as they move, and in a drag the shell draws the pointer itself so it stays on what it holds. Any other cursor theme is a switch away.
  • Glass. One slider for how far the desktop shows through the shell, kitty and your windows.

Theming

One palette from your wallpaper, everywhere

Matugen and Pywal build a palette from your wallpaper, Your colour from one colour you pick, and Catppuccin Mocha, Gruvbox, Nightfox, Nord and Tokyo Night are fixed palettes. Every one has a light mode, and the theme can follow each new wallpaper into light or dark. Settings → Colours sets Matugen's style, its contrast and which of the wallpaper's colours to start from.

The palette reaches beyond the shell: Hyprland's borders, kitty, starship, GTK, Qt and KDE apps (through qt6ct and a colour scheme), Zen, VSCodium and the login screen follow it, and any app can through a matugen template:

[templates.myapp]
input_path = '~/.config/matugen/templates/myapp.css'
output_path = '~/.config/myapp/colors.css'
post_hook = 'pkill -USR1 myapp'   # optional: tell the app to reload

Settings → Colours lists every template with how its last render went, adds the ones Lucid ships for apps you have, and takes your own from a file or a link. Settings → Palettes adds themes from a gallery of a few hundred base16 and base24 schemes, from any scheme repo or file, or from its editor, and exports the palette on screen as a Lucid palette or base16 YAML.

python3 ~/.config/lucid/add-theme.py <repo-url|file|folder> [--list] [--variant <name>] [--name <label>]

Keybinds

The binds Lucid ships &nbsp;(SUPER + / shows them all, and Settings → Keybinds changes any of them)
KeyDoes
SUPER (tap)Launcher
SUPER + PCommands
SUPER + T / BTheme / wallpaper picker
SUPER + SHIFT + VClipboard history
SUPER + SSettings
SUPER + .Emoji picker
SUPER + KOn-screen keyboard
SUPER + /Every keybind
SUPER + WWorkspace overview (or a three-finger swipe)
SUPER + EscSession screen
CTRL + ALT + TABWindow switcher, newest first (+SHIFT steps back)
Print / SUPER + DLucidShot
SUPER + PrintWhole screen
SUPER + SHIFT + T / CCopy text / pick a colour
SUPER + ELumen
SUPER + CClose the window
SUPER + VFloat it at 1366×768, centred, or tile it again
SUPER + JToggle the split
SUPER + 1–0Workspace (+SHIFT moves the window there)
SUPER + arrowsMove focus
SUPER + RReload Hyprland
SUPER + MExit Hyprland
F1–F6Mute, volume, microphone, brightness
F8 / F9 / F10 / F12Radios / terminal / lock / calculator

Everything is also reachable over IPC, so a config of your own can bind it:

hl.bind("SUPER + SPACE", hl.dsp.exec_cmd("qs ipc call -- launcher toggle"))
hl.bind("SUPER + L",     hl.dsp.exec_cmd("qs ipc call -- lock lock"))
hl.bind("SUPER + A",     hl.dsp.exec_cmd("qs ipc call -- controlcentre toggle"))

Keep the --: a call that takes an argument fails without it (qs ipc call -- settings show bar), and it does no harm elsewhere.

IPC reference

Every surface is scriptable: qs ipc call -- &lt;target&gt; &lt;function&gt; [arg]
TargetFunctions
launchertoggle open close wallpaper live theme power emoji clipboard blur command shuffle search <query> hide <id> unhide <id> hidden
controlcentretoggle open close
mediatoggle open close identify lyrics playPause next previous
clockopen <tab> toggle close, tab being today, calendar, timer, stopwatch or world
timerstart <seconds> stopwatch pomodoro pomodoroSkip pomodoroStop pomodoroAdd <minutes> status
alarmadd <hour> <minute> <label> remove <id> list stop snooze status
workspacestoggle open close
settingstoggle open close show <page> search <words> reset, and a function per page (bar, sound, displays…)
edittoggle on off bar dock open <module> close undo revert status
widgetspanel openPanel <screen> closePanel add <type> <variant> remove <uid> preset <name> save <name> list catalogue toggle lock unlock…
desktopicons arrange selectAll undo refresh
snaptoggle open close text color video
recordertoggle start stop pause status
screenshotfull text
notifstoggle open close clear toggleDnd expandAll settings count
toastshow <icon> <label> warn <icon> <label>
soundsplay <name> list
locklock unlock isLocked status (nothing here gets past the password)
sessiontoggle open close
switchernext prev toggle open close status
keybindstoggle open close edit editBind <id>
mojitoggle open close emoji kaomoji gif center
keyboardtoggle open close letters fnkeys center bigger smaller
idlestatus keepawake awake normal on off restart
networkstatus list rescan
bluetoothsend <address> <path>
kdeconnectstatus list rescan ring <id> ping <id> clipboard <id> files <id> send <id> <path>
nightlighttoggle on off status
displayslist settings shell <where> bar <where> dock <where>
updatesstatus check whatsnew update beta show
whatsnewopen close status
polkitstatus demo <action-id> fail grant close
debugtoggle on off (draws input and blur regions)

Lumen and Lens run as their own processes with launchers of their own: ~/.config/quickshell/lucidlumen/lumen [folder] and ~/.config/quickshell/lucidlens/lens <file>.

Requirements

What the installer pulls in

Required: hyprland · quickshell · qt6-5compat · qt6-declarative · qt6-multimedia · qt6-webengine (Qt's PDF module, which Lumen's window needs)

Per feature, where a missing one breaks only its own feature:

PackagesBack
matugen jq python-pywal awww gitColours, themes, wallpapers, importing schemes
networkmanager qrencodeWi-Fi and sharing a network as a QR code
bluez bluez-utils bluez-obex python-gobjectBluetooth, and files both ways
kdeconnect sshfsThe Phone page and browsing a phone's files
libpulse wireplumber pipewire-audio sound-theme-freedesktopSound, its devices and its tests
gvfs gvfs-smb gvfs-nfs gvfs-dnssd gvfs-wsdd ffmpegthumbnailerDrives, network shares and thumbnails
qt6-imageformats kimageformats libjpeg-turbo exiv2Lens and pictures in every format
grim wf-recorder ffmpeg imagemagickScreenshots and recording
tesseract tesseract-data-eng python-pillow python-numpy python-fonttoolsReading text off the screen, emoji included
wl-clipboard wtype cliphistPasting and clipboard history
cava songrecThe visualiser and song identification
brightnessctl upower hypridle hyprsunsetBrightness, battery, idle and night light
polkit accountsserviceAdministrator prompts and the Users page
librsvg python-cairoLucid's pointer and the cursor shadow switch
xdg-desktop-portal-hyprland xdg-desktop-portal-gtkScreen sharing and portals
smartmontools udisks2 inotify-toolsDrive health, mounting, the camera toast
curl libnotify xdg-utils noto-fonts-emojiWeather, lyrics, notifications, links, emoji

The Hyprland config and the look (unless --no-hypr / --no-look): kitty · fish · playerctl · gnome-calculator · starship · ttf-jetbrains-mono-nerd · adw-gtk-theme · papirus-icon-theme

The dock's default pins (unless --no-apps): zen-browser-bin · vscodium-bin · spotify · vesktop · steam · proton-vpn-gtk-app. An equivalent you already have counts, and Steam brings the Vulkan drivers for the graphics cards you have.

Fonts: Google Sans Flex ships with Lucid under the Open Font License, so nothing needs installing; any installed font can be picked in Settings.

Optional setup

GIF search needs a free Giphy key from developers.giphy.com (Tenor works too), in ~/.config/quickshell/lucidmoji/config.json:

{ "giphyKey": "your-key-here", "tenorKey": "", "gifDir": "" }

Wallpapers live in ~/Pictures/wallpapers, a folder per theme; the folder can be changed in Settings → General.

Questions

What do I need to run Lucid?

Arch Linux and Hyprland 0.55 or newer. Lucid uses Hyprland's own APIs for workspaces and windows, so it does not run on Sway, niri, GNOME or KDE, and the installer relies on pacman and the AUR. The installer brings Hyprland itself when it is missing; the shell needs quickshell, its Qt modules and qt6-webengine, and everything else backs one feature each.

Will the installer overwrite my own config?

Not without asking, and never without a backup. A Hyprland config of your own is backed up and you are asked first; an existing matugen/config.toml is appended to; your old ~/.config/quickshell moves aside with a timestamp. --no-hypr, --no-look and --no-theming keep each part entirely yours.

What does Lucid connect to?

The update check asks api.github.com/repos/Sn3akyy1/lucid/releases/latest once a day, a plain curl that carries nothing about you; Settings → About turns it off. The weather comes from Open-Meteo, lyrics from lrclib.net only while something shows them, and GIF search talks to Giphy or Tenor only if you gave it a key.

Nothing appears when I run qs

Check qs log for QML errors, and make sure you are on Hyprland. If the log names an error you can't place, it belongs in a bug report: it is the most useful thing to include.

Everything is grey, or the colours look wrong

The palette cache is missing. Set a wallpaper through Settings → General, or copy a bundled palette: cp ~/.config/lucid/themes/nord/quickshell.json ~/.cache/quickshell/matugen.json

The glass shows my windows, not the wallpaper

That is on purpose: the glass frosts whatever is really behind it. To frost only the wallpaper, uncomment the xray rule in ~/.config/hypr/modules/layerrules.lua and reload Hyprland. Settings → Glass sets how far anything shows through at all.

How do I add my own theme, or switch to light mode?

Settings → Palettes has a gallery of a few hundred base16 and base24 schemes, takes the link of any scheme repo or file, and has an editor; nothing from a repo is ever run. Light or dark on the Theme page switches every palette, and the theme can follow each new wallpaper into light or dark by itself.

Can each display have its own wallpaper, or its own bar?

Yes. A line per output in ~/.config/lucid/wallpaper-outputs.conf gives it its own picture, and Settings → Displays puts a bar on every display or sends the bar and the dock to the display you pick: qs ipc call -- displays shell next.

Do I need Google Sans installed?

No. Lucid ships Google Sans Flex itself, under the Open Font License. Any installed font can be picked in Settings → General instead.

Animations feel choppy on an NVIDIA card

Qt refuses threaded OpenGL on the NVIDIA driver, which pins animations to about 60 fps. Lucid starts through ~/.config/lucid/launch-shell.sh, which moves such machines to Qt's Vulkan backend; launch-shell.sh --explain says what it decided.

Another app's notifications show instead of Lucid's

Only one program can own org.freedesktop.Notifications, and an installed daemon (swaync, dunst, mako) is started by the first notification. Check with busctl --user status org.freedesktop.Notifications | grep PID, then mask the other daemon (systemctl --user mask swaync.service) and log back in. The installer offers to.

A keybind with an argument does nothing

Put -- before the target: qs ipc call -- settings show bar. Without it qs reads the argument as its own.

Where is the full list of shortcuts?

Super + / lays every keybind over the screen, and Settings → Keybinds lists, searches, edits, adds and switches them off. They live in ~/.config/lucid/keybinds.json.

Which password unlocks the lock screen, and what is “Too many attempts”?

Your account password, checked through PAM; nothing in the lock IPC target gets past it. “Too many attempts” is faillock's real count: with Arch's defaults three failures in 15 minutes lock the account for 10, and the screen counts down. Cancelled administrator prompts count too.

How do I use the Lucid login screen?

Turn on Login screen in the installer window, or run ./install.sh --login-screen. It sets Current=lucid in /etc/sddm.conf (backed up first), and offers to make SDDM the login screen when another one is in use.