Temas PrimeFaces

Para projetos JSF com PrimeFaces, o MDS gera temas prontos. Eles seguem o Saga, o tema oficial do PrimeFaces: mesmos componentes e mesma estrutura de variáveis. As cores, a tipografia (Manrope), os raios, os espaçamentos e o comportamento dos componentes vêm do MDS.

Os temas são gerados dos mesmos tokens do @mobiis/mds-style. Uma tela em PrimeFaces e uma tela feita com o CSS do MDS ficam com as mesmas cores, no claro e no escuro.

Downloads

Cada tema está disponível em dois formatos:

• JAR: pronto para o classpath, com o CSS e a fonte. É a forma recomendada.
• CSS: o mesmo theme.css do JAR, para colocar nos recursos da aplicação. Precisa da fonte Manrope ao lado. Veja Usar o CSS em vez do JAR.

Temas principais

Os três temas com as cores primárias da Mobiis (brand-mobiis). Use estes, a menos que o produto tenha outra cor primária.

• ClaromdsTema padrãoJAR (96 KB)CSS (291 KB)
• Escuromds-darkAzul dessaturadoJAR (96 KB)CSS (291 KB)
• Escuro navy (dark-blue)mds-dark-blueNavy do Mobiis Dark BlueJAR (96 KB)CSS (291 KB)

Variações de cor primária

Os mesmos temas, trocando a cor primária, como o data-primary do CSS. Use só quando o produto ou tenant tiver outra cor de marca.

Primary	Claro	Escuro	Escuro navy (dark-blue)
blue	mds-blue JAR · CSS	mds-blue-dark JAR · CSS	mds-blue-dark-blue JAR · CSS
teal	mds-teal JAR · CSS	mds-teal-dark JAR · CSS	mds-teal-dark-blue JAR · CSS
aqua	mds-aqua JAR · CSS	mds-aqua-dark JAR · CSS	mds-aqua-dark-blue JAR · CSS
green	mds-green JAR · CSS	mds-green-dark JAR · CSS	mds-green-dark-blue JAR · CSS
yellow	mds-yellow JAR · CSS	mds-yellow-dark JAR · CSS	mds-yellow-dark-blue JAR · CSS
orange	mds-orange JAR · CSS	mds-orange-dark JAR · CSS	mds-orange-dark-blue JAR · CSS
red	mds-red JAR · CSS	mds-red-dark JAR · CSS	mds-red-dark-blue JAR · CSS
pink	mds-pink JAR · CSS	mds-pink-dark JAR · CSS	mds-pink-dark-blue JAR · CSS

Também há um pacote com todos os temas num único JAR: primefaces-mds-todos-os-temas.jar. Ele é útil quando a aplicação troca de tema em tempo de execução (por exemplo, claro e escuro por usuário).

Instalação

1. Adicione o JAR ao projeto. Copie o arquivo baixado para WEB-INF/lib ou instale no repositório Maven local e declare a dependência:

   mvn install:install-file -Dfile=primefaces-mds.jar -DgroupId=com.mobiis.mds \
       -DartifactId=primefaces-mds -Dversion=1.0.0 -Dpackaging=jar

   <dependency>
       <groupId>com.mobiis.mds</groupId>
       <artifactId>primefaces-mds</artifactId>
       <version>1.0.0</version>
   </dependency>

   Dentro do JAR, o tema fica em META-INF/resources/primefaces-<tema>/ (theme.css e a fonte Manrope), que é onde o PrimeFaces procura.

2. Configure o tema no web.xml. O valor é o nome do tema, como aparece nas tabelas acima:

   <context-param>
       <param-name>primefaces.THEME</param-name>
       <param-value>mds</param-value>
   </context-param>

   Para alternar entre claro e escuro, use uma expressão EL, como #{preferencias.tema}, que devolva mds, mds-dark ou mds-dark-blue. Nesse caso, inclua os três JARs, ou o pacote com todos os temas.

Usar o CSS em vez do JAR

Coloque o CSS e a fonte na pasta de recursos JSF da aplicação, numa biblioteca com o nome primefaces-<tema>. Renomeie o CSS para theme.css:

src/main/webapp/resources/primefaces-mds/theme.css
src/main/webapp/resources/primefaces-mds/fonts/Manrope-VariableFont_wght.ttf

Depois configure primefaces.THEME com mds, como no passo 2. O CSS carrega a fonte por #{resource['primefaces-mds:fonts/…']}, uma expressão que o JSF resolve. Por isso ele precisa ser servido pelo PrimeFaces, como tema, e não por um <link> comum. Não minifique o arquivo: os minificadores alteram essa expressão.

Gerar a partir do código

Os downloads acima são gerados pelo build do mds-styles. Para gerar localmente (por exemplo, depois de mudar tokens):

npm run tokens                        # se os tokens mudaram
npm run primefaces:build              # todos os temas, JARs e downloads do site
npm run primefaces:build blue red     # só as marcas indicadas

Os temas saem em dist/primefaces/primefaces-<tema>/ e os JARs em dist/primefaces/jar/. O build completo também atualiza os arquivos de download deste site (JARs, CSS e fonte).

Versão do PrimeFaces

O build usa o theme-base do PrimeFaces 16.0.1. A estrutura do dialog e do sidebar segue o PrimeFaces 15 em diante (.ui-dialog como contêiner e .ui-dialog-box como painel). Para outra versão, rode PF_VERSION=15.0.5 npm run primefaces:build. Versões anteriores à 15 não são compatíveis.

O que segue o MDS

Componente	Comportamento
Botões	Altura 48px, padding 24px, texto 14px semibold, raio 8px, degrau inferior em vez de borda, variantes primary, control, success, warning, danger e info, outline e flat
Campos	Altura 48px, borda 2px, rótulo flutuante e estados do MDS: preenchido, foco, obrigatório vazio, inválido e desabilitado
Tabela	Cabeçalho dimmed-3, linhas de 48px, zebra e hover do .mds-table, borda e raio no contêiner
Dialog	.ui-dialog como overlay (fundo translúcido + blur) e .ui-dialog-box como o modal do float-panel
Sidebar	Mesma estrutura interna do modal, abrindo pela lateral

Classes extras

O PrimeFaces não tem algumas variações do MDS. O tema adiciona estas classes, usadas pelo styleClass dos componentes.

Botões

Classe	Uso
ui-button-secondary ou ui-button-control	Botão neutro do MDS (.mds-btn--control), para ações como “Cancelar”
ui-button-sm	32px, texto 12px, raio 6px
ui-button-lg	56px, texto 16px, padding 40px

<p:commandButton value="Cancelar" styleClass="ui-button-secondary ui-button-sm"/>

Campos

Classe	Altura	Fonte
ui-inputfield-xs	24px	12px
ui-inputfield-sm	32px	14px
(padrão)	48px	16px
ui-inputfield-lg	56px	20px

Rótulo flutuante: o rótulo vem depois do campo, dentro de ui-float-label. O estado “obrigatório vazio” é aplicado automaticamente quando o componente tem required="true".

<span class="ui-float-label">
    <p:inputText id="placa" value="#{bean.placa}" required="true"/>
    <p:outputLabel for="@previous" value="Placa do veículo"/>
</span>

Dialog

Larguras do float-panel pelo styleClass: ui-dialog-xs (320px), ui-dialog-sm (540px), ui-dialog-md (720px), ui-dialog-lg (960px) e ui-dialog-xl (1140px). O dialog maximizado ocupa a tela inteira.

Sidebar

O p:sidebar não tem cabeçalho nem rodapé próprios. Use estas classes dentro dele para ter a mesma estrutura do modal:

<p:sidebar widgetVar="sbEntrega" position="right" styleClass="ui-sidebar-sm">
    <div class="ui-sidebar-header"><span class="ui-sidebar-title">Detalhes da entrega</span></div>
    <div class="ui-sidebar-body">…</div>
    <div class="ui-sidebar-footer">
        <p:commandButton value="Cancelar" styleClass="ui-button-secondary"/>
        <p:commandButton value="Salvar"/>
    </div>
</p:sidebar>

Nas laterais, o sidebar ocupa a altura total (620px de largura por padrão, ou ui-sidebar-sm, -md, -lg). No topo e na base, ocupa a largura total, com altura até 80vh.

Como o tema é feito

O código fica em primefaces/primefaces-mds/ e o build em scripts/primefaces/build-theme.js:

• _variables.scss define as variáveis do Saga com os tokens do MDS. Os valores vêm dos JSON gerados por npm run tokens, sem hexadecimal fixo.
• _extensions.scss adiciona o que o Saga não cobre por variável: o layout dos botões, os estados de campo, a tabela, o dialog, o sidebar e as classes extras.
• theme.scss (claro) e theme-dark.scss (variações escuras) são os pontos de entrada.

Quando os tokens mudam, rode npm run tokens e depois npm run primefaces:build para os temas acompanharem.

Limitações conhecidas

• Componentes compostos: os tamanhos de campo valem para campos com .ui-inputfield (inputText, password, inputMask, inputTextarea, inputNumber). No datePicker e no autoComplete, use inputStyleClass. selectOneMenu, chips e spinner ficam no tamanho padrão.
• Seletor :has(): usado nos estados do rótulo flutuante e na máscara do sidebar. Funciona no Chrome 105+, Safari 15.4+ e Firefox 121+.
• Texto de ajuda dos campos: o .mds-input__helper ainda não tem equivalente; o p:message inline segue o estilo do Saga.