Creating a DXPR Theme subtheme (Drupal 11).

Learn DXPR ThemeCreating a sub-theme

DXPR Theme changes colours, 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 colour palette you ship with the code. The subtheme inherits every setting and every stylesheet of DXPR Theme, 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.

1. Generate the subtheme from the starter kit

The theme ships a script that copies the starter kit into themes/custom and renames everything for you. It expects DXPR Theme to live in themes/contrib/dxpr_theme, which is where Composer installs it.

  1. Open a terminal in your Drupal project and change into the theme: cd web/themes/contrib/dxpr_theme.
  2. Make the scripts executable once: chmod +x scripts/*.
  3. Run ./scripts/create_subtheme.sh.
  4. Enter a human name when asked, for example Northwind Theme, and then a machine name, for example northwind_theme.

The script creates web/themes/custom/northwind_theme, renames the starter kit's files and configuration to your machine name and replaces the THEMETITLE placeholder in the info and schema files. If it stops with an error, read it: it refuses to run from any folder other than themes/contrib/dxpr_theme and it needs both names.

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. From then on the dashboard works exactly as it does for DXPR Theme: colours, typography, header, footer, spacing, all of it belongs to the subtheme now.

Keep the subtheme's regions identical to the base theme's. The starter kit declares the same fourteen regions as DXPR Theme, and the DXPR Theme Helper module relies on that to place its fields and blocks.

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 every DXPR Theme library you can 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 colour palettes, shown in the colour scheme dropdown 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 colour or a font.

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

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

The base colour, accent colours, text, headings, links, cards and footer all have a variable. The full list is in the README of the theme 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 matching line in libraries-override in your info file and set it 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 Builder elements it is meant for.

7. Ship a colour 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, page title and the rest. The scheme appears in the colour scheme dropdown 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 colours, typography, header layout and spacing through Drupal settings, the same place the dashboard writes to.

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

No. Colours, 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 can change them from a brief. Generating the subtheme itself is the shell script above, which an agent can run for you as well.

The starter kit in DXPR Theme 8.2 declares core_version_requirement: ^9.4 || ^10 || ^11, the same as the theme, so it runs on Drupal 10 and Drupal 11.

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