What's the vision for the Discourse design system?

I’d love to make custom themes and components that are aligned with the Discourse design system and that will blend into the app in a consistent and harmonious way.

Just looking at the code and how styles are defined and applied in core I find it difficult to make sense and actually get the idea of the bigger picture and the envisioned direction of the design system.

I’ll try to break this down into three main topics: color, type and spacing.


There was an introduction of a numeric scale for some values two years ago. I think it was mentioned that it’s just meant to supplement the named color transformations. For the tertiary color value it looks like this now:


I see both models applied in new code in core. Is the long-term idea to keep using them side-by-side or is there a different vision?

In any case, shouldn’t there be a numeric scale for all four main color values? Right now it’s just there for primary and tertiary, but not secondary and quaternary.


There’s currently three different types of font size progression defined:


There also haven’t been updates to this in more than two years. Should these be used at all in new code? Tbh I never touched the multiplier definitions as it’s difficult to define the actual final font-size. But I also don’t understand the base-font definitions. The scale defined would be:

  • 13px - 14px - 15px - 17px - 19px

But when I look at actual font-sizes, the default scale in use is more or less:

  • 13px - 15px - 17.25px - 22px - 26px


I see that new elements like the sidebar introduce root variables for spacing. E.g.:


That definitely makes it easier to adjust the sidebar layout. But it doesn’t translate to any other layout elements. On the other hand I don’t see foundational spacing variables being introduced that would allow for more consistent layout adjustments across the app. Is this on the roadmap in any way?


It would be great to know if there plans to move towards a more consistent and simple design system?

There seem to be just too many unrelated and standalone definitions right now, and they make it pretty difficult to build a consistent and rhythmic layout with a notion of ease (and joy :slight_smile: ).

I understand it’s a big app with a ton of different elements. However, I just did a little test on the default latest list view:

This is a rebuild with every spacing value picked from a very simple geometrical progression (2px/4px/8px/16px/32px/64px). And font sizes from just 4 values:

Screenshot from 2024-01-30 21-05-48

Screenshot from 2024-01-30 21-04-12

It just seems design-wise there is no need for the number of unique definitions that is present across the app now?


This is something we’ve wanted to do, and have gradually worked towards in bits and pieces, but it isn’t something that can happen all at once. Every change we make causes potential theme regressions across thousands of sites (and we have to fix a lot of these for our customers), so it takes a long time to make small changes.

We have also been undergoing Ember modernization work for a while now, which also requires fixing regressions and refactoring existing themes. This is still underway and will also take time to get everything updated (replacing our widget system, for example, could easily take 6 more months). There are a lot of priorities to balance.

There’s no envisioned direction outside of more consistency. We’ve considered decoupling our base styles so the default “unthemed” Discourse has a lot less CSS (which might make it easier to maintain themes)… but that’s just an idea at the moment.

I think these were added “as needed,” so we haven’t had a need for additional secondary/quaternary scales. We don’t have any plan to remove the named versions, so either can be used for the foreseeable future.

The smallest/smaller/larger/largest sizes are for the text size user setting. Most of the time these won’t need to be changed.

The em scale is roughly based on a classic typographic scale (The typographic scale, for example). A more evenly spaced scale like 13-15-17-19 doesn’t create a lot of contrast and everything stays kind of small unless you have many steps. On a classic scale the gaps between the scale increase along with the size to create more contrast.

The idea behind the em-based scale is that everything in the app can scale proportionately, and individual sections of the app can be scaled proportionately. So I could do something like

.sidebar-wrapper {
  font-size: 20px; 

and everything within would scale up proportionately without having to alter every individual font-size and all the related spacing.

Internally the feedback is similar to your own, in that developers want to know exactly what font size they’re getting regardless of context, which is a downside of the system. Ideally we wouldn’t be worrying about exact sizes and could just say “this should go up a step because I want it to be larger” but that mental model does not seem to come naturally.

There’s some desire to move to a rem-based system instead, but as mentioned earlier… this would likely take a long time to change because it would affect so many existing sites. I’d also prefer the browser-default base of 16px rather than our 15px, but similar story (it used to be 14px! so we’ve made one step at least).

The rem scale is used for headings in cooked post content, because nesting heading tags using ems meant individuals could infinitely scale up text and cause layout problems.

Yeah, it’s come up a couple times… (I’m sounding like a broken record but…) it would have to be a very gradual change to avoid regressions in existing sites. At the moment we’ve been adding shared variables within specific areas as we update them, which is a step in the right direction.

The speed at which this stuff happens is understandably a little frustrating, but for most of Discourse’s history there was no full-time designer on staff at all. The design team has grown to 7 over the past couple of years (including dedicated designers to work on customer projects, which mostly happen out of public view) so hopefully we’ll be moving towards more consistency faster now.


Thank you for the explanations Kris! That’s really helpful.

So I only face this on a very small scale. I do think sometimes though it could be helpful to change the overall expectation with regards to the Product. To establish that Discourse is moving fast.

That could be nice but I believe it would still require easier handles. There’s just so many templates. Even if each of those has a simpler CSS, if I can’t modify them in an orchestrated way then it’s still a lot of work.

It’s a beautiful mental model. I might prefer having exact sizes because they are so much easier to apply. Like, someone has a design system, I just apply the numbers and look at the outcome. While as otherwise I feel I’d need to align two systems. Like I’d need to understand both their character and find their common tune.


Thinking more about this… I could have several visions for a Discourse design system.

Discourse Design System-95

A practical design system with standardized atomic building blocks. That would always be a necessary first step I guess.

Discourse Construction Kit 8

A system that abstracts some high-level components. For Discourse these could be about moderation, recognition, information,…


A common system of patterns for online conversation. Similar to the foundational scope of a system like Material Design.