discourse-theme-authoring

name: discourse-theme-authoring description: Use when creating, developing, or modifying Discourse themes and theme components — covers scaffolding, SCSS architecture, BEM CSS, viewport design, localization, settings, icons, value transformers, theme modifiers, and CSS variables

Discourse Theme Authoring

Themes and theme components are the primary way to customize Discourse's appearance and behavior without modifying core code. Themes can include SCSS stylesheets, JavaScript/Glimmer components, locale files, settings, and assets.

For detailed reference data, see the sibling files in this directory:

• css-variables.md — All ~400 CSS custom properties
• icons.md — Default icon list and icon system details
• transformers.md — All value and behavior transformers

Scaffolding a New Theme

Always use the discourse_theme CLI to scaffold a new theme or component. Never create theme files manually unless the user explicitly asks.

First, confirm the details with the user:

1. Theme name (defaults to directory name)
2. Is this a component? (Y/n — default Y, answer n for a full theme)
3. Author (defaults to "Discourse")
4. Description
5. Start watching? (Y/n — usually n during development)

Then run with piped answers:

printf 'Theme Name\nn\nAuthor Name\nTheme description here\nn\n' | discourse_theme new /path/to/my-theme

It clones from the discourse-theme-skeleton repo, customizes files based on the answers, initializes git, and runs pnpm install.

Generated Structure

my-theme/
├── about.json                  # Theme metadata (required)
├── settings.yml                # Theme settings schema
├── locales/
│   └── en.yml                  # i18n translations
├── javascripts/
│   └── discourse/
│       └── api-initializers/
│           └── my-theme.gjs    # Theme initializer
├── common/
│   └── common.scss             # Common styles entry point
├── stylesheets/                # Additional SCSS files (importable)
├── assets/                     # Static assets (images, fonts)
├── spec/                       # Ruby system tests
├── test/                       # JS acceptance tests
├── .discourse-compatibility    # Version mapping
├── eslint.config.mjs
├── stylelint.config.mjs
├── .prettierrc.cjs
├── .template-lintrc.cjs
└── package.json

about.json

{
  "name": "My Theme",
  "component": false,
  "authors": "Discourse",
  "about_url": null,
  "license_url": null,
  "theme_version": "0.0.1",
  "minimum_discourse_version": null,
  "maximum_discourse_version": null,
  "assets": {},
  "color_schemes": {},
  "modifiers": {},
  "screenshots": []
}

For theme components, set "component": true and remove color_schemes.

Color Schemes

Full themes can define color schemes in about.json. These appear in the admin color scheme picker and set the core color variables:

{
  "color_schemes": {
    "My Light Theme": {
      "primary": "333333",
      "secondary": "ffffff",
      "tertiary": "0088cc",
      "quaternary": "e45735",
      "header_background": "ffffff",
      "header_primary": "333333",
      "highlight": "ffff4d",
      "danger": "e45735",
      "success": "009900",
      "love": "fa6c8d"
    },
    "My Dark Theme": {
      "primary": "dddddd",
      "secondary": "222222",
      "tertiary": "0088cc",
      "quaternary": "e45735",
      "header_background": "111111",
      "header_primary": "dddddd",
      "highlight": "ffff4d",
      "danger": "e45735",
      "success": "009900",
      "love": "fa6c8d"
    }
  }
}

Color values are hex without the # prefix. These 10 base colors generate the full set of color scale variables (--primary-low, --tertiary-hover, etc.).

To restrict the color scheme picker to only this theme's schemes, use:

{
  "modifiers": {
    "only_theme_color_schemes": true
  }
}

SCSS Architecture

Follow this pattern for all themes. No code in common.scss — only imports. Every top-level folder in stylesheets/ has an _index.scss file.

Directory Structure

common/
└── common.scss          # Only imports, no rules
stylesheets/
├── brand/
│   ├── _index.scss      # @import "fonts"; @import "colors";
│   ├── fonts.scss
│   └── colors.scss
├── app/
│   ├── _index.scss      # @import "variables"; @import "header"; ...
│   ├── variables.scss
│   ├── header.scss
│   ├── sidebar.scss
│   ├── buttons.scss
│   └── topic-list.scss
├── blocks/
│   ├── _index.scss      # @import "block-hero"; @import "block-featured-list"; ...
│   ├── block-hero.scss
│   └── block-featured-list.scss
└── layouts/
    ├── _index.scss      # @import "homepage"; @import "sidebar-discovery";
    ├── homepage.scss
    └── sidebar-discovery.scss

common.scss

@use "lib/viewport";
@import "brand";
@import "app";
@import "blocks";
@import "layouts";

Rules:

• common.scss imports top-level folders only, never individual files
• Each folder's _index.scss imports all files within that folder
• Adding a new file only requires updating that folder's _index.scss
• Only _index.scss files use the underscore prefix — regular SCSS files do not

BEM CSS Conventions

Discourse uses a modified BEM variant for CSS. All theme styles must follow these conventions.

Syntax

• Block: A standalone component. One BEM block per Ember component. Example: .topic-card
• Element: A part of a block, joined with __. Example: .topic-card__title
• Modifier: Changes appearance, written as a separate -- prefixed class. Example: --featured

Nesting in SCSS

Use & to visually nest elements under their block. This keeps related styles together and makes them easy to collapse:

.topic-card {
  display: flex;
  gap: var(--space-3);

  &__title {
    font-size: var(--font-up-1);
    font-weight: 700;
  }

  &__excerpt {
    color: var(--primary-medium);
    line-height: var(--line-height-large);
  }

  &__meta {
    display: flex;
    gap: var(--space-2);
  }

  // Modifier applied directly to element
  &__title.--highlighted {
    color: var(--tertiary);
  }

  // Modifier on the block affects children
  &.--compact {
    gap: var(--space-1);
  }

  // Indirect modifier: style children when block has modifier
  .--featured & {
    border-left: 3px solid var(--tertiary);
  }
}

State Prefixes

For conditional states, use is- and has- prefixes:

.sidebar-panel {
  &.is-open { display: block; }
  &.is-collapsed { display: none; }
  &.has-errors { border-color: var(--danger); }
}

HTML Usage

<div class="topic-card --featured">
  <h3 class="topic-card__title --highlighted">Title</h3>
  <p class="topic-card__excerpt">...</p>
  <div class="topic-card__meta">...</div>
</div>

Key Rules

• One BEM block per reusable component
• Blocks can contain other blocks
• Elements belong to their block only — never use .block-a__element inside .block-b
• Modifiers are standalone classes (--modifier), not chained to the element name
• Prefer indirect modifiers (on the parent block) over repeating modifiers on every child

Viewport Library

Never use raw CSS media queries. Use the viewport library from Discourse core.

SCSS Mixins

If common.scss already has @use "lib/viewport", all @imported files inherit the namespace — no per-file import needed. Otherwise, add @use "lib/viewport" at the top of the file that uses it.

@include viewport.from(lg) {
  // Applies at lg (1024px) and larger
}

@include viewport.until(sm) {
  // Applies below sm (640px)
}

@include viewport.between(sm, md) {
  // Applies between sm (640px) and md (768px)
}

Breakpoints

JavaScript (Advanced Cases)

For conditional rendering in components, use the capabilities service:

import Component from "@glimmer/component";
import { service } from "@ember/service";

class MyComponent extends Component {
  @service capabilities;

  <template>
    {{#if this.capabilities.viewport.lg}}
      Only shown on lg and larger
    {{/if}}
  </template>
}

Touch Detection

html.discourse-touch {
  // Touch devices (phones, tablets, touch laptops)
}

html.discourse-no-touch {
  // Non-touch devices
}

Localized Strings

Locale File Structure

locales/en.yml:

en:
  theme_metadata:
    description: "My theme description"
    settings:
      my_setting: "Description of my_setting"
  homepage:
    welcome: "Welcome to our community"
    topic_count:
      one: "%{count} topic"
      other: "%{count} topics"

Using Theme Strings in Templates

themePrefix is automatically injected in .gjs files — no import needed. It resolves the key under the theme's namespace (theme_translations.{themeId}.{key}).

import { i18n } from "discourse-i18n";

<template>
  {{! Theme string via themePrefix }}
  {{i18n (themePrefix "homepage.welcome")}}

  {{! Pluralized theme string }}
  {{i18n (themePrefix "homepage.topic_count") count=@topicCount}}

  {{! Passing theme string key to a component }}
  <DButton @label={{theme-prefix "homepage.welcome"}} />
</template>

Using Core Strings

Reference core i18n strings directly without themePrefix:

import { i18n } from "discourse-i18n";

<template>
  {{! Core string — no themePrefix }}
  {{i18n "topic.create"}}
</template>

Theme Settings

Settings are defined in settings.yml at the theme root. Type is auto-detected from the default value unless explicitly set.

Setting Types

Integer

max_items:
  type: integer
  default: 5
  min: 1
  max: 20

Float

opacity:
  type: float
  default: 0.8
  min: 0.0
  max: 1.0

String

heading_text:
  default: "Welcome"

custom_css_class:
  default: ""
  min: 0
  max: 50

bio_text:
  default: ""
  textarea: true

Bool

show_banner: true

show_sidebar:
  default: false

Enum

layout_style:
  type: enum
  default: grid
  choices:
    - grid
    - list
    - cards

List

Pipe-separated values. The list_type controls the admin UI widget.

# Plain list (default)
featured_tags:
  type: list
  default: "announcements|support|feedback"

# Compact list with predefined choices
layout_options:
  type: list
  list_type: compact
  default: "grid|list"

# Category picker
homepage_categories:
  type: list
  list_type: category
  default: ""

# Tag picker
featured_tags:
  type: list
  list_type: tag
  default: ""

# Simple (tag-style free-form input)
contact_fields:
  type: list
  list_type: simple
  default: "email|phone"

Upload

Stores a file upload. The value is a CDN URL in JavaScript.

hero_image:
  type: upload
  default: ""

Objects

Structured data with schema validation. Stored as JSON. Max 0.5 MB.

navigation_links:
  type: objects
  default:
    - label: "Home"
      url: "/"
      icon: "house"
    - label: "About"
      url: "/about"
      icon: "circle-info"
  schema:
    name: link
    properties:
      label:
        type: string
        required: true
        validations:
          min_length: 1
          max_length: 100
      url:
        type: string
        required: true
        validations:
          url: true
      icon:
        type: string

Object property types: string, integer, float, boolean, datetime, upload, enum, categories, groups, tags, objects (nested).

Validations by type:

• string: min_length, max_length, url (boolean)
• integer/float: min, max
• categories/groups/tags: min, max (item count)

Accessing Settings in JavaScript

The settings object is automatically injected in theme .gjs files:

// In an api-initializer:
const heroImage = settings.hero_image;
const links = settings.navigation_links;

Setting Descriptions in Locales

en:
  theme_metadata:
    settings:
      show_banner: "Toggle the hero banner on the homepage"
      navigation_links: "Configure the navigation links"

Theme Modifiers

Modifiers are declared in the modifiers key of about.json. They affect server-side behavior.

Boolean Modifiers

String Array Modifiers

Complex Modifiers

Example

{
  "modifiers": {
    "serialize_topic_excerpts": true,
    "custom_homepage": true,
    "svg_icons": ["star", "rocket", "chart-line", "far-comments"],
    "topic_thumbnail_sizes": ["400x300"]
  }
}

Setting-Dependent Modifiers

Pull modifier values from a theme setting:

{
  "modifiers": {
    "serialize_topic_excerpts": {
      "type": "setting",
      "value": "enable_excerpts"
    }
  }
}

Font Awesome Icons

Discourse uses Font Awesome 6 Free (solid, regular, brands) plus custom Discourse icons. See icons.md for the full default icon list.

Icon Name Conventions

Adding Non-Default Icons

For any icon not in the default set, add it to svg_icons in about.json:

{
  "modifiers": {
    "svg_icons": ["chart-line", "wand-magic-sparkles", "far-face-grin"]
  }
}

Custom SVG Icons

Upload a custom SVG sprite file as a theme asset with variable name icons-sprite. Icons are registered using their <symbol> IDs.

Icon Replacement

Replace icons globally via the plugin API:

api.replaceIcon("heart", "thumbs-up");

Value and Behavior Transformers

Transformers let themes modify values and behavior used by core components. See transformers.md for the full list.

Value Transformers

Register in an api-initializer. The callback receives the current value and context:

api.registerValueTransformer("transformer-name", ({ value, context }) => {
  return transformedValue;
});

Commonly used value transformers for theming:

Behavior Transformers

Wrap core logic with chainable callbacks. Call next() to continue the chain; omit it to override:

api.registerBehaviorTransformer("topic-list-item-click", ({ next, context }) => {
  if (context.topic.pinned) {
    // Custom handling for pinned topics
    return;
  }
  next();
});

CSS Variables

Discourse defines ~400 CSS custom properties. Override them in your theme's SCSS. See css-variables.md for the full listing.

Key variable categories and examples:

// Core colors
--primary, --secondary, --tertiary, --quaternary, --danger, --success

// Spacing (base unit: 0.25rem)
--space-1 through --space-12

// Typography
--font-up-1 through --font-up-6, --font-down-1 through --font-down-6
--font-family, --heading-font-family

// Layout
--d-max-width, --d-sidebar-width, --d-border-radius

// Component-specific
--d-button-{variant}-bg-color, --d-input-border, --d-nav-color
--d-topic-list-title-font-size, --d-sidebar-link-color

Testing

Themes include a system spec at spec/system/core_features_spec.rb that runs shared examples from Discourse core to verify basic functionality (login, topic creation, search, etc.) still works with the theme active.

Core Features Spec

The generated spec looks like:

RSpec.describe "Core features" do
  before { upload_theme_or_component }

  it_behaves_like "having working core features"
end

Skipping Examples

If the theme intentionally changes behavior that causes a core features test to fail (e.g., a custom homepage without a Create Topic button), skip that example rather than removing the entire spec:

RSpec.describe "Core features" do
  before { upload_theme_or_component }

  it_behaves_like "having working core features",
                  skip_examples: %i[topics:create]
end

Available skip keys: login, likes, profile, topics, topics:read, topics:reply, topics:create, search, search:quick_search, search:full_page.

To find the right key, look in core's spec/support/shared_examples/core_features.rb for the skip_examples.exclude? guard around the failing example.

Only skip examples when the failure is caused by intentional theme behavior, not actual bugs.

Key Files Reference