Skip to main content
Ryoku’s desktop is Hyprland + the Ryoku shell. Hyprland composites, handles input, and tiles windows; the Ryoku shell — a Quickshell (QML) frontend driven by the ryoku-shell Go daemon — paints everything else: the frame, the pill, the launcher, the overview, the screenshot tool, and the desktop widgets. This page is a map of those surfaces. For the keyboard workflow — opening, focusing, moving, and tiling windows — see Navigation; to configure any of it, see Settings.

​
Shell surfaces

  • Frame. The rounded screen border and the popouts that melt into it. Always present; it is the desktop’s signature chrome.
  • Pill. The morphing bar at the top of the screen, and its popouts. It has three island styles set in Ryoku Settings — the fused island, a floating pill, or none — each optionally revealed on hover; the frame stays the same in all three. Notifications, the update island, and the GNOME keyring prompt all grow from the pill, and it swells into the control deck (Mod + D: stash, tools, and utilities).
  • Launcher. The command palette (Mod + Space): apps plus quick prefixes — = calc, ; clipboard, ? web, / actions, @ YouTube Music, and \ a Rashin ask — over a zero-query rest card with the solar-arc clock and weather.
  • Overview. The full-screen workspace expo (Mod + Tab): scaled mini-desktops with live window previews. Click to switch or focus, drag windows between workspaces, and step between desktops. The Navigation page covers it in full.
  • Switcher. A full-screen most-recently-used window switcher. Day to day you cycle windows through the overview above and directional focus (Mod + Arrow); see Navigation.
  • Ryoshot. Screenshot capture (full screen, region, or window) and annotation — rectangles, arrows, pen, marker, blur, and text, with undo/redo. Mod + S opens it; shots save as PNG to ~/Pictures/Screenshots.
  • Keyring island. The GNOME keyring password prompt, grown from the pill centre rather than a floating dialog. System-driven — it appears when an app needs your keyring unlocked.
  • Desktop widgets. The clock and weather painted on the wallpaper. Right-click to move or configure; enable and lay them out from Settings → Desktop Widgets.
The Go daemon (ryoku-shell, in ryoku/shell/ipc/) is the control plane: it supervises the persistent components and decides what is on screen, and the QML frontend renders it. Theme tokens flow from the wallpaper through wallust, so picking a new wallpaper repaints every surface without restarting anything.

​
Getting around

Nothing is open when you log in — Hyprland is a tiling compositor, so it only shows what you launch. Open a window with Mod + Return, move focus with Mod + Arrow, and switch workspaces with Mod + 1 … 0. Navigation walks the whole workflow — opening, focusing, moving, resizing, floating, workspaces, the scratchpad, and multi-monitor. Keybindings is the exhaustive bind reference.

​
Where things live

The Hyprland load order from hyprland.lua is: base modules, then the active theme, then settings (what the Hub writes), then user (your overrides, which win). Customize covers what to put in each layer, and Settings documents the Hub that writes the settings layer.

​
Logs

ryoku-shell is autostarted by Hyprland at login; ryoku reload restarts it and rewrites the log above.

​
Next steps

  • Navigation: the keyboard workflow for windows and workspaces.
  • Settings: the Hub — every panel that configures the desktop.
  • Keybindings: the full shipped reference.
  • Customize: wallpapers, themes, and user.lua overrides.
Last modified on July 4, 2026