1. Introdução e Visão Geral

Este documento fornece uma introdução abrangente à abordagem de desenvolvimento de soluções web usando Astro 5, estabelecendo as bases para o restante da documentação MCP (Model-Context-Purpose).

Propósito da Documentação

Esta documentação MCP foi criada para:

1. Estabelecer padrões consistentes para o desenvolvimento de soluções web com Astro 5
2. Fornecer contexto claro para decisões arquiteturais e de design
3. Servir como referência para desenvolvedores novos e existentes no projeto
4. Documentar boas práticas para criar aplicações web modernas, performáticas e acessíveis
5. Facilitar a manutenção e evolução do código ao longo do tempo

A documentação MCP não é apenas um conjunto de regras, mas um guia vivo que evolui com o projeto e as tecnologias utilizadas. Ela representa o conhecimento coletivo e as decisões tomadas pela equipe, servindo como fonte única de verdade para questões técnicas e de design.

Filosofia de Desenvolvimento

Nossa abordagem para o desenvolvimento de soluções web é guiada por quatro princípios fundamentais:

Performance

A performance é uma característica fundamental, não um adicional. Seguimos as seguintes diretrizes:

• Código mínimo: Enviamos apenas o código necessário para cada página
• Otimização de assets: Imagens, fontes e outros recursos são otimizados automaticamente
• Renderização apropriada: Escolhemos o método de renderização mais adequado para cada componente (estático, SSR, ilhas)
• Métricas objetivas: Utilizamos Core Web Vitals e outras métricas para medir e melhorar continuamente

// Exemplo de configuração para otimização de imagens no Astro
import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image({
      serviceEntryPoint: '@astrojs/image/sharp',
      cacheDir: './.cache/image',
      logLevel: 'debug',
    })
  ],
});

Modularidade

A modularidade permite maior reutilização, manutenção mais fácil e melhor organização do código:

• Componentes independentes: Cada componente tem uma responsabilidade única e bem definida
• Composição sobre herança: Preferimos compor componentes menores para criar interfaces complexas
• Interfaces claras: Componentes têm interfaces bem definidas através de props e eventos
• Isolamento: Componentes são isolados para evitar efeitos colaterais indesejados

---
// Exemplo de componente modular em Astro
import Header from '../components/Header.astro';
import Footer from '../components/Footer.astro';
import Sidebar from '../components/Sidebar.astro';
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---

<div class="layout">
  <Header />
  <main>
    <div class="content">
      {posts.map(post => <PostCard post={post} />)}
    </div>
    <Sidebar />
  </main>
  <Footer />
</div>

Separação de Aparência e Funcionalidade

Mantemos uma clara separação entre apresentação visual e lógica de negócios:

• CSS para estilo, JavaScript para comportamento: Evitamos misturar responsabilidades
• Tailwind para estilização: Utilizamos classes utilitárias para estilização rápida e consistente
• JavaScript vanilla para interatividade: Usamos JavaScript puro para comportamentos dinâmicos
• Astro para composição: Aproveitamos o sistema de componentes do Astro para estruturar a interface

---
// Exemplo de separação de aparência e funcionalidade
---

<button
  class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
  data-action="toggle"
>
  Alternar
</button>

<script>
  // JavaScript separado para comportamento
  document.querySelectorAll('[data-action="toggle"]').forEach(button => {
    button.addEventListener('click', () => {
      const target = document.querySelector(button.dataset.target);
      if (target) {
        target.classList.toggle('hidden');
      }
    });
  });
</script>

Simplicidade

Valorizamos soluções simples e diretas:

• Evitamos complexidade desnecessária: Preferimos abordagens diretas quando possível
• Ferramentas apropriadas: Escolhemos as tecnologias certas para cada problema
• Código legível: Priorizamos legibilidade e manutenibilidade sobre código “inteligente”
• Convenções sobre configuração: Seguimos padrões estabelecidos para reduzir decisões arbitrárias

Tecnologias Principais

Nossa stack tecnológica é cuidadosamente selecionada para oferecer o equilíbrio ideal entre performance, produtividade e manutenibilidade.

Astro 5

Astro é o framework central de nossa arquitetura, oferecendo:

• Arquitetura MPA (Multi-Page App): Cada página é uma entrada separada, otimizada para SEO e performance
• Ilhas de interatividade: Hidratação parcial que envia JavaScript apenas onde necessário
• Content Collections: Sistema tipado para gerenciar conteúdo estruturado
• Renderização híbrida: Suporte para SSG (Static Site Generation) e SSR (Server-Side Rendering)
• Sistema de componentes: Sintaxe familiar semelhante a JSX, mas com foco em HTML

---
// Exemplo de componente Astro básico
import { getEntry } from 'astro:content';
const { slug } = Astro.params;
const post = await getEntry('blog', slug);
const { Content } = await post.render();
---

<article>
  <h1>{post.data.title}</h1>
  <time datetime={post.data.publishDate.toISOString()}>
    {post.data.publishDate.toLocaleDateString()}
  </time>
  <Content />
</article>

Tailwind CSS

Tailwind CSS é nosso framework de estilização, proporcionando:

• Classes utilitárias: Estilização rápida e consistente diretamente no HTML
• Design system integrado: Escala de cores, tipografia e espaçamento consistentes
• Responsividade nativa: Prefixos de breakpoint para design adaptativo
• Purge CSS: Remoção automática de classes não utilizadas para CSS mínimo
• Extensibilidade: Personalização através de configuração em tailwind.config.js

<!-- Exemplo de uso do Tailwind CSS -->
<div class="max-w-md mx-auto bg-white rounded-xl shadow-md overflow-hidden md:max-w-2xl">
  <div class="md:flex">
    <div class="md:shrink-0">
      <img class="h-48 w-full object-cover md:h-full md:w-48" src="/img/example.jpg" alt="Exemplo">
    </div>
    <div class="p-8">
      <div class="uppercase tracking-wide text-sm text-indigo-500 font-semibold">Categoria</div>
      <a href="#" class="block mt-1 text-lg leading-tight font-medium text-black hover:underline">Título do Card</a>
      <p class="mt-2 text-slate-500">Descrição do conteúdo do card com detalhes adicionais.</p>
    </div>
  </div>
</div>

JavaScript Vanilla

Utilizamos JavaScript puro (vanilla) para lógica do cliente, com foco em:

• Código mínimo: Enviamos apenas o JavaScript necessário
• Web APIs modernas: Aproveitamos APIs nativas do navegador
• Sem dependências desnecessárias: Evitamos frameworks JS pesados quando não necessários
• Progressivamente aprimorado: Funcionalidade básica funciona sem JavaScript
• Módulos ES: Organização do código em módulos nativos

utils/dom.js

// Exemplo de JavaScript vanilla moderno
export function $(selector, context = document) {
  return context.querySelector(selector);
}

export function $$(selector, context = document) {
  return [...context.querySelectorAll(selector)];
}

// Uso em um componente
import { $, $$ } from '../utils/dom.js';

// Usando módulos ES nativos
document.addEventListener('DOMContentLoaded', () => {
  const toggleButtons = $$('[data-toggle]');

  toggleButtons.forEach(button => {
    button.addEventListener('click', () => {
      const targetId = button.dataset.toggle;
      const target = $(`#${targetId}`);

      if (target) {
        target.classList.toggle('hidden');

        // Atualizando aria-expanded para acessibilidade
        const expanded = target.classList.contains('hidden') ? 'false' : 'true';
        button.setAttribute('aria-expanded', expanded);
      }
    });
  });
});

Benefícios da Abordagem

Nossa abordagem oferece diversos benefícios:

1. Performance excepcional: Sites rápidos com pontuações altas no Lighthouse
2. SEO otimizado: Conteúdo renderizado no servidor para melhor indexação
3. Experiência de desenvolvimento produtiva: Ferramentas modernas com feedback rápido
4. Manutenibilidade: Código organizado e bem estruturado
5. Acessibilidade: Foco em criar sites utilizáveis por todos
6. Escalabilidade: Arquitetura que cresce com as necessidades do projeto

Casos de Uso Ideais

Esta stack é particularmente adequada para:

• Sites de conteúdo (blogs, documentação, portfólios)
• Sites institucionais e landing pages
• Aplicações web com interatividade moderada
• E-commerce e marketplaces
• Dashboards e interfaces administrativas
• Aplicações progressivas (PWAs)

Próximos Passos

Agora que você compreende a filosofia e as tecnologias por trás de nossa abordagem, os próximos documentos detalharão aspectos específicos:

• Arquitetura: Estrutura de pastas e organização do código
• Style Guide: Convenções de código e formatação
• Design System: Sistema visual e componentes base

---

Última atualização: 21 de março de 2025