@lumencrm/design-system

Design System do LumenCRM construído com Atomic Design e suporte completo a theming via CSS Variables.

Perfeito para projetos multi-tenant onde cada instância precisa de sua própria identidade visual.

Instalação

NPM (Publicado)

npm install @lumencrm/design-system

Workspace Local (Desenvolvimento)

# No package.json do seu projeto
{
  "dependencies": {
    "@lumencrm/design-system": "workspace:*"
  }
}

Link Local

cd packages/design-system
npm link

cd seu-projeto
npm link @lumencrm/design-system

Uso Básico

1. Importar Estilos

Importe o CSS no seu arquivo principal (main.tsx, App.tsx, etc):

// main.tsx ou App.tsx
import '@lumencrm/design-system/styles'

2. Usar Componentes

import { Button, Card, Input, FormField, Text } from '@lumencrm/design-system'

function App() {
  return (
    <Card title="Bem-vindo" variant="elevated">
      <Text variant="h2">Olá Mundo</Text>

      <FormField label="Nome" id="name">
        <Input
          id="name"
          placeholder="Digite seu nome"
        />
      </FormField>

      <Button variant="primary" size="medium">
        Enviar
      </Button>
    </Card>
  )
}

Componentes Disponíveis

Atoms (Básicos)

Button

import { Button } from '@lumencrm/design-system'

<Button variant="primary" size="medium" onClick={() => alert('Clicou!')}>
  Clique Aqui
</Button>

Props: variant, size, disabled, onClick, children, type

Input

import { Input } from '@lumencrm/design-system'

<Input
  placeholder="Digite algo"
  type="text"
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>

Props: type, placeholder, value, onChange, disabled, id

Label

import { Label } from '@lumencrm/design-system'

<Label htmlFor="email" required>
  E-mail
</Label>

Props: htmlFor, required, children

Text

import { Text } from '@lumencrm/design-system'

<Text variant="h1">Título Principal</Text>
<Text variant="body">Texto normal</Text>
<Text variant="caption" color="secondary">Texto pequeno</Text>

Props: variant, color, align, children

Icon

import { Icon } from '@lumencrm/design-system'

<Icon name="user" size="medium" color="primary" />

Props: name, size, color

Molecules (Compostos)

FormField

Combina Label + Input com tratamento de erros:

import { FormField } from '@lumencrm/design-system'

<FormField
  label="E-mail"
  id="email"
  error="E-mail inválido"
  required
>
  <Input
    id="email"
    type="email"
    placeholder="[email protected]"
  />
</FormField>

Props: label, id, error, required, children

Card

Container estilizado com título e ações:

import { Card } from '@lumencrm/design-system'

<Card
  title="Informações do Usuário"
  subtitle="Dados pessoais"
  variant="elevated"
  actions={<Button size="small">Editar</Button>}
>
  <p>Conteúdo do card...</p>
</Card>

Props: title, subtitle, variant, actions, children

SearchBar

Barra de busca com ícone:

import { SearchBar } from '@lumencrm/design-system'

<SearchBar
  placeholder="Buscar clientes..."
  value={searchTerm}
  onSearch={(value) => setSearchTerm(value)}
/>

Props: placeholder, value, onSearch

Organisms (Complexos)

Header

Cabeçalho da aplicação:

import { Header } from '@lumencrm/design-system'

<Header
  user={{
    name: 'João Silva',
    email: '[email protected]',
    avatar: '/avatar.jpg'
  }}
  onLogout={() => handleLogout()}
/>

Props: user, onLogout

Sidebar

Menu lateral de navegação:

import { Sidebar } from '@lumencrm/design-system'

<Sidebar
  isCollapsed={false}
  onToggle={() => setCollapsed(!collapsed)}
  items={[
    { label: 'Dashboard', icon: 'home', path: '/' },
    { label: 'Clientes', icon: 'users', path: '/clientes' }
  ]}
/>

Props: isCollapsed, onToggle, items

DataTable

Tabela de dados com ordenação:

import { DataTable } from '@lumencrm/design-system'

const columns = [
  { key: 'id', label: 'ID', sortable: true },
  { key: 'name', label: 'Nome', sortable: true },
  { key: 'email', label: 'E-mail' }
]

const data = [
  { id: 1, name: 'João', email: '[email protected]' },
  { id: 2, name: 'Maria', email: '[email protected]' }
]

<DataTable
  columns={columns}
  data={data}
  onSort={(key, direction) => handleSort(key, direction)}
/>

Props: columns, data, onSort

Modal

Modal/Dialog para conteúdo sobreposto:

import { Modal } from '@lumencrm/design-system'

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirmar Ação"
  actions={
    <>
      <Button variant="secondary" onClick={() => setIsOpen(false)}>
        Cancelar
      </Button>
      <Button variant="primary" onClick={handleConfirm}>
        Confirmar
      </Button>
    </>
  }
>
  <p>Tem certeza que deseja continuar?</p>
</Modal>

Props: isOpen, onClose, title, actions, children

Templates (Layouts)

DashboardTemplate

Layout completo com Header + Sidebar:

import { DashboardTemplate } from '@lumencrm/design-system'

<DashboardTemplate
  user={{
    name: 'João Silva',
    email: '[email protected]'
  }}
  onLogout={handleLogout}
  navigationItems={[
    { label: 'Dashboard', icon: 'home', path: '/' },
    { label: 'Clientes', icon: 'users', path: '/clientes' }
  ]}
>
  {/* Conteúdo da página */}
  <h1>Dashboard</h1>
</DashboardTemplate>

Props: user, onLogout, navigationItems, children

FormTemplate

Layout centralizado para formulários:

import { FormTemplate } from '@lumencrm/design-system'

<FormTemplate
  title="Login"
  subtitle="Entre com suas credenciais"
  logo="/logo.png"
  onSubmit={handleLogin}
>
  <FormField label="E-mail" id="email">
    <Input id="email" type="email" />
  </FormField>

  <FormField label="Senha" id="password">
    <Input id="password" type="password" />
  </FormField>

  <Button type="submit" variant="primary" fullWidth>
    Entrar
  </Button>
</FormTemplate>

Props: title, subtitle, logo, onSubmit, children

Theming (CSS Variables)

O Design System usa CSS Variables para permitir customização completa via .env.

Variáveis Disponíveis

/* Cores Principais */
--color-primary
--color-primary-light
--color-primary-dark
--color-secondary
--color-secondary-light
--color-secondary-dark

/* Cores Semânticas */
--color-error
--color-warning
--color-info
--color-success

/* Cores de Interface */
--color-background
--color-surface
--color-text-primary
--color-text-secondary

/* Configurações */
--border-radius
--font-family

Exemplo de Customização

// ThemeProvider.tsx (seu projeto)
import { useEffect } from 'react'

export const ThemeProvider = ({ children }) => {
  useEffect(() => {
    const root = document.documentElement

    // Cores do .env
    root.style.setProperty('--color-primary', '#1d3b9e')
    root.style.setProperty('--color-secondary', '#F97316')
    root.style.setProperty('--border-radius', '8px')
    // ... outras variáveis
  }, [])

  return <>{children}</>
}

Usar no CSS

.meu-componente {
  background-color: var(--color-primary);
  color: white;
  border-radius: var(--border-radius);
}

.meu-botao:hover {
  background-color: var(--color-primary-dark);
}

Build da Biblioteca

Desenvolvimento (watch mode)

cd packages/design-system
npm run dev

Build de Produção

npm run build

Isso gera:

• dist/index.mjs - Build ESM
• dist/index.js - Build CommonJS
• dist/index.d.ts - TypeScript types
• dist/style.css - Estilos compilados

Publicação

NPM Registry

cd packages/design-system

# Login no NPM
npm login

# Publicar
npm publish --access public

Registry Privado (Verdaccio)

npm publish --registry http://seu-registry.com

GitHub Packages

npm publish --registry https://npm.pkg.github.com

TypeScript

A biblioteca inclui type definitions completas. O autocomplete funcionará automaticamente:

import { Button, Card, type ButtonProps } from '@lumencrm/design-system'

const props: ButtonProps = {
  variant: 'primary', // ✅ Autocomplete funciona
  size: 'large',
  onClick: () => {}
}

<Button {...props}>Click</Button>

Peer Dependencies

A biblioteca requer:

• react: ^19.0.0
• react-dom: ^19.0.0

Certifique-se de tê-los instalados no seu projeto.

Estrutura do Pacote

@lumencrm/design-system/
├── dist/
│   ├── index.mjs          # ESM build
│   ├── index.js           # CommonJS build
│   ├── index.d.ts         # TypeScript types
│   └── style.css          # Estilos compilados
├── src/
│   ├── atoms/             # Componentes básicos
│   ├── molecules/         # Compostos simples
│   ├── organisms/         # Componentes complexos
│   ├── templates/         # Layouts
│   └── index.ts           # Exports centralizados
└── package.json

Exemplos de Uso

Micro Frontend 1 - Clientes

// clientes-app/src/main.tsx
import '@lumencrm/design-system/styles'
import { DashboardTemplate, Card, DataTable } from '@lumencrm/design-system'

function ClientesApp() {
  return (
    <DashboardTemplate {...layoutProps}>
      <Card title="Lista de Clientes">
        <DataTable columns={columns} data={clientes} />
      </Card>
    </DashboardTemplate>
  )
}

Micro Frontend 2 - Vendas

// vendas-app/src/main.tsx
import '@lumencrm/design-system/styles'
import { DashboardTemplate, Card, Button } from '@lumencrm/design-system'

function VendasApp() {
  return (
    <DashboardTemplate {...layoutProps}>
      <Card title="Painel de Vendas">
        <Button variant="primary">Nova Venda</Button>
      </Card>
    </DashboardTemplate>
  )
}

Ambos os apps compartilham o mesmo Design System e theming!

Vantagens

✅ Consistência: Mesmos componentes em todos os micro projetos ✅ Theming: CSS Variables para customização total ✅ Type-Safe: TypeScript completo com autocomplete ✅ Tree-Shaking: Importa apenas o que usar ✅ Performance: Build otimizado com Vite ✅ Multi-Tenant: Cada Docker com suas cores

Licença

MIT

Suporte

Para dúvidas ou problemas, abra uma issue no repositório.