Instalação

O IDPlugger UI é publicado no GitHub Packages, não no npmjs.com. Antes de instalar, o projeto precisa saber que o escopo @handsondigital vem de lá e ter um token do GitHub com permissão read:packages na variável GITHUB_TOKEN.

1. Configure o escopo no projeto que vai usar a biblioteca:

   pnpm

   .npmrc

   @handsondigital:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

   npm

   .npmrc

   @handsondigital:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

   yarn

   Yarn 1 lê o mesmo .npmrc. No Yarn 2 ou superior, use o .yarnrc.yml:

   npmScopes:
     handsondigital:
       npmRegistryServer: 'https://npm.pkg.github.com'
       npmAuthToken: '${GITHUB_TOKEN}'

   bun

   bunfig.toml (o Bun também lê o .npmrc; o bunfig.toml lê variáveis de .env):

   [install.scopes]
   "@handsondigital" = { token = "$GITHUB_TOKEN", url = "https://npm.pkg.github.com/" }

2. Instale uma versão exata (promoções no ar não devem receber atualizações automáticas):

   pnpm

   pnpm add --save-exact @handsondigital/idplugger-ui@3.0.0

   npm

   npm install --save-exact @handsondigital/idplugger-ui@3.0.0

   yarn

   yarn add --exact @handsondigital/idplugger-ui@3.0.0

   bun

   bun add --exact @handsondigital/idplugger-ui@3.0.0

   React e ReactDOM 18 ou superior precisam estar no projeto.

3. Importe os tokens e o CSS uma vez, no CSS global do app:

   src/index.css

   @import '@handsondigital/idplugger-ui/tokens.css';
   @import '@handsondigital/idplugger-ui/fonts.css'; /* só com a identidade idPlugger */
   @import '@handsondigital/idplugger-ui/style.css';

   O fonts.css traz as fontes da idPlugger (Poppins e VAG Rundschrift D) e é opcional: em hotsites de outras marcas, não importe e defina as fontes da marca (veja Tipografia). Vite e webpack copiam os arquivos de fonte sozinhos.

4. Use os componentes:

   src/Participar.tsx

   import { AppButton } from '@handsondigital/idplugger-ui'
   
   export function Participar() {
     return <AppButton onClick={() => console.log('Participação enviada')}>Participar</AppButton>
   }

Com Tailwind

O Tailwind é opcional. Escolha o CSS do pacote conforme a versão:

Sem Tailwind ou Tailwind 3

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

Para usar bg-brand-primary e afins no próprio app com Tailwind 3, adicione o preset @handsondigital/idplugger-ui/tailwind.config.js em presets.

Tailwind 4

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

A ordem das camadas é obrigatória: com idplugger-ui antes de base, o preflight zera fundo e raio dos botões. Assim, utilitários passados em className vencem o CSS do pacote.

Cuidado

Não use style.layer.css com Tailwind 3: o preflight dele não tem camada e venceria o pacote.

Só o CSS dos componentes que você usa

Em vez do style.css, importe o tokens.css e o CSS de cada componente. Dependências vêm por @import; as fontes da idPlugger continuam no fonts.css, à parte.

@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';

Com Tailwind 4, use css/layer/<Nome>.css com a mesma ordem de camadas. Não misture com style.css ou style.layer.css. Mais detalhes e tamanhos em CSS e Tailwind.

Com Next.js

Importe o CSS no layout raiz (app/layout.tsx) e use os componentes dentro de Client Components: o pacote não declara 'use client', e AppModal, AppToast, AppPagination, AppInput e AppTextarea usam hooks.

app/layout.tsx

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

app/participar.tsx

'use client'

import { AppButton } from '@handsondigital/idplugger-ui'

export function Participar() {
  return <AppButton>Participar</AppButton>
}

Trocar a marca

Para outra marca, sobrescreva o contrato da marca (--color-brand-*, --font-brand-*, --radius-brand) depois dos imports ou importe um preset de @handsondigital/idplugger-ui/themes/ e marque o elemento com data-brand.