English · العربية · Français · Deutsch · 中文 · 한국어 · हिन्दी

Spectra — Lenovo LOQ keyboard backlight control

A polished Electron + React desktop app to control the white keyboard backlight on a Lenovo LOQ 15IRX9 (and similar ideapad/LOQ laptops) — with a live keyboard preview, reactive‑on‑keypress glow, and a clean root‑free setup via udev.

Designed & developed by Kareem Aksh.

---

Table of contents

• Hardware reality
• Features
• Screenshots
• Quick start
• How it works
• Tech stack
• Project structure
• Build & package
• Uninstall
• Contributing & license

Hardware reality

Note

The LOQ 15IRX9 has a single‑zone white backlight with 3 levels (off / low / high) exposed at /sys/class/leds/*::kbd_backlight. There is no RGB and no per‑key zones, so colored or spatially‑moving effects are physically impossible. Spectra controls exactly what the hardware supports — honestly. (The UI's keyboard visualizer is a preview, not fake capability.)

Features

	Feature	Description
💡	Brightness	Off · Low · High, with a live on‑screen keyboard that glows to match.
⚡	Reactive backlight	Pulses high on every keypress and fades to off when you stop typing (glow→fade, since the hardware has 3 levels).
♻️	Reset to default	Restores factory brightness (high).
🔁	Restore on launch	Reapplies your last level at startup.
🔓	Root‑free	One‑time udev setup; no sudo for everyday use.
🎛️	60 fps engine	Smooth UI driven by src/lib/engine.js.

Screenshots

Dark	Light

Quick start

# 1) One-time setup — grants your user access to the backlight + keyboard input (no root afterwards)
bash install-driver.sh

# 2) Install deps (first time only) and launch
npm install
bash run.sh        # builds if needed, then opens Spectra

Development mode (hot reload):

npm run dev        # Vite + Electron with live reload

How it works

flowchart LR
    UI["React UI (Vite)<br/>brightness · preview · reactive toggle"] -->|IPC| M["Electron main<br/>main.cjs · preload.cjs"]
    M --> B["backlight.cjs<br/>writes /sys/class/leds/*::kbd_backlight"]
    M --> K["keys.cjs (evdev)<br/>reads /dev/input/event*"]
    K -->|keypress events| M
    B --> HW(("⌨️ keyboard backlight"))
    UDEV["udev rules<br/>(install-driver.sh)"] -. grants access .-> B
    UDEV -. grants access .-> K

Loading

The two udev rules add your user to the right group so Spectra can write the backlight sysfs node and read keyboard event devices (for reactive mode) — without running as root.

Tech stack

• Electron 33 (desktop shell, IPC, sysfs/evdev access via Node)
• React 18 + Vite 6 (UI, hot reload, fast builds)
• Framer Motion (animation)
• electron-builder (AppImage / .deb packaging)
• Pure Linux sysfs + evdev backend — no kernel module needed

Project structure

electron/
  main.cjs        window + IPC + signal sources (keys / CPU)
  preload.cjs     safe IPC bridge
  backlight.cjs   sysfs brightness driver (off/low/high)
  keys.cjs        evdev keypress listener (reactive + per-key preview)
  cpu.cjs         CPU signal source
  store.cjs       persists last level
  make-icon.cjs   renders the app icon set via Chromium
src/
  App.jsx, main.jsx, styles.css
  lib/   effects.js (catalog) · engine.js (60fps runtime) · keymap.js
  components/  KeyboardViz · EffectGallery · Presets · ConfigPanel · About · Logo · ThemeToggle
  assets/  logo + hero art
resources/
  99-spectra-kbd-backlight.rules   write access to the backlight
  99-spectra-kbd-input.rules       read access to keyboard input
  icon.png, icons/                 app icons
install-driver.sh · run.sh · vite.config.js

Build & package

npm run build      # production web build -> dist/
npm run dist       # build AppImage + .deb via electron-builder

Artifacts land in release/ (or dist/); the .AppImage is portable and the .deb installs system‑wide.

Uninstall / roll back

sudo rm -f /etc/udev/rules.d/99-spectra-kbd-backlight.rules \
           /etc/udev/rules.d/99-spectra-kbd-input.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

Contributing & license

• 🤝 Contributions welcome — see CONTRIBUTING.md.
• 🔒 Responsible use & reporting — see SECURITY.md.
• 🌍 Languages — English · العربية · Français · Deutsch · 中文 · 한국어 · हिन्दी
• 📄 Licensed under the MIT License — see LICENSE. © Kareem Aksh.

---

_{Topics: electron · react · vite · linux · keyboard-backlight · lenovo · loq · ideapad · udev · sysfs · leds · desktop-app · backlight-control · framer-motion}