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.

Alexander Rink

Published in

Geek Culture

5 min readJun 24, 2021

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.

Roam Research with Quattro Theme in light and dark mode

Quick Start

Using my CSS System is quite easy. Go to your roam/css page and add a new CSS code block containing:

@import url('https://rcvd.github.io/roam-css-system/themes/quattro.css');

A roam/css page prepared for using the CSS System

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

@import url(‘https://rcvd.github.io/roam-css-system/themes/quattro_light.css');

@import url(‘https://rcvd.github.io/roam-css-system/themes/quattro_dark.css');

If you are already happy with the result, you are done. More themes will follow soon.

Update: There are two additional themes available. LessWrong (inspired by their awesome website) and Cultured Code Things.

Use them by adding this to your roam/css page:

@import url('https://rcvd.github.io/roam-css-system/themes/lesswrong.css');

Roam Research with the LessWrong Theme (Light and Dark Mode)

@import url('https://rcvd.github.io/roam-css-system/themes/things.css');

Roam Research with the Things Theme (Light and Dark Mode)

If you have the desire to change something more special (e.g. you like the color green more than the color red), read on.

Customize it

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.

Example showing how to overwrite font settings for level 1 headings

You can find more detailed documentation and reference to all variables in this public Roam Research graph.

Screenshot showing the documentation for customizing the theme

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.

Showing how CSS selectors and Variables interact

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.

Maintaining all CSS Selector and settings in one big spreadsheet

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.