Farbfächer — Color clashes and suggestions for Kimai

Note: A calculation aid without guarantee. Roughly 20–30 colors stay reliably distinct; with more entries, Farbfächer prioritizes pairs that are used together or sit next to each other, the rest stays a “notice”. Colors are written directly, without going through Kimai’s update events.Hinweis: Eine Berechnungshilfe ohne Gewähr. Etwa 20–30 Farben sind sicher unterscheidbar; bei mehr Einträgen bevorzugt Farbfächer Paare, die zusammen genutzt werden oder nebeneinanderstehen, der Rest bleibt „Hinweis“. Farben werden direkt geschrieben, ohne über Kimais Update-Events zu laufen.

ΔEPerceived distance in the OKLab color spaceWahrgenommener Abstand im OKLab-Farbraum

2Suggestion strategies: hierarchical and maximally distinctVorschlagsstrategien: zusammenhängend und maximal unterscheidbar

15 minUndo window, plus a full history to restoreRückgängig-Fenster, dazu ein Verlauf zum Wiederherstellen

GPL-3Open sourceOpen Source

ClashesClashes

Find clashes by severity

Clashes nach Schwere finden

Notice, warning or critical, measured as perceived distance (ΔE) in the OKLab color space. How much a clash weighs depends on whether two entries are booked in the same weeks or sit in the same group.

Hinweis, Warnung oder kritisch, gemessen als wahrgenommener Abstand (ΔE) im OKLab-Raum. Wie schwer ein Clash wiegt, hängt davon ab, ob zwei Einträge in denselben Wochen gebucht werden oder in derselben Gruppe liegen.

PreviewVorschau

Suggestions with a preview

Vorschlag mit Vorschau

Scope: fix clashes, fill in missing colors, or recolor everything. Apply with a bulk selection, then 15 minutes of “Undo”. Every state is backed up and can be restored from the history.

Umfang: Clashes beheben, fehlende Farben ergänzen oder alles neu färben. Übernehmen per Sammelauswahl, danach 15 Minuten „Rückgängig“. Jeder Stand wird gesichert und lässt sich aus dem Verlauf wiederherstellen.

StrategyStrategie

Two ways to assign colors

Zwei Wege der Farbvergabe

Hierarchical: projects take their customer’s hue, activities stay close to their project. Maximally distinct: every color as far from all others as possible.

Zusammenhängend: Projekte im Farbton ihres Kunden, Tätigkeiten nahe ihrem Projekt. Maximal unterscheidbar: jede Farbe möglichst weit weg von allen anderen.

PalettePalette

Kimai’s color list, or free

Kimais Farbliste oder frei

Suggestions can lean on Kimai’s color list (theme.color_choices) — Gruvbox with the Knust theme — or use the free color space. Optionally limit the palette to N colors, chosen for the largest mutual distance.

Vorschläge lehnen sich an Kimais Farbliste an (theme.color_choices), mit Knust also an Gruvbox, oder nutzen den freien Farbraum. Optional auf N Farben begrenzen, gewählt nach dem größten gegenseitigen Abstand.

FormsFormulare

A color field with live hints

Farbfeld mit Live-Hinweisen

A free color picker instead of a fixed list in customer, project and activity forms, with clash hints while typing and suggestions on click. Applies to the REST API too — external clients can set any hex value.

Freier Farbwähler statt fester Liste in Kunden-, Projekt- und Tätigkeitsformularen, mit Clash-Hinweisen beim Tippen und Vorschlägen per Klick. Gilt auch für die REST-API, externe Clients können jeden Hex-Wert setzen.

LockingSperre

Automatic color, or locked

Automatische Farbe oder gesperrt

New entries without a color get one automatically, including over the API. Lock a color per entry — Farbfächer will never change it, no matter which suggestion you apply.

Neue Einträge ohne Farbe bekommen automatisch eine, auch über die API. Eine Farbe pro Eintrag sperren — Farbfächer ändert sie nie, egal welchen Vorschlag du übernimmst.

OverviewÜbersicht

See every clash at a glance

Jeden Clash auf einen Blick

The overview under Administration → Farbfächer lists every clash with severity, type, the two entries involved, their ΔE, how many weeks they were booked together and why the clash matters.

Die Übersicht unter Administration → Farbfächer listet jeden Clash mit Schwere, Typ, den beiden betroffenen Einträgen, ihrem ΔE, den gemeinsam gebuchten Wochen und dem Grund, warum der Clash zählt.

Color map by hue and lightness, an overview by customer, and a history of every change
The shared-usage window (default 90 days) and the ΔE threshold are set under System → Settings
bin/console kimai:farbfaecher:analyze --plan clashes gives the same list on the console, read-only

Farbkarte nach Farbton und Helligkeit, eine Übersicht nach Kunde und ein Verlauf aller Änderungen
Das Fenster für gemeinsame Nutzung (Standard 90 Tage) und die ΔE-Schwelle stellst du unter System → Einstellungen ein
bin/console kimai:farbfaecher:analyze --plan clashes liefert dieselbe Liste auf der Konsole, rein lesend

Farbfächer overview: 46 clashes by severity, counts for customers, projects and activities, a form to compute a suggestion, and the clash table — Clash overview (demo data)Clash-Übersicht (Demodaten)

Farbfächer-Übersicht: 46 Clashes nach Schwere, Zahlen für Kunden, Projekte und Tätigkeiten, ein Formular für einen Vorschlag und die Clash-Tabelle — Clash overview (demo data)Clash-Übersicht (Demodaten)

SuggestionVorschlag

Preview before you touch anything

Vorschau, bevor sich etwas ändert

Pick a scope and a strategy, and Farbfächer computes a plan: every planned change with the old and new color and a reason, plus clash counts before and after. Nothing is written until you select and apply.

Umfang und Strategie wählen, Farbfächer berechnet einen Plan: jede geplante Änderung mit alter und neuer Farbe und einem Grund, dazu die Clash-Zahlen vorher und nachher. Geschrieben wird erst nach Auswahl und Übernehmen.

Deselect single entries or whole groups (customers, projects, activities) before applying
Locked colors are always kept, even inside the selected scope
Applied changes stay undoable for 15 minutes, and every earlier state can be restored from the history later

Einzelne Einträge oder ganze Gruppen (Kunden, Projekte, Tätigkeiten) vor dem Übernehmen abwählen
Gesperrte Farben bleiben immer erhalten, auch innerhalb des gewählten Umfangs
Übernommene Änderungen bleiben 15 Minuten rückgängig machbar, jeder frühere Stand lässt sich später aus dem Verlauf wiederherstellen

Farbfächer suggestion: 19 planned changes reducing 46 clashes to 1, grouped by customers and projects with old and new color and a reason — Suggestion preview (demo data)Vorschlagsvorschau (Demodaten)

Farbfächer-Vorschlag: 19 geplante Änderungen senken 46 Clashes auf 1, gruppiert nach Kunden und Projekten mit alter und neuer Farbe und einem Grund — Suggestion preview (demo data)Vorschlagsvorschau (Demodaten)

How it works

So funktioniert es

Farbfächer adds one screen under Administration and runs the same logic from the console. It reads timesheets to weigh shared usage, then plans and writes colors in four steps.

Farbfächer bringt einen Bereich unter Administration und lässt dieselbe Logik auch über die Konsole laufen. Es liest Zeiteinträge, um gemeinsame Nutzung zu gewichten, und plant und schreibt Farben in vier Schritten.

GraphBuilderCustomers, projects, activities, plus shared usage from timesheets per user and weekKunden, Projekte, Tätigkeiten, dazu gemeinsame Nutzung aus Zeiteinträgen je Benutzer und Woche

ColorEngineClashes below the ΔE threshold, weighted; candidates per strategyClashes unter der ΔE-Schwelle, gewichtet; Kandidaten je Strategie

ColorPlannerGreedy assignment plus one improvement pass, fast enough for hundreds of entriesGreedy-Zuteilung plus ein Verbesserungsdurchlauf, schnell genug für Hunderte Einträge

ColorWriterWrites colors, backs up every state, restores only what’s unchangedSchreibt Farben, sichert jeden Stand, stellt nur Unverändertes wieder her

Install

Installation

Clone the plugin into var/plugins/FarbfaecherBundle; the folder name must stay FarbfaecherBundle.
Run bin/console kimai:reload. There is no migration to run.
Grant the farbfaecher permission under System → Roles to the roles that should see it (Admin and Super-Admin by default).
Set palette, ΔE threshold, palette size and the shared-usage window under System → Settings → Farbfächer.

Klone das Plugin nach var/plugins/FarbfaecherBundle; der Ordnername muss FarbfaecherBundle bleiben.
Führe bin/console kimai:reload aus. Eine Migration ist nicht nötig.
Vergib das Recht farbfaecher unter System → Rollen an die Rollen, die es sehen sollen (standardmäßig Admin und Super-Admin).
Stelle Palette, ΔE-Schwelle, Palettengröße und das Fenster für gemeinsame Nutzung unter System → Einstellungen → Farbfächer ein.

Permissions

Rechte

PermissionRecht	PurposeZweck	DefaultStandard
`farbfaecher`	Overview, suggestions and settingsÜbersicht, Vorschläge und Einstellungen	Admin, Super-AdminAdmin, Super-Admin

Questions

Fragen

Do I need the Knust theme?Brauche ich das Knust-Theme?

No. Farbfächer works with Kimai’s default color list or the free color space. With the Knust theme it follows Gruvbox automatically, because Knust sets that as Kimai’s color list.

Nein. Farbfächer funktioniert mit Kimais Standard-Farbliste oder dem freien Farbraum. Mit dem Knust-Theme folgt es automatisch Gruvbox, weil Knust das als Kimais Farbliste einträgt.

Does it change my colors right away?Ändert es meine Farben sofort?

No. Every scope first computes a preview; nothing is written until you select the changes and apply them.

Nein. Jeder Umfang berechnet zuerst eine Vorschau; geschrieben wird erst, wenn du Änderungen auswählst und übernimmst.

What if I don’t like a change?Was, wenn mir eine Änderung nicht gefällt?

Applied changes stay undoable for 15 minutes. Beyond that, every earlier state is kept in the history and can be restored from there.

Übernommene Änderungen bleiben 15 Minuten rückgängig machbar. Darüber hinaus bleibt jeder frühere Stand im Verlauf erhalten und lässt sich von dort wiederherstellen.

Does it fire Kimai’s update events?Löst es Kimais Update-Events aus?

No, colors are written directly to stay fast across hundreds of entries. Anything that listens for update events on customers, projects or activities won’t see these changes.

Nein, Farben werden direkt geschrieben, damit es auch bei Hunderten Einträgen schnell bleibt. Wer auf Update-Events von Kunden, Projekten oder Tätigkeiten hört, bekommt diese Änderungen nicht mit.

Changes

Änderungen

What each release brought, newest first. Every release adds an entry here and the same notes on the release page.

Was jede Version gebracht hat, die neueste zuerst. Jede Version bekommt hier einen Eintrag und dieselben Notizen auf der Release-Seite.

0.1.026 Sep 202626. Sep. 2026
The first release: Farbfächer finds colors in Kimai that are hard to tell apart and suggests colors for customers, projects and activities that stay distinct and still belong together.Die erste Version: Farbfächer findet Farben in Kimai, die sich schwer unterscheiden lassen, und schlägt Farben für Kunden, Projekte und Tätigkeiten vor, die sich unterscheiden und trotzdem zusammengehören.
NewNeu
- Clash analysis by perceived distance (OKLab), weighted by how often two entries are booked in the same weeks and whether they share a group.Clash-Analyse nach wahrgenommenem Abstand (OKLab), gewichtet danach, wie oft zwei Einträge in denselben Wochen gebucht werden und ob sie in derselben Gruppe liegen.
- Suggestions "related" (projects in their customer's hue, activities close to their project) or "maximally distinct", from Kimai's color list or the free color space, with a size limit for the palette.Vorschläge „zusammenhängend“ (Projekte im Farbton ihres Kunden, Tätigkeiten nahe ihrem Projekt) oder „maximal unterscheidbar“, aus Kimais Farbliste oder dem freien Farbraum, mit einstellbarer Größe der Palette.
- Preview with bulk selection, undo for 15 minutes, and a history to restore every earlier state.Vorschau mit Sammelauswahl, Rückgängig für 15 Minuten und ein Verlauf, aus dem sich jeder frühere Stand wiederherstellen lässt.
- Free color picker with clash hints in the customer, project and activity forms and in the API; new entries without a color get one automatically; "lock color" keeps a color as it is.Freier Farbwähler mit Clash-Hinweisen in den Formularen für Kunden, Projekte und Tätigkeiten und in der API; neue Einträge ohne Farbe bekommen automatisch eine; „Farbe sperren“ lässt eine Farbe, wie sie ist.
- Interface after the shared Kimai plugin UI kit and Knust.Oberfläche nach dem gemeinsamen UI-Kit für Kimai-Plugins und Knust.
- A full palette never hands out the same color twice: a clash costs more than a crowded palette.Eine volle Palette vergibt keine Farbe doppelt: ein Clash wiegt schwerer als Gedränge.
NoteHinweis
- Needs Kimai 2.67 or newer and PHP 8.1 or newer. Install into var/plugins/FarbfaecherBundle and run bin/console kimai:reload; no migration.Braucht Kimai 2.67 oder neuer und PHP 8.1 oder neuer. Nach var/plugins/FarbfaecherBundle installieren und bin/console kimai:reload ausführen; keine Migration.
- Each release zip is tested in Kimai 2.67 before it is attached.Jedes Release-Zip wird vor dem Anhängen in Kimai 2.67 getestet.