CURSOR.md - Guia de Regras e Diretrizes para Desenvolvimento

📋 Índice

🎯 Visão Geral

Este documento estabelece as regras e diretrizes utilizadas para criar interfaces web profissionais, acessíveis e responsivas. Todas as regras foram testadas e aplicadas em projetos reais, garantindo consistência e qualidade.

Princípios Fundamentais

  • Acessibilidade First: Sempre considerar usuários com diferentes necessidades
  • Mobile First: Design responsivo começando pelo mobile
  • Performance: Otimização contínua para melhor experiência
  • Consistência: Padrões visuais e de código uniformes
  • Usabilidade: Interface intuitiva e fácil de usar

🎨 Regras de Layout e Design

1. Estrutura de Grid Responsivo

/* Desktop (1200px+) */
.grid-desktop {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: 2rem;
}

/* Tablet (768px-1199px) */
.grid-tablet {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 1.5rem;
}

/* Mobile (<768px) */
.grid-mobile {
    display: grid;
    grid-template-columns: 1fr;
    gap: 1rem;
}

2. Harmonia Visual - Layout 3x2

Regra: Para telas de 1024px, sempre buscar layout com 3 cards por linha em 2 linhas (total 6 cards).

<!-- Exemplo de estrutura harmoniosa -->
<div class="feature-grid">
    <!-- Linha 1: 3 cards -->
    <div class="feature-card">Card 1</div>
    <div class="feature-card">Card 2</div>
    <div class="feature-card">Card 3</div>
    
    <!-- Linha 2: 3 cards -->
    <div class="feature-card">Card 4</div>
    <div class="feature-card">Card 5</div>
    <div class="feature-card">Card 6</div>
</div>

3. Espaçamentos Consistentes

/* Sistema de espaçamento */
.spacing-xs { padding: 0.5rem; }
.spacing-sm { padding: 1rem; }
.spacing-md { padding: 1.5rem; }
.spacing-lg { padding: 2rem; }
.spacing-xl { padding: 3rem; }

/* Gaps de grid */
.gap-sm { gap: 1rem; }
.gap-md { gap: 1.5rem; }
.gap-lg { gap: 2rem; }

4. Cores e Temas

/* Paleta de cores profissional */
:root {
    --primary: #0ea5e9;
    --secondary: #8b5cf6;
    --success: #10b981;
    --warning: #f59e0b;
    --danger: #ef4444;
    --info: #3b82f6;
    --dark: #1e293b;
    --light: #f8fafc;
}

/* Uso de cores por categoria */
.category-problem { border-left-color: var(--primary); }
.category-solution { border-left-color: var(--success); }
.category-market { border-left-color: var(--secondary); }
.category-business { border-left-color: var(--warning); }

♿ Diretrizes de Acessibilidade

1. Labels e ARIA

<!-- Sempre incluir labels ocultos -->
<label for="campo-id" class="sr-only">Descrição do Campo</label>
<input id="campo-id" type="text" aria-label="Descrição clara do campo" />

<!-- Para elementos editáveis -->
<div id="campo-editavel" 
     contenteditable="true" 
     role="textbox" 
     aria-label="Descrição do que o usuário deve inserir"
     data-placeholder="Texto do placeholder">
</div>

2. Navegação por Teclado

/* Estilos de foco obrigatórios */
.focusable:focus {
    outline: 2px solid var(--primary);
    outline-offset: 2px;
}

/* Indicadores visuais de foco */
.focus-indicator:focus {
    box-shadow: 0 0 0 3px rgba(14, 165, 233, 0.1);
    border-color: var(--primary);
}

3. Screen Readers

/* Classe para elementos ocultos visualmente mas acessíveis */
.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
}

4. Contraste e Legibilidade

/* Contraste mínimo WCAG AA */
.text-primary { color: #0ea5e9; } /* 4.5:1 ratio */
.text-dark { color: #1e293b; }   /* 7:1 ratio */
.text-muted { color: #64748b; }  /* 4.5:1 ratio */

/* Tamanhos de fonte acessíveis */
.text-sm { font-size: 0.875rem; }   /* 14px */
.text-base { font-size: 1rem; }     /* 16px */
.text-lg { font-size: 1.125rem; }  /* 18px */

📱 Responsividade

1. Breakpoints Padrão

/* Mobile First Approach */
@media (min-width: 640px) { /* sm */ }
@media (min-width: 768px) { /* md */ }
@media (min-width: 1024px) { /* lg */ }
@media (min-width: 1280px) { /* xl */ }
@media (min-width: 1536px) { /* 2xl */ }

2. Grid Responsivo

.responsive-grid {
    display: grid;
    grid-template-columns: 1fr; /* Mobile: 1 coluna */
    gap: 1rem;
}

@media (min-width: 768px) {
    .responsive-grid {
        grid-template-columns: repeat(2, 1fr); /* Tablet: 2 colunas */
        gap: 1.5rem;
    }
}

@media (min-width: 1024px) {
    .responsive-grid {
        grid-template-columns: repeat(3, 1fr); /* Desktop: 3 colunas */
        gap: 2rem;
    }
}

3. Tipografia Responsiva

.responsive-text {
    font-size: 1rem; /* Base mobile */
    line-height: 1.5;
}

@media (min-width: 768px) {
    .responsive-text {
        font-size: 1.125rem; /* Tablet */
    }
}

@media (min-width: 1024px) {
    .responsive-text {
        font-size: 1.25rem; /* Desktop */
    }
}

🎨 Harmonia Visual

1. Cards Consistentes

.feature-card {
    background: white;
    border-radius: 20px;
    padding: 2rem;
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
    transition: all 0.3s ease;
    min-height: 200px;
}

.feature-card:hover {
    transform: translateY(-5px);
    box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}

2. Ícones e Cores por Categoria

/* Sistema de cores por categoria */
.icon-problem { 
    background: rgba(14, 165, 233, 0.1); 
    color: #0ea5e9; 
}
.icon-solution { 
    background: rgba(16, 185, 129, 0.1); 
    color: #10b981; 
}
.icon-market { 
    background: rgba(139, 92, 246, 0.1); 
    color: #8b5cf6; 
}
.icon-business { 
    background: rgba(245, 158, 11, 0.1); 
    color: #f59e0b; 
}

3. Espaçamentos Harmoniosos

/* Sistema de espaçamento 8px */
.spacing-1 { padding: 0.25rem; }  /* 4px */
.spacing-2 { padding: 0.5rem; }   /* 8px */
.spacing-3 { padding: 0.75rem; } /* 12px */
.spacing-4 { padding: 1rem; }     /* 16px */
.spacing-6 { padding: 1.5rem; }   /* 24px */
.spacing-8 { padding: 2rem; }    /* 32px */

🧭 Navegação e UX

Regra: Nunca usar href="#" - sempre links reais e funcionais.

<!-- ❌ ERRADO -->
<a href="#">Link quebrado</a>

<!-- ✅ CORRETO -->
<a href="https://exemplo.com" target="_blank" class="footer-link">
    <i class="fas fa-external-link-alt me-2"></i>
    Link Funcional
</a>

2. Navegação Suave

// Smooth scrolling para links âncora
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
    anchor.addEventListener('click', function (e) {
        e.preventDefault();
        document.querySelector(this.getAttribute('href')).scrollIntoView({
            behavior: 'smooth'
        });
    });
});

3. Estados de Loading

.loading {
    opacity: 0.6;
    pointer-events: none;
}

.loading::after {
    content: '';
    position: absolute;
    top: 50%;
    left: 50%;
    width: 20px;
    height: 20px;
    margin: -10px 0 0 -10px;
    border: 2px solid #f3f3f3;
    border-top: 2px solid var(--primary);
    border-radius: 50%;
    animation: spin 1s linear infinite;
}

💼 Tom Profissional

1. Tipografia Hierárquica

/* Títulos */
.display-6 { 
    font-size: 3.5rem; 
    font-weight: 800; 
    line-height: 1.1; 
}

.display-5 { 
    font-size: 3rem; 
    font-weight: 700; 
    line-height: 1.2; 
}

/* Subtítulos */
.section-title {
    font-size: 2.5rem;
    font-weight: 700;
    margin-bottom: 2.5rem;
    position: relative;
}

.section-title::after {
    content: "";
    position: absolute;
    bottom: -10px;
    left: 0;
    width: 60px;
    height: 4px;
    background: linear-gradient(to right, var(--primary), var(--secondary));
    border-radius: 2px;
}

2. Cores Profissionais

/* Gradientes sutis */
.hero-gradient {
    background: linear-gradient(90deg, #0ea5e9 0%, #8b5cf6 100%);
}

/* Sombras profissionais */
.card-shadow {
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 
                0 2px 4px -1px rgba(0, 0, 0, 0.06);
}

.card-shadow-hover {
    box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 
                0 4px 6px -2px rgba(0, 0, 0, 0.05);
}

3. Microinterações

/* Transições suaves */
.smooth-transition {
    transition: all 0.3s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

/* Hover effects */
.hover-lift:hover {
    transform: translateY(-5px);
}

.hover-scale:hover {
    transform: scale(1.05);
}

⚡ Otimizações de Performance

1. Animações Otimizadas

/* Reduzir animações em dispositivos com preferência */
@media (prefers-reduced-motion: reduce) {
    * {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
    }
}

/* Animações performáticas */
@keyframes fadeIn {
    from { opacity: 0; transform: translateY(20px); }
    to { opacity: 1; transform: translateY(0); }
}

.animate-fade-in {
    animation: fadeIn 0.8s ease forwards;
}

2. Lazy Loading

// Intersection Observer para animações
const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
        if (entry.isIntersecting) {
            entry.target.classList.add('visible');
        }
    });
}, { threshold: 0.1 });

document.querySelectorAll('.animate-fade-in').forEach(element => {
    observer.observe(element);
});

3. Auto-save Inteligente

// Debounced auto-save
let saveTimeout;
function autoSave(data) {
    clearTimeout(saveTimeout);
    saveTimeout = setTimeout(() => {
        localStorage.setItem('app-data', JSON.stringify(data));
        showSaveIndicator();
    }, 1000);
}

📝 Padrões de Código

1. Estrutura HTML Semântica

<!-- Estrutura recomendada -->
<header class="hero-section">
    <div class="container">
        <div class="row">
            <div class="col-lg-8">
                <h1 class="display-4">Título Principal</h1>
                <p class="lead">Descrição</p>
            </div>
        </div>
    </div>
</header>

<main>
    <section class="py-5">
        <div class="container">
            <!-- Conteúdo -->
        </div>
    </section>
</main>

<footer class="bg-dark text-white py-5">
    <div class="container">
        <!-- Footer content -->
    </div>
</footer>

2. CSS Organizado

/* 1. Reset e Base */
* { box-sizing: border-box; }

/* 2. Variáveis CSS */
:root {
    --primary: #0ea5e9;
    --secondary: #8b5cf6;
}

/* 3. Layout */
.container { max-width: 1200px; }

/* 4. Componentes */
.feature-card { /* estilos */ }

/* 5. Estados */
.feature-card:hover { /* estilos */ }

/* 6. Responsividade */
@media (min-width: 768px) { /* estilos */ }

3. JavaScript Modular

// Estrutura modular
const App = {
    init() {
        this.setupEventListeners();
        this.loadSavedData();
        this.setupAnimations();
    },
    
    setupEventListeners() {
        // Event listeners
    },
    
    loadSavedData() {
        // Auto-save functionality
    },
    
    setupAnimations() {
        // Animation setup
    }
};

// Inicialização
document.addEventListener('DOMContentLoaded', () => {
    App.init();
});

✅ Checklist de Qualidade

Acessibilidade

  • Todos os campos têm labels apropriados
  • Navegação por teclado funcional
  • Contraste de cores WCAG AA
  • Screen readers compatíveis
  • Foco visível em todos os elementos

Responsividade

  • Mobile first implementado
  • Breakpoints consistentes
  • Grid adaptativo funcional
  • Tipografia responsiva
  • Touch targets adequados (44px mínimo)

Performance

  • Animações otimizadas
  • Lazy loading implementado
  • Auto-save com debounce
  • Imagens otimizadas
  • CSS/JS minificado

UX/UI

  • Links funcionais (nunca href=”#”)
  • Estados de loading
  • Feedback visual
  • Navegação intuitiva
  • Consistência visual

Código

  • HTML semântico
  • CSS organizado
  • JavaScript modular
  • Comentários adequados
  • Padrões consistentes

🚀 Implementação Rápida

Template Base

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Seu Projeto</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body>
    <!-- Conteúdo seguindo as diretrizes -->
</body>
</html>

CSS Base

/* Reset e base */
* { box-sizing: border-box; }

body {
    font-family: 'Inter', sans-serif;
    background: linear-gradient(135deg, #f0f9ff 0%, #e0f2fe 100%);
    color: #1e293b;
    overflow-x: hidden;
}

/* Grid responsivo */
.responsive-grid {
    display: grid;
    grid-template-columns: 1fr;
    gap: 1rem;
}

@media (min-width: 768px) {
    .responsive-grid {
        grid-template-columns: repeat(2, 1fr);
        gap: 1.5rem;
    }
}

@media (min-width: 1024px) {
    .responsive-grid {
        grid-template-columns: repeat(3, 1fr);
        gap: 2rem;
    }
}

📚 Recursos Adicionais

Bibliotecas Recomendadas

  • Bootstrap 5.3+: Framework CSS
  • Font Awesome 6.4+: Ícones
  • Tailwind CSS: Utility-first CSS
  • jsPDF: Geração de PDF
  • html2canvas: Captura de tela

Ferramentas de Teste

  • Lighthouse: Performance e acessibilidade
  • WAVE: Avaliação de acessibilidade
  • Chrome DevTools: Debugging
  • Responsive Design Mode: Teste de dispositivos

Referências

📞 Suporte

Para dúvidas sobre implementação ou melhorias, consulte:

  • Este documento como referência principal
  • Exemplos de código nos comentários
  • Padrões estabelecidos em projetos existentes
  • Testes de acessibilidade e responsividade

Última atualização: Janeiro 2025
Versão: 1.0
Status: Ativo e em uso