Material Clock

A Material Design 3 clock application for Linux, built with Electron + React. Adapts its color scheme from your system's Material You palette (via quickshell/material-colors.scss) for seamless desktop integration.

Features

• Alarms — Create and manage alarms with custom labels and sounds. Persisted across sessions via ~/.config/material-clock/. Scheduled through systemd timers for reliability even when the app is closed.
• Timers — Multiple concurrent countdown timers with circular progress indicators, custom sounds, and labels.
• Stopwatch — Lap tracking with animated flash effect. Tray menu integration for adding laps without switching windows.
• World Clock — Track multiple time zones at once.
• Dynamic theming — Reads Material You colors from ~/.local/state/quickshell/user/generated/material_colors.scss and applies them live. Falls back to warm dark defaults (#1C1B17).
• System tray — Hides to tray on close; context menu for quick alarm/timer/stopwatch access.
• Desktop notifications — notify-send integration with functional Snooze (+1 min) and Stop actions.
• Single instance — Prevents duplicate windows; second-instance launches restore the existing window or trigger alarms.

Requirements

Dependency	Purpose
electron ≥ 41	App runtime
mpv	Alarm and timer audio
libnotify (notify-send)	Desktop notifications
systemd	Reliable alarm scheduling (optional)
Node.js ≥ 18	Build only

Install (Arch Linux / CachyOS)

A PKGBUILD is included. To build and install from source:

makepkg -si

This compiles a production build and installs the app to /opt/material-clock with a .desktop entry, system icon, and /usr/bin/material-clock launcher.

Development

npm install
npm run dev:electron   # Vite dev server + Electron with hot reload

Build

npm run build          # Vite production build → dist/
npm run dist           # Build AppImage via electron-builder

Project Structure

electron-main.cjs     Main process — window, tray, IPC, alarm scheduling, audio
preload.cjs           Context bridge exposing electronAPI to the renderer
src/
  bridge.js           Renderer-side wrapper around window.electronAPI
  main.tsx            React entry point
  app/
    App.tsx           Theme initialization + router
    routes.tsx        Hash router config
    components/
      Layout.tsx            Persistent shell: ringing overlay, bottom nav, stopwatch state
      AlarmsScreen.tsx
      TimersScreen.tsx
      StopwatchScreen.tsx
      WorldClockScreen.tsx
      TimePickerDialog.tsx  Radial time/duration picker
      AlarmCard.tsx
      AlarmDetailSheet.tsx
      SettingsDialog.tsx
      BottomNavigation.tsx
      ui/                   shadcn/ui component library
  styles/
    index.css / theme.css / fonts.css / tailwind.css
assets/               App icons (PNG + SVG)
PKGBUILD              Arch Linux package build script

Theming

Material Clock reads color tokens from:

~/.local/state/quickshell/user/generated/material_colors.scss

If absent, the app falls back to a warm brown-black dark palette. See electron-main.cjs → get-theme IPC handler for the full token mapping.

Data Location

All user data is stored in ~/.config/material-clock/:

• alarms.json — alarm definitions
• timers.json — timer state
• settings.json — volume, debug mode
• custom_sounds.json — user-added audio files

License

See ATTRIBUTIONS.md.