Instalação

O Velon Design System publica quatro pacotes no registry privado do GitHub Packages.

1. Autenticar no registry

Cada app precisa de um .npmrc na raiz:

@velon-finance:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
always-auth=true

Faça commit deste arquivo. O placeholder ${NODE_AUTH_TOKEN} é resolvido em runtime a partir da env var.

2. Obter um token

Local (cada dev, uma vez)

Gere um Personal Access Token em https://github.com/settings/tokens com o escopo read:packages, depois adicione ao seu ~/.npmrc global:

//npm.pkg.github.com/:_authToken=ghp_your_pat_here

Verifique com npm whoami --registry=https://npm.pkg.github.com.

CI (GitHub Actions)

Um NPM_TOKEN com escopo de leitura para o registry privado fica exposto nos workflows de CI que rodam install:

- name: Install
  run: pnpm install --frozen-lockfile
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Render (builds de produção)

Defina NODE_AUTH_TOKEN como variável de ambiente no serviço, vinda do seu secrets manager.

3. Instalar os pacotes

pnpm add @velon-finance/tokens @velon-finance/tailwind-preset
pnpm add @velon-finance/ui            # when you start consuming components
pnpm add @velon-finance/icons         # when icons are curated

4. Conectar o Tailwind

// tailwind.config.ts
import type { Config } from 'tailwindcss'
import velonPreset from '@velon-finance/tailwind-preset'
 
export default {
  presets: [velonPreset],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@velon-finance/ui/dist/**/*.{js,mjs,cjs}',
  ],
} satisfies Config

O glob content para @velon-finance/ui é obrigatório. O Tailwind precisa escanear o código-fonte do pacote para gerar os utilitários usados dentro dos componentes.

5. Importar as variáveis CSS

/* src/styles/globals.css (or equivalent) */
@import '@velon-finance/tokens/css';
 
@tailwind base;
@tailwind components;
@tailwind utilities;

Isso importa os blocos :root (light) e .dark que alimentam os utilitários semânticos (bg-card, text-foreground, etc.).

6. Usar um componente

import { Button } from '@velon-finance/ui'
 
export function ConfirmButton() {
  return <Button>Confirmar</Button>
}

Troubleshooting

Consulte o guia de uso no BrainOrchard para a tabela de diagnóstico completa, que cobre 401 Unauthorized, 404 Not Found, utilitários faltando, falhas de dark mode e erros EAUTH no Render.

Padrões Como contribuir