Design System React

Um design system moderno construído com shadcn/ui, Radix UI e Tailwind CSS v4. Oferece componentes reutilizáveis, acessíveis e altamente personalizáveis para aplicações React.

Sumário

• Instalação
• Uso
  • Importando
  • Usando Componentes
  • Documentação
• Componentes Disponíveis
• Sistema de Design
  • Estrutura de Tokens
  • Temas
• Desenvolvimento
• Migração

Instalação

npm install @evoapi/design-system

Uso

Importando

O design system agora possui entrypoints separados por componente, e um entry dedicado para os estilos.

Importe assim:

import "@evoapi/design-system/styles"; // CSS global
import { Button } from "@evoapi/design-system/button";
import { Input } from "@evoapi/design-system/input";
import { Select } from "@evoapi/design-system/select";
import { Tabs } from "@evoapi/design-system/tabs";

O import direto do root ainda funciona, mas é considerado modo legacy:

import "@evoapi/design-system/dist/index.css"; // CSS global
import { Button } from "@evoapi/design-system";

Usando Componentes

import "@evoapi/design-system/styles";

import { Button } from "@evoapi/design-system/button";
import { Input } from "@evoapi/design-system/input";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@evoapi/design-system/select";
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@evoapi/design-system/tabs";

function App() {
  return (
    <div className="p-4 space-y-4">
      <Button variant="default" size="lg">
        Clique Aqui
      </Button>

      <Tabs defaultValue="account" className="w-[400px]">
        <TabsList>
          <TabsTrigger value="account">Conta</TabsTrigger>
          <TabsTrigger value="password">Senha</TabsTrigger>
        </TabsList>

        <TabsContent value="account">Conteúdo da aba conta</TabsContent>
        <TabsContent value="password">Conteúdo da aba senha</TabsContent>
      </Tabs>

      <Select>
        <SelectTrigger className="w-[180px]">
          <SelectValue placeholder="Selecione uma opção" />
        </SelectTrigger>

        <SelectContent>
          <SelectItem value="option1">Opção 1</SelectItem>
          <SelectItem value="option2">Opção 2</SelectItem>
          <SelectItem value="option3">Opção 3</SelectItem>
        </SelectContent>
      </Select>
    </div>
  );
}

Componentes Disponíveis

Nosso design system inclui uma biblioteca completa de 45+ componentes baseados no shadcn/ui:

Formulários e Inputs

• Button: Botões com múltiplas variantes (default, destructive, outline, secondary, ghost, link)
• Input: Campos de entrada de texto com suporte a diferentes tipos
• Textarea: Área de texto multilinha
• Label: Rótulos para formulários
• Checkbox: Caixas de seleção
• Radio Group: Grupos de botões radio
• Switch: Controles de alternância (toggle)
• Toggle: Botões de alternância
• Toggle Group: Grupos de toggles para seleção única ou múltipla
• Select: Menus dropdown para seleção
• Slider: Controles deslizantes para valores numéricos
• Input OTP: Campos para códigos de verificação
• Form: Sistema completo de formulários com validação

Navegação

• Navigation Menu: Menus de navegação com dropdown
• Menubar: Barra de menu estilo desktop
• Dropdown Menu: Menus dropdown com suporte a submenus, checkboxes e radio buttons
• Context Menu: Menus contextuais (clique direito)
• Breadcrumb: Navegação hierárquica
• Pagination: Controles de paginação
• Sidebar: Barras laterais responsivas

Layout e Estrutura

• Table: Tabelas com suporte a seleção, ordenação e ações
• Card: Cards para exibir conteúdo
• Accordion: Painéis expansíveis
• Collapsible: Seções recolhíveis
• Separator: Divisores visuais
• Aspect Ratio: Controle de proporção de elementos
• Scroll Area: Áreas de scroll customizadas
• Resizable: Painéis redimensionáveis
• Tabs: Sistema de abas navegáveis

Feedback e Notificações

• Alert: Alertas para diferentes tipos de mensagem
• Alert Dialog: Diálogos de confirmação
• Progress: Barras de progresso
• Badge: Etiquetas para status e categorização
• Skeleton: Placeholders de carregamento
• Sonner (Toaster): Sistema de notificações toast
• Tooltip: Dicas contextuais

Overlays e Modais

• Dialog: Modais e diálogos
• Sheet: Gavetas deslizantes (top, bottom, left, right)
• Drawer: Gavetas deslizantes mobile
• Popover: Popovers para conteúdo contextual
• Hover Card: Cards que aparecem no hover
• Command: Interface de comando com busca

Data Display

• Avatar: Avatares de usuário
• Calendar: Calendário para seleção de datas
• Carousel: Carrosséis de conteúdo
• Chart: Gráficos e visualizações de dados

Sistema de Design

Estrutura de Tokens

O design system utiliza Tailwind CSS v4 com CSS Custom Properties para máxima flexibilidade:

@import "tailwindcss";

@theme {
  --color-background: 0 0% 100%;
  --color-foreground: 240 10% 3.9%;
  --color-primary: 240 5.9% 10%;
  --color-primary-foreground: 0 0% 98%;
  --color-secondary: 240 4.8% 95.9%;
  --color-secondary-foreground: 240 5.9% 10%;
  --color-muted: 240 4.8% 95.9%;
  --color-muted-foreground: 240 3.8% 46.1%;
  --color-accent: 240 4.8% 95.9%;
  --color-accent-foreground: 240 5.9% 10%;
  --color-destructive: 0 84.2% 60.2%;
  --color-destructive-foreground: 0 0% 98%;
  --color-border: 240 5.9% 90%;
  --color-input: 240 5.9% 90%;
  --color-ring: 240 5% 64.9%;
  --radius: 0.5rem;
}

Temas

O sistema suporta temas claro e escuro automaticamente através de CSS variables:

@media (prefers-color-scheme: dark) {
  :root {
    --color-background: 240 10% 3.9%;
    --color-foreground: 0 0% 98%;
    --color-primary: 0 0% 98%;
    --color-primary-foreground: 240 5.9% 10%;
    /* ... */
  }
}

Variantes de Componentes

Cada componente possui variantes bem definidas usando Class Variance Authority (CVA):

// Exemplo: Button variants
<Button variant="default">Default</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Tamanhos
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon</Button>

// Exemplo: Select variants
<Select>
  <SelectTrigger size="sm">Small</SelectTrigger>
  <SelectTrigger size="default">Default</SelectTrigger>
</Select>

// Exemplo: Tabs orientações
<Tabs orientation="horizontal">...</Tabs>
<Tabs orientation="vertical">...</Tabs>

Documentação

Para ver a documentação completa dos componentes, execute:

npm run storybook

Isso iniciará o Storybook na porta 6006, onde você pode explorar:

• ✅ 45+ Stories com exemplos práticos
• ✅ Documentação interativa de todos os componentes
• ✅ Casos de uso reais para cada componente
• ✅ Controles dinâmicos para testar variações
• ✅ Código fonte de cada exemplo
• ✅ Acessibilidade demonstrada em cada componente

Componentes Documentados

Formulários:

• Button: 6 variações (Default, Variants, Sizes, With Icons, Icon Only, States)
• Form: 5 variações (Default, Profile Form, Login Form, Realtime Validation, Survey Form)
• Input: 6 variações (Default, With Label, File Input, Disabled, With Icon, Password)
• Textarea: 6 variações (Default, With Label, States, Sizes, Feedback Form, Controlled)
• Select: 6 variações (Default, With Label, With Groups, States, Sizes, Controlled)
• Switch: 5 variações (Default, With Label, States, Settings, Controlled)
• Slider: 7 variações (Default, With Label, Range, States, Vertical, Settings, Different Scales)
• Toggle: 6 variações (Default, Variants, Sizes, With Icons, States, Formatting Toolbar)
• Toggle Group: 6 variações (Default, Selection Types, Variants, Sizes, Formatting Toolbar, States)

Layout e Navegação:

• Tabs: 6 variações (Default, Simple, With Icons, States, Controlled, Product Navigation)
• Scroll Area: 4 variações (Default, Horizontal, Long Text, Sizes)
• Table: 6 variações (Default, Selectable, With Actions, Sortable, With Footer, Empty)
• Accordion: 5 variações (Default, Multiple, With Icons, Custom Styling, FAQ)
• Card: 6 variações (Default, With Image, Profile Card, Statistics, Product Card, Interactive)

Feedback:

• Sonner: 6 variações (Default, All Types, With Actions, Positioning, Advanced Settings, Form Example)
• Alert: 5 variações (Default, With Icon, Variants, Custom, Dismissible)
• Progress: 6 variações (Default, With Label, Variants, Sizes, Animated, Multi-step)

E muitos outros...

Desenvolvimento

Para contribuir com o design system:

1. Clone o repositório
2. Instale as dependências: npm install
3. Inicie o Storybook: npm run storybook
4. Faça suas alterações
5. Execute os testes: npm run test
6. Faça o build: npm run build

Estrutura do Projeto

ui-design-system/
├── src/
│   ├── components/
│   │   ├── ui/           # Componentes base (shadcn/ui)
│   │   └── stories/      # Stories do Storybook (45+ stories)
│   ├── utils/            # Utilitários (cn, etc.)
│   ├── hooks/            # Hooks customizados (use-mobile)
│   └── index.ts          # Exportações principais
├── .storybook/           # Configuração do Storybook
└── docs/                 # Documentação adicional

Migração

Componentes Depreciados

⚠️ Importante: Os seguintes componentes foram depreciados e substituídos por versões baseadas no shadcn/ui:

• BAccordion → Accordion
• BAlert → Alert
• BMenu → DropdownMenu / NavigationMenu
• BProfile → Avatar + custom components
• BAppBar → custom implementation using Button + DropdownMenu

Guia de Migração

// ❌ Antes (depreciado)
import { BButton, BAlert } from "@evoapi/design-system";

<BButton variant="primary">Click me</BButton>
<BAlert type="success">Success message</BAlert>

// ✅ Depois (novo)
import { Button, Alert } from "@evoapi/design-system";

<Button variant="default">Click me</Button>
<Alert>
  <CheckCircle className="h-4 w-4" />
  <AlertTitle>Success</AlertTitle>
  <AlertDescription>Success message</AlertDescription>
</Alert>

Tecnologias

• React 18: Biblioteca principal
• shadcn/ui: Componentes base
• Radix UI: Primitivos acessíveis
• Tailwind CSS v4: Sistema de design e estilização
• Class Variance Authority: Gerenciamento de variantes
• Lucide React: Ícones consistentes
• React Hook Form: Gerenciamento de formulários
• Zod: Validação de schemas
• Sonner: Sistema de notificações toast
• Storybook 8: Documentação interativa
• TypeScript: Tipagem estática completa

Licença

MIT