@humu-tech/ui

47 primitives · 32 patterns · tema claro/escuro · React 18 · Tailwind preset · TypeScript

Biblioteca de componentes React do Design System V2 da Humu (Inovanti) — extraída dos apps de crédito (admin + portal cliente) para ser consumida por todos os projetos da empresa.

Nome do pacote: publica como @humu-tech/ui (coexiste com o legado @inovanti/react@3). O rebrand do escopo do pacote para @humu/* será feito quando o registry @humu estiver provisionado.

@humu-tech/ui entrega:

• Tokens (@humu-tech/ui/tokens.css) — CSS custom properties em oklch (v4-ready), self-contained, com variantes claro/escuro.
• 47 primitives — Button, Input, Dialog, Combobox, DateInput, Switch, Tabs, Tooltip, Badge, Avatar, etc.
• 32 patterns — DataTable, EmptyState, FilterBarV2, KpiCard, AppShell, Sidebar, DashboardBlock, charts, etc.
• cn — tailwind-merge estendido com os grupos de classe v2.
• Preset Tailwind (@humu-tech/ui/tailwind-preset) — o theme.extend com os utilitários v2.
• Tema claro/escuro — hook useDsV2Theme + componente ThemeToggle, via atributo data-theme na raiz do documento.
• Pronto para Next.js — os bundles emitem "use client" (compatível com App Router/RSC; inerte em Vite).
• Framework-agnóstico — navegação desacoplada via prop linkComponent (sem react-router/next/link embutido).

Instalação

O pacote é publicado no registry privado AWS CodeArtifact (inovanti/bankeiro), o mesmo do @inovanti/*. Com o ~/.npmrc já apontando o escopo @inovanti para lá:

npm install @humu-tech/ui

react e react-dom (^18) são peerDependencies.

Setup

1. Tokens

Importe o CSS de tokens uma vez na raiz do app:

// Vite/CRA: src/main.tsx
import '@humu-tech/ui/tokens.css'

/* Next.js App Router: app/globals.css */
@import '@humu-tech/ui/tokens.css';

2. Tailwind

O preset traz os utilitários v2 (bg-v2-action-primary, text-v2-fg-default, rounded-v2-md, …). Inclua o dist da lib no content para o Tailwind gerar as classes usadas pelos componentes.

Se o app NÃO usa outro preset: adicione como preset normal.

// tailwind.config.ts
export default {
  presets: [require('@humu-tech/ui/tailwind-preset').default],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@humu-tech/ui/dist/**/*.{js,mjs}',
  ],
}

Se o app já usa @inovanti/react/tailwind.config como preset: NÃO empilhe dois presets — o preset do @inovanti/react perde as próprias cores quando combinado com qualquer outro preset. Puxe os tokens via theme.extend em vez de presets:

export default {
  presets: [require('@inovanti/react/tailwind.config')],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@humu-tech/ui/dist/**/*.{js,mjs}',
  ],
  theme: {
    extend: {
      ...require('@humu-tech/ui/tailwind-preset').default.theme.extend,
    },
  },
}

Uso

import { Button, Input, DataTable, cn } from '@humu-tech/ui'

export function Example() {
  return (
    <div className={cn('flex flex-col gap-4')}>
      <Input label="Nome" />
      <Button variant="primary">Salvar</Button>
    </div>
  )
}

Navegação desacoplada

Componentes de navegação (AppShell, Sidebar, Breadcrumb, KpiHero) recebem linkComponent e currentPath por prop — o app injeta o roteador dele:

import { AppShell, type DsLinkComponent } from '@humu-tech/ui'
import { Link, useLocation } from 'react-router-dom'

const RouterLink: DsLinkComponent = ({ to, className, children }) => (
  <Link to={to} className={className}>{children}</Link>
)

<AppShell linkComponent={RouterLink} currentPath={useLocation().pathname} sidebarGroups={groups}>
  {children}
</AppShell>

Sem linkComponent, o default renderiza um <a href>.

Catálogo de componentes

Todos exportados diretamente de @humu-tech/ui (import { X } from '@humu-tech/ui').

Primitives (47)

| Grupo | Componentes | | --- | --- | | Formulário / inputs | Button, Checkbox, CepInput, ColorPicker, Combobox, DateInput, DateRangeInput, DocumentInput, FileUpload, ImageUpload, Input, Label, MaskedInput, MoneyInput, MultiCombobox, OtpInput, PasswordInput, PercentInput, PhoneInput, RadioGroup, Switch, TextArea | | Overlays / menus | ConfirmDialog, ContextMenu, Dialog, Drawer, Dropdown, Popover, Tooltip | | Exibição de dados | Avatar, Badge, Card, CopyButton, Skeleton, Sparkline, SparklineBadge, Text, Heading | | Navegação / layout | Breadcrumb, Separator, Stepper, Tabs | | Feedback | FormAlert, HelpHint, Spinner, Toast(er) | | Tema | ThemeToggle |

Patterns (32)

| Grupo | Componentes | | --- | --- | | Formulário / inputs | FormSection, FormWithAside, WizardShell | | Exibição de dados | DataField, DataTable, DataTablePagination, EmptyState, LegalDocumentRenderer, PanelCard, ReadOnlyDataView, SectionCard, SortableColumnHeader, TutorialCard | | Navegação / layout | AppShell, ErrorPageLayout, NavigatorTile, PublicPageLayout, Sidebar, Topbar | | Gráficos | ChartTimeSeries, DonutChart, HorizontalBarChart, KpiCard, KpiHero, LineChart, StackedBarChart | | Feedback / diversos | CommandPalette, DashboardBlock, DSAccordion, FilterBarV2, NotificationCenter, WorkflowDesigner |

Tema claro/escuro

O DS ativa o tema escuro via :root[data-theme="dark"] (equivalente .dark) nos tokens CSS. A biblioteca fornece as duas peças necessárias para o app consumidor:

• ThemeToggle — botão pronto que cicla light → dark → system, persiste a preferência em localStorage (storageKey, default "ds-v2-theme-preference"), escuta prefers-color-scheme quando a preferência é system, e escreve data-theme/classe dark/light em document.documentElement.
• useDsV2Theme() — hook somente-leitura que observa o atributo data-theme da raiz (via MutationObserver) e retorna 'light' | 'dark' (tipo DsV2Theme) — útil para adaptar lógica de app (ex.: cor de um gráfico de terceiros) ao tema atual sem duplicar a fonte da verdade.

import { ThemeToggle, useDsV2Theme } from '@humu-tech/ui'

function Topbar() {
  const theme = useDsV2Theme() // 'light' | 'dark'
  return (
    <header>
      <span>Tema atual: {theme}</span>
      <ThemeToggle size="md" />
    </header>
  )
}

Não é necessário nenhum ThemeProvider: o estado vive no DOM (data-theme), então qualquer parte da árvore — inclusive fora do React (CSS puro) — reage automaticamente.

Storybook

Catálogo interativo de todos os componentes (com stories co-localizadas) publicado via GitHub Pages a partir do repositório humu-ui (pacote packages/docs).

Versionamento

Este pacote usa changesets para versionamento semântico. Consulte o CHANGELOG.md no registry ou o histórico de tags do repositório para o changelog completo.