CSS e Tailwind

Tailwind no consumidor não é necessário para os componentes. Há duas variantes do mesmo CSS; escolha pela versão do Tailwind (ou por nenhum).

Arquivo	Quando usar
style.css (sem camada)	Sem Tailwind ou com Tailwind 3
style.layer.css (em @layer idplugger-ui)	Tailwind 4 e outros projetos que usam camadas

Os dois precisam do tokens.css antes.

Sem Tailwind / Tailwind 3

src/index.css

@import '@handsondigital/idplugger-ui/tokens.css';
@import '@handsondigital/idplugger-ui/style.css';

O preflight do Tailwind 3 também é CSS sem camada e não zera os componentes.

Tailwind 4

src/index.css

@layer theme, base, idplugger-ui, components, utilities;
@import 'tailwindcss';
@import '@handsondigital/idplugger-ui/tokens.css';
@import '@handsondigital/idplugger-ui/style.layer.css';

Cuidado

Não use style.layer.css com Tailwind 3: o preflight dele não tem camada e venceria o pacote, deixando botões, inputs e títulos sem estilo. Camadas exigem Chrome 99+, Safari 15.4+ ou Firefox 97+.

Só o CSS dos componentes que você usa

Em vez do style.css completo, importe o tokens.css (+ tema) e o CSS de cada componente. O arquivo tem o nome da pasta do componente (AppTabs.css cobre AppTabList, AppTab e AppTabPanel). Dependências vêm por @import (as fontes da idPlugger ficam no fonts.css, opcional): não é preciso importar a base nem as dependências à mão.

Sem Tailwind / Tailwind 3

src/index.css

@import '@handsondigital/idplugger-ui/tokens.css';
@import '@handsondigital/idplugger-ui/css/AppButton.css';
@import '@handsondigital/idplugger-ui/css/Container.css';
@import '@handsondigital/idplugger-ui/css/Grid.css';

Tailwind 4

src/index.css

@layer theme, base, idplugger-ui, components, utilities;
@import 'tailwindcss';
@import '@handsondigital/idplugger-ui/tokens.css';
@import '@handsondigital/idplugger-ui/css/layer/AppButton.css';
@import '@handsondigital/idplugger-ui/css/layer/Container.css';
@import '@handsondigital/idplugger-ui/css/layer/Grid.css';

Não misture com style.css nem style.layer.css. No Next.js, os mesmos imports funcionam em app/layout.tsx.

Cenário	CSS (gzip)
style.css completo (sem fontes)	~10,9 kB
Landing com Button, Container e Grid	~3,1 kB
Com formulário de cadastro (Button, Input, Select, Checkbox, Modal, Toast, Alert, Container, Grid)	~5,5 kB
Hotsite completo típico (18 componentes)	~8,4 kB

Tailwind 3: preset

Para usar bg-brand-primary e afins no seu app, adicione o preset exportado pelo pacote:

tailwind.config.js

import idpluggerPreset from '@handsondigital/idplugger-ui/tailwind.config.js'

export default {
  presets: [idpluggerPreset],
  content: ['./src/**/*.{ts,tsx}'],
}

Tailwind 4: @theme

O tokens.css já traz um bloco @theme (utilitários como bg-brand-primary e text-gray-700) e um @theme inline. Navegadores ignoram essas regras; só o Tailwind 4 as processa.

O @theme inline aponta utilitários para tokens derivados (--font-heading, --font-body, --color-button-primary, --shadow-button…). Ele é inline para o utilitário ler var(--button-*) no próprio elemento e acompanhar data-brand e data-theme, em vez de um valor resolvido no :root.

Ordem das camadas

A ordem theme, base, idplugger-ui, components, utilities é obrigatória e deve vir antes dos imports. Com idplugger-ui antes de base, o preflight zera fundo e raio dos botões. Com o pacote entre base e os utilitários, bg-*, rounded-* etc. passados em className vencem o CSS do pacote.

Com Tailwind 4, use style.layer.css: com o style.css sem camada, os utilitários perdem para o pacote, porque CSS sem camada vence o das camadas do Tailwind.

Sobrescrever estilos

className é apenas anexada (sem tailwind-merge).

Classes BEM

A API pública de classes BEM (app-button--primary-solid) é estável. As regras são de classe única:

• Com style.css, carregue o seu CSS depois dele ou use um seletor mais específico.
• Com style.layer.css, qualquer CSS fora da camada ou em camada posterior vence.

meu-hotsite.css

.minha-tela .app-button--primary-solid {
  letter-spacing: 0.02em;
}

Tokens de componente

Para ajustar um componente sem mudar a marca, sobrescreva o token dele (veja Design system):

meu-hotsite.css

.minha-tela {
  --button-shadow: none;
}

Para trocar a identidade, sobrescreva o contrato da marca em vez dos tokens --button-*: veja Marcas e presets.