Criar um subtema do DXPR Theme (Drupal 11).

Learn DXPR ThemeEen subthema maken

O DXPR Theme muda cores, tipos de letra, cabeçalho, espaçamento e disposição no painel de definições, por isso a maioria dos sites nunca precisa de uma linha de CSS. Um subtema é para o resto: a sua própria folha de estilos, substituições de modelos, bibliotecas extra ou uma paleta de cores distribuída com o código. O subtema herda todas as folhas de estilos e modelos do DXPR Theme, tem as suas próprias definições, e as atualizações do DXPR Theme não lhe tocam.

Este guia abrange o DXPR Theme 8.2 em Drupal 10.3 e Drupal 11. O kit inicial que usa vem dentro do tema em dxpr_theme/dxpr_theme_STARTERKIT; o comando generate-theme do núcleo do Drupal não é usado, porque o DXPR Theme traz o seu próprio kit inicial e comando.

Antes de começar

Adicione o DXPR Theme e ative o seu módulo auxiliar, de que o tema precisa antes de o Drupal o instalar:

composer require drupal/dxpr_theme
drush en dxpr_theme_helper

1. Gerar o subtema a partir do kit inicial

A forma mais rápida é o comando Drush fornecido pelo DXPR Theme Helper. Execute-o na raiz do projeto; valida o nome de máquina, copia o kit inicial para themes/custom e muda os nomes de tudo por si:

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

Sem argumentos, o comando pede os dois nomes. Sem o Drush, use o script incluído no tema: entre em web/themes/contrib/dxpr_theme, torne os scripts executáveis uma vez com chmod +x scripts/*, execute ./scripts/create_subtheme.sh e indique o nome legível e o nome de máquina quando pedido. O script só corre nessa pasta.

De qualquer forma, obtém web/themes/custom/northwind_theme, com os ficheiros e a configuração do kit inicial renomeados para o seu nome de máquina e o THEMETITLE substituído nos ficheiros info e schema.

2. Ativar e guardar as definições uma vez

  1. Aceda a Appearance e escolha Install and set as default para o seu subtema.
  2. Abra as Settings e prima Save configuration sem alterar nada.

Essa primeira gravação gera a folha de estilos de definições para o novo tema. O subtema parte das definições predefinidas do kit inicial, não das definições feitas no DXPR Theme. Para as transferir, exporte-as do DXPR Theme e importe-as para o subtema:

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

A partir daí, o painel funciona exatamente como no DXPR Theme: cores, tipografia, cabeçalho, rodapé e espaçamento pertencem todos ao subtema.

Mantenha as regiões do subtema iguais às do tema base. O kit inicial declara as mesmas catorze regiões do DXPR Theme, e a opção Hide regions para conteúdos do DXPR Theme Helper refere-se a elas pelo nome.

3. O que o kit inicial oferece

  • northwind_theme.info.yml: base theme: dxpr_theme, as regiões e uma biblioteca, global-styling, que carrega a sua folha de estilos. Um bloco libraries-override comentado lista as bibliotecas do DXPR Theme que mais provavelmente vai desativar, de dxpr_theme/bootstrap-5 a dxpr_theme/helper-classes.
  • css/dxpr_theme_subtheme.css: carregada em todas as páginas após as folhas de estilos do próprio tema. O seu CSS fica aqui.
  • templates/: vazia, exceto um README. Copie qualquer modelo de dxpr_theme/templates para aqui para o substituir.
  • config/install e config/schema: as definições predefinidas e o respetivo schema, renomeados para o seu tema.
  • color-settings.json: as suas próprias paletas de cores nomeadas, mostradas na lista de esquemas de cores junto às integradas.
  • logo.svg, favicon.ico, screenshot.png: substitua-os pelos seus.

4. Escrever CSS que segue as definições

O DXPR Theme escreve as suas definições em variáveis CSS: --dxt-color-* para a paleta e --dxt-setting-* para tipografia, espaçamento e disposição, mapeando-as para as variáveis --bs-* do Bootstrap. Use as variáveis na sua folha de estilos em vez de valores fixos, e o seu CSS continua a seguir o painel quando alguém muda uma cor ou um tipo de letra.

/* 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);
}

A cor base, as cores de destaque, o texto, os títulos, as ligações, os cartões e o rodapé têm todos uma variável. A lista completa está no README do tema, em CSS Custom Properties (Variables) Reference.

5. Substituir modelos e bibliotecas

Copie o modelo a alterar de themes/contrib/dxpr_theme/templates para a pasta templates do seu subtema, mantenha o nome do ficheiro, edite-o e limpe as caches. O Drupal escolhe primeiro a cópia do subtema.

Para remover uma folha de estilos ou script do tema base, descomente a linha libraries-override: no ficheiro info juntamente com as linhas das bibliotecas a remover; já estão definidas como false. Para adicionar as suas, declare mais bibliotecas em northwind_theme.libraries.yml e liste-as em libraries no ficheiro info, como o kit inicial faz para global-styling.

6. Disponibilizar as suas classes no DXPR Builder

As classes declaradas em dxpr_builder_classes: no ficheiro info do subtema aparecem no seletor de classes do DXPR Builder, para que os editores apliquem a sua faixa escura ou painel de vidro sem escrever nomes de classes. Estilize a classe em dxpr_theme_subtheme.css, limitada aos elementos do DXPR Builder a que se destina.

7. Distribuir uma paleta de cores com o tema

Adicione esquemas nomeados a color-settings.json na raiz do subtema. Cada esquema define as mesmas chaves usadas pelo painel: base, basetext, link, accent1, accent2, text, headings, card, footer, header, pagetitle e as restantes. O esquema aparece na lista de esquemas de cores do formulário de definições, para que um site mude para a paleta da marca com um clique.

8. Atualizar o DXPR Theme mais tarde

  1. Atualize o tema base com o Composer: composer update drupal/dxpr_theme --with-dependencies.
  2. Execute as atualizações da base de dados e limpe as caches.
  3. Abra o formulário de definições do subtema e grave-o mais uma vez, para que a folha de estilos de definições seja regenerada com as novas variáveis.
  4. Leia as notas de versão para alterações de modelos ou regiões, e compare qualquer modelo substituído com a nova versão.

Deixe o agente de IA tratar do tema

O DXPR Theme 8.1.1 e posteriores incluem uma skill de agente. Execute drush dxt:setup-ai no projeto, e o seu agente de programação (Claude Code, Codex, Gemini CLI ou Cursor) aprende as definições do tema e o seu significado. Descreva a marca, e o agente define cores, tipografia, disposição do cabeçalho e espaçamento com as mesmas definições que o painel grava, para rever no site. Também pode criar o subtema com drush dxt:subtheme:create.

A skill DXPR Builder faz o mesmo para páginas, e o Drush Webmaster para conteúdos e para o Views. Ver as skills de agente em ação.

Perguntas sobre subtemas do DXPR Theme

Não. Cores, tipos de letra, cabeçalho, rodapé, espaçamento e disposição são definições no painel do DXPR Theme. Um subtema só é preciso para o seu próprio CSS, substituições de modelos, bibliotecas extra ou uma paleta distribuída com o código.

Sim. Após drush dxt:setup-ai o agente conhece as definições do tema e altera-as a partir de um briefing, podendo criar o próprio subtema com drush dxt:subtheme:create. Reveja o resultado no site.

As mesmas do DXPR Theme 8.2: Drupal 10.3 e posteriores, e Drupal 11. O ficheiro info do kit inicial declara também versões mais antigas, mas o DXPR Theme 8.2 depende de módulos que exigem Drupal 10.3.

Não. O Composer só substitui themes/contrib/dxpr_theme; o seu subtema está em themes/custom. Grave o formulário de definições do subtema uma vez após uma atualização, para que a sua folha de estilos inclua as novas variáveis.