FinqUI

Design system da FINQIA sobre Material UI v9. O FinqUI é um wrapper fino do Material UI: ele re-exporta a API do MUI (mesmos componentes, mesmas props) e agrega o design system da FINQIA — tema, cores, tipografia, fontes e overrides, aplicados pelo FinqUIProvider. Todo projeto que usa a lib herda a mesma aparência sem configurar nada.

Por que usar a lib (e não o MUI direto)?

1. Design system garantido — FinqUIProvider aplica tema/tipografia/cores/overrides; todo projeto fica idêntico.
2. Componentes próprios compartilhados — Kpi, StatusChip, DetailDrawer, gráficos, app shell (Sidebar/Topbar)…
3. Ponto único de versão — atualiza-se a MUI/o tema num lugar só; todos os projetos herdam.
4. Helpers/hooks/tokens compartilhados (formatMoney, usePagination, styles.css).

A API é a do Material UI v9 — sem camada de abstração, sem trocar de engine.

Install

npm install @finqia/finqui
# peers (a aplicação fornece):
npm install react react-dom @mui/material@^9 @emotion/react @emotion/styled

Uso

import { FinqUIProvider, Button, TextField, Kpi } from "@finqia/finqui";
import "@finqia/finqui/styles.css";

export default function App() {
  return (
    <FinqUIProvider mode="light">
      <Button variant="contained">Entrar</Button>
      <TextField label="E-mail" size="small" />
      <Kpi label="Carteira" value="R$ 1,2 mi" delta="+4,8%" deltaDir="up" />
    </FinqUIProvider>
  );
}

<Button>, <TextField>, <Table> etc. são os componentes do Material UI (re-exportados) — a aparência FINQIA vem do tema. FinqUIProvider aplica ThemeProvider + CssBaseline com makeFinqiaTheme.

Modo escuro: mode="dark" e data-theme="dark" num wrapper (para os tokens CSS dos gráficos/timeline acompanharem).

Tree-shaking: como a lib re-exporta @mui/material (que é sideEffects:false), import { Button } from "@finqia/finqui" puxa só o Button, não a lib inteira.

O que é exportado

| Grupo | Exports | | --------------- | ------------------------------------------------------------------------------------------------ | | Material UI v9 | toda a API do @mui/material (Button, TextField, Table, styled, createTheme, …) | | Provider / Tema | FinqUIProvider, makeFinqiaTheme, ThemeMode | | Componentes | Kpi, StatusChip, DetailDrawer, Spec, Pager, Timeline | | Gráficos | BarChart, HBar, Donut | | App shell | Sidebar, Topbar, BrandMotif | | Ícones do Material | todos os ícones SVG do @mui/icons-material, via subpath @finqia/finqui/icons (import { Home } from "@finqia/finqui/icons"). | | Ícones de marca | ICONS, StrokeIcon (SVG inline). Alternativas: <Icon> (fonte, do MUI). | | Hooks / Helpers | usePagination, useDebouncedValue; formatMoney, formatDate, show, formatCPF, formatCNPJ, formatCEP, formatPhone, formatPercent |

usePagination do FinqUI (paginação client-side) prevalece sobre o usePagination homônimo do MUI. Para o hook do MUI, importe direto de @mui/material.

Estrutura (src)

core/        FinqUIProvider (aplica o tema + CssBaseline)
theme/       makeFinqiaTheme — overrides do MUI = a aparência FINQIA
components/  Kpi, StatusChip, DetailDrawer, Spec, Pager, Timeline,
             Sidebar, Topbar, BrandMotif, charts/, icons (marca)
helpers/ hooks/ types/ styles/tokens.css → "finqui/styles.css"
icons.ts     export * from "@mui/icons-material" → subpath "finqui/icons"
index.ts     export * from "@mui/material" + o que está acima

Build

npm run build   # tsup → dist/ (ESM + d.ts) + styles.css

Documentação e playground: workspace docs/ (Storybook). npm run dev na raiz do monorepo. Veja Primitivos (componentes do MUI) e Componentes (composições próprias).

Ou acesse https://finqui.finqia.com.br