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

manuel
Tue, 07 Apr 2026 09:44:00 +0000
Site feedback

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

11 posts - 6 participants