Frontend Style Guide & Coding Conventions (Übersetzung)
Dieses Dokument definiert die Codestandards, Architekturmuster und das Designsystem für die Guessimate Angular-Frontend-Anwendung.
1. Technologie-Stack
- Framework: Angular 20+
- Styling: Tailwind CSS 4
- Zustandsverwaltung: Angular Signals & RxJS
- Build-System: Angular CLI (Esbuild)
2. Projektstruktur
Wir folgen einem Feature-basierten Verzeichnisaufbau. Der Code wird nach Domänenfunktionen (Features) statt nach technischen Typen organisiert.
src/app/
├── core/ # Globale Singletons (Guards, Interceptors, globale Services)
├── layout/ # Layout-Komponenten (Navigation, Footer, Shell)
├── features/ # Feature-Module (Domänenlogik)
│ ├── home/
│ ├── session/
│ │ ├── components/ # Dumme/Präsentationskomponenten
│ │ ├── pages/ # Smart/Container-Komponenten (geroutet)
│ │ ├── services/ # Featurspezifische Zustandsverwaltung/Logik
│ │ └── models/ # Featurspezifische Typen
│ └── ...
├── websocket/ # WebSocket-Infrastruktur
└── shared/ # Gemeinsam genutzte Hilfsmittel (Pipes, Directives, generische UI)
Namenskonventionen
- Dateien: Kebab-Case (z.B.
session-page.component.ts,auth.service.ts). - Klassen: PascalCase (z.B.
SessionPageComponent,AuthService). - Selektoren:
app--Präfix, Kebab-Case (z.B.app-user-profile). - Signals: Kein Suffix, beschreibendes Nomen/Verb (z.B.
user(),isLoading()). - Observables:
$-Suffix (z.B.user$).
3. Komponentenstandards
Definition
- Verwende Standalone-Komponenten (ab v19 ist
standalone: trueStandard). - Bevorzuge Inline-Templates für die meisten Komponenten, um Logik und Ansicht beieinander zu halten.
- Vermeide externe CSS-Dateien; verwende direkt Tailwind CSS-Utility-Klassen im Template.
@Component({
selector: 'app-example',
imports: [CommonModule, RouterLink], // Explizite Imports
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');
}
Kontrollfluss
Verwende die neue eingebaute Angular-Control-Flow-Syntax.
<!-- Gut -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
Abhängigkeitsinjektion
Bevorzuge die inject()-Funktion gegenüber der Konstruktorinjektion, um bessere Typinferenz und saubereren Code zu erhalten.
// Gut
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// Vermeiden, wenn möglich
constructor(private
route: ActivatedRoute
)
{
}
4. Zustandsverwaltung
- Lokaler Zustand: Verwende
signal()für primitive Zustände. - Geteilter Zustand: Verwende Signal Stores (Services, die Signals verwenden), die auf der entsprechenden Ebene (Root oder Komponente) bereitgestellt werden.
- Reaktive Daten: Verwende
computed()für abgeleitete Zustände undeffect()sparsam für Seiteneffekte.
@Injectable()
export class SessionStore {
// Zustand
private readonly _state = signal<SessionState>(initialState);
// Selektoren
readonly lobby = computed(() => this._state().lobby);
readonly connection = computed(() => this._state().connection);
// Aktionen
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. Styling & Designsystem
Wir verwenden Tailwind CSS 4 mit einer semantischen Farbpalette, die in styles.css definiert ist.
Nutzungsregeln
- Utility-First: Schreibe Klassen direkt in HTML.
- Keine magischen Zahlen: Verwende Themenwerte (z.B.
p-4, nichtp-[16px]). - Dark Mode: Verwende den Modifikator
dark:für alle farbbezogenen Klassen.
Farbpalette
Die Anwendung verwendet eine semantische Benennungskonvention, die auf Tailwind-Farben abgebildet wird.
Kernfarben
| Kategorie | Semantischer Name | Heller Modus | Dunkler Modus | Verwendung |
|---|---|---|---|---|
| Hintergrund | background | gray-50 | gray-950 | Hauptanwendungshintergrund |
| Oberfläche | surface | white | gray-900 | Karten, Modale, Abschnitte |
| Oberfläche Alt | surface-alt | gray-100 | gray-800 | Sekundäre Hintergründe, Eingabefelder |
| Primär | brand | blue-600 | blue-600 | Primäre Aktionen, Buttons, Hervorhebungen |
| Primär dezent | brand-muted | blue-50 | blue-900/30 | Ausgewählte Zustände, dezente Hervorhebungen |
| Erfolg | success | emerald-500 | emerald-600 | Erfolgszustände, Bestätigungen |
| Erfolg dezent | success-muted | emerald-50 | emerald-900/30 | Erfolgshintergründe |
| Gefahr | danger | red-600 | red-600 | Fehler, destruktive Aktionen |
| Gefahr dezent | danger-muted | red-50 | red-900/30 | Fehlerhintergründe |
| Warnung | warning | amber-500 | amber-600 | Warnungen, ausstehende Zustände |
| Warnung dezent | warning-muted | amber-50 | amber-900/30 | Warnungshintergründe |
Typografie & Rahmen
| Kategorie | Heller Modus | Dunkler Modus | Verwendung |
|---|---|---|---|
| Primär | gray-900 | white | Hauptüberschriften und Fließtext |
| Sekundär | gray-500 | gray-400 | Untertitel, Labels, sekundäre Info |
| Dezent | gray-400 | gray-500 | Deaktivierter Text, Platzhalter |
| Rahmen | gray-200 | gray-800 | Standardtrennlinien und Kartenrahmen |
Umsetzung in styles.css
Farben werden mit CSS-Variablen im @theme-Block definiert:
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. Häufige Komponentenmuster
Karten & Container
Standardstyling für Inhaltscontainer (z.B. Schätzkarten, Listen):
<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">
<!-- Inhalt -->
</div>
- Hintergrund:
bg-surface-100/60(Hell) /dark:bg-gray-900/40(Dunkel) - Rahmen:
border border-surface-200(Hell) /dark:border-gray-800/60(Dunkel) - Abrundung:
rounded-md(Standard) - Trennlinien:
divide-y divide-surface-300 dark:divide-gray-800
Typografie-Überschriften
<div class="flex flex-col gap-1">
<h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">Titel</h2>
<span class="text-sm font-normal text-gray-600 dark:text-gray-400">Untertitel Beschreibung</span>
</div>