Skip to main content

Convenções de Estilo (Frontend)

Camada: Arquitetura — Define o stack de estilização e as regras de uso para todo o frontend do CRM. Decisão: Adotado como padrão inegociável para manter consistência visual e facilitar manutenção.

1. Stack de Estilização​

TecnologiaPapel
Tailwind CSSLayout, espaçamento, tipografia e composição de componentes
shadcn/uiBiblioteca de componentes base (acessíveis, customizáveis via CSS Variables)
CSS VariablesDesign Tokens — valores semânticos centralizados (--primary, --danger, --radius)
CSS puroComportamentos complexos, animações, seletores de atributo e estados especiais

2. Regra de Divisão de Responsabilidades​

Tailwind → Layout e Composição​

Use Tailwind para tudo que é estrutural e estático:

<!-- Correto: layout, espaçamento, tipografia via Tailwind -->
<div class="flex items-center gap-4 p-4 rounded-lg bg-card">
  <span class="text-sm font-medium text-muted-foreground">Lead</span>
</div>

Classes típicas de Tailwind no projeto:

CategoriaExemplos
Layoutflex, grid, grid-cols-3, items-center, justify-between
Espaçamentop-4, px-6, py-2, gap-4, space-y-2
Tipografiatext-sm, font-medium, text-muted-foreground, truncate
Dimensõesw-full, max-w-sm, h-10, min-h-screen
Visual estáticorounded-lg, border, shadow-sm, bg-card

CSS Puro → Comportamento Complexo​

Use CSS puro para tudo que é dinâmico, animado ou dependente de estado de dados:

/* Animação de pulso para leads com interação pendente */
.pipeline-card {
  animation: pulseLead 2s infinite;
}

@keyframes pulseLead {
  0%, 100% { opacity: 1; }
  50%       { opacity: 0.6; }
}

/* Estilo por prioridade via atributo de dado */
.pipeline-card[data-priority="high"] {
  border-color: var(--danger);
}

.pipeline-card[data-priority="medium"] {
  border-color: var(--warning);
}

3. Design Tokens (CSS Variables)​

Todos os valores semânticos são definidos como CSS Variables e nunca hardcodados:

:root {
  /* Cores semânticas */
  --primary:     hsl(221 83% 53%);
  --primary-foreground: hsl(0 0% 100%);
  --danger:      hsl(0 84% 60%);
  --warning:     hsl(38 92% 50%);
  --success:     hsl(142 71% 45%);
  --muted:       hsl(210 40% 96%);
  --muted-foreground: hsl(215 16% 47%);

  /* Superfícies */
  --background:  hsl(0 0% 100%);
  --card:        hsl(0 0% 100%);
  --border:      hsl(214 32% 91%);

  /* Forma */
  --radius:      0.5rem;
}

Tokens de cor seguem o padrão hsl() para facilitar ajustes de opacidade via hsl(var(--primary) / 0.1).

4. Regras de Uso do shadcn/ui​

  • Usar os componentes do shadcn como base — nunca reescrever do zero o que já existe.
  • Customizações visuais são feitas via CSS Variables, nunca sobrescrevendo classes internas do componente.
  • Novas variantes de componentes existentes devem ser criadas via cva (Class Variance Authority), mantendo o padrão do shadcn.
// Correto: variante via cva
const cardVariants = cva("rounded-lg border p-4", {
  variants: {
    priority: {
      high:   "border-[--danger]",
      medium: "border-[--warning]",
      low:    "border-border",
    },
  },
})

5. Regras que Não Devem ser Quebradas​

RegraMotivo
Nunca use valores de cor hardcodados (#FF0000, red)Quebra o sistema de temas e dark mode
Nunca use style="" inline para layoutImpossível de sobrescrever e não é rastreável
Nunca use !importantIndica falha de especificidade — resolva na arquitetura do CSS
Animações complexas ficam em CSS puroTailwind não suporta keyframes customizados de forma escalável
Seletores de atributo [data-*] ficam em CSS puroSão comportamento orientado a estado de dado — fora do escopo do Tailwind