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 and configured to build cleanly (even in a clean chroot) by utilizing a local npm cache. 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 one of these locations (in order of priority):

1. Matugen: ~/.config/material-clock/colors.json
2. Quickshell: ~/.local/state/quickshell/user/generated/material_colors.scss

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

Using Matugen

To theme Material Clock using matugen, copy the provided template file assets/matugen-template.json into your Matugen templates directory (e.g., ~/.config/matugen/templates/material-clock.json):

mkdir -p ~/.config/matugen/templates
cp /opt/material-clock/assets/matugen-template.json ~/.config/matugen/templates/material-clock.json

Then, add it to your matugen config (~/.config/matugen/config.toml):

[templates.material_clock]
input_path = '/home/youruser/.config/matugen/templates/material-clock.json'
output_path = '/home/youruser/.config/material-clock/colors.json'

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.