Ideas about Joplin Theming

[uxamanda]

There have been a lot of conversations around theming (https://discourse.joplinapp.org/t/plugin-css-improvement-ideas) , I took a deep dive into how I think we might better approach things.

What we have now

Built-in Themes

From settings, users can choose between a handful of stock themes in dark and light mode and (on desktop) customize some basics like fonts and size.

Pros

• are not CSS based / are compiled, so they are built to work in desktop and mobile
• are integrated with plugins (the plugin developer has the ability to uses the joplin css variables without knowing what theme the user is using)
• super easy for a user to find / switch in preferences

Cons

• making a theme require knowledges of how to build a "joplin theme" (which isnt documented?). I recently went through this process, and it took me a while to get the app building properly, and then figuring out what the theme is changing (i intend to publish this, but haven't had time)
• Only affects colors, doesnt affect layout
• Bundled into an app release

CSS Themes

Pros

• as customizable as the theme developer wants!
• can make / customize a theme with only normal CSS knowledge + dev tools, no Joplin specific knowledge needed
• don't need to build / run the app in dev mode
• can do whatever you want in the app (hate that button? hide it, want to move a feature to a new spot, go for it, your CSS hacking skills are the limit)
• extremely fast to add things (I change my css at least monthly, often much more often)

Cons

• hard to distribute, other's have to manually keep up to date
• fragile, the app does not have many built in CSS classes, and so there is a lot of span > div > div:first-child nonsense. even without strict classes, I suspect this makes the devs more hesitant to change structure (even though there is a warning it can/will change)
• messy, have to keep it well documented to remember what does what
• not everything is "reachable" without CSS classes because the style is being applied directly to an element that is the same from an HTML perspective (for instance, selected notebook was impossible to style until a class was added)
• does not work on mobile
• different "hacks" break each other's functionality, so need strong css skills to keep things stable

---

Recommendation

Lean all the way into CSS

Warning: I need lots of feedback on how this could be realized Please take any "implementation details" as directional only, I don't know the right way to do it yet.

While there are only a half dozen regular developers, maybe a dozen plugin developers, there are another dozen of us in the forums who contribute regularly to CSS. Right now, all of our CSS is haphazard and messy. (Every time I post messy CSS with lots of !important tags I feel like I am setting that user up for confusion later.)

My dream scenario looks something like this:

• random new user makes a request for "theme" type change. I see how to change that with CSS, and instead of just giving them a random code snippet, I have some way of adding it somewhere so that it becomes a new setting / toggle in preferences. If it really feels like a 1 off, maybe it goes into an "experimental" or "advanced" area that most users wouldn't see.
• ideally i could give someone "temporary code" that works immediately, while at the same time putting it into the main app as a new option for theming.

Issues:

• Right now the plugins are in iFrames and can't "see" the main CSS. I think this is going to be the biggest hurdle to making this work right.
• Oh... and mobile... (would still ideally have this be CSS)

Focus the main dev effort on being hyper modular

Seeing how plugins are working out (very well), I feel like the app itself can become very modular and it would give us a great framework to build themes on.
For example, take tags:

• Right now, they are connected to notebooks in a way that isn't really needed
• ideally they could be moved to it's own column or below sync or whatever
  This probably sounds unnecessary, is it that big of a deal to be able to move that? No, not at all, but by making everything strictly modular, we can make super consistent classes that make CSS easy to build on. Users can also use the normal "change application layout" to move things around.
  For instance, every "panel" (i.e. a plugin, Tags, search, sync, tags) can have (at least) a top level panel class. From that, I can easily define margins and sizing and spacing, etc across all panels. Likely there'd be other main classes we use, for things like lists and such that make them easy to theme together). Then each panel would have an ID (joplin_tags or whatnot) so that I could provide specific CSS for that panel as appropriate.

The goal of this is to build a "way" of building panels and new features that make the main devs able to focus on the features and not get bogged down in the styles, thus (hopefully) saving time and shifting responsibility.

Risk: Maybe there aren't actually that many people who want to help with theming, and the main devs are less interested in CSS.

Build a theme editor

I've talked about this before (Any suggestions on what plugins could be created? - #155 by uxamanda), but imagine that in settings, the CSS that us "theme builders" make gets exposed as color pickers and drop downs for size etc. Ideally the user could export those variables and that is what is passed around in the forums. (I.e. base_color: #000000, font_size: 20, "hey guys, this is a great e-ink customization") I know that still has people passing things around, but instead of CSS code, it is just variables and therefore much easier for non-coders to comprehend. If any of us see a theme that is looking really nice, we can save those variables and make it a "stock" theme.

---

Short term ideas

• I consider the MacOS theme to be a huge leap forward in design. I know its only been a few months since Joplin was "redesigned" but I would love to see all the changes from that theme integrated as the stock design. Looking through the CSS that is making that work is clearly an effort of love, but it is unnecessarily complicated. Ideally we could (I include myself in this we!) break down that theme into not just the style changes but work through the structure changes that would enable this "CSS theme world".

---

I realize this post is rambling, but wanted to get some conversations started!

[uxamanda]

Just saw @whitewall's post on this Populating userchrome.css with common classes for new installs? I think this would also be a nice short term solution as we built up to an in-app theme editor.

[andrejilderda]

Nice detailed write-up @uxamanda

Before diving into details I think we should start with a fundamental problem, which in my point of view is Joplin's overall design.

I think Joplin looks dated.

I think quite a few users are put off by it which is such a pity for a feature rich application Joplin is. Sure, we can distribute themes as plugins. Or create ways to enable CSS snippets. But imo the main UI should just be really good to begin with.

[laurent]

Thanks for looking into this @uxamanda. I agree that going with CSS would make things easier both for users and developers, and would be more flexible than theme files.

In fact while reading your post, I've been thinking we could perhaps keep the current hybrid approach - with themes that define various colours, and custom CSS files that set the rest of it. But instead of having the themes part of the app, like now, we'd convert them to CSS too.

So instead of this:

const theme = {
    color: '#32373F',
    backgroundColor: '#ffffff',
    // ...
}

We'd have this:

:root {
    --joplin-color: #32373F;
    --joplin-background-color: #ffffff;
    /* ... */
}

The advantage this special CSS theme files is that it can easily be parsed by the mobile app, and used as if it was a regular theme.

So basically a theme plugin would essentially contain two files:

• "colors.css" - contains the Joplin color definitions

• "theme.css" - contains any custom CSS that changes padding, margin, borders, etc.

That color.css file could also be loaded in plugins so that they can access the theme colors.

I think that approach would be a bit more consistent since everything would be CSS, and in terms of development I believe we won't have that much to change since once colors.css is parsed, we can apply the colours in the codebase as we're doing now. It's backward compatible basically.

[laurent]

I think Joplin looks dated.

It's indeed a relatively frequent criticism of the app, even though we got a brand new design less than a year ago! What change could we make so that it doesn't look dated?

[whitewall]

@laurent

It's indeed a relatively frequent criticism of the app

I'm also really curious what people mean when they say this. The only thing I can think of would be to do away with the top menu bar. Browsers seemed to have ditched that a long time ago. But I believe this has been discussed and there was some technical reason it couldn't be done.

[roman_r_m]

@laurent

It's indeed a relatively frequent criticism of the app, even though we got a brand new design less than a year ago! What change could we make so that it doesn't look dated?

I agree with this, especially with regards to the mobile app, but I struggle to express why it feels this way. It just does, I guess.

[CWPfVTkNBMyfdFW]

Just a guess, but I wonder if this could be because of the "point & click" nature of the app and the static UI, both on desktop and mobile.

In the case of the mobile app, I'd say there is no animations (which is not necessarily a bad thing depending on who you ask) and a lack of gesture commands compared to something like Gmail (I know Joplin is an open source project with a small team of dev, so it's not exactly a fair comparison). Things like sliding a note to the left to edit the tags, showing tags and last edit time from the note list.

In a similar way on desktop, everything needs a click, hovering with the mouse is barely used anywhere. For instance, there is no way to see the tags of a note without opening said note (another click).
Another thing, while rounded edges and curvy shapes seems to be the current norm, Joplin's design is very angular, almost no rounded edges anywhere, only straight lines.
A good example of this is the CSS table of content that was shared a while ago. There is animation, rounded edges, hovering and as a result, it feels modern and dynamic. I realize not everybody likes animations in their face while working, but probably some ideas are worth considering among those.

There's also the lack of colors (like colored tags and notebook for quick at-a-glance identification), but this is starting to sound like a rant requesting a dozen new features when it's not, just an observation compared to some other apps.

[whitewall]

@CWPfVTkNBMyfdFW

hovering with the mouse is barely used anywhere.

I imagine hovering is an afterthought for developers, since there is always another way to get things done rather than hovering. Hovering isn't the best thing for accessibility as I understand.

Now that you spell all those things out, I can see how they might give it a more modern feel. But as you say, they are all feature requests, not really design issues. Except for the rounded edges. But just wait a couple years and rounded edges will be for "squares"

But maybe I'm just totally out of touch because ...

@uxamanda

I consider the MacOS theme to be a huge leap forward in design.

... I really couldn't tell any difference!

[laurent]

I guess all this is an argument in favour of a more flexible CSS based theming system. Once it's in place those with an eye for design can easily tweak it and that way more modern designs will emerge, which could then be installed by default with the app.

[CWPfVTkNBMyfdFW]

@laurent

I guess all this is an argument in favour of a more flexible CSS based theming system

CSS is definitely the reason I use and like Joplin so much. Being able to customize your app with barely any understanding of CSS (just replace some html color) is really accessible to anyone with a notepad. Unlike themes baked in the app which need to be compiled (things way above what I understand).

Just another observation, but maybe there is also a need for design guidelines on plugins.

Just looking at some of the plugins I use, there is no standardized style for the header:

• Joplin: icon, bold, uppercase title
• Favorites plugin: icon, uppercase title
• Outline plugin: no icon, bold, uppercase title
• Backlink plugin: no icon, bold, normal case title

It may not seem like much, but it feels like there is a lack of visual integration with the plugins. They literally feel 'plugged-in', not unified with the app.

This is a minor nitpick, but I believe things like this also contribute to the general feeling about the interface.

[andrejilderda]

I know. I'll try to explain what I mean with outdated the best that I can.

In Design Systems Alla Kholmatova makes a distinction between:

1. Functional patterns
   makes a user accomplish goals (buttons, tabs, dropdowns, etc.)

2. Perceptual patterns
   makes a product/UI feel a certain way (color, typography, iconography, spacing, etc.)

When I'm talking about Joplin feeling outdated im talking about 2. the perceptual patterns primarily. There's nothing wrong with the functional parts (1.) of Joplin. Also the application shell (notebooks on the left, notelist + note on the right) is just fine as it is.

Alla gives a very striking example of Atlassian’s Hipchat (which is now killed) vs. Slack. Both are really similar feature wise, but they feel very different due to their perceptual patterns:

You can make the same comparison of Joplin vs. any other note editor. Joplin’s perceptual patterns consist of:

• Typography: Roboto + alternate font for text editor (default: Avenir)
• Iconography: Font Awesome + icons from Icomoon
• Color: Neutral tones with a touch of blue.
• Spacing: Cozy, high information density
• etc.

For me it’s especially the typefaces, icon families and the way they’re applied where things can be improved.

What makes an app look outdated is related to what we consider modern. This is why I refer to a few options that are widely used in the industry.

Typefaces

When aiming for a neutral UI I'd consider the more modern Inter in stead of Roboto (or the system's default sans-serif font stack, but in that case you’d have a different typeface per platform). To improve consistency I'd replace the default editor typeface (Avenir) with the typeface used in the rest of the UI.

The above is for a neutral look. For a more branded look I'd draw inspiration from other text heavy, well branded apps like Slack (which uses Lato).

Icon families

Joplin uses both Font Awesome and icons pulled together in Icomoon (?) throughout the interface. Font Awesome is quite old and it shows it age if you ask me. But the thing is that both families are very different and makes the UI look inconsistent. Take for example the globe icon (Font Awesome) and the icons next to it:

The main problem is that Font Awesome's default icon set is solid, where some other icons are outlined. I'd go for outline icons as that is the industry standard (most modern OS'es and apps use outlined icons) and stick to one icon family to improve consistency. I found that the Phosphor icon family contained all icons for Joplin while working on my macOS theme.

Typography/iconography

I don't mean to just swap fonts and icons. It's mainly in how the type is applied. In quite a few places I feel the hierarchy is off. One thing that is bothering me for example is what is happening in the sidebar:

Which in my macOS theme I changed to:

A few things were cleaned up, like the add icon is only shown on hover and the icon in front of ‘Notebooks’ was removed. But the biggest difference is that the focus is changed to what matters most to the user: their notebooks (by adding the icon, increasing the text color contrast of the notebook titles and decreasing the size and color contrast of the ‘Notebooks’ label).

It may sound like nitpicking, but I think fundamental changes like changing fonts + icon families (for the sake of improving consistency + design update) and improve typography + hierarchy makes a huge difference in how users perceive Joplin.

For inspiration you may want to check out this Twitter thread by Steve Schoger.

I can give it a go and share a few design ideas, but I'm a bit short on time the next few weeks.

[whitewall]

@andrejilderda

by adding the icon

Personally, I dont like that. Because this is a list exclusively of folders, aka notebooks. If the notebooks and notes were together in one list then that would make sense.

Also, cant the user change the interface font? I changed to Fira Sans Compressed almost as soon as I started using Joplin.

[symisz]

Adding icons to the menu has the opposite effect for me of creating clarity and achieving a modern look. But I agree that the design approach should be focused on font choices, white spaces and subtle state changes.

However, changing the word notebook to a smaller font-size and removing the icon, I like that.
While making "all notes" look undistinguished from the rest of the menu is defeating its purpose, although the current design is too obstructive and could use more coherence.

I never use the + button to add new notebooks on the desktop app, I find right clicking more convenient and intuitive. But its still useful for new users to find their way with the app.

I prefer the arrow, that indicate a collapsing tree, to align to the right side, like how its on the mobile app.
And my current gripe with the current menu is that the indent spacing is too much.

Before looking into a more modern design however, current dark mode still doesn't darken the window top bar, that's an issue.

[Daeraxa]

@symisz

Before looking into a more modern design however, current dark mode still doesn't darken the window top bar, that's an issue.

Although not ideal, if you are on Windows then I believe this is controlled from your system theming (i.e. if you set Windows to dark mode then that bar will be dark).

[symisz]

Strange, Joplin doesn't apply my Windows dark mode settings. Not sure if it's an isolated bug.

[roman_r_m]

I think it's an issue with Electron rather than Joplin

[uxamanda]

@laurent

Once it's in place those with an eye for design can easily tweak it and that way more modern designs will emerge, which could then be installed by default with the app.

I think this is the key takeaway, for whatever version of "modern design" an individual prefers. And as we all know, each day there is a new person in the forum using the app in a totally new way (just saw someone mention they plan to use it to write a book) and even in this thread there are different preferences on what a "good design" is. Ideally Joplin has lots of very different themes for different people to meet their needs and preferences.

@andrejilderda mentioned design systems and to me that is the crux. A great design system provides the necessary bones to make theming easy. For instance, whether you prefer the style of the MacOS theme or not, you'll find that it is very internally consistent, especially around fonts, colors, spacing, and iconography. Having looked through his CSS, I feel like I could take that and make a dramatically different looking app – for example a high contrast theme or a "journal" theme with more bright colors. I would go this route, but I feel like it is built on an unstable foundation because the app wasn't really built in that way (no shade Andre, your work is impressive!!).

Ideally, a person who wants to make a theme can compose / build up from a design system:

• variables (often called atoms): color, size, fonts, borders *** I think individual users should be able to access and modify these easily in Settings
• elements: i.e. Body Text: Color-1, Size-2, Font-1, List Item: Icon, Body, Helper Text *** I think theme developers should be able to customize here easily
• components: i.e. Accordion List: Header + [List Item + Spacer] *** I think this level will need to be Joplin-opinionated and might take CSS hacking for someone to override
• panels: mentioned in my initial post where base spacers and borders are used for consistent padding across different pieces of functionality - *** I think these are mostly styled via variables and should be easy for a user to manage via the existing "change application layout"

Don't get me wrong, doing this right is a lot of work! I am on the final stretch of a huge project where we moved a legacy app to a design system so that it could support whitelabeling. In that project, you can simply flip the theme and the app looks completely different, but the "bones" of it are the same (although in this case the user cannot manage/edit themes themselves).

So again, rambling, but tl;dr....

I think the next step would be to start decomposing the design that @andrejilderda created into a comprehensive design system. Then, there would need to be an effort to integrate that system into the code so that anyone who wants to start building themes could do it. After that, we could work on the Preferences part so users could manage variables themselves...

I can get started on figuring out a design system (ideally with whoever else wants to participate), but I would need support on the code / integration side of things to see it through. This will need good collaboration to make it successful, so if I'm on the wrong path / too big of an effort / not the right time, stop me and I'll keep tweaking away as needed in the existing CSS.

[laurent]

@uxamanda

I think the next step would be to start decomposing the design that @andrejilderda created into a comprehensive design system. Then, there would need to be an effort to integrate that system into the code so that anyone who wants to start building themes could do it. After that, we could work on the Preferences part so users could manage variables themselves...

I've been thinking about this and I get the feeling there's not much more to do than giving proper class names to various elements. Andre already started doing that and we could continue adding more. Perhaps we can even start from his design, see what areas feels a bit hackish (due to not being able to easily select certain elements), and improve that. Once classnames are set consistently throughout the codebase, it should be much easier to create custom theme. Do you think something more than that would be needed?

Next to this, there's also indeed the issue with theme colours being baked into the app, but I believe that can be changed without too much troubles by converting the themes to a list of CSS colour variables. Then all these could be overridden by user stylesheet.

[uxamanda]

(Sorry for the very long delay in responding, life got in my way!)

I went back and forth on this, and I think you are right that adding classes is the best and most incremental way to start. I have a bunch of ideas of how to improve it over time, but as we can see with my long delay, incremental wins. If I look at an app like Atom, which is very themable, it seems they are

1. not including any style in the code, but include named classes as hooks
2. creating a base theme that is built from CSS (this would mean that over time, all the inline style is moved from the code and pushed into a base theme. This is where i'd like to focus on making it more consistent from a design system standpoint, but i think this can be incremental as long as any new theme developers realize theming is in beta for a while).
3. theme developers can create a css file that is either just light adjustments to the base css / variables OR they can really override it (more like what @andrejilderda did). users just choose the theme and don't have to care how complex it is.
4. users always have the ability to add their css on top of the theme (like we already have with userstyles).

And, since Andre already figured out a way to make his theme work with the existing Joplin classes, it seems like we could use that as an experiment by:

1. Switching the existing themes to pull from CSS variables (we could take a bit to redefine what the right css variables / names should be, but maybe that is best for v2 for speed?)
2. Have Andre (or I can do it) add in the Joplin named CSS variables at the beginning of his theme so that they can be used be other parts of the app (plugins) and then derive his named colors from those. This would have the added bonus of his theme working in mobile.
3. Include his theme with the app (and ideally use it as the default theme for new users).
4. Still include userstyles.css for users to customize on top of themes.

Other considerations

1. Now that he has it built as a plugin, he is also including other toggles / settings for the user. It would be really cool if theme developers could surface these types of toggles on the appearance tab. I am not sure the right way to include these, but seems like lots of themes would want to include options.

2. It would also be really cool to have the CSS variables (color, fonts) that the theme is setting exposed to the user so that they could override them easily in an advanced tab. Building on something @whitewall suggested, these could at least be shown in a default userstyles.css that the user can easily override.

How to develop a theme

1. A new theme developer would just provide a CSS file to be included with the app. These could also be handled like plugins where the theme developer "submits them" but they aren't included by default. In think this would be ok so long as it was something like "fork this repo with a base css file and then submit your theme to this page" instead of having to manage NPM, but that might be wishful thinking.

Risks:

1. we are likely to have some churn on theming for a bit, which might break people's userstyles.css. They are likely to be unhappy about this. BUT, if they get a better designed / more themable mobile app and plugins + ability to get better themes, I imagine the majority will be for it.

@andrejilderda do you have thoughts on a better way to approach?