Creating a DXPR Theme subtheme (Drupal 11).

Learn DXPR ThemeCreating a sub-theme

DXPR Theme changes colors, fonts, header, spacing and layout from its settings dashboard, so most sites never need a line of CSS. A subtheme is for the rest: your own stylesheet, template overrides, extra libraries or a color palette you ship with the code. The subtheme inherits every stylesheet and template of DXPR Theme, gets its own settings, and updates to DXPR Theme leave it untouched.

This guide covers DXPR Theme 8.2 on Drupal 10.3 and Drupal 11. The starter kit it uses ships inside the theme at dxpr_theme/dxpr_theme_STARTERKIT; Drupal core's generate-theme command is not used, because DXPR Theme brings its own starter kit and command.

Before you start

Add DXPR Theme and enable its helper module, which the theme needs before Drupal will install it:

composer require drupal/dxpr_theme
drush en dxpr_theme_helper

1. Generate the subtheme from the starter kit

The quickest way is the Drush command that DXPR Theme Helper provides. Run it from your project root; it validates the machine name, copies the starter kit into themes/custom and renames everything for you:

drush dxt:subtheme:create northwind_theme --theme-name="Northwind Theme"

Without arguments the command asks for both names. Without Drush, use the script that ships with the theme: change into web/themes/contrib/dxpr_theme, make the scripts executable once with chmod +x scripts/*, run ./scripts/create_subtheme.sh and enter the human name and the machine name when asked. The script only runs from that folder.

Either way you get web/themes/custom/northwind_theme, with the starter kit's files and configuration renamed to your machine name and the THEMETITLE placeholder replaced in the info and schema files.

2. Enable it and save the settings once

  1. Go to Appearance and choose Install and set as default for your subtheme.
  2. Open the subtheme's Settings and press Save configuration without changing anything.

That first save generates the settings stylesheet for the new theme. The subtheme starts from the starter kit's default settings, not from the settings you made in DXPR Theme. To carry those over, export them from DXPR Theme and import them into the subtheme:

drush dxt:config:export --theme=dxpr_theme --file=theme.yml
drush dxt:config:import theme.yml --theme=northwind_theme

From then on the dashboard works exactly as it does for DXPR Theme: colors, typography, header, footer and spacing all belong to the subtheme.

Keep the subtheme's regions identical to the base theme's. The starter kit declares the same fourteen regions as DXPR Theme, and DXPR Theme Helper's Hide regions option on content refers to them by name.

3. What the starter kit gives you

  • northwind_theme.info.yml: base theme: dxpr_theme, the regions, and one library, global-styling, that loads your stylesheet. A commented libraries-override block lists the DXPR Theme libraries you are most likely to switch off, from dxpr_theme/bootstrap-5 to dxpr_theme/helper-classes.
  • css/dxpr_theme_subtheme.css: loaded on every page after the theme's own stylesheets. Your CSS goes here.
  • templates/: empty apart from a README. Copy any template from dxpr_theme/templates here to override it.
  • config/install and config/schema: the default settings and their schema, renamed to your theme.
  • color-settings.json: your own named color palettes, shown in the color scheme list next to the built-in ones.
  • logo.svg, favicon.ico, screenshot.png: replace them with yours.

4. Write CSS that follows the settings

DXPR Theme writes its settings into CSS variables: --dxt-color-* for the palette and --dxt-setting-* for typography, spacing and layout, and it maps them onto Bootstrap's --bs-* variables. Use the variables in your stylesheet instead of fixed values, and your CSS keeps following the dashboard when someone changes a color or a font.

/* css/dxpr_theme_subtheme.css */
.card {
  border-radius: 1rem;
  border-color: color-mix(in srgb, var(--dxt-color-base) 20%, transparent);
}

.dxpr-theme-footer h2 {
  font-family: var(--dxt-setting-headings-font-face);
  color: var(--dxt-color-footertext);
}

The base color, accent colors, text, headings, links, cards and footer all have a variable. The full list is in the theme's README under CSS Custom Properties (Variables) Reference.

5. Override templates and libraries

Copy the template you want to change from themes/contrib/dxpr_theme/templates into your subtheme's templates folder, keep the file name, edit it, and clear caches. Drupal picks the subtheme's copy first.

To drop a stylesheet or script of the base theme, uncomment the libraries-override: line in your info file together with the lines of the libraries you want to remove; they are already set to false. To add your own, declare more libraries in northwind_theme.libraries.yml and list them under libraries in the info file, as the starter kit does for global-styling.

6. Give editors your classes in DXPR Builder

Classes declared under dxpr_builder_classes: in the subtheme's info file appear in the class picker of DXPR Builder, so editors apply your dark band or glass panel without typing a class name. Style the class in dxpr_theme_subtheme.css, scoped to the DXPR Builder elements it is meant for.

7. Ship a color palette with the theme

Add named schemes to color-settings.json in the subtheme root. Each scheme sets the same keys the dashboard uses: base, basetext, link, accent1, accent2, text, headings, card, footer, header, pagetitle and the rest. The scheme appears in the color scheme list of the settings form, so a site can switch to the brand palette in one click.

8. Updating DXPR Theme later

  1. Update the base theme with Composer: composer update drupal/dxpr_theme --with-dependencies.
  2. Run database updates and clear caches.
  3. Open the subtheme's settings form and save it once more, so the settings stylesheet is regenerated with any new variables.
  4. Read the release notes for template or region changes, and compare any template you overrode with the new version.

Let your AI agent do the theming

DXPR Theme 8.1.1 and later ship an agent skill. Run drush dxt:setup-ai in your project, and your coding agent (Claude Code, Codex, Gemini CLI or Cursor) learns the theme's settings and their meaning. Describe the brand, and the agent sets colors, typography, header layout and spacing through the same settings the dashboard writes to, for you to review on the site. It can also create the subtheme with drush dxt:subtheme:create.

The DXPR Builder skill does the same for pages, and Drush Webmaster for content and Views. See the agent skills in action.

Questions about DXPR Theme subthemes

No. Colors, fonts, header, footer, spacing and layout are settings in the DXPR Theme dashboard. A subtheme is only needed for your own CSS, template overrides, extra libraries or a palette you ship with the code.

Yes. After drush dxt:setup-ai the agent knows the theme settings and changes them from a brief, and it can create the subtheme itself with drush dxt:subtheme:create. You review the result on the site.

The same as DXPR Theme 8.2: Drupal 10.3 and later, and Drupal 11. The starter kit's info file declares older versions too, but DXPR Theme 8.2 depends on modules that need Drupal 10.3.

No. Composer only replaces themes/contrib/dxpr_theme; your subtheme lives in themes/custom. Save the subtheme's settings form once after an update so its stylesheet picks up new variables.