Skip to main content

Theme, colour derivation and icon size

Status Version Implementation

Context​

K3 (qt_quick) paints several surfaces that are not plain page background: the alternating rows of a file list, the selected row, the logo band and the Selection page surface. This spec defines where those colours come from and what the Theme setting is allowed to change.

The rule behind it: a colour is either taken from the desktop colour scheme through Kirigami.Theme, or it does not exist. Literal colour constants ("white", "black", hex brand blues) do not follow the user's scheme and are what this spec removes. (Two accepted exceptions, each bounded by its row: the Statistics chart series colours (THM-C17), and K2's Katalog Colors palette under theme id 1 only (THM-F4, THM-C19, THM-C20), amended 2026-09-30.)

Decision of 2026-09-30 (finishing Katalog Colors). The maintainer: "I want to "finish" the Katalog Colors theme. This means that all items with colors (non grey) should use a defined Katalog color. Can you assign one for all these elements, including: background of collection name in drawer, Selection background & selected item, section titles, for now I accept that checkbox and other non-text object have the default dekstop theme color". On the proposed mapping: "yes let's start with this, easier for me to look once implemented". Under theme id 1 the coloured K3 surfaces and texts now take K2's brand palette (THM-F17 to THM-F21, THM-C20); non-text controls and semantic status colours stay the desktop's (THM-C21). Themes 0 and 2 are unchanged.

Decision of 2026-09-30 (finishing Desktop Theme (gray)). The maintainer: "good. as you define application colors, can you now complete the Desktop Theme (grey) by attributing a grey color to the colored elements (ex: section title)". Under theme id 2 the section titles, the selection highlight and the Selection reminder hover now take greys derived from the desktop scheme (THM-F17, THM-F18, THM-F21, amended; THM-C22). Its Selection page surface, logo band and stripe were already grey (THM-C4, THM-F4). No hex literal: the palette exception stays theme id 1 only.

Decision of 2026-10-01 (list background, gray highlight and band). Three changes, approved by the maintainer on 2026-10-01. (1) The empty area below the last row of the Search results, Explore file and Explore folder lists takes a theme-dependent colour (THM-F22, THM-C23): "I want that for the Katalog Colors theme actually. for the 2 desktop themes, put the non-alternate so whitish row color (in light mode)", then "ok". (2) Under theme id 2 on a light desktop the selection highlight is lightened (THM-F18, amended): "the color for selection ... in desktop theme gray is too dark", option "1" chosen. (3) Under theme id 2 on a light desktop the drawer collection-name band takes that same highlight colour (THM-F20, THM-C4, amended): "put that same color for the background of the collection name in the drawer".

Reading the requirement IDs. Each requirement has a permanent ID. IDs are never renumbered or reused; a retired requirement is marked [Removed], not deleted. Status is one of [Implemented] / [Planned] / [Backlog] / [Removed].

Scope at a glance​

In scope: K3 colour derivation — the file-list row pair, and the reach of the three Settings/Theme values on K3's derived colours — and the icon size preference of THM-F7, which belongs here because it is stored in the same Settings/Theme* key family and shared with K2 — and the Explore folder list's row surfaces (THM-F8, THM-F9, THM-C11) — and the surface of the Selection page's SEL-F5 reminder row (THM-F10, THM-C13, THM-C14). (Scope widened 2026-09-12, first from colour derivation alone, then to the folder list; widened again 2026-09-21 to the reminder row.) — and the operational goal THM-O2, whose delivery is owned by SpecK3Deployment.md (DPL-F5) — and the light/dark variant of the fallback icon set (THM-F11). (Widened 2026-09-23, twice.) Recorded as [Backlog] only, 3.1 candidates, not authorised for 3.0: a Katalog colour-scheme setting (THM-F12, THM-C15) and a startup workaround for a misread portal preference (THM-F13, THM-C16). (Added 2026-09-24.) — and the Statistics page chart's light/dark theme (THM-F14, THM-C17). (Widened 2026-09-27.) — and the odd-row stripe colour per Settings/Theme value (THM-F4, THM-C2, THM-C19). (Amended 2026-09-30: the Theme setting now changes the file-list odd-row colour; before, it did not.) — and the Katalog Colors palette under theme id 1 for section titles, the selection highlight, the Selection page surface, the drawer logo band and the Selection reminder hover (THM-F17 to THM-F21, THM-C20, THM-C21). (Widened 2026-09-30.) — and the background of the empty area below the last row of the Search results, Explore file and Explore folder lists (THM-F22, THM-C23). (Widened 2026-10-01.)

Out of scope (non-goals):

  • K2 (qt_widgets) — in maintenance mode. It shares the same Settings/Theme key and keeps its own Katalog Colors rendering, untouched (THM-C5).
  • Icon theme — icon set selection is not governed here, except that the fallback icon set follows light/dark (THM-F11); THM-F7 sets a size, never which icon set is used.
  • Which K3 views honour THM-F7 — see THM-C10.
  • File-list text colour — rows keep Kirigami.Theme.textColor under every Theme value; K2's #333 (from its Katalog Colors light stylesheet) is not ported (THM-C19).
  • Removing the "Katalog Colors" entry from the Settings combo — explicitly future work, not authorised by this spec (THM-C3).
  • Typography, spacing, and any other non-colour theming.
  • Non-text controls and semantic colours under theme id 1 — checkboxes, radio buttons, focus rings, progress bars, scrollbars and other non-text controls, and semantic status colours, keep the desktop's colours under every Theme value (THM-C21; accepted by the maintainer "for now", 2026-09-30).

Note on the stored default. Settings/Theme defaults to 1 for a new K3 profile. Under THM-C2 that default renders K2's Katalog Colors palette on the file-list odd-row stripe (THM-F4), on the surfaces of THM-F17 to THM-F21 and on the list background of THM-F22, and theme 0 everywhere else (amended 2026-09-30; THM-F22 added 2026-10-01). This is recorded, not changed: altering the default value is not authorised here. Beta testers whose stored value is 1 will see the brand colours after this change; no key is added or rewritten.

Operational requirements — why / for whom​

Goals in real use, independent of how they are built.

IDRequirementStatus
THM-O1A user scanning a long file list can tell one row from the next at a glance, and does not lose the line they are reading — under their own desktop colour scheme, light or dark, and whichever Theme value is stored.[Planned]
THM-O2A user who has set their system to dark (or light) sees K3 in that mode as a whole window, not a mix of dark surfaces and light controls — in packaged builds on non-Plasma Linux desktops, on Windows and on macOS, as well as on Plasma. Delivered by packaging, per DPL-F5 / DPL-C6 (SpecK3Deployment.md).[Planned]

Functional requirements — what the system does​

Observable behaviour that can be triggered and watched.

IDRequirementStatus
THM-F1File-list rows alternate between exactly two background colours: (a) the View background — Kirigami.Theme.backgroundColor read under Kirigami.Theme.colorSet: Kirigami.Theme.View with inherit: false; on Breeze this is #fcfcfc light / #1b1e20 dark, so it reads as the near-white / near-black extreme, while still following any other scheme — and (b) the stripe colour, which depends on Settings/Theme as defined in THM-F4. The View colour (a) is never a literal white, black or hex constant; the stripe (b) is derived from the desktop under theme ids 0 and 2, and is K2's hardcoded pair under theme id 1 only (THM-C19). (Amended 2026-09-30: (b) was the Window background under every theme; that is now theme id 2's stripe.)[Planned]
THM-F2Parity: even rows — row index 0, the first row — take the View colour of THM-F1, under every Theme value; odd rows take the stripe colour of THM-F4. This is the ordinary list-view convention. (Amended 2026-09-30: odd rows were the Window background.)[Planned]
THM-F3The THM-F1 / THM-F2 row pair applies to the Search results file list and the Explore file list, identically in both.[Planned]
THM-F4The odd-row stripe of the file lists (THM-F3, THM-F8) depends on Settings/Theme: theme id 0, Desktop Theme — the desktop accent Kirigami.Theme.highlightColor laid at 11 % opacity over the View colour (Qt.tint(View, accent at alpha 0.11)), so it follows light, dark and any accent (K2's #e9f7fc is almost exactly Breeze's #3daee9 at ~11 % over white); theme id 2, Desktop Theme (gray) — the Window background, Kirigami.Theme.backgroundColor (the former THM-F1 (b)); theme id 1, Katalog Colors — K2's hardcoded stripe, #e9f7fc on a light desktop and #161b1d on a dark one, copied verbatim from K2 (loadCustomThemeLight / loadCustomThemeDark, qt_widgets/mainwindow_setup.cpp, "alternate-background-color"). Even rows stay the View colour under every value (THM-F2); the selected row is unchanged (THM-F5). A change of the Theme setting repaints the stripe without restart, as THM-F6 does for the desktop scheme. (Amended 2026-09-30, approved by the maintainer on that date: "Desktop Theme: exactly what you proposed and I tested. Desktop Theme (grey): the theme grey that was there before. Katalog Colors: the blue as in K2 (hardcoded colors). This should work for dark mode as well." Before this amendment the Theme setting did not change row colours. Theme id 0 was tested by the maintainer on 2026-09-30.)[Planned]
THM-F5A selected row is painted with the selection highlight instead of its parity colour; the row pair applies only to unselected rows. Existing behaviour, unchanged by this spec.[Implemented]
THM-F6Derived colours are bindings on Kirigami.Theme, so changing the desktop colour scheme while Katalog is running repaints the lists to the new scheme without restarting the application.[Planned]
THM-F7The Settings page offers a bigger icon size choice, as K2 does. Unset, icons are drawn at the smaller size; set, at the larger one. K2's pixel values map onto the Kirigami size tokens: checked → the medium token (32), unchecked → the small-medium token (22). The user asked for this port on 2026-09-12 and chose the Settings page, as in K2, over a per-page control.[Planned]
THM-F8The THM-F1 / THM-F2 row pair also applies to the Explore folder list, identically to the file list beside it — the folder rows stripe. (Added 2026-09-12. THM-F3 named only the Search results and Explore file lists, so the folder list was never covered by any row; it painted no surface of its own at all.) The list is a tree and its rows are indented, which was the argument for leaving it unstriped; it is overruled because K2 stripes its own Explore directory tree (alternatingRowColors on Explore_treeview_Directories, qt_widgets/mainwindow.ui) and because two lists side by side on one page with different row surfaces is the more visible inconsistency.[Planned]
THM-F9A row surface in these lists is painted by the application, not left to the active Qt Quick Controls style. The Explore folder list drew no background of its own, so its rows took the style's — Breeze under Plasma, Fusion on every other platform (qt_quick/main.cpp:32-34) — while their text colour came from Kirigami either way, which is how a Kirigami text colour ended up on a Fusion background. The user reported the resulting difference between Linux and Windows on 2026-09-12. The lists governed by THM-F3 and THM-F8 MUST look the same under either style.[Planned]
THM-F10The SEL-F5 selection reminder at the top of the Selection page (SpecSelection.md) paints its own surface instead of taking the active Qt Quick Controls style's: transparent when idle, so the tinted Selection page surface shows through, and a hover tint from Kirigami.Theme — hoverColor, see THM-C13 — while the pointer is over it, because the row is clickable (SEL-F6). Reported 2026-09-21 against the 3.0.beta2 AppImage on a non-Plasma desktop, and measured against the real styles: under Fusion — the style every packaged build resolves to, see SpecK3Deployment.md Known limitations — Controls.ItemDelegate's background is an opaque #ffffff rectangle with visible: true that paints unconditionally, so the row showed as a white band; under org.kde.desktop the same delegate is Kirigami's DefaultListItemBackground, transparent until hovered or selected, which is why a local development build never showed it. This is THM-F9 applied to one further element, not a sweep.[Planned]
THM-F11K3's fallback icon set — the light set (:/fallback-icons) or the dark set (:/fallback-icons-dark) — follows the same light/dark preference as DPL-F5 (SpecK3Deployment.md), in every K3 build, packaged or built from source: when Qt reports the preference (Qt.styleHints.colorScheme / QStyleHints::colorScheme) as Dark, the dark set is used; as Light, the light set; as Unknown, the existing test on the application palette's window lightness decides, so a Plasma source build keeps its current behaviour. When the preference changes while Katalog runs, the icon set follows without a restart, and icons already on screen are redrawn from the new set. Reported 2026-09-23: in dark mode the packaged build showed light-mode icons, because the set was chosen once at startup from the palette alone (qt_quick/main.cpp). Approved by the maintainer on 2026-09-23. This row authorises the qt_quick source change it needs (main.cpp and whatever QML/C++ the live refresh requires); SpecK3Deployment.md's "no qt_quick source change" sentence governs that page's own rows only, as THM-C14 already records. It adds, changes and removes no user-visible string and changes nothing under core/.[Planned]
THM-F123.1 candidate. The Settings page offers a choice of Katalog's colour scheme: System (follow the desktop — the default), Light or Dark. The choice applies immediately, without restart, and drives one effective scheme from which both the Kirigami / Fusion colours (DPL-F5) and the fallback icon set (THM-F11) are derived. System behaves exactly as DPL-F5 and THM-F11 do today. Recorded at the maintainer's request on 2026-09-24 as a candidate for Katalog 3.1, not for 3.0. It is a new feature with no K2 equivalent, so under the project rule that new UI features follow K2 parity it is the maintainer's explicit decision; the open points under Open, not authorised must be settled before it can move to [Planned].[Backlog]
THM-F133.1 candidate. On Linux, when Qt reports the colour scheme as Unknown at startup, Katalog reads the preference directly from the XDG desktop portal with Settings.ReadOne (org.freedesktop.appearance / color-scheme), so a host whose portal misreports it through ReadAll — the Linux Mint / Cinnamon case in SpecK3Deployment.md Known limitations — starts in the correct scheme. Live changes continue to come from Qt. Recorded on 2026-09-24; the maintainer chose to ship 3.0 with the known limitation rather than add a dependency.[Backlog]
THM-F14The Statistics page chart follows the desktop's light/dark mode: its plot area, axes, grid, labels and legend use Qt Charts' dark theme when the desktop is dark and its light theme otherwise, and follow a live scheme change without a restart, as THM-F6 and THM-F11 do. Reported 2026-09-27: the chart set no theme, so it stayed on Qt Charts' default light theme — a white plot inside an otherwise dark window, against THM-O2. This is a deliberate divergence from K2, whose chart is always light (no theme is ever set in qt_widgets); K2 is not changed (THM-C5, THM-C17).[Planned]
THM-F15The file-type icon on each Search results row is drawn at the size set by THM-F7: the medium token when the option is set, the small-medium token when it is not — as K2's Search_treeView_FilesFound does. With the option off the icon becomes larger than it was — small-medium (22) where it was small (16): that growth is part of the user's request of 2026-09-30, as it was for SEL-F7. In folders-only results the icon is drawn in the Directory column (SRS-F2, SpecSearchResults.md; clarified 2026-10-03).[Planned]
THM-F17Under theme id 1, section titles — the titles of PGL-F8 (SpecPageLayout.md), including the Search section checkbox titles — and the Settings announcements hyperlink are drawn in blue darkest #095676 on a light desktop and blue light #39b2e5 on a dark one. They read one application-level colour (working name titleColor), which under theme id 0 is Kirigami.Theme.linkColor (unchanged) and under theme id 2 is Kirigami.Theme.textColor; under theme id 2 titles stay distinguished by the line after the text (PGL-F5) and by the title row spanning the form width; on forms still on the two-column grid, also from field labels by those labels' 0.7 opacity. (Added 2026-09-30, maintainer-approved; see Context. Amended 2026-09-30: theme id 2 branch added, was linkColor. Amended 2026-10-11: forms on Kirigami.FormLayout, SpecPageLayout.md PGL-F15, have no 0.7 label opacity.)[Planned]
THM-F18Under theme id 1, the selection highlight (selectionHighlightColor: the selected Selection card, the selected rows of the Search results and Explore lists, the device pickers) is blue dark #0D79A6 on light and dark desktops. Text on it stays Kirigami.Theme.highlightedTextColor. Under theme id 2 it is a grey: Qt.lighter(Kirigami.Theme.textColor, 3.0) on a light desktop (about #6a7276 on Breeze) and Qt.lighter(Kirigami.Theme.backgroundColor, 1.9) on a dark one (about #50585f on Breeze Dark), light/dark by isDarkDesktop(); text on it stays highlightedTextColor. Theme id 0 unchanged. (Added 2026-09-30. Amended 2026-09-30: theme id 2 branch added, was the accent highlight. Amended 2026-10-01, approved by the maintainer ("the color for selection ... in desktop theme gray is too dark", option "1"): theme id 2 light factor raised from 2.0 (about #464c4e) to 3.0 — ×2.0 was too dark, and ×3.0 is about the lightest that keeps the white highlighted text at ≥ 4.5:1 contrast (about 4.9:1). Dark desktop unchanged.)[Planned]
THM-F19Under theme id 1, the Selection page surface (selectionPageColor) is blue lightest #e9f7fc on a light desktop and blue darkest #095676 on a dark one. Themes 0 and 2 unchanged. (Added 2026-09-30.)[Planned]
THM-F20Under theme id 1, the drawer collection-name band (logoBandColor) is blue dark #0D79A6 on a light desktop and Qt.darker(#095676, 1.6) on a dark one, so the band stays at least as dark as a selected card (THM-F18). Under theme id 2 it is the selection highlight of THM-F18 (selectionHighlightColor) on a light desktop, and the plain Kirigami.Theme.backgroundColor on a dark one. Theme id 0 unchanged. (Added 2026-09-30. Amended 2026-10-01, approved by the maintainer ("put that same color for the background of the collection name in the drawer"): theme id 2 light desktop was Qt.darker(Kirigami.Theme.backgroundColor, 1.18); dark desktop unchanged.)[Planned]
THM-F21Under theme id 1, the Selection reminder hover tint of THM-F10 is blue light #39b2e5 at 20 % alpha; idle stays transparent. Under theme id 2 it is Kirigami.Theme.textColor at 8 % alpha. Under theme id 0 it stays Kirigami.Theme.hoverColor. (Added 2026-09-30; amends THM-C13. Amended 2026-09-30: theme id 2 branch added, was hoverColor.)[Planned]
THM-F22The list background — the empty area below the last row — of the Search results file list, the Explore file list and the Explore folder list depends on Settings/Theme: under theme id 1, Katalog Colors it is the odd-row stripe colour of THM-F4 (rowStripeColor: #e9f7fc light / #161b1d dark); under theme ids 0, Desktop Theme, and 2, Desktop Theme (gray) it is the even-row View colour of THM-F1 (rowBaseColor; #fcfcfc light / #1b1e20 dark on Breeze). It follows a Theme or desktop-scheme change without restart, as the rows do (THM-F4, THM-F6). (Added 2026-10-01, approved by the maintainer: "I want that for the Katalog Colors theme actually. for the 2 desktop themes, put the non-alternate so whitish row color (in light mode)", then "ok".)[Planned]
THM-F16The row icons of the Explore folder tree and of the Explore file list are drawn at the size set by THM-F7, with the same two-state rule — as K2's Explore_treeview_Directories and Explore_treeView_FileList do. The same off-state growth from small (16) to small-medium (22) applies and is part of the user's request of 2026-09-30.[Planned]

Constructional requirements — how it is built / limits / MUST-NOTs​

Boundaries and implementation constraints, not user-visible behaviour.

IDRequirementStatus
THM-C1Both colours of the THM-F1 pair are defined once, in Main.qml at applicationWindow() scope, and consumed from there by the three list delegates — Search results, Explore files and Explore folders (THM-C11). A page or delegate MUST NOT hardcode, re-derive or locally redefine either colour — including the odd-row stripe of THM-F4 (rowStripeColor), which is theme-dependent but still defined once (THM-C19). One definition, three consumers. (Amended 2026-09-30: the second colour was the Window colour. Amended 2026-10-01: "two consumers" became three, aligning with THM-C11 / THM-F8.)[Planned]
THM-C2Katalog Colors (theme id 1) applies K2's brand palette in K3 to exactly these: the file-list odd-row stripe (THM-F4), section titles (THM-F17), the selection highlight (THM-F18), the Selection page surface (THM-F19), the drawer logo band (THM-F20), the Selection reminder hover (THM-F21) and the list background below the last row (THM-F22, which takes the THM-F4 stripe). It MUST NOT apply a brand override anywhere else — in particular not to the even-row (View) colour, text colours other than THM-F17, or the items of THM-C21. For everything else, theme id 1 renders exactly as theme id 0 — the accent-derived variant — and not as theme id 2. (Amended 2026-09-30, twice: first the stripe alone was added; then, at the maintainer's request to "finish" Katalog Colors, THM-F17 to THM-F21. Amended 2026-10-01: THM-F22 added, maintainer-approved.)[Planned]
THM-C3The stored value Settings/Theme = 1 and the Katalog Colors entry in the Settings combo are preserved. No user-visible string is added, changed or removed by this spec, and no translation slot is spent. In K3 the entry's visual effect is the brand palette of THM-C2 (THM-F4, THM-F17 to THM-F22). (Amended 2026-09-30, twice: previously "the entry simply has no visual effect in K3", then "only the THM-F4 stripe".) Removing it is out of scope (see Scope).[Planned]
THM-C4Theme id 2, Desktop Theme (gray), keeps its existing distinct derivation from the desktop background (no hue) for the Selection page surface, and for the logo band on a dark desktop. On a light desktop the logo band is the theme id 2 selection grey of THM-F18, derived from Kirigami.Theme.textColor — still no hue, no hex literal (THM-F20, THM-C22). (Amended 2026-09-30: was "Unchanged by this spec"; theme id 2 now also has its own greys for titles, highlight and reminder hover, THM-F17, THM-F18, THM-F21, THM-C22. Amended 2026-10-01: light-desktop logo band now the selection grey, was Qt.darker(backgroundColor, 1.18); maintainer-approved.)[Implemented]
THM-C5K2 (qt_widgets) MUST NOT be modified by this work. It shares the Settings/Theme key and keeps its own Katalog Colors rendering; the divergence between K2 and K3 on theme id 1 — K3 ports K2's palette onto the K3 surfaces named in THM-C2, not K2's per-widget stylesheet (header, tab, button and text colours) — is accepted and deliberate. (Amended 2026-09-30, twice.)[Planned]
THM-C6The View colour set MUST be entered in a scope narrow enough that it does not leak onto surrounding items — inherit: false on the item that reads it, so sibling and parent surfaces keep the Window colour set.[Planned]
THM-C7The item that reads the View colour set MUST NOT be hidden (visible: false). A hidden item is given no resolved palette by the KDE platform theme and its background colour reads back as opaque black, which paints the first row of every file list black on a light desktop. This failure does not reproduce under QT_QPA_PLATFORM=offscreen, where a hidden item still returns the correct colour, so it cannot be caught by an offscreen run — it must be checked against the real desktop.[Planned]
THM-C8THM-F7 is stored in the existing key Settings/ThemeBiggerIconSize, the one K2 already writes (qt_widgets/mainwindow_tab_settings.cpp:624-645, restored at qt_widgets/mainwindow_setup.cpp:384), so both versions share one preference. K2 stores the Qt check state (2 / 0) and reads it with toBool(), so a K3 boolean round-trips through it; K3 MUST NOT introduce a second key, nor change the value encoding.[Planned]
THM-C9THM-F7 reuses K2's existing label Use bigger icon size byte-for-byte — approved per string by the user on 2026-09-12 — so the 30 existing translations carry it and no slot is spent. No other new string is authorised by these rows. K2 MUST NOT be modified, per THM-C5.[Planned]
THM-C10THM-F7 is consumed by the Devices page cards (DVP-F20, SpecDevicesPage.md), the Selection page cards (SEL-F7, SpecSelection.md), the Devices page table rows (DVP-F31, SpecDevicesPage.md), the Search results rows (THM-F15) and the Explore folder tree and file list rows (THM-F16) — and by nothing else. (Amended 2026-09-12: the Selection page was added at the user's explicit request, which is the "separate request" this row originally reserved. Amended 2026-09-30: the user asked for the setting to "apply to all pages (devices, search, explore) & drawer, like in K2" and approved the Devices table, Search results and Explore consumers; the drawer was held back pending an impact report. Each widening was asked for, not assumed.) K2 applies its equivalent to all eight of its tree views; K3 MUST NOT be widened beyond the views named here, and in particular not to every icon in the application as a side effect. Each further view — the global drawer, the Create page, the Tags page, a Selection folder tree — remains a separate request.[Planned]
THM-C11The Explore folder delegate consumes the colours defined once in Main.qml — the two row colours and the selection highlight — and MUST NOT derive, hardcode or locally redefine any of them, exactly as THM-C1 requires of the file-list delegates. THM-C1's wording "one definition, two consumers" becomes three consumers; the definition stays single. The selected row keeps the highlight of THM-F5, and the highlighted text colour it already sets is unchanged — only the surface beneath it is now painted.[Planned]
THM-C12A code comment is not a requirement. Main.qml already claimed these colours were consumed by "explore files and folders" while the folder delegate consumed neither. The comment was ahead of both the code and the spec; it described an intention, and the requirement is THM-F8, not the comment. Correcting the comment is part of this work; it MUST NOT be cited as authorisation for anything.[Planned]
THM-C13THM-F10 is one QML element: the background of the Controls.ItemDelegate in the pageSelection header (qt_quick/Main.qml). It MUST NOT change the reminder's content, its SEL-F6 scroll behaviour or SEL-C7's prohibition on changing or clearing the selection; MUST NOT touch the shared DeviceIdentity component (SEL-C1); adds, changes and removes no user-visible string; and changes nothing under core/. background: null was considered and rejected — approved per option by the maintainer on 2026-09-21 in favour of the hover tint: null removes hover feedback from a row that is clickable, and CDT-F3 (SpecCardsAndTables.md) already decided that such feedback is what tells the user a target is clickable. The idle state MUST be fully transparent and the hover tint MUST come from Kirigami.Theme — no literal colour constant, per this page's Context. As built: the delegate (id: selectionReminder, added so the binding can reference it) reads Kirigami.Theme.hoverColor inline, with "transparent" as the idle value. The tint is deliberately not lifted to an applicationWindow()-level property: it has exactly one consumer, and THM-C1's single-definition rule covers the two row colours and the highlight, not this. Whoever takes on the parked sweep of the other seven delegates may lift it then; nothing here promises it. "transparent" is the absence of a surface, not a colour constant, and MUST NOT be reported as a breach of the no-literals rule. (Amended 2026-09-30: under theme id 1 the hover tint is the brand colour of THM-F21, taken from the palette of THM-C20; under theme id 2 it is the grey of THM-F21 (Kirigami.Theme.textColor at 8 % alpha); under theme id 0 it stays Kirigami.Theme.hoverColor. These amendments are [Planned]; the rest of the row stands as built.)[Implemented]
THM-C14Painting K3's own surfaces so they look the same under any Controls style is not the work DPL-C4 withholds. DPL-C4 (SpecK3Deployment.md) withholds bundling qqc2-desktop-style, frameworkintegration or Breeze icon files into a package; it does not reserve K3's own QML. THM-F9 and THM-F10 take the opposite approach — make the application independent of the style it is given — so they need no amendment to SpecK3Deployment.md, and packaged builds continue to resolve to Fusion. That page's Known limitations are the cause of the THM-F10 report and MUST NOT be cited as its authorisation: SpecK3Deployment.md authorises no qt_quick source change, and the authority for THM-F10 is this page.[Implemented]
THM-C153.1 candidate, with THM-F12. The choice is stored in a new key (working name Settings/ColorScheme) in the same settings file. An absent key means System, so existing 3.0 beta settings files keep working unchanged and need no migration; K2 does not read the key and MUST NOT be changed for it (THM-C5). The effective scheme is provided by Katalog and read by Theme.qml and by the fallback icon selection instead of Qt.styleHints.colorScheme directly; implementing this therefore amends DPL-C6 and THM-F11, which today read Qt's value.[Backlog]
THM-C163.1 candidate, with THM-F13. THM-F13 requires linking Qt6::DBus, on Linux only. That is a new Qt module in CMakeLists.txt and a new library in every Linux package; per the project rule on new libraries it needs the maintainer's explicit approval at implementation time, and recording THM-F13 here does not give it.[Backlog]
THM-C17THM-F14 is built as a binding of ChartView.theme to ChartView.ChartThemeDark / ChartView.ChartThemeLight, whose dark/light test is the existing isDarkDesktop() in Main.qml, called inside the binding as the other derived colours do — it MUST NOT be a second, locally re-derived test. A theme switch resets series colours, so the three series MUST show their K2-matching colours #209fdf, #f6a625, #99ca53 again after every switch; these are series colours, not surface colours, an accepted exception to this page's no-literal-colour rule, and MUST NOT be reported as a breach of it. The chart's surface colours come from Qt Charts' built-in theme, not from Kirigami.Theme — a second accepted exception to this page's Context, limited to this chart. The zoom rubber-band rectangle is unchanged. The text-size binding of TYP-F7 MUST still hold after a switch. Adds, changes and removes no user-visible string; changes nothing under core/; persists nothing new, so existing prerelease settings files are unaffected. K2 MUST NOT be modified (THM-C5).[Planned]
THM-C18For every consumer listed in THM-C10, only the row or item icon follows THM-F7. A row's height MAY grow to fit the larger icon; its text size stays governed by TYP-F2 and MUST NOT change with this setting. The following MUST NOT change: the tree disclosure chevrons (CDT-F3, SpecCardsAndTables.md), the expand / collapse buttons, toolbar, button and combo icons, the boolean tick icons (DVP-F5), the Explore header controls (EXP-F9), and the Create and Tags pages. No user-visible string is added (THM-C9); core/ and K2 are not modified (THM-C5).[Planned]
THM-C19The THM-F4 stripe is built as one theme-dependent property, rowStripeColor, defined once in Main.qml and consumed by the file-list and folder-list delegates (THM-C1, THM-C11 — the single definition stands). Theme id 0 uses Qt.tint(viewBackground, accent at alpha 0.11); theme id 2 uses Kirigami.Theme.backgroundColor; theme id 1 chooses between #e9f7fc and #161b1d with the existing isDarkDesktop() (Kirigami background hslLightness < 0.5, the same test as K2's window lightness() < 128, qt_widgets/mainwindow.cpp) — MUST NOT be a second, locally re-derived test. Those two hex values are K2's brand palette, an accepted exception to this page's no-literal-colour rule limited to theme id 1's stripe, and MUST NOT be reported as a breach of it. The text colour is not changed: rows keep Kirigami.Theme.textColor under every Theme value; K2's #333 comes from its Katalog Colors light stylesheet and is deliberately not ported. The stripe reads the existing Settings/Theme key — no new key, no change of encoding, so existing prerelease settings files need nothing. Adds, changes and removes no user-visible string; changes nothing under core/; K2 MUST NOT be modified (THM-C5). (Added 2026-09-30, maintainer-approved with THM-F4. Extended 2026-09-30: the hex exception now covers the whole palette of THM-C20, under theme id 1 only.)[Planned]
THM-C20K2's Katalog Colors palette is defined once, in Main.qml, copied from K2 (qt_widgets/styles/tabwidget_blue_light.css, tabwidget_blue_dark.css, and loadCustomThemeLight / loadCustomThemeDark in qt_widgets/mainwindow_setup.cpp): blue light #39b2e5, blue #10a2df, blue dark #0D79A6, blue darkest #095676, blue lightest #e9f7fc, alternate dark #161b1d. The theme-id-1 colours of THM-F4 and THM-F17 to THM-F21 are built from these constants and MUST NOT repeat a hex literal elsewhere; they remain the application-level properties already defined once (rowStripeColor, selectionHighlightColor, selectionPageColor, logoBandColor) plus the one new titleColor, consumed, not redefined, by pages and delegates (THM-C1, THM-C11). Light/dark is chosen by the existing isDarkDesktop(), never a second test. These hex values are an accepted exception to the no-literal-colour rule, limited to theme id 1. Reads the existing Settings/Theme key only: no new key, no change of encoding, so beta settings files need nothing. Adds, changes and removes no user-visible string; changes nothing under core/; K2 MUST NOT be modified (THM-C5). (Added 2026-09-30.)[Planned]
THM-C22Theme id 2's colours of THM-F17, THM-F18 and THM-F21 are derived from Kirigami.Theme (textColor, backgroundColor) with Qt.lighter / alpha, carry no hue of their own, and MUST NOT use a hex literal — the palette exception of THM-C19 / THM-C20 stays theme id 1 only. They are branches of the same single application-level properties (titleColor, selectionHighlightColor, the reminder hover), not new definitions; light/dark by the existing isDarkDesktop(). THM-C21 applies unchanged. No new key, no string change, no core/ or K2 change. (Added 2026-09-30.)[Planned]
THM-C23The THM-F22 list background is one application-level property, listBackgroundColor, defined once in Main.qml from the existing rowStripeColor and rowBaseColor (no new derivation, no new hex literal), and consumed by the three list pages (Search results, Explore files, Explore folders). A page MUST NOT hardcode, re-derive or locally redefine it — the same one-definition rule as THM-C1 / THM-C11. Reads the existing Settings/Theme key only; no new key, no string change, no core/ or K2 change. (Added 2026-10-01 with THM-F22.)[Planned]
THM-C21Under every Theme value, these keep the desktop's colours and MUST NOT take a brand colour: checkboxes, radio buttons, focus rings, progress bars, scrollbars and other non-text controls (accepted by the maintainer "for now", 2026-09-30); semantic status colours (Backup positive / neutral text, Settings negative / error text); and the Statistics chart series (THM-C17). (Added 2026-09-30.)[Planned]

Open, not authorised​

ItemDetail
Other lists that inherit the platform styleThe same pattern — a bare Controls.ItemDelegate painting no surface of its own — exists in seven other places: the device tree combo box's popup rows (DeviceTreeComboBox.qml); the search history list rows and the file-type combo popup rows (PageSearchForm.qml, two places); the file-type combo popup rows of the Create form (PageCreateForm.qml) and of the device editor (PageDeviceEditForm.qml); the batch-action combo popup rows (PageSearchResultsForm.qml); and the language combo popup rows (PageSettings.qml). Each will show the same difference between Linux and Windows, and between a local and a packaged build. Only what the user reports is ever authorised: so far the Explore folder list (THM-F8, THM-F9, reported 2026-09-12) and the Selection reminder row (THM-F10, reported 2026-09-21 — it has left this list). A sweep across the seven that remain is a separate request and MUST NOT be carried in behind either fix. (Line numbers were dropped on 2026-09-21: every number first recorded here had drifted — Main.qml:1304, the reminder row, had become Main.qml:1399 — and a stale line number is worse than none, so the elements are identified by file and role instead.)
THM-F12 stringsOnly "System" exists today (the K3 first-run dialog). "Light", "Dark" and a label for the setting would be new user-visible strings, each needing per-string approval and a translation slot in all 30 languages. Not decided.
THM-F12 on Plasma source buildsSource builds on Plasma use org.kde.desktop and KColorScheme, not the bundled Theme.qml. Forcing Light or Dark there needs KColorSchemeManager (the KF6 KColorScheme component, a new dependency needing approval), or the override is limited to packaged builds. Not decided.
THM-F12 is new, not a portageNo K2 equivalent exists; the project rule is that new UI features come after K2 parity. Taking it on in 3.1 is the maintainer's explicit decision to make.

Manual test charter​

For each row: set up the stated condition, look at the result.

  • THM-F1 / THM-F2 (light desktop) — On a light Breeze scheme, with Desktop Theme (gray), open the Search results list. Row 0 is the near-white View colour; row 1 is the THM-F4 stripe for theme id 2, the slightly darker Window colour; the alternation continues. Row 0 is not pure #ffffff. Under every other Theme value row 0 is the same View colour and row 1 is that theme's THM-F4 stripe (theme id 0: accent tint; theme id 1: #e9f7fc).
  • THM-F1 / THM-F2 (dark desktop) — Switch to Breeze Dark, same Theme (Desktop Theme (gray)). Row 0 is the near-black View colour; row 1 is the THM-F4 stripe for theme id 2, the lighter Window colour. Row 0 is not pure #000000. Under every other Theme value row 1 is that theme's dark THM-F4 stripe (theme id 0: accent tint; theme id 1: #161b1d).
  • THM-F1 (non-Breeze scheme) — Apply a Plasma colour scheme whose View colour is not near-white (a tinted or sepia scheme). Row 0 takes that scheme's View colour, not white/black; under Desktop Theme (gray) row 1 takes its Window colour.
  • THM-F3 — Repeat the light and dark checks on the Explore file list. The two lists look identical row for row.
  • THM-F4 (theme id 0, light and dark) — Settings → Theme → Desktop Theme. On light Breeze, odd rows are a pale blue close to #e9f7fc (accent #3daee9 at 11 % over the View colour); on Breeze Dark, a dark blue-tinted row, still distinguishable from row 0. Change the desktop accent colour: the stripe follows without a restart. (Tested by the maintainer 2026-09-30.)
  • THM-F4 (theme id 1, light and dark) — Switch to Katalog Colors. On a light desktop odd rows are exactly #e9f7fc; on a dark desktop exactly #161b1d. The logo band, Selection page surface, selection highlight, section titles and reminder hover take the brand colours of THM-F17 to THM-F21 (THM-C2). Row text stays the desktop text colour, not #333 (THM-C19).
  • THM-F4 (theme id 2, light and dark) — Switch to Desktop Theme (gray). Odd rows are the Window background (#eff0f1 / #2a2e32 on Breeze), as before 2026-09-30; the logo band and Selection page surface show the grey derivation, still distinct from theme 0 (THM-C4).
  • THM-F4 (live) — With the Search results list open, switch between the three Theme values: the stripe repaints each time without a restart; even rows and the selected row do not change.
  • THM-C19 — Grep: rowStripeColor is defined once in Main.qml and the three delegates consume it; the only hex literals are the palette constants of THM-C20, defined once in Main.qml; the dark/light choice calls isDarkDesktop(). Run ninja translations_lupdate: no new string. Diff touches no core/ or qt_widgets/ file and writes no new settings key.
  • THM-F17 to THM-F21 (theme id 1, light and dark) — Select Katalog Colors. On a light desktop: section titles on Settings, Search (including the section checkboxes), Create, Tags, Device Edit and the Backup link form, and the Settings announcements link, are #095676; a selected Selection card and selected Search results / Explore rows, and the device pickers' selection, are #0D79A6 with legible highlighted text; the Selection page surface is #e9f7fc; the drawer collection-name band is #0D79A6; hovering the Selection reminder shows #39b2e5 at 20 %. On a dark desktop: titles #39b2e5, highlight #0D79A6, Selection surface #095676, band Qt.darker(#095676, 1.6), which is no lighter than a selected card. Switch to Desktop Theme: all of these return to their previous colours (titles in the desktop link colour). Switching repaints without a restart.
  • THM-F17 / F18 / F21 / THM-C22 (theme id 2, light and dark) — Select Desktop Theme (gray). Section titles and the Settings announcements link are the normal text colour, still set apart by their line and their full-width title row, and, on forms still on the two-column grid, by the dimmed field labels. A selected Selection card, selected Search results / Explore rows and the device pickers' selection are a neutral grey (about #6a7276 on Breeze, #50585f on Breeze Dark) with legible highlighted (white) text, at least 4.5:1 contrast on light. On a light desktop the drawer collection-name band is the same grey as a selected row (THM-F20); on a dark desktop it is the plain window background. Hovering the Selection reminder shows a faint grey tint. No blue remains on these, the Selection page surface, the logo band or the stripe; non-text controls keep the desktop accent (THM-C21). Grep: no hex literal in the theme id 2 branches.
  • THM-C20 / THM-C21 — Grep: the six palette hex values appear once, in Main.qml; titleColor is defined once and the title labels consume it; the dark/light choice calls isDarkDesktop(). Under Katalog Colors, checkboxes, radio buttons, focus rings, progress bars and scrollbars keep the desktop colours; Backup positive / neutral labels, Settings error text and the Statistics series are unchanged. ninja translations_lupdate: no new string. Diff touches no core/ or qt_widgets/ file and writes no new settings key.
  • THM-F22 / THM-C23 — With a short Search results list (fewer rows than the view height), and the same on the Explore file and folder lists: under Katalog Colors the empty area below the last row is the stripe colour (#e9f7fc light / #161b1d dark); under Desktop Theme and Desktop Theme (gray) it is the even-row View colour (#fcfcfc / #1b1e20 on Breeze). Switching Theme repaints it without a restart. Grep: listBackgroundColor defined once in Main.qml, consumed by the three pages, no local colour.
  • THM-C3 — After the above, reopen Settings: the Katalog Colors entry is still listed and still selectable, and the stored Settings/Theme value survives a restart.
  • THM-F6 (live scheme switch) — With Katalog open on the Search results list, change the Plasma colour scheme from light to dark in System Settings. The list repaints to the new scheme without restarting Katalog; both row colours follow, and the selected row's highlight follows too.
  • THM-C1 — Compare a Search results row and an Explore row of the same parity under the same scheme: they are the same colour. Grep confirms neither page defines a row colour of its own.
  • THM-C5 — Open K2 and select Katalog Colors. K2 still renders its own brand palette and is unmodified; K3 matches it on the row stripe only, and differs elsewhere by design.
  • THM-F7 / THM-C8 (shared key) — Tick Use bigger icon size in K3, then open K2: its own checkbox is ticked and its tree icons are the larger size. Untick it in K2 and reopen K3: K3 draws the smaller icons. Confirm only Settings/ThemeBiggerIconSize is written, with no second key.
  • THM-F7 (sizes) — With the option off, a Devices card icon and a Selection card icon both match the small-medium token; with it on, both match the medium token. The change takes effect without restarting.
  • THM-C9 — Run ninja translations_lupdate: no new untranslated string appears. With the interface in French, the Settings label is translated, proving the K2 string was reused verbatim.
  • THM-C10 / THM-C18 — With the option on, confirm these follow it: the Devices cards, the Selection cards, the Devices table rows, the Search results rows, and the Explore folder tree and file list rows. Confirm these do not: the drawer, the disclosure chevrons, the toolbar and button icons, the tick icons, the Explore header controls, and the Create and Tags pages. Toggling the option does not change the text size.
  • THM-F15 / THM-F16 — Toggle Use bigger icon size: the Search results icons and the Explore folder tree and file list icons switch between the small-medium and the medium token without a restart. At both sizes the rows stay legible and no icon is clipped.
  • THM-F8 — On the Explore page, compare the folder list with the file list beside it: the same two row colours in the same parity, the first row of each taking the View colour. Confirm a selected folder row takes the selection highlight and that its text stays legible on it.
  • THM-F9 (Fusion) — Run the application with the Fusion style forced (QT_QUICK_CONTROLS_STYLE=Fusion) and compare the Explore page with the same page under org.kde.desktop: the folder rows and the file rows are the same colours in both, because the application paints them. This is the Linux stand-in for the Windows report and MUST be run before the fix is called done.
  • THM-F9 / THM-F6 — With the folder list open, change the desktop colour scheme from light to dark: the folder rows follow the new scheme without a restart, as the file rows do.
  • THM-C11 — Grep the folder delegate: it references the application-level colour properties and defines no colour of its own.
  • THM-F10 (Fusion) — Run the application with the Fusion style forced (QT_QUICK_CONTROLS_STYLE=Fusion) and compare the Selection page with the same page under org.kde.desktop: in both, the reminder row at the top shows the tinted Selection page surface, with no white band and no surface of its own while the pointer is elsewhere. Open: not yet run. The QML was applied on 2026-09-21 without launching the application.
  • THM-F10 (hover) — Move the pointer over the reminder row under each style: the same light tint appears in both, and it disappears when the pointer leaves. Compare it with a Selection card, which keeps its own card surface either way. Open: not yet run.
  • THM-F10 (packaged build) — Repeat the first two checks against the AppImage on a non-Plasma desktop, the case that was reported. This is the check that closes the row; until it is confirmed there, THM-F10 stays [Planned]. Open: the QML is in as of 2026-09-21 and builds, but no visual check has been made on any style — this is the only thing between THM-F10 and [Implemented].
  • THM-C13 — Click the reminder row: the list still scrolls to the selected card and the selection is unchanged (SEL-F6, SEL-C7). Run ninja translations_lupdate: no new untranslated string appears. Review the diff: one background in qt_quick/Main.qml, nothing under core/, and no change to DeviceIdentity.qml. Verified 2026-09-21 by diff review: one file changed, no core/ file, no DeviceIdentity.qml, no tr( or qsTr( added, changed or removed; Katalog3_qmllint reports nothing on the inserted lines and the build links. The click behaviour was not re-run — the change adds a background and an id and touches no handler.
  • THM-C14 — Review the same diff against SpecK3Deployment.md: no Breeze icon file is copied into the AppDir and neither qqc2-desktop-style nor frameworkintegration has been added to the bundle, so DPL-C4 still holds. The packaged build still resolves to Fusion — and now looks the same as the local build on this row anyway. Verified 2026-09-21: the diff is one qt_quick file and touches no part of the bundle.
  • THM-O2 — Run the three DPL-F5 checks in SpecK3Deployment.md. On each OS, set the system to dark: the Search results and Explore lists show the dark row pair for the stored Theme value (THM-F1, THM-F4), and the surrounding controls are dark too. Nothing in the window stays light.
  • THM-F11 — On each of: the packaged Linux build on a non-Plasma desktop, the Windows and macOS portable builds, and a Plasma source build — start Katalog in dark mode: icons drawn from the fallback set are the dark variants (light glyphs on the dark surface). Start in light mode: the light variants. With Katalog open, switch the system between light and dark: the icons already on screen change set without a restart. On the Plasma source build, confirm nothing changes against today's behaviour in either mode.
  • THM-F12 / THM-C15 (Backlog, 3.1) — With no Settings/ColorScheme key in an existing beta settings file, start Katalog: it behaves as System. Choose Light, then Dark, then System on a dark desktop: colours, controls and fallback icons switch each time without a restart. Open K2 on the same settings file: nothing changes.
  • THM-F13 / THM-C16 (Backlog, 3.1) — On the Linux Mint / Cinnamon tester VM, start the AppImage with the desktop dark: it opens dark. Confirm Qt6::DBus is linked on Linux only and that the maintainer approved it.
  • THM-F14 / THM-C17 — With the Statistics page open and data loaded, switch the desktop between light and dark: without a restart, the plot, axes, grid, labels and legend follow the new mode, and the three series keep #209fdf, #f6a625 and #99ca53. Check the axis and legend text size still matches the text-size setting after each switch (TYP-F7). Repeat with the packaged (Fusion) build on a dark desktop: no white plot. Open K2's Statistics tab: unchanged, still light.