Biblioteca de componentes UI, hooks headless e ferramentas reutilizáveis para projetos React/TypeScript.
O Flowtomic é um sistema de design moderno que oferece componentes UI prontos para uso e hooks headless para máxima flexibilidade. Construído sobre Radix UI e inspirado em shadcn/ui, o Flowtomic permite que você acelere seu desenvolvimento mantendo controle total sobre customização.
- ✅ 54 Atoms - Componentes básicos reutilizáveis
- ✅ 36 Molecules - Componentes compostos
- ✅ 23 Organisms - Componentes complexos
- ✅ 11 Hooks Headless - Lógica reutilizável sem UI
- ✅ 3 Blocks - Templates pré-construídos
- ✅ Arquitetura Separada - UI e lógica completamente desacopladas
- ✅ Customização Total - Componentes copiados para seu projeto
- ✅ TypeScript First - Tipagem completa e type-safe
- ✅ Acessibilidade - Baseado em Radix UI (WAI-ARIA compliant)
# 1. Inicializar configuração do Flowtomic
npx flowtomic-cli@latest init
# 2. Adicionar componentes desejados
npx flowtomic-cli@latest add button card input
# 3. Usar no seu projeto// Importar componentes
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { Input } from "@/components/ui/input";
// Usar componentes
function MyComponent() {
return (
<Card>
<Input placeholder="Digite algo..." />
<Button>Enviar</Button>
</Card>
);
}# Instalar packages npm
npm install @flowtomic/ui @flowtomic/logic
# Usar diretamente
import { Button, Card } from "@flowtomic/ui";
import { useStatCard } from "@flowtomic/logic";💡 Dica: Para customização total, use o CLI. Para uso rápido sem customização, use os packages npm.
No desenvolvimento de software, frequentemente nos deparamos com a repetição das mesmas lógicas, principalmente em projetos grandes. A engenharia de software desenvolveu paradigmas como a Programação Orientada a Objetos (POO) para modelar sistemas com base em entidades do mundo real, promovendo encapsulamento, abstração e reutilização. Posteriormente, surgiram princípios gerais como Don't Repeat Yourself (DRY) e, dentro do paradigma OO, os princípios SOLID (formulados por Robert C. Martin) como boas práticas.
O ambiente frontend, por sua vez, ainda está se desenvolvendo nessa questão. Daí nasce o Flowtomic: uma solução reutilizável com componentes prontos ou customizáveis para acelerar seu desenvolvimento, seguindo as melhores práticas de engenharia de software.
- Reutilização: Componentes e hooks prontos para uso imediato
- Flexibilidade: Customização total ou uso direto dos packages
- Separação de Responsabilidades: UI e lógica completamente desacopladas
- Type Safety: TypeScript em todo o projeto
- Acessibilidade: Componentes acessíveis por padrão (WAI-ARIA)
- Performance: Otimizado para produção
O Flowtomic adota o Composition Pattern como abordagem fundamental de design, construindo interfaces complexas a partir de componentes menores e reutilizáveis, em vez de usar herança. Essa técnica promove flexibilidade, reutilização de código e modularidade.
Composição sobre Herança: A abordagem fundamental do React é a composição, onde componentes menores são combinados para criar outros maiores e mais complexos. Isso evita o acoplamento excessivo e a rigidez da herança de classes.
Reutilização de Componentes: Ao quebrar a interface em partes pequenas e isoladas, é possível reutilizá-las em diferentes partes do aplicativo, garantindo consistência e economia de tempo.
Flexibilidade: A composição permite customizar componentes de forma flexível. Um componente Card pode aceitar diferentes tipos de conteúdo através de props e composição de subcomponentes.
Melhor Gerenciamento de Estado: Padrões como Compound Components ajudam a compartilhar estado e lógica entre componentes filhos sem a necessidade de passar muitas props (Prop Drilling), melhorando desempenho e legibilidade.
Modularidade: Cada componente tem sua própria lógica e estilo, tornando o desenvolvimento mais fácil de manter e organizar.
Renderiza conteúdo passado entre as tags de abertura e fechamento de um componente:
import { Card } from "@flowtomic/ui";
function MyComponent() {
return (
<Card>
<h2>Título</h2>
<p>Conteúdo customizado</p>
</Card>
);
}Componente principal que gerencia estado e fornece dados aos componentes filhos via React.Context:
import { Dialog, DialogTrigger, DialogContent } from "@flowtomic/ui";
function MyDialog() {
return (
<Dialog>
<DialogTrigger>Abrir</DialogTrigger>
<DialogContent>
<p>Conteúdo do diálogo</p>
</DialogContent>
</Dialog>
);
}Em vez de adicionar muitas propriedades a um único componente, criamos componentes menores (subcomponentes) para customizar partes específicas:
import { Card, CardHeader, CardTitle, CardContent } from "@flowtomic/ui";
function MyCard() {
return (
<Card>
<CardHeader>
<CardTitle>Título do Card</CardTitle>
</CardHeader>
<CardContent>
<p>Conteúdo do card</p>
</CardContent>
</Card>
);
}- Flexibilidade: Combine componentes de forma dinâmica para criar interfaces complexas
- Reutilização: Componentes pequenos e isolados podem ser reutilizados em diferentes contextos
- Manutenibilidade: Mudanças em um componente não afetam outros componentes compostos
- Testabilidade: Componentes menores são mais fáceis de testar isoladamente
- Performance: Evita prop drilling e permite otimizações mais granulares
flowtomic/
├── packages/
│ ├── ui/ # Componentes UI (flowtomic/ui)
│ │ ├── src/
│ │ │ ├── components/ # Atoms, Molecules, Organisms
│ │ │ └── blocks/ # Blocks pré-construídos
│ │ └── dist/ # Build output
│ └── logic/ # Hooks e lógica (flowtomic/logic)
│ ├── src/
│ │ └── hooks/ # Hooks headless
│ └── dist/ # Build output
├── cli/ # CLI para instalação (flowtomic)
│ ├── src/
│ │ ├── commands/ # Comandos CLI
│ │ └── utils/ # Utilitários
│ └── dist/ # Build output
├── registry/ # Registry para componentes e blocks
├── docs/ # Documentação do projeto
└── .storybook/ # Configuração do Storybook
O Flowtomic segue uma arquitetura de separação clara entre UI e lógica, permitindo máxima flexibilidade e reutilização:
- Componentes UI (
@flowtomic/ui): Focados em apresentação visual, com mínima ou nenhuma lógica de negócio - Hooks Headless (
@flowtomic/logic): Contêm toda a lógica complexa, cálculos e gerenciamento de estado, sem qualquer markup ou estilos
O StatCard demonstra perfeitamente essa arquitetura de separação:
// Hook headless - APENAS lógica, SEM UI
import { useStatCard } from "@flowtomic/logic";
function MyCustomStatCard() {
// Hook fornece toda a lógica de cálculo e formatação
const { formattedValue, trend, getCardProps } = useStatCard({
value: 122380,
lastMonth: 105922, // Delta calculado automaticamente: +15.5%
});
// Você controla completamente o markup e estilos
return (
<div {...getCardProps()}>
<span>{formattedValue}</span>
<Badge variant={trend.variant}>{trend.percentage}</Badge>
</div>
);
}O que o hook fornece:
- ✅ Cálculo automático de delta/variação percentual
- ✅ Formatação de valores (prefix, suffix, custom format)
- ✅ Informações de tendência (direção, variante, porcentagem)
- ✅ Estado e processamento de dados
- ❌ NÃO fornece: markup, styles ou componentes visuais
// Componente visual - usa o hook headless internamente
import { StatCard } from "@flowtomic/ui";
// Componente pronto para uso com UI completa
function Dashboard() {
return (
<StatCard
title="Receita Total"
value={122380}
lastMonth={105922}
color="blue"
/>
);
}O que o componente fornece:
- ✅ Markup completo (Card, Header, Content)
- ✅ Estilos e animações
- ✅ Ícones e badges visuais
- ✅ Menu de ações (opcional)
- ❌ NÃO contém: lógica de cálculo ou processamento complexo
- Reutilização Máxima: Use a lógica (
useStatCard) em qualquer UI customizada - Flexibilidade Total: Crie seu próprio visual mantendo a lógica consistente
- Testabilidade: Teste lógica e UI separadamente
- Manutenibilidade: Mudanças na lógica não afetam o visual e vice-versa
- Composição: Combine múltiplos hooks headless para criar componentes complexos
Use o hook headless quando:
- ✅ Precisa de UI completamente customizada
- ✅ Quer reutilizar a lógica em diferentes contextos
- ✅ Está criando um design system próprio
- ✅ Precisa de controle total sobre o markup
Use o componente visual quando:
- ✅ Precisa de uma solução rápida e pronta
- ✅ O design padrão atende suas necessidades
- ✅ Quer customizar apenas estilos (via
classNameou variáveis CSS) - ✅ Quer começar rápido e iterar depois
O CLI copia os arquivos dos componentes diretamente para o seu projeto, permitindo customização total:
# Inicializar configuração do Flowtomic
npx flowtomic-cli@latest init
# Adicionar componentes individuais
npx flowtomic-cli@latest add button card input
# Adicionar blocks completos
npx flowtomic-cli@latest add-block dashboard-01
# Listar todos os componentes e blocks disponíveis
npx flowtomic-cli@latest listVantagens do CLI:
- ✅ Customização total dos componentes
- ✅ Componentes copiados para seu projeto
- ✅ Imports ajustados automaticamente
- ✅ Controle completo sobre o código
Instale os packages diretamente do npm:
# Instalar packages
npm install @flowtomic/ui @flowtomic/logic
# Ou usando outros gerenciadores
yarn add @flowtomic/ui @flowtomic/logic
pnpm add @flowtomic/ui @flowtomic/logic
bun add @flowtomic/ui @flowtomic/logicVantagens dos packages npm:
- ✅ Instalação rápida
- ✅ Atualizações via npm
- ✅ Sem necessidade de copiar arquivos
⚠️ Customização limitada (apenas viaclassNamee variáveis CSS)
Use o registry do Flowtomic com o shadcn CLI:
# Instalar via shadcn CLI
npx shadcn@latest add https://registry.flowtomic.dev/all.jsonNota: O CLI automaticamente baixa o repositório do GitHub quando necessário (via variável de ambiente ou caminho local).
// Importar componentes UI
import { Button, Card, Input, Badge, Dialog } from "@flowtomic/ui";
// Exemplo de uso
function MyComponent() {
return (
<Card>
<Input placeholder="Digite algo..." />
<Button variant="default">Enviar</Button>
<Badge variant="success">Novo</Badge>
</Card>
);
}// Importar hooks headless
import { useStatCard, useIsMobile, useResizable } from "@flowtomic/logic";
// Exemplo: Hook useStatCard
function MyStatCard() {
const { formattedValue, trend, getCardProps } = useStatCard({
value: 122380,
lastMonth: 105922, // Delta calculado automaticamente: +15.5%
});
return (
<div {...getCardProps()}>
<span>{formattedValue}</span>
<Badge variant={trend.variant}>{trend.percentage}</Badge>
</div>
);
}
// Exemplo: Hook useIsMobile
function ResponsiveComponent() {
const isMobile = useIsMobile();
return <div>{isMobile ? <MobileView /> : <DesktopView />}</div>;
}💡 Dica: Você pode combinar o uso dos packages npm com o CLI. Use os packages para componentes que não precisa customizar e o CLI para componentes que precisa modificar.
Actions:
button- Botão com variantesbadge- Badge/etiquetadropdown-menu- Menu dropdowncontext-menu- Menu de contexto
Animation:
animated-3d- Componente com animação 3Dbackdrop-blur- Componente com efeito de blur no fundoloader- Loading spinner animadoprogress- Barra de progressoshimmer- Texto com efeito shimmersliding-number- Número com animação de deslizamentospinner- Spinner animado
Code:
code-block- Bloco de código com syntax highlightingsnippet- Snippet de código
Data Display:
calendar- Calendáriocarousel- Carrosselchart- Gráficos base
Display:
avatar- Componente de avatar com imagem e fallbackcard- Card containerempty- Estado vaziokbd- Teclas de atalhoseparator- Separador horizontal/verticalskeleton- Loading skeletontable- Tabela base
Feedback:
alert- Alertaalert-dialog- Diálogo de confirmaçãodialog- Modal/diálogohover-card- Card que aparece ao passar o mouseinline-citation- Citação inline com hover cardpopover- Popover flutuantesheet- Sheet lateralsonner- Toast notificationstooltip- Tooltip para informações adicionais
Forms:
autocomplete- Autocompletecheckbox- Checkboxfield- Campo de formulário completoform- Wrapper de formulário com React Hook Forminput- Campo de entradainput-otp- Input para códigos OTPlabel- Label para formuláriosradio-group- Grupo de radio buttonsselect- Campo de seleçãoslider- Slider de valoresswitch- Switch toggletextarea- Campo de texto multilinhatoggle- Toggle button
Layout:
accordion- Container colapsávelaspect-ratio- Container com proporção fixacollapsible- Container colapsáveldrawer- Drawer lateralresizable- Componente redimensionável com painéisscroll-area- Área de scroll customizadasidebar- Sidebar navegáveltoggle-group- Grupo de toggles
Navigation:
breadcrumb- Breadcrumb navigationcommand- Command palette/menumenubar- Barra de menunavigation-menu- Menu de navegaçãopagination- Paginaçãotabs- Abas
Animation:
animated-modal- Modal com animaçõesanimated-sliding-number- Número com animação de deslizamentobutton-counter- Contador com botões de incremento/decremento
Auth:
auth-form-error-message- Mensagem de erro de formulárioauth-navigation-link- Link de navegação de authpassword-input- Input de senhasocial-login-buttons- Botões de login social
Data Display:
artifact- Container de artifactbar-chart- Gráfico de barras simpleschart-area-interactive- Gráfico de área interativochart-bar-interactive- Gráfico de barras interativocheckpoint- Checkpoint displaycircular-progress-chart- Gráfico circular de progressodata-table- Tabela avançadamessage- Componente de mensagem com branchesproject-list- Lista de projetosreminder-card- Card de lembretessources- Lista de fontes colapsávelstat-card- Card de estatísticasuggestion- Lista de sugestõestask- Item de taskteam-member-list- Lista de membros da equipetime-tracker- Timer com controlestool- Display de tool
Feedback:
confirmation- Confirmation dialog wrapper
Flow:
canvas- Canvas do ReactFlowconnection- Connection do @xyflow/react
Forms:
button-group- Grupo de botõesimage-dropzone- Upload de imageminput-group- Grupo de input com addonsitem- Item de formulário
Layout:
dashboard-header- Header com busca, notificações e perfil
Navigation:
menu-dock- Dock de menusidebar-navigation- Menu lateral completo
Theme:
theme-toggle-button- Botão de toggle de tema
Typography:
animated-shiny-text- Texto com efeito shimmer animado
chain-of-thought- Cadeia de raciocíniocontext- Uso de contexto/tokens do modelocontrols- Controls do @xyflow/reactconversation- Container de conversadashboard-header-actions- Ações do headerdashboard-layout- Layout de dashboarddashboard-movements-section- Seção de movimentaçõesedge- Edge do ReactFlowgenealogy-canvas- Canvas de genealogiaimage- Display de imagem geradamodel-selector- Seletor de modelomonthly-summary- Resumo mensalnode- Node do ReactFlowopen-in-chat- Dropdown para abrir em outras plataformaspanel- Panel do @xyflow/reactplan- Exibição de planos do modeloprompt-input- Input de prompt complexoqueue- Fila de mensagens e tarefasreasoning- Exibição de raciocínio do modeloresizable-layout- Componente redimensionável com sidebarscript-editor- Editor de scripts com terminal interativostats-grid- Grid de estatísticastoolbar- Toolbar do @xyflow/reactweb-preview- Visualizador de páginas web
use-animated-indicator- Hook para indicadores animadosuse-genealogy- Hook para gerenciar genealogia/hierarquiause-mobile(exportado comouseIsMobile) - Hook para detectar dispositivos móveisuse-project-progress- Hook para calcular progresso de projetosuse-project-stats- Hook para calcular estatísticas de projetosuse-react-table-back- Hook para tabelas com paginação/ordenação no backenduse-react-table-front- Hook para tabelas com paginação/ordenação no frontenduse-resizable- Hook para componentes redimensionáveisuse-script-editor- Hook para gerenciar editor de scripts com terminal interativouse-stat-card- Hook para StatCarduse-theme-transition- Hook para transições de tema com View Transitions APIuse-time-tracker- Hook para gerenciar timer (start, pause, stop, resume, format)
dashboard-01- Dashboard simples com cardsflowtomic-dashboard- Dashboard completo com sidebar, header, estatísticas, gráficos, listas e timerdeveloper-panel- Painel de desenvolvedor com informações do sistema, ambiente, ferramentas de desenvolvimento e editor de scripts integrado
# Instalar dependências
bun install
# Desenvolvimento com watch (todos os packages)
bun run dev
# Build todos os packages
bun run build
# Build específico
bun run build:ui
bun run build:logic
bun run build:cli
# Type check
bun run type-check
# Linting e formatação
bun run lint # Verificar lint
bun run lint:fix # Corrigir problemas de lint
bun run format # Formatar código
bun run format:check # Verificar formatação
bun run fix:all # Corrigir lint e formatar tudo
# Testes
bun run test
# Storybook
bun run storybook # Iniciar Storybook
bun run build-storybook # Build do Storybook
# Registry
bun run registry:build # Build do registry
bun run registry:server # Servidor do registry (desenvolvimento)
# Limpeza
bun run clean # Limpar builds e node_modulescd cli
bun run dev # Modo desenvolvimento
bun run build # Build
bun run type-check # Verificar tipos- 📚 Índice de Documentação - Guia central de toda a documentação
- Guia de Desenvolvimento - Guia completo de uso do monorepo e CLI
- cli/README.md - Documentação detalhada do CLI
O Flowtomic oferece duas formas principais de uso:
O CLI copia os arquivos dos componentes diretamente para o seu projeto (similar ao shadcn/ui), permitindo customização total:
# Componentes são copiados para seu projeto
npx flowtomic-cli@latest add button
# Arquivo criado: src/components/ui/button/button.tsx
# Você pode modificar completamente o componenteVantagens:
- ✅ Customização total do código
- ✅ Imports ajustados automaticamente
- ✅ Controle completo sobre estilos e comportamento
- ✅ Componentes fazem parte do seu projeto
Os packages npm fornecem componentes prontos para uso:
// Importar diretamente do package
import { Button } from "@flowtomic/ui";Vantagens:
- ✅ Instalação rápida
- ✅ Atualizações via npm
- ✅ Customização via
classNamee variáveis CSS ⚠️ Customização limitada (não pode modificar o código fonte)
Estilo Padrão:
- Funciona imediatamente após importar os arquivos CSS do Flowtomic
- Baseado em Tailwind CSS com variáveis CSS customizáveis
Customização:
- Via
className: Ajustes pontuais em componentes específicos - Via variáveis CSS: Temas globais e personalização de cores/espaçamentos
- Modificando código fonte (apenas com CLI): Customização completa do componente
Para mais detalhes sobre customização, consulte a documentação de estilos.
import { Form, Input, Button, Card } from "@/components/ui";
import { useForm } from "react-hook-form";
function LoginForm() {
const form = useForm();
return (
<Card>
<Form {...form}>
<Input name="email" type="email" placeholder="Email" required />
<Input name="password" type="password" placeholder="Senha" required />
<Button type="submit">Entrar</Button>
</Form>
</Card>
);
}import { StatCard } from "@/components/ui";
import { useStatCard } from "@flowtomic/logic";
function Dashboard() {
return (
<div className="grid grid-cols-3 gap-4">
<StatCard
title="Receita Total"
value={122380}
lastMonth={105922}
color="blue"
/>
<StatCard
title="Usuários Ativos"
value={15420}
lastMonth={12800}
color="green"
/>
<StatCard title="Conversão" value={3.2} lastMonth={2.8} color="purple" />
</div>
);
}import { DataTable } from "@/components/ui";
import { useReactTableBack } from "@flowtomic/logic";
function UsersTable() {
const { table, data, isLoading } = useReactTableBack({
endpoint: "/api/users",
columns: userColumns,
});
if (isLoading) return <Skeleton />;
return <DataTable table={table} data={data} />;
}import { useStatCard } from "@flowtomic/logic";
function CustomStatCard() {
const { formattedValue, trend } = useStatCard({
value: 122380,
lastMonth: 105922,
});
// UI completamente customizada
return (
<div className="custom-card">
<div className="value">{formattedValue}</div>
<div className={`trend ${trend.direction}`}>{trend.percentage}</div>
</div>
);
}- 📚 Índice de Documentação - Guia central de toda a documentação
- Guia de Desenvolvimento - Guia completo de uso do monorepo e CLI
- Documentação do CLI - Documentação detalhada do CLI
- Componentes Disponíveis - Lista completa de componentes
- Atoms - Componentes básicos (54 componentes)
- Molecules - Componentes compostos (36 componentes)
- Organisms - Componentes complexos (23 componentes)
- Hooks - Hooks headless (11 hooks)
- Blocks - Blocks pré-construídos (3 blocks)
- Arquitetura do Monorepo - Estrutura e organização
- Package UI - Detalhes do package UI
- Package Logic - Detalhes do package Logic
- Registry - Sistema de registry
- Guia de Deploy - Como fazer deploy
O Flowtomic está publicado no npm em três packages principais:
| Package | Descrição | Instalação |
|---|---|---|
flowtomic-cli |
CLI para instalação de componentes | npx flowtomic-cli@latest init |
@flowtomic/ui |
Componentes UI reutilizáveis | npm install @flowtomic/ui |
@flowtomic/logic |
Hooks headless e lógica | npm install @flowtomic/logic |
O registry está disponível em https://registry.flowtomic.dev e é compatível com o shadcn CLI:
# Usar com shadcn CLI
npx shadcn@latest add https://registry.flowtomic.dev/all.jsonPara mais informações sobre publicação e deploy, consulte a documentação de deploy.
Contribuições são bem-vindas! Por favor, consulte a documentação de desenvolvimento para mais informações sobre como contribuir.
Este projeto está sob licença MIT. Veja o arquivo LICENSE para mais detalhes.
O Flowtomic é construído sobre os ombros de projetos incríveis da comunidade open source:
- Radix UI - Componentes primitivos acessíveis e sem estilização
- TanStack Table - Tabelas poderosas e flexíveis para React
- shadcn/ui - Inspiração e padrões de design para componentes
- Tailwind CSS - Framework CSS utilitário
- class-variance-authority - Gerenciamento de variantes de componentes
- Lucide React - Biblioteca de ícones
- Sonner - Sistema de notificações toast
- Bun - Runtime JavaScript rápido e moderno
- Biome - Linter e formatter rápido
- Turbo - Build system para monorepos
- Storybook - Ambiente de desenvolvimento de componentes
Desenvolvido com ❤️ e ☕ por JaimeJunr