Skip to content
GitLab
Closed
Issue created by Gustavo Barros@gusbrs

Some thoughts about org-agenda faces

Hi Prot,

as I promised, I have one more suggestion for modus, a tricky one at that, but which I regard as particularly interesting and worth your while.

The TL;DR is: I think modus-themes could benefit from employing a (deliberate) semantic color scheme for groups of faces in org-agenda. Indeed, the themes are already close to something of the sort, but are not quite there. I have come up with one such scheme tweaking few faces from the current set, and I think the agenda improved considerably in both aesthetics and readability.

Preliminary "meta" comment: I'm well aware that this is an opinionated suggestion, and also that this is an area which is specially complex to deal with, and sensitive to change. So, do feel absolutely free to take this into consideration as you see fit, and if you see fit.

This effort of mine to systematize the faces in org-agenda was actually triggered by a change in one face made in the 1.2.0 release, to the face org-scheduled which had been fg-special-warm until then, and was changed to magenta-alt, which bothered me. This change was made in response to #153 (closed) . And I do share the diagnosis of that report. But I think a more panoramic view of the agenda is probably a better answer to those issues.

Note that what follows does not try to encompass every possible face interaction in Org agenda, which would be insane, but a meaningful subset of it, comprising of tasks with timestamps (plain, schedule, deadline) and the structural elements which make the agenda agenda type (that is, daily/weekly agenda, rather than "todo list"). This is a very important agenda case, but this is just to say I'm not even trying to cover everything.

That said, straight ahead. The semantic color scheme I came up for this context is the following:

  • structural elements: green, blue (this comprises block and date headers, faces org-agenda-structure, org-agenda-date, org-agenda-date-weekend, org-agenda-date-today).

  • deadline tasks: red, magenta (faces org-upcoming-deadline, org-upcoming-distant-deadline, org-warning)

  • schedule tasks: brown, yellow (faces org-scheduled,org-scheduled-previously, org-scheduled-today)

  • plain timestamp tasks ("events", including calendar sexp ones): gray, black, white (faces org-agenda-calendar-event, org-agenda-calendar-sexp, org-agenda-diary)

  • done tasks: green (face org-agenda-done) (and in this case I don't fear much a clash with structural elements for two reasons: it is not too complicated to choose a distinctive green tone here and a common use case is to hide done tasks from the agenda and only bring them in log-mode).

I think that's pretty much it as far as "semantic color scheme" goes. I may have missed some faces there, but I hope this is enough to get the general idea.

And I'm suggesting some scheme of the sort. This particular scheme seems intuitive to me, and is close enough to what modus currently has to be considered a good starting point. But I hold no pretense of "prescription" there.

What I like in this particular scheme: it organizes the agenda in a meaningful way, similar things receive similar colors, proper contrast shows when it is needed, "done state" coloring is traditional, the "urgency scale" of tasks (plain, schedule, deadline) is conveyed in a "crescendo" (grey, yellow, red) which makes for "intuitiveness" there too. It fits well, and it looks good. I'm saying this from experience of using it for the last couple of months now.

That given, I've mentioned above modus-themes already mostly fits into the scheme, but what does not? And this is the actionable part of this report.

  1. "schedule tasks": mix of magenta and yellow (before v1.2.0, two yellow/brown, one magenta; after v1.2.0, two magenta, one yellow)

  2. "plain timestamp tasks": org-agenda-calendar-sexp is cyan

  3. "structural elements": org-agenda-date-today is black

Other things, within this overall scheme, which make for further improvements:

  1. #153 (closed) made the case for org-agenda-structure to stand out more, a need I agree with. But the solution given was conditioned on the use of modus-themes-scale-headings. Well, "headings" in the agenda are the "tasks" and the block header is something different. I believe some "toning up" of this face is granted regardless of the use of scaling for headings.

  2. org-agenda-calendar-event and org-agenda-diary currently receive fg-main which fits the "semantic scheme" fine, but makes these tasks stand out quite a lot (the highest contrast ratio possible, they do show). However, considering the relation of these tasks to scheduled and deadline tasks, dimming the "plain timestamp tasks" foreground just a little makes for a more balanced relation in the overall "scheme".

What I'm actually using for this purpose:

`(org-scheduled ((,class :foreground ,fg-special-warm)))
`(org-scheduled-today ((,class :inherit org-scheduled-previously)))
`(org-agenda-calendar-sexp ((,class :foreground ,fg-unfocused)))
`(org-agenda-calendar-event ((,class :foreground ,fg-inactive)))
`(org-agenda-structure ((,class :inherit 'variable-pitch :height 1.05
                                :bold t :foreground ,blue-alt)))

Some comments about these choices:

Note, as I said, just a few faces. But do try it out, the change is actually quite remarkable.

Of course, inheriting org-scheduled-previously in org-scheduled-today is very debatable. I don't feel the need to distinguish them, but the particular color choice is not the point, the "scheme" is.

I don't use either variable-pitch nor scale for headings in Org, but they do work well for org-agenda-structure (as a matter of fact, I don't use variable-pitch or scaling anywhere else). Again, I'm not arguing for this particular face value, but I think the case for more prominence to this face in the agenda is due regardless of the value of modus-themes-scale-headings. It should convey a hierarchical relation to the org-agenda-date... faces somehow.

Finally, org-agenda-date-today is not covered in this list. And this is a tricky one. I've shared with you some time ago my solution to this, but it is not useful to modus-themes. Ideally, we'd have a fourth face available -- org-agenda-date-weekend-today -- so that we could use color for the weekend/weekday distinction, and other face attributes (bold, underline) to indicate "today". Alas, it is not currently available.

It is actually easy to provide it on the user side, since Org offers a nice "handle" for this without having to tamper with the complex agenda internals, which is org-agenda-day-face-function. Indeed, this could well grant a DIY section in the manual. It is easy to do, and I'm happy to help here.

Either way, short of an upstream request, the default case would still have to be sorted out. And I do think the current face could use a "lift up", even regardless of the "semantic scheme". Up for discussion, I'd say.

Well, that's it. WDYT?