Rebuilding the Meta Branded theme: New icons, a custom homepage, and a first look at the Blocks API

[manuel (Manuel Kostka)]

We’ve just shipped a second iteration of our theme rebuild. While the first update was a visual refresh built on top of the previous Meta Branded theme, this version is essentially a new theme rebuilt from scratch. The new brand language was already introduced with the previous release, so there isn’t that much visible change on that front. What’s changed significantly with this update is the theme implementation itself, and what it showcases about where we’re heading with Discourse customization more broadly.

I’ll walk through a few implementation details, starting with the smaller items:

Lucide Icons

Lucide is an open-source set of modern stroke icons, and we’ve been adopting it across several of our customization projects. With this iteration we’ve included it in the Meta Branded theme as well. There are no plans to replace Font Awesome in Discourse core, but the free tier of Font Awesome only offers a limited selection of stroke-style icons, not enough to form a coherent stroke icon system. The theme component is available at Discourse Lucide Icons.

Theme modifier to restrict color palettes

We’ve added a new only_theme_color_schemes theme modifier that restricts which color palettes are available for a given theme, both for admins and for users in their interface preferences. Meta has multiple user-selectable palettes which would clash with the Meta Branded theme’s visual identity. With this modifier, only palettes bundled with the theme are offered as options. PR: FEATURE: add modifier to restrict theme color schemes

Full-width layout

We’re also trying some tweaks to the Discourse Full-width component to better center the main content on the page. There’s a lot of dynamic elements on the header that complicate the setup and so far this is experimental and only available on a branch of the component.

Value transformer to control Welcome Banner visibility

We’ve used a new welcome-banner-display-for-route value transformer to programmatically control on which routes the core Welcome Banner appears. We use this to ensure the banner only shows on the default custom homepage and not on pages a user might have set as their personal landing page. PR: DEV: Add welcome-banner-display-for-route value transformer

This brings us to the two bigger changes:

Custom homepage via theme modifier

The custom_homepage theme modifier has been available for nearly two years, but this is the first time we’re using it to shape the homepage experience on Meta itself. We’re introducing a custom landing page populated with featured components. For the initial launch this includes highlighted featured categories and a preview of the latest discussion topics.

We built these featured components using our new experimental Blocks API, which leads us to the biggest change:

Blocks API: First production usage

The Blocks API is a new framework for building modular, composable layouts in Discourse. It lets theme developers assemble pages from self-contained, reusable components that can be placed into defined layout areas. The Meta theme is our first production deployment of it.

The framework features a rich set of developer tooling: enable developer tools and you can inspect the block structure of any page with a built-in overlay that visualizes all active layout areas and their components.

Beyond the homepage, we’re also using blocks to render custom category banners that show each category’s subcategories:

This is still an early preview of the system in a production context. We’re planning to publish documentation and more examples soon. PR: DEV: Add Block API for declarative, validated UI extension points

[Canapin (Coin-coin le Canapin)]

@manuel

Lucide is an open-source set of modern stroke icons, and we’ve been adopting it across several of our customization projects.

This is a good choice. This set caught my attention when I was looking at which icon sets were available for Discourse. It’s refined and elegant.

The complete lack of filled-in icons was causing a few issues, for example the unread indicator was barely visible as a colored circle, or the dark/light button switch would be difficult to render properly without a filled-in part.

I notice you solved those issues on the meta branded theme. Did you add custom icons for this?

---

The Discourse logo on the top left isn’t clickable on the meta branded theme, by the way (it has been the case for months I believe)

[manuel (Manuel Kostka)]

@Canapin

I notice you solved those issues on the meta branded theme. Did you add custom icons for this?

No, we just didn’t map some icons like circleand square to the lucide version. Or rather, we only mapped the stroke version of Fontawesome for these icons (far-circle,..). There might be other instances where we need to keep improving the mapping.

E.g. the heart icon is tricky. I think a filled version would be better when liked, but so far I’m not sure how to best do that..

@Canapin

The Discourse logo on the top left isn’t clickable on the meta branded theme, by the way (it has been the case for months I believe)

I can’t reproduce that, do you have more details?

[NateDhaliwal]

I’m curious, what’s the difference Blocks brings that Plugin Outlets does not?

[Canapin (Coin-coin le Canapin)]

Only tested on Chrome and Edge, and it only happens on desktop:

The sidebar toggle div covers the logo, rendering it unclickable.

(and yes, the outlined liked heart looks bad )

[Canapin (Coin-coin le Canapin)]

I don’t like at all the current icon for “replied to”:

I suppose it’s temporary as there isn’t a good FA equivalent in Lucide?

---

Icons on the topic list are very, very small:

Edit: it’s the same on other themes.

Category icons look smaller than tag icons and it’s weird. I feel that the chosen category icons size was constrained by the boxed category style, which leaves less room for it…

[darkpixlz (Pyx)]

I didn’t expect to see something like Lucide added to an official theme like this. Looks great! I do wish that the heart was filled though. Besides that nitpick, the theme looks amazing on mobile as far as I’m concerned.

Looks like there’s no padding to the body in PMs:

[Ed_S]

@Canapin

I don’t like at all the current icon for “replied to”

Agree!

And agree with the above, the hollow heart is not good.

[NateDhaliwal]

Hmm… one thing that I feel could be changed is the chat icon from message-square-text to message-square? The lines seem a bit distracting. The change makes the UI “cleaner”, it’s quite a nice change.

[manuel (Manuel Kostka)]

Thanks for all the icon feedback! I just added a dedicated topic for the set: Discourse Lucide Icons.

Ideally we’d want to collect further feedback there and keep polishing the set as we go.

[ToddZ]

Agree the icons are nearly illegible at the current .74em. They need about 1em.

[ToddZ]

Is it my imagination or did vertical padding within the topic list increase today? Either it’s less dense, or I’m more dense.

[darkpixlz (Pyx)]

I also noticed this, tried manually reverting it (because I prefer information density over looks) but no luck

[manuel (Manuel Kostka)]

@NateDhaliwal

I’m curious, what’s the difference Blocks brings that Plugin Outlets does not?

The main difference from a design view is that a PluginOutlet is an insertion point. You inject your component directly into a core template. Every customization actually changes the app structure.

A BlockOutlet is a layout frame. You register one or multiple components with the frame. Then customizations happen within that frame rather than in app templates. So we get more predictable and stable layouts

Another big difference is that the Blocks API can handle the full spectrum of conditional render logic. You don’t need to add that to your component. A block component can focus purely on content and template and we have much less repeated logic.

[darkpixlz (Pyx)]

@darkpixlz

but no luck

If anybody would like to have a more compact topic list, this is what worked for me:

.topic-list .topic-list-data {
  padding: 8px 0px;
  line-height: 0px;
}

[Canapin (Coin-coin le Canapin)]

The new meta branded theme has too much spacing to my taste on mobile.

• 1s spacing between the screen border and the content’s container
• 2nd spacing between the page’s container and the actual content

Other themes don’t have this first gap between the screen border and the content container.

It makes the content a bit “crushed” horizontally; there’s very little room. It’s well visible on the “my post” page, compared to Horizon:

Horizon can show much more content without losing readability.

I understand the intent of the purple “outline” background so the brand aspect of the theme is visible on a full-content page, but I think we lose too much space on those narrow screens.

Another small criticisms:

The icon on the top left is not perfectly round. It’s very slightly oblate.

The category/tag pop-up lets the textarea bleed slightly (not sure it’s related to this theme):

. It would be better if it covered it.