The Roam CSS System
The Roam CSS System is a modular, block-based approach for changing the look and feel of Roam Research. It has been thoughtfully designed to allow easy customization by the non-tech-affine end user.
Updated on August, 7th regarding new available themes lesswrong and things.
The idea behind it
Roam Research is an awesome tool for note-taking, interconnecting ideas, brainstorming, structuring topics — in short, it contains almost everything you need to build a second brain.
While we all enjoy the technical aspects of this application, not everyone shares the same aesthetic taste. Some like it more minimal, some more colorful. One may prefer a dark mode while another one loves the light mode or wants the theme to automatically change whenever the OS setting changes.
Roam Research supports custom CSS for a long time, but whenever something in the background of the application changes, you have to update your custom settings. This can be a quite time-intense process and has to be done by every single user who wants to change their CSS.
This leads me to the idea, to abstract the underlying technology in a way that the normal, non-technical user could concentrate on the optical changes without knowing all the details.
Using my CSS System is quite easy. Go to your
roam/css page and add a new CSS code block containing:
You should see an instant change to the new CSS System (based on your OS settings in light or dark). If you prefer forced light or dark settings, chose
If you are already happy with the result, you are done. More themes will follow soon.
Use them by adding this to your
If you have the desire to change something more special (e.g. you like the color green more than the color red), read on.
If you want to change certain aspects of the look and feel, this is easier than ever before.
The CSS System already offers more than 700 variables to further customize the details. Whenever you change a variable and put it below the
roam/css import block, it will overwrite the theme's default settings.
You can find more detailed documentation and reference to all variables in this public Roam Research graph.
I’ve also put some common examples there to further show you how this works.
All of this together gives you a minimally invasive approach to achieving the look you want.
What to do if something doesn’t work?
While the CSS System already has a very robust foundation I may have missed some objects for theming. I may have also overlooked attributes on some objects that you would like to change. And my documentation might be still too short or imprecise to guide you through the whole process.
In any case, you can contact me here on Medium, on Twitter, or (and this is my preferred way) open an issue in GitHub. Be assured that the whole CSS system will grow over time and more themes will be added.
A brief look behind the curtain
If you are one of those tech-savvy people curious about how this works, let’s take a short look inside the system.
The first and most important thing is the separation of CSS selectors and variables. This guarantees that the user can change some aspects (the lower part of the next screenshot) without having to care about the underlying technic (the upper part of the screenshot) which can change from one version to another of Roam Research.
I have created a spreadsheet containing relevant CSS selectors (more than 240) and default values. I used a three-level naming scheme for the objects based on BEM (Block, Element, Modifier) that stays over time. I’ve then decided which objects should be customizable regarding different aspects (you see the small crosses there?) and put in values that I personally prefer in my iA Quattro Theme. Whenever a CSS selector changes upstream, I only have to update a single cell in the spreadsheet and almost never changes on the user's side are necessary. Whenever we find something I haven’t themed yet, I have to add just a few additional rows.
To create the reference pages for variables in the Roam Research graph, I’ve written a script to automatically create a JSON file for import. This will help to always have an up-to-date reference.
If you are interested in more in-depth aspects, let me know.
Have fun #roamcult.