Notes on aesthetics

[Kommynct]

• Bold chatroom name
  • The names of the chat rooms should be bolded for prominence. They currently look just like the message text.
• Avoid including labels to the top bar
  • The icons on the bar at the top combined with the labels are a bit visually clunky. It might be better not to include the labels, or to move these into a ... menu.
• Reduce border usage
  • There are way too many borders. Most apps with modern design now use different shades to distinguish rather than borders.
• Line break in tooltip on "read"
  • The tooltip on "read" has the d on a newline.
• Make default icon theme configurable
  • The default icon theme is a bit weak. It'd be better if the system icon theme were an option or being able to set one in general.
• Make timestamp theme configurable
  • Timestamps should be their own thing to theme. Setting them to be "text" means that timestamps, the headers, and the unselected room names all have to be the same color. I don't think that's good, as I want timestamps to be dim and room headers to be bright. Currently this is not possible.
• Bold text with theme engine
  • An option to bold texts with the theme engine would be good.
• Monochrome tray icon
  • A monochrome tray icon would be nice.

Just generally there's too many things controlled by one thing in the theme file, as many things as possible should be individualized. The labels in the theme file are also extremely unclear and could benefit from layering (such as a sidebar.text sidebar.background messagearea.text).

This is such a good client, I think the only things left are these (and probably more that I can't think of) aesthetic concerns and element call, thanks for all the hard work, you've finally made matrix good on the desktop!

--

Edited to clarify each item's point, trying to make them more actionable.

[spantaleev]

Walking through each item.

Bold chatroom name

Already differentiated, just not via weight in the read state. The three elements in a row are styled like this:

Element	Font size	Color in light-komai	Color in dark-komai
Room name	uiFontSizePt (100%)	palette.text = #334258	palette.text = #f0f6fc
Last message preview	uiFontSizePt × 0.95	palette.buttonText = #555459	palette.buttonText = #a3acb8
Timestamp	uiFontSizePt × 0.95	palette.buttonText = #555459	palette.buttonText = #a3acb8

The room name is also bolded when the room has unread messages.

Honest assessment of the gap, given the actual values:

• Font size: 95% of 100% is a 5% delta. Real but subtle, almost imperceptible at typical UI sizes.
• Color: The relative luminance gap between text and buttonText is ~24% in light-komai and ~30% in dark-komai. Real but modest, especially in light themes where both values are dark-on-light and read as "dark text" at a glance.
• Weight: Identical for read rooms, divergent for unread.

So in light themes specifically, the differentiation is on the subtle side. I did experiment with bolding the room name unconditionally during this round of changes, and ran into two problems:

1. Read rooms looked too active, and the visual distance to the unread state shrank — bold-as-unread is doing real work alongside the count badge, not redundant signal.
2. To stay hierarchically consistent, the communities sidebar buttons (one level up from rooms) would arguably also need to become bold, which starts cascading.

Other directions exist that haven't been explored yet. Shrinking the preview's font further or pushing it dimmer to widen the visual gap from the room name would need careful contrast-ratio checks (Komai aims for WCAG AA across all builtin themes, and the last-message preview is genuinely important information — often the only signal of what a conversation is currently about). Dimming palette.buttonText directly isn't the right lever either, because it has other consumers (buttons, hence the name).

A plausible and not-too-difficult follow-up experiment: introduce a faded/lightened variant of palette.text and use that for the room list preview and the room list timestamps. They'd share a hue family with the room name but differ in lightness in a controlled way. Timestamps can probably fade further than the preview since they carry less information. Caveat: the timestamps inside timeline message bubbles should stay visually consistent with whichever color the room list timestamp ends up at, so any change there needs to be coordinated.

Holding off in this round but happy to revisit. If you're on a theme where the gap looks even smaller than the values above, sharing the theme name would help.

Avoid labels on the top bar

Shipped. New control: Settings → Timeline → Room header bar → Show button labels, with two choices: Adaptive (the current width-driven hysteresis, default) and Never (always hide). Commit: 9217671d2.

Reduce border usage

Komai borrows from systems where borders are part of the visual language (macOS, GNOME, KDE Breeze all use them deliberately). The flat / shade-only aesthetic is one valid design language but not the only one, and reworking ~200 border uses across the app while preserving accessibility in high-contrast palettes would be a substantial undertaking. Holding off unless this becomes a broader request, or you have specific recommendations or mockups. In any case, following "modernity" (like Element Web, etc.) at the expense of contrast is not what Komai aims for.

Typo in tooltip on "read"

Can't reproduce here (KDE Plasma 6 / Wayland), but the underlying cause looked real on inspection: the tooltip width formula was using the font's pen-advance metric, which is a hair narrower than the actual rendered text width on some fonts, so the wrapping engine occasionally clipped the last character to a new line. Landed two fixes in d011ede87 (the icon-button tooltips, where the Read indicator lives) and 5858b4683 (same fix propagated to the four other tooltip call sites that had the same pattern). Hopefully this resolves what you saw.

Make default icon theme strong / system icon theme

The icon set is Fluent UI System Icons (inherited from Nheko, which Komai forked from) plus Font Awesome for the gaps in Fluent. Fluent is a deliberately rich, stroke-consistent, free icon family. Letting the system icon theme override would mean either inconsistent icons (when the system theme lacks the specific icon used here) or maintaining a Fluent→freedesktop mapping that goes stale every release. Not pursuing.

Make timestamp theme configurable

Already the case, but it may not look that way in your current theme. Per the table above, timestamps use palette.buttonText (a distinct dimmer role) while room names use palette.text (bright). In any palette where buttonText is clearly dimmer than text (which is the standard convention), timestamps are already dim while room names are bright. If they look the same in your theme, that's the theme's color choices, not a Komai code issue.

Bold text with theme engine

Font weight is a typography decision, not a color one. Adding per-element weight toggles to the theme engine would explode the theme surface area and every QML row that consumes those weights, for little benefit. Not pursuing.

Monochrome tray icon

Shipped. New control: Settings → Desktop → System tray → Icon style, with three choices: Colorized (default), Monochrome (light) (light icon for dark panels), Monochrome (dark) (dark icon for light panels). Auto-detecting the panel theme isn't reliable enough across Linux desktops, so the variant is explicit. Commit: b588a9c04.

One caveat: the monochrome SVG is auto-derived from the current komai.svg, which itself is an AI-generated raster image traced into SVG, with no semantic structure. The auto-derivation gives a recognizable symbolic icon (eyes, nose, mouth, ears, face contour) but the line weights are uneven and on the thin side. Hand-redrawing the symbolic icon (and ideally the colorized one too) would improve things, but it isn't something easily automated.

---

Leaving the issue open in case you want to add anything.

[Kommynct]

The room name is also bolded when the room has unread messages.

I missed that, that's good enough

Honest assessment of the gap, given the actual values:

* **Font size**: 95% of 100% is a 5% delta. Real but subtle, almost imperceptible at typical UI sizes.

yeah this is probably slightly too little

Dimming palette.buttonText directly isn't the right lever either, because it has other consumers (buttons, hence the name).

This is precisely the issue, it should be a separate lever, there's a genuine reason here to control it separately.

Reduce border usage

Komai borrows from systems where borders are part of the visual language (macOS, GNOME, KDE Breeze all use them deliberately). The flat / shade-only aesthetic is one valid design language but not the only one, and reworking ~200 border uses across the app while preserving accessibility in high-contrast palettes would be a substantial undertaking. Holding off unless this becomes a broader request, or you have specific recommendations or mockups. In any case, following "modernity" (like Element Web, etc.) at the expense of contrast is not what Komai aims for.

I actually thought about this more since then, there's only one place where this is an issue for me, and that's around the currently highlighted room name and the border between that, the message box, and the psuedo-spaces section with the avatar, I think that border should match the highlight, since it's differentiated by the highlighting anyway, this would look a lot nicer to me. Perpaps removing the left and right borders from room names would look nicer?

Typo in tooltip on "read"

Can't reproduce here (KDE Plasma 6 / Wayland), but the underlying cause looked real on inspection: the tooltip width formula was using the font's pen-advance metric, which is a hair narrower than the actual rendered text width on some fonts, so the wrapping engine occasionally clipped the last character to a new line. Landed two fixes in d011ede87 (the icon-button tooltips, where the Read indicator lives) and 5858b4683 (same fix propagated to the four other tooltip call sites that had the same pattern). Hopefully this resolves what you saw.

yup resolved

Make default icon theme strong / system icon theme

The icon set is Fluent UI System Icons (inherited from Nheko, which Komai forked from) plus Font Awesome for the gaps in Fluent. Fluent is a deliberately rich, stroke-consistent, free icon family. Letting the system icon theme override would mean either inconsistent icons (when the system theme lacks the specific icon used here) or maintaining a Fluent→freedesktop mapping that goes stale every release. Not pursuing.

What about a few options for icon themes that are constrained, right now my primary issue with fluent is honestly just that it's line-art instead of solid, perhaps they have a solid variant?

Make timestamp theme configurable

Already the case, but it may not look that way in your current theme. Per the table above, timestamps use palette.buttonText (a distinct dimmer role) while room names use palette.text (bright). In any palette where buttonText is clearly dimmer than text (which is the standard convention), timestamps are already dim while room names are bright. If they look the same in your theme, that's the theme's color choices, not a Komai code issue.

this just appears to not be true, I made my own theme from scratch, editing palette.text edits the room name AND the timestamp color as well as the labels at the top of the chat, each of these should be controlled individually. I don't currently see a way to do that?

[spantaleev]

Two follow-ups from your last comment:

Timestamps and secondary text color. Decoupled both from palette.buttonText in 999f422. Last-message preview and timestamps in the room list (and the timestamp on the bubble metadata bar, for consistency) now derive their dim variant by blending palette.text toward the surrounding background rather than reusing palette.buttonText. That fixes the flattening you saw when a theme has text and buttonText set to the same value. Blend factors are tuned to stay at WCAG AA-normal for the preview and AA-large for the timestamp across the bundled themes.

Intentionally not introducing new theme keys/fields for this. The theme schema aims to stay lean, with keys that target multiple UI elements semantically rather than letting every element be themed individually. The latter is more flexible but also more complex, and adding keys breaks compatibility with existing themes. The derived approach above gives the same hierarchy decoupling without growing the schema.

Selected room blending / removing the side borders. Don't see a clean path. The "selected row visually continues across the column splitters" gesture only works cleanly when the sidebar borders one continuous content surface. The Komai room list column borders the chrome strip (room header + tab bar, both alternateBase) for its top portion and the timeline content (base) below, and the line between those shifts with topic length, tab bar visibility, banners. The blend target for a "selected row flows right" treatment would have to depend on the row's vertical position relative to chrome that itself moves around.

The simpler "drop the left and right column splitters entirely" path is what Element Web does, and the result isn't great: less border noise (which is considered "modern design"), but everything starts blending together. In fact, Element Web's lack of borders around the composer textarea is one of the long-standing annoyances I've had with their design. It's "too clean" - to the point of being not-too-usable. And even with that surface treatment, Element Web (and Slack) don't lean into the "selected room flows onto the timeline" metaphor either; both mark the selected room with a rounded-corner pill, no blending. Keeping the current darker-stripe selection visual.

[spantaleev]

On the icon variant: Fluent does ship both Regular and Filled variants of essentially every icon, so it's technically available. Choosing not to expose it as a setting though.

I don't think any app offers a "Regular vs Filled" toggle for its icons. A 2-option toggle seems like the worst-of-both-worlds shape: ongoing maintenance and a confusing settings surface for what's ultimately a personal aesthetic preference that the next user will still want to override differently.

Going with Regular by default, because outlines are enough and solid is.. too busy/heavy. Ultimately, it's a design choice and it's subjective.

[Kommynct]

https://cdr.lib.unc.edu/concern/masters_papers/6w924g35w

"An application was developed that allowed participants to take a test measuring their speed and accuracy in selecting prompted icons from an array of distractors. The test was made available on the web and was completed by 1,260 participants. Averaged across the 20 unique icon forms used in the test, the outline style led to slightly longer task times, but only when icons were displayed in white against a black background."

Since Fluent already ships parallel Filled variants, this is less about introducing a second icon ecosystem and more about exposing an alternate rendering style from the same design system.

There is at least some usability evidence in favor of filled icons. The above study with 1,260 participants found outline icons produced slower recognition times in some conditions, particularly high-contrast dark presentations, which is relevant since komai is commonly used in dark themes. More broadly, filled icons tend to produce stronger silhouettes at small sizes and better peripheral recognition because they carry more visual mass.

modern UI systems also frequently reserve filled icons for emphasis and active affordances precisely because they are visually stronger. telegram, apple, material, and many mobile UIs use this pattern extensively.

My argument is not necessarily that filled should replace regular globally, but that since fluent already provides both variants with matching geometry and naming, supporting filled would be unusually low-maintenance compared to supporting an entirely separate icon theme.

[luixxiul]

since komai is commonly used in dark themes

I'm not willing to nitpick here, but it's not really possible to say so as Komai does not have telemetry and therefore does not know about settings tendency among users— I'm a user of light themes (Cappuchin Latte) FYI.

There are many things to take into consideration, such as UI language, screen size, gender, age (because the condition of cognition and eyes are obviously different between young people and old people), race of users, etc. Honestly I think it is pretty difficult, if not outright impossible, to draw a rational and decisive conclusion on the topic from a single master thesis, though it can be one reference.

[spantaleev]

Thanks for linking to this article! I've skimmed some parts (sorry, not enough time in my day for complete thorough reading!) and think it's quite interesting.

What stood out:

• Across all 20 icon forms, style and color independently had no effect on accuracy or task time. The significant interaction was specifically outline icons rendered white-on-black, which were about 170ms slower than the other three style/color combinations. That polarity does map to dark-theme Komai. Light-theme Komai is the polarity the paper tested but did not find an effect in.
• Per-icon, the picture is mixed: 9 forms showed no style effect, 8 favored filled, 3 favored outline. Effect sizes were mostly small.
• The author's own conclusion is that filled is "not objectively better than the outline style, and that the form of an icon has a greater influence on its usability than do either style or color."

So there is something to the argument, particularly for dark themes. The strongest takeaway for me is that picking the right glyph matters more than style.

Reading your comment a second time, I am not sure which pattern you are actually proposing. Three readings are all consistent with it:

1. Flip every icon globally from Regular to Filled.
2. Use Filled only for selected/active state (a common pattern in design systems that ship parallel variants), keep Regular elsewhere.
3. Offer both as a user-chosen toggle.

Could you clarify which one? The cost and design tradeoff is quite different for each.

Some practical context on the "Fluent already ships both, so it is low maintenance" point, because the wiring is less loose than it sounds:

• A full clone of the Fluent assets/ directory is 200+MB. Mirroring everything is not on the table; most of it is per-size and per-format duplication of the same glyphs.
• Each icon Komai uses is fetched explicitly (just icons-fetch-fluent) and aliased into resources/res.qrc. There is no implicit "ask Fluent for home-filled" path. Switching style means fetching and wiring the counterpart for each icon in use.
• Naming parity in Fluent is real, so a one-time global flip is bounded but still a manual pass per icon. Komai's other icons mostly come from Font Awesome (same workflow, just icons-fetch-fontawesome), which also ships Regular and Solid variants for most glyphs, so that side of the catalog is covered too.

For option 2 specifically, the conditional would not be a user setting but state-driven at the call site (this item is selected, so render the filled variant). Lighter than option 3 in surface area, but not free: it still adds branching at every use site, doubles the assets vendored for those icons, and delivers a modest aesthetic improvement on top of the existing selection chrome rather than a clear usability win.

The aesthetic risk worth naming: filled icons can read as busier and visually heavier in a text-dense UI like Komai's, so any of options 1, 2, or 3 carries real churn and a potential regression for what looks like a marginal benefit, if any.

That said, a one-time all-solid switch (option 1) is something I may experiment with to see how it looks. Same for option 2. Let me know which you are pushing for and I will plan accordingly.

[Kommynct]

since komai is commonly used in dark themes

I'm not willing to nitpick here, but it's not really possible to say so as Komai does not have telemetry and therefore does not know about settings tendency among users— I'm a user of light themes (Cappuchin Latte) FYI.

There are many things to take into consideration, such as UI language, screen size, gender, age (because the condition of cognition and eyes are obviously different between young people and old people), race of users, etc. Honestly I think it is pretty difficult, if not outright impossible, to draw a rational and decisive conclusion on the topic from a single master thesis, though it can be one reference.

Most people use dark themes for messaging apps these days, commonly doesn't mean even the majority, but there is a very small but tangible benefit and no downside besides the cost of switching I think?

[Kommynct]

Thanks for linking to this article! I've skimmed some parts (sorry, not enough time in my day for complete thorough reading!) and think it's quite interesting.

What stood out:

* Across all 20 icon forms, style and color independently had no effect on accuracy or task time. The significant interaction was specifically outline icons rendered white-on-black, which were about 170ms slower than the other three style/color combinations. That polarity does map to dark-theme Komai. Light-theme Komai is the polarity the paper tested but did not find an effect in.

* Per-icon, the picture is mixed: 9 forms showed no style effect, 8 favored filled, 3 favored outline. Effect sizes were mostly small.

* The author's own conclusion is that filled is _"not objectively better than the outline style, and that the form of an icon has a greater influence on its usability than do either style or color."_

So there is something to the argument, particularly for dark themes. The strongest takeaway for me is that picking the right glyph matters more than style.

Reading your comment a second time, I am not sure which pattern you are actually proposing. Three readings are all consistent with it:

1. Flip every icon globally from Regular to Filled.

2. Use Filled only for selected/active state (a common pattern in design systems that ship parallel variants), keep Regular elsewhere.

3. Offer both as a user-chosen toggle.

Could you clarify which one? The cost and design tradeoff is quite different for each.

Some practical context on the "Fluent already ships both, so it is low maintenance" point, because the wiring is less loose than it sounds:

* A full clone of the Fluent `assets/` directory is 200+MB. Mirroring everything is not on the table; most of it is per-size and per-format duplication of the same glyphs.

* Each icon Komai uses is fetched explicitly (`just icons-fetch-fluent`) and aliased into `resources/res.qrc`. There is no implicit "ask Fluent for `home-filled`" path. Switching style means fetching and wiring the counterpart for each icon in use.

* Naming parity in Fluent is real, so a one-time global flip is bounded but still a manual pass per icon. Komai's other icons mostly come from Font Awesome (same workflow, `just icons-fetch-fontawesome`), which also ships Regular and Solid variants for most glyphs, so that side of the catalog is covered too.

For option 2 specifically, the conditional would not be a user setting but state-driven at the call site (this item is selected, so render the filled variant). Lighter than option 3 in surface area, but not free: it still adds branching at every use site, doubles the assets vendored for those icons, and delivers a modest aesthetic improvement on top of the existing selection chrome rather than a clear usability win.

The aesthetic risk worth naming: filled icons can read as busier and visually heavier in a text-dense UI like Komai's, so any of options 1, 2, or 3 carries real churn and a potential regression for what looks like a marginal benefit, if any.

That said, a one-time all-solid switch (option 1) is something I may experiment with to see how it looks. Same for option 2. Let me know which you are pushing for and I will plan accordingly.

Tbh I'm fine with either option, maybe we should have a poll in the komai chat?