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
Jun 24 · 5 min read

The idea behind it

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.

The default look of Roam Research

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.

The look and feel of Roam Research with the iA Quattro Theme in dark mode

Quick Start

@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');

or

@import url(‘https://rcvd.github.io/roam-css-system/themes/quattro_dark.css');
The new look in light or dark

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

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

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?

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

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.

Development of the Roam CSS System
The final JSON file

If you are interested in more in-depth aspects, let me know.

Last Words

Have fun #roamcult.

Geek Culture

Proud to geek out. Follow to join our 1M monthly readers.