Guía de Estilo y Convenciones de Codificación Frontend
Este documento define los estándares de codificación, patrones arquitectónicos y el sistema de diseño para el frontend Angular de Guessimate.
1. Stack Tecnológico
- Framework: Angular 20+
- Estilado: Tailwind CSS 4
- Gestión de Estado: Angular Signals y RxJS
- Sistema de Compilación: Angular CLI (Esbuild)
2. Estructura del Proyecto
Seguimos una estructura de directorios Basada en Funcionalidades. El código se organiza por dominio funcional en lugar de por tipo técnico.
src/app/
├── core/ # Singletons globales (Guards, Interceptors, Servicios Globales)
├── layout/ # Componentes de diseño (Navegación, Pie de página, Shell)
├── features/ # Módulos de funcionalidad (Lógica de dominio)
│ ├── home/
│ ├── session/
│ │ ├── components/ # Componentes tontos/de presentación
│ │ ├── pages/ # Componentes inteligentes/contenedores (Enrutados)
│ │ ├── services/ # Estado/lógica específica de la funcionalidad
│ │ └── models/ # Tipos específicos de la funcionalidad
│ └── ...
├── websocket/ # Infraestructura WebSocket
└── shared/ # Utilidades compartidas (Pipes, Directivas, UI genérica)
Convenciones de Nomenclatura
- Archivos: Kebab-case (ej.,
session-page.component.ts,auth.service.ts). - Clases: PascalCase (ej.,
SessionPageComponent,AuthService). - Selectores: Prefijo
app-, kebab-case (ej.,app-user-profile). - Signals: Sin sufijo, nombre descriptivo sustantivo/verbo (ej.,
user(),isLoading()). - Observables: Sufijo
$(ej.,user$).
3. Estándares de Componentes
Definición
- Usar Componentes Independientes (
standalone: truees el valor predeterminado en v19+). - Preferir Plantillas en Línea para la mayoría de los componentes, manteniendo la lógica y la vista juntas.
- Evitar archivos CSS externos; usar clases utilitarias de Tailwind CSS directamente en la plantilla.
@Component({
selector: 'app-example',
imports: [CommonModule, RouterLink], // Importaciones 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');
}
Flujo de Control
Usar la nueva sintaxis de flujo de control integrada de Angular.
<!-- Bien -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
Inyección de Dependencias
Preferir la función inject() sobre la inyección por constructor para una mejor inferencia de tipos y código más limpio.
// Bien
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// Evitar si es posible
constructor(private
route: ActivatedRoute
)
{
}
4. Gestión de Estado
- Estado Local: Usar
signal()para estado primitivo. - Estado Compartido: Usar Signal Stores (Servicios que usan Signals) proporcionados al nivel adecuado (Raíz o Componente).
- Datos Reactivos: Usar
computed()para estado derivado yeffect()con moderación para efectos secundarios.
@Injectable()
export class SessionStore {
// Estado
private readonly _state = signal<SessionState>(initialState);
// Selectores
readonly lobby = computed(() => this._state().lobby);
readonly connection = computed(() => this._state().connection);
// Acciones
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. Estilado y Sistema de Diseño
Usamos Tailwind CSS 4 con una paleta de colores semántica definida en styles.css.
Reglas de Uso
- Utility-First: Escribir clases directamente en HTML.
- Sin Números Mágicos: Usar valores del tema (ej.,
p-4nop-[16px]). - Modo Oscuro: Usar el modificador
dark:para todas las clases relacionadas con colores.
Paleta de Colores
La aplicación utiliza una convención de nomenclatura semántica mapeada a colores de Tailwind.
Colores Principales
| Categoría | Nombre Semántico | Modo Claro | Modo Oscuro | Uso |
|---|---|---|---|---|
| Fondo | background | gray-50 | gray-950 | Fondo principal de la aplicación |
| Superficie | surface | white | gray-900 | Tarjetas, modales, secciones |
| Superficie Alt | surface-alt | gray-100 | gray-800 | Fondos secundarios, campos de entrada |
| Principal | brand | blue-600 | blue-600 | Acciones principales, botones, resaltados |
| Principal Sutil | brand-muted | blue-50 | blue-900/30 | Estados seleccionados, resaltados suaves |
| Éxito | success | emerald-500 | emerald-600 | Estados de éxito, confirmación |
| Éxito Sutil | success-muted | emerald-50 | emerald-900/30 | Fondos de éxito |
| Peligro | danger | red-600 | red-600 | Errores, acciones destructivas |
| Peligro Sutil | danger-muted | red-50 | red-900/30 | Fondos de error |
| Advertencia | warning | amber-500 | amber-600 | Advertencias, estados pendientes |
| Advertencia Sutil | warning-muted | amber-50 | amber-900/30 | Fondos de advertencia |
Tipografía y Bordes
| Categoría | Modo Claro | Modo Oscuro | Uso |
|---|---|---|---|
| Principal | gray-900 | white | Encabezados principales y texto del cuerpo |
| Secundario | gray-500 | gray-400 | Subtítulos, etiquetas, información secundaria |
| Sutil | gray-400 | gray-500 | Texto deshabilitado, marcadores de posición |
| Borde | gray-200 | gray-800 | Divisores estándar y bordes de tarjeta |
Implementación en styles.css
Los colores se definen usando variables CSS en el bloque @theme:
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. Patrones Comunes de Componentes
Tarjetas y Contenedores
Estilado estándar para contenedores de contenido (como tarjetas de estimación, 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">
<!-- Contenido -->
</div>
- Fondo:
bg-surface-100/60(Claro) /dark:bg-gray-900/40(Oscuro) - Borde:
border border-surface-200(Claro) /dark:border-gray-800/60(Oscuro) - Redondeo:
rounded-md(Estándar) - Divisores:
divide-y divide-surface-300 dark:divide-gray-800
Encabezados de Tipografía
<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">Descripción del subtítulo</span>
</div>