Guia de Estilo e Convenções de Codificação Frontend
Este documento define os padrões de codificação, padrões arquiteturais e sistema de design para o frontend Angular do Guessimate.
1. Stack Tecnológica
- Framework: Angular 20+
- Estilização: Tailwind CSS 4
- Gerenciamento de Estado: Angular Signals e RxJS
- Sistema de Build: Angular CLI (Esbuild)
2. Estrutura do Projeto
Seguimos uma estrutura de diretórios Baseada em Features. O código é organizado por domínio da funcionalidade, e não por tipo técnico.
src/app/
├── core/ # Singletons globais (Guards, Interceptors, Serviços Globais)
├── layout/ # Componentes de layout (Navegação, Rodapé, Shell)
├── features/ # Módulos de funcionalidades (Lógica de domínio)
│ ├── home/
│ ├── session/
│ │ ├── components/ # Componentes burros/ de apresentação
│ │ ├── pages/ # Componentes inteligentes/contêineres (roteados)
│ │ ├── services/ # Estado/lógica específicos da funcionalidade
│ │ └── models/ # Tipos específicos da funcionalidade
│ └── ...
├── websocket/ # Infraestrutura WebSocket
└── shared/ # Utilitários compartilhados (Pipes, Diretivas, UI genérica)
Convenções de Nomenclatura
- Arquivos: Kebab-case (ex.:
session-page.component.ts,auth.service.ts). - Classes: PascalCase (ex.:
SessionPageComponent,AuthService). - Seletores: Prefixo
app-, kebab-case (ex.:app-user-profile). - Signals: Sem sufixo, substantivo/verbo descritivo (ex.:
user(),isLoading()). - Observables: Sufixo
$(ex.:user$).
3. Padrões de Componentes
Definição
- Use Componentes Standalone (
standalone: trueé o padrão na v19+). - Prefira Templates Inline para a maioria dos componentes, mantendo lógica e visão co-localizadas.
- Evite arquivos CSS externos; use classes utilitárias Tailwind CSS diretamente no template.
@Component({
selector: 'app-example',
imports: [CommonModule, RouterLink], // Importações explícitas
template: `
<div class="p-4 bg-surface-100 rounded-lg">
<h1 class="text-2xl font-bold text-gray-900">{{ title() }}</h1>
</div>
`
})
export class ExampleComponent {
title = signal('Hello World');
}
Fluxo de Controle
Use a nova sintaxe de Fluxo de Controle nativa do Angular.
<!-- Bom -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
Injeção de Dependência
Prefira a função inject() em vez da injeção via construtor para melhor inferência de tipos e código mais limpo.
// Bom
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// Evite se possível
constructor(private
route: ActivatedRoute
)
{
}
4. Gerenciamento de Estado
- Estado Local: Use
signal()para estado primitivo. - Estado Compartilhado: Use Signal Stores (Serviços usando Signals) fornecidos no nível apropriado (Raiz ou Componente).
- Dados Reativos: Use
computed()para estado derivado eeffect()com moderação para efeitos colaterais.
@Injectable()
export class SessionStore {
// Estado
private readonly _state = signal<SessionState>(initialState);
// Seletores
readonly lobby = computed(() => this._state().lobby);
readonly connection = computed(() => this._state().connection);
// Ações
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. Estilização e Sistema de Design
Usamos Tailwind CSS 4 com uma paleta de cores semântica definida em styles.css.
Regras de Uso
- Utility-First: Escreva classes diretamente no HTML.
- Sem Números Mágicos: Use valores do tema (ex.:
p-4, nãop-[16px]). - Modo Escuro: Use o modificador
dark:para todas as classes relacionadas a cores.
Paleta de Cores
A aplicação usa uma convenção de nomenclatura semântica mapeada para as cores do Tailwind.
Cores Principais
| Categoria | Nome Semântico | Modo Claro | Modo Escuro | Uso |
|---|---|---|---|---|
| Fundo | background | gray-50 | gray-950 | Fundo principal da aplicação |
| Superfície | surface | white | gray-900 | Cartões, modais, seções |
| Superfície Alt | surface-alt | gray-100 | gray-800 | Fundos secundários, campos de input |
| Primária | brand | blue-600 | blue-600 | Ações primárias, botões, destaque |
| Primária Suave | brand-muted | blue-50 | blue-900/30 | Estados selecionados, realces leves |
| Sucesso | success | emerald-500 | emerald-600 | Estados de sucesso, confirmação |
| Sucesso Suave | success-muted | emerald-50 | emerald-900/30 | Fundos de sucesso |
| Perigo | danger | red-600 | red-600 | Erros, ações destrutivas |
| Perigo Suave | danger-muted | red-50 | red-900/30 | Fundos de erro |
| Aviso | warning | amber-500 | amber-600 | Avisos, estados pendentes |
| Aviso Suave | warning-muted | amber-50 | amber-900/30 | Fundos de aviso |
Tipografia e Bordas
| Categoria | Modo Claro | Modo Escuro | Uso |
|---|---|---|---|
| Primário | gray-900 | white | Títulos principais e texto do corpo |
| Secundário | gray-500 | gray-400 | Subtítulos, rótulos, info secundária |
| Suave | gray-400 | gray-500 | Texto desabilitado, placeholders |
| Borda | gray-200 | gray-800 | Divisores padrão e bordas de cartões |
Implementação em styles.css
As cores são definidas usando variáveis CSS no bloco @theme:
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. Padrões Comuns de Componentes
Cartões e Contêineres
Estilização padrão para contêineres de conteúdo (como cartões de estimativa, listas):
<div class="flex flex-col bg-surface-100/60 border border-surface-200 dark:bg-gray-900/40 dark:border-gray-800/60 rounded-md shadow-sm">
<!-- Conteúdo -->
</div>
- Fundo:
bg-surface-100/60(Claro) /dark:bg-gray-900/40(Escuro) - Borda:
border border-surface-200(Claro) /dark:border-gray-800/60(Escuro) - Arredondamento:
rounded-md(Padrão) - Divisores:
divide-y divide-surface-300 dark:divide-gray-800
Cabeçalhos Tipográficos
<div class="flex flex-col gap-1">
<h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">Título</h2>
<span class="text-sm font-normal text-gray-600 dark:text-gray-400">Descrição do subtítulo</span>
</div>