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.

Versão do PrimeFaces

A marcação dos componentes muda entre as versões do PrimeFaces, e um CSS só não serve para todas. Por isso há um conjunto de temas por versão, com os mesmos nomes de tema. Baixe o da versão que a aplicação usa:

PrimeFaces	Temas	O que muda nessa versão
10.x	pf10	O .ui-dialog é o painel e o sidebar não tem .ui-sidebar-content. Inclui o carousel, a galleria e o lightbox antigos
15.x	pf15	O dialog ainda não tem .ui-dialog-box, como no 10. As páginas do paginador são button.ui-button
16.x	pf16	O .ui-dialog é o contêiner de tela cheia e o .ui-dialog-box é o painel

O nome configurado em primefaces.THEME é o mesmo nas três versões (mds, mds-dark…). Só o arquivo muda: o JAR leva a versão no nome (primefaces-mds-pf10.jar). Ao atualizar o PrimeFaces, troque o JAR pelo da nova versão.

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.

PrimeFaces 16

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 (100 KB)CSS (336 KB)
• Escuromds-darkAzul dessaturadoJAR (100 KB)CSS (336 KB)
• Escuro navy (dark-blue)mds-dark-blueNavy do Mobiis Dark BlueJAR (100 KB)CSS (336 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

Todos os temas num único JAR: primefaces-mds-todos-os-temas-pf16.jar. É útil quando a aplicação troca de tema em tempo de execução (por exemplo, claro e escuro por usuário).

PrimeFaces 15

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 (100 KB)CSS (330 KB)
• Escuromds-darkAzul dessaturadoJAR (100 KB)CSS (330 KB)
• Escuro navy (dark-blue)mds-dark-blueNavy do Mobiis Dark BlueJAR (100 KB)CSS (330 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

Todos os temas num único JAR: primefaces-mds-todos-os-temas-pf15.jar. É útil quando a aplicação troca de tema em tempo de execução (por exemplo, claro e escuro por usuário).

PrimeFaces 10

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 (100 KB)CSS (333 KB)
• Escuromds-darkAzul dessaturadoJAR (100 KB)CSS (333 KB)
• Escuro navy (dark-blue)mds-dark-blueNavy do Mobiis Dark BlueJAR (100 KB)CSS (333 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

Todos os temas num único JAR: primefaces-mds-todos-os-temas-pf10.jar. É ú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-pf16.jar -DgroupId=com.mobiis.mds \
       -DartifactId=primefaces-mds -Dversion=1.0.0-pf16 -Dpackaging=jar

   <dependency>
       <groupId>com.mobiis.mds</groupId>
       <artifactId>primefaces-mds</artifactId>
       <version>1.0.0-pf16</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, sempre da mesma versão do PrimeFaces.

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              # todas as versões e temas, JARs e downloads do site
npm run primefaces:build pf10         # só os temas do PrimeFaces 10
npm run primefaces:build pf16 blue    # só as marcas indicadas, numa versão

Os temas saem em dist/primefaces/<versão>/primefaces-<tema>/ e os JARs em dist/primefaces/<versão>/jar/. Só o build completo atualiza os arquivos de download deste site (JARs, CSS e fonte).

Base de cada versão

Cada versão compila sobre o theme-base do PrimeFaces correspondente: 15.0.19 para o pf15 e 16.0.1 para o pf16. O PrimeFaces não publicou o theme-base do 10. O pf10 usa o 12.0.0, o mais antigo publicado e o mais próximo do Saga que vem no JAR do PrimeFaces 10, e completa o que faltava (carousel e galleria antigos). Os ajustes de cada versão ficam em themes/primefaces/primefaces-mds/versions/.

O que segue o MDS

Componente	Comportamento
Botões	Altura 48px, padding 24px, texto 14px bold, raio 8px, degrau inferior em vez de borda. Sem classe é o control (neutro); ui-button-secondary é o primary. Variantes success, warning, danger e info, outline e flat (Text). Dentro de células de tabela, o tamanho é sm
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	Modal do float-panel sobre o overlay (fundo translúcido + blur). Título, corpo e rodapé em coluna: com conteúdo longo, o corpo rola e o rodapé continua visível. No PrimeFaces 16 o .ui-dialog é o overlay e o .ui-dialog-box o painel; no 10 e no 15 o .ui-dialog é o painel
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
(sem classe) ou ui-button-control	Botão neutro do MDS (.mds-btn--control), para ações como “Cancelar”
ui-button-secondary ou ui-button-primary	Botão primary do MDS (.mds-btn--primary), para a ação principal da tela
ui-button-sm	32px, texto 12px, raio 6px
ui-button-lg	56px, texto 16px, padding 40px

<p:commandButton value="Salvar" styleClass="ui-button-secondary"/>
<p:commandButton value="Cancelar" styleClass="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"/>
        <p:commandButton value="Salvar" styleClass="ui-button-secondary"/>
    </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.

Migrando do tema anterior (Planner)

O tema anterior do Planner era um Saga com cor primária preta, cabeçalhos escuros e espaçamento reduzido. No MDS, o visual segue o design system, mas estes pontos foram mantidos:

• Variáveis --pathfind-planner-primary-color-teste-1 e -2 continuam existindo e apontam para a cor primária do MDS.
• Tabelas compactas: o tema anterior reduzia o espaçamento das tabelas. No MDS, use styleClass="ui-datatable-sm" (linhas de 32px) onde a densidade for necessária.
• Ajustes funcionais: data com botão na mesma linha, reticências no texto longo do select, listas do picklist com largura total, botão de fechar dentro da mensagem, barra de rolagem fina nas áreas roláveis e lightbox com legenda e navegação.

Os botões sem classe agora são o control (neutro). Revise as telas para marcar a ação principal com ui-button-secondary ou ui-button-primary.

Como o tema é feito

O código fica em themes/primefaces/primefaces-mds/ (no repositório mds-styles) 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.