diff --git a/AGENTS.md b/AGENTS.md index 448accc..9b5fd62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,9 @@ > **Projekt:** hms-licht-ton (ID 30) > **Stack:** Nuxt 3 (Frontend) + FastAPI (Backend) + PostgreSQL + Redis > **Deployment:** Coolify (Docker) auf coolify-01 +> +> **DESIGN-RICHTLINIEN:** `docs/design-rules.md` – VERBINDLICH für alle Erweiterungen! +> Jeder KI-Agent MUSS diese Regeln vor der Implementierung lesen und einhalten. --- diff --git a/docs/design-rules.md b/docs/design-rules.md new file mode 100644 index 0000000..64fe5f9 --- /dev/null +++ b/docs/design-rules.md @@ -0,0 +1,508 @@ +# HMS Licht & Ton – Design-Richtlinien für KI-Agenten + +> **VERBINDLICH:** Diese Regeln MÜSSEN bei jeder Erweiterung der Website eingehalten werden. +> Abweichungen sind Fehler. Der freigegebene Prototyp ist die Quelle der Wahrheit. +> Prototyp: `https://webspace.media-on.de/hms-prototype/index.html?v=8` +> Referenz-Dateien: `docs/prototype-app.js`, `docs/prototype-index.html`, `frontend/assets/css/prototype-style.css` + +--- + +## 1. Farbsystem (Dark Theme + Orange Akzent) + +### Hauptfarben (Agent Zero Dark Theme Grautöne) +| Token | Hex | Verwendung | +|-------|-----|------------| +| `--bg` | `#131313` | Seiten-Hintergrund | +| `--panel` | `#1a1a1a` | Panels, Cards, Header | +| `--surface` | `#212121` | Input-Felder, Surface-Level | +| `--row` | `#272727` | List-Items, Zwischenebenen | +| `--card` | `#2d2d2d` | Card-Hintergrund | +| `--border` | `#444444a8` | Borders (mit Alpha) | +| `--border-strong` | `#555555` | Strong Borders (Inputs) | +| `--secondary` | `#656565` | Sekundärfarbe, Icons, grauer Text | +| `--primary` | `#737a81` | Primärfarbe (leicht bläuliches Grau) | +| `--text` | `#ffffff` | Haupttext | +| `--text-muted` | `#d4d4d4` | Gedimmter Text | + +### Orange Akzent (DEZENT – keine großen Flächen!) +| Token | Wert | Verwendung | +|-------|------|------------| +| `--color-accent` | `#EC6925` | Buttons, Badges, Text-Akzente, Logo-Border | +| `--color-accent-hover` | `#d4581a` | Button Hover | +| `--color-accent-light` | `rgba(236, 105, 37, 0.08)` | Badge-Hintergrund, Nav-Active | +| `--color-accent-border` | `rgba(236, 105, 37, 0.25)` | Card Hover Border | +| `--color-accent-dark` | `#b8461a` | Dunkle Variante | + +### Status-Farben +| Token | Hex/RGBA | Verwendung | +|-------|----------|------------| +| `--color-success` | `#4ade80` | Erfolg-Meldungen | +| `--color-success-bg` | `rgba(74, 222, 128, 0.08)` | Erfolg-Hintergrund | +| `--color-error` | `#f87171` | Fehler, Pflichtfelder | +| `--color-error-bg` | `rgba(248, 113, 113, 0.08)` | Fehler-Hintergrund | +| `--color-warning` | `#fbbf24` | Warnungen | +| `--color-info` | `#60a5fa` | Info | + +### FARB-REGELN +- **Orange NIEMALS als große Fläche** – nur für Buttons, Badges, kleine Text-Highlights, Border +- **Hintergründe IMMER Grautöne** (#131313 bis #2d2d2d) +- **Text IMMER `var(--text)` (#ffffff) oder `var(--text-muted)` (#d4d4d4)** +- **Sekundärer Text `var(--secondary)` (#656565)** für sehr gedimmte Infos +- **Inline Styles mit CSS Variablen:** `style="color: var(--text)"`, `style="background: var(--panel)"` + +--- + +## 2. Typography +- **Font Family:** Inter (Google Fonts), Weights: 400, 500, 600, 700, 800 +- **Größen:** Tailwind Utilities (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`) +- **Headings:** `font-bold` oder `font-semibold`, `leading-tight` für große Headlines +- **Body:** `leading-relaxed` für längere Texte +- **Line Height:** 1.6 (Body), 1.1-1.3 (Headings) + +--- + +## 3. Layout-System + +### Container +- **Max-Width:** `max-w-7xl` (1280px) +- **Padding:** `px-4 sm:px-6 lg:px-8` +- **Center:** `mx-auto` + +### Sections +- **Vertical Padding:** `py-12 sm:py-16` (Standard), `py-16 sm:py-20` (große Sections), `py-20 sm:py-32` (Hero) +- **Background Alternation:** `var(--bg)` → `var(--panel)` → `var(--bg)` für visuelle Trennung +- **Section Dividers:** `.hms-section-divider` (subtiler Gradient) + +### Grid +- **Cards Grid:** `grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-6` +- **Speaker Grid:** `.hms-speaker-grid` (auto-fill, minmax 160px) +- **Gallery Grid:** `.hms-gallery` (auto-fill, minmax 300px) +- **2-Spalten Layout:** `grid lg:grid-cols-2 gap-8` oder `gap-12` + +### Responsive Breakpoints +- `sm:` 640px (Tablet Portrait) +- `md:` 768px (Desktop Nav visible, Mobile Burger hidden) +- `lg:` 1024px (Desktop, 3-4 Column Grids) +- **Mobile-First:** Alle Layouts starten 1-Spalte + +--- + +## 4. CSS Komponenten-Klassen (hms-*) + +### ÜBERSICHT: Alle hms-* Klassen aus prototype-style.css +Diese Klassen sind in `assets/css/main.css` definiert und MÜSSEN verwendet werden. +Keine eigenen Klassen erfinden! + +### Buttons +```html + + + + + + + + +``` +- **Padding:** `px-8 py-4` für große Buttons, `px-4 py-2` für kleine, `px-3 py-1.5` für Mini +- **Font:** `font-semibold` oder `font-medium`, `text-sm` für Standard +- **Hover-Effekte:** Primary → box-shadow glow + translateY(-1px); Secondary → border accent +- **Disabled:** `--secondary` bg, `cursor: not-allowed` + +### Cards +```html +
+

Title

+

Description

+
+``` +- **Background:** `var(--panel)` (#1a1a1a) +- **Border:** `1px solid var(--border)` (#444444a8) +- **Border-Radius:** `4px` (--radius-lg) +- **Hover:** Box-shadow wird stärker, Border wird heller + +### Equipment Cards +```html +
+
+ +
📦
+ {{ item.category }} +
+
+

{{ item.name }}

+

{{ item.description }}

+
+ {{ item.code }} + +
+
+
+``` + +### Badges +```html +Badge Text +Gray Badge +Success +Error +``` +- **Border-Radius:** `9999px` (pill shape) +- **Primary:** Orange bg (12% alpha), orange text, orange border (20% alpha) + +### Inputs +```html + + + + +``` +- **Background:** `var(--surface)` (#212121) +- **Border:** `1px solid var(--border-strong)` (#555555) +- **Focus:** Orange border + subtle orange box-shadow +- **Error:** Red border + red box-shadow +- **Padding:** `var(--space-md) var(--space-lg)` + +### Filter Chips +```html + +``` +- **Inactive:** Surface bg, muted text, border +- **Active:** Orange bg, white text, orange border + +### Navigation Buttons +```html + +``` +- **Hover:** Orange text + accent-light bg + Unterstrich-Animation +- **Active:** Orange text + accent-light bg + +### Skeleton Loading +```html +
+``` +- Shimmer Animation von `prototype-style.css` + +### Spinner +```html + +``` + +### Icon Circle (Service Icons) +```html +
+``` +- 48x48px, surface bg, border, centered content + +### Hero +```html +
+
+
+
+ +
+
+``` +- **hms-hero-bg:** Absolute, background-size cover, opacity 0.35 +- **hms-hero-overlay:** Linear gradient von rgba(19,19,19,0.6) zu var(--bg) +- **Content:** `relative z-10` über Overlay + +--- + +## 5. Inline Style Pattern + +### REGEL: Inline Styles verwenden IMMER CSS Variablen +```html + +

Title

+

Text

+
+ + +

Title

+

Text

+``` + +### Häufige Inline Styles aus dem Prototyp +- `style="color: var(--text)"` – Haupttext +- `style="color: var(--text-muted)"` – Gedimmter Text +- `style="color: var(--secondary)"` – Sehr gedimmter Text +- `style="color: var(--color-accent)"` – Orange Akzent +- `style="background: var(--panel)"` – Panel BG +- `style="background: var(--bg)"` – Seiten BG +- `style="background: var(--surface)"` – Surface BG +- `:style="{ borderColor: 'var(--border)' }"` – Border Color +- `:style="{ background: 'var(--color-success-bg)', color: 'var(--color-success)' }"` – Success State + +--- + +## 6. Komponenten-Struktur + +### Bestehende Komponenten (NICHT neu erfinden) +| Komponente | Datei | Zweck | +|---|---|---| +| HmsLogo | `components/HmsLogo.vue` | Echtes SVG Logo (H + orange Border) | +| SpeakerIcon | `components/SpeakerIcon.vue` | 6 Lautsprecher-Typ SVG Icons | +| AppHeader | `components/AppHeader.vue` | Sticky Header, Nav, Cart, Mobile Burger | +| AppFooter | `components/AppFooter.vue` | 4-Spalten Footer | +| ServiceCard | `components/ServiceCard.vue` | Service Card mit Icon Circle | +| EquipmentCard | `components/EquipmentCard.vue` | Equipment Card mit Badge, Image, Add-to-Cart | +| LoadingSkeleton | `components/LoadingSkeleton.vue` | Skeleton Loading Cards | +| EmptyState | `components/EmptyState.vue` | Empty State mit Icon + Action | +| ErrorState | `components/ErrorState.vue` | Error State mit Retry | + +### Neue Komponenten erstellen – Checklist +1. CSS Klassen aus `prototype-style.css` verwenden (hms-*) +2. Inline Styles mit CSS Variablen +3. Tailwind Utilities für Layout/Spacing +4. TypeScript mit `lang="ts"` +5. `useHead()` für Meta Tags +6. ARIA Attributes (role, aria-label, aria-current, etc.) +7. Responsive (mobile-first, sm/md/lg breakpoints) + +--- + +## 7. UX States (MUSS in jeder View implementiert) + +### Loading State +```html + +``` + +### Empty State +```html + +``` + +### Error State +```html + +``` + +### Success State +```html +
+
+ ✓ +
+

Erfolg

+

Nachricht

+
+``` + +### Submitting State +```html + +``` + +--- + +## 8. Accessibility (WCAG 2.1 AA) + +### MUSS-Regeln +- **Skip Link:** `` am Seitenanfang +- **Semantic HTML:** `
`, `
`, `