Installation

The Velon Design System ships four packages from the private GitHub Packages registry.

1. Authenticate the registry

Each app needs an .npmrc at the root:

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

Commit this file. The placeholder ${NODE_AUTH_TOKEN} is resolved at runtime from the env var.

2. Get a token

Local (each developer, once)

Generate a Personal Access Token at https://github.com/settings/tokens with the read:packages scope, then add to your global ~/.npmrc:

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

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

CI (GitHub Actions)

The org-level secret NPM_TOKEN (configured on the velon-finance org with read access to Console / User / Manager) is exposed in workflows that run install:

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

Render (production builds)

Set NODE_AUTH_TOKEN as an environment variable on the service. We source it from Infisical at velon-backend/shared/NODE_AUTH_TOKEN.

3. Install the packages

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. Wire 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

The content glob for @velon-finance/ui is required. Tailwind needs to scan the package’s source so it generates the utilities used inside the components.

5. Import the CSS variables

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

This imports the :root (light) and .dark blocks that power semantic utilities (bg-card, text-foreground, etc.).

6. Use a component

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

Troubleshooting

See the usage guide in BrainOrchard for the full diagnostic table covering 401 Unauthorized, 404 Not Found, missing utilities, dark mode misses, and Render EAUTH failures.

Patterns Contributing