michaelschiemer/docs/components/README.md

Component System

Das Component-System ermöglicht wiederverwendbare UI-Komponenten mit konsistenter Syntax und Design-Token-Integration.

Syntax

Alle Components verwenden die <x-*> Syntax:

<x-button variant="primary" size="sm">Click me</x-button>

Verfügbare Components

Button

Vielseitige Button-Komponente mit verschiedenen Varianten und Größen.

Syntax:

<x-button variant="primary|secondary|danger|success|ghost" 
          size="sm|md|lg" 
          href="/url"
          disabled>
    Button Text
</x-button>

Attribute:

• variant (optional): primary, secondary, danger, success, ghost (Standard: primary)
• size (optional): sm, md, lg (Standard: md)
• href (optional): Wenn gesetzt, wird ein <a>-Tag statt <button> verwendet
• disabled (optional): Deaktiviert den Button
• type (optional): Button-Typ (button, submit, reset) - nur bei <button> relevant
• full-width (optional): Button nimmt volle Breite ein
• icon (optional): Icon-HTML für Icon-Button

Beispiele:

<!-- Primary Button -->
<x-button variant="primary">Save</x-button>

<!-- Secondary Button als Link -->
<x-button variant="secondary" href="/admin">Back</x-button>

<!-- Small Danger Button -->
<x-button variant="danger" size="sm">Delete</x-button>

<!-- Disabled Button -->
<x-button variant="primary" disabled>Processing...</x-button>

<!-- Full Width Button -->
<x-button variant="primary" full-width>Submit Form</x-button>

Card

Card-Komponente für strukturierte Inhaltsblöcke.

Syntax:

<x-card variant="default|highlighted|success|warning|error"
        title="Card Title"
        subtitle="Subtitle"
        footer="Footer Content">
    Card content here
</x-card>

Attribute:

• variant (optional): default, highlighted, success, warning, error (Standard: default)
• title (optional): Card-Titel
• subtitle (optional): Card-Untertitel
• footer (optional): Footer-Text
• image-src (optional): Bild-URL für Card-Header
• image-alt (optional): Alt-Text für Bild

Beispiele:

<!-- Einfache Card -->
<x-card>
    <p>Card content</p>
</x-card>

<!-- Card mit Titel -->
<x-card title="Welcome">
    <p>Welcome to our platform!</p>
</x-card>

<!-- Card mit Variante -->
<x-card variant="success" title="Success" subtitle="Operation completed">
    <p>Your changes have been saved.</p>
</x-card>

<!-- Card mit Bild -->
<x-card image-src="/images/hero.jpg" image-alt="Hero Image" title="Featured">
    <p>Featured content here</p>
</x-card>

Badge

Kleine Status-Indikatoren und Labels.

Syntax:

<x-badge variant="default|success|warning|error|info"
         size="sm|md|lg"
         pill>
    Badge Text
</x-badge>

Attribute:

• variant (optional): default, success, warning, error, info (Standard: default)
• size (optional): sm, md, lg (Standard: md)
• pill (optional): Rundet die Badge ab (pill-Form)

Beispiele:

<!-- Default Badge -->
<x-badge>New</x-badge>

<!-- Success Badge -->
<x-badge variant="success">Active</x-badge>

<!-- Warning Badge -->
<x-badge variant="warning">Pending</x-badge>

<!-- Pill Badge -->
<x-badge variant="info" pill>Beta</x-badge>

<!-- Small Badge -->
<x-badge variant="error" size="sm">Error</x-badge>

Best Practices

Konsistente Verwendung

1. Immer Components verwenden: Verwende <x-button> statt <button class="btn">
2. Varianten statt Custom CSS: Nutze variant Attribute statt eigene CSS-Klassen
3. Design Tokens: Components nutzen automatisch Design Tokens für konsistente Styles

Performance

• Components werden server-side gerendert
• Keine JavaScript-Dependencies für statische Components
• Caching für bessere Performance

Accessibility

• Components generieren semantisch korrektes HTML
• ARIA-Attribute werden automatisch gesetzt wo nötig
• Keyboard-Navigation wird unterstützt

Migration von alten Templates

Von direkten CSS-Klassen

<!-- Vorher -->
<button class="btn btn--primary btn--sm">Click</button>

<!-- Nachher -->
<x-button variant="primary" size="sm">Click</x-button>

Von admin-* Klassen

<!-- Vorher -->
<button class="admin-btn admin-btn--secondary">Click</button>

<!-- Nachher -->
<x-button variant="secondary">Click</x-button>

Von Syntax

<!-- Vorher -->
<component name="button" variant="primary">Click</component>

<!-- Nachher -->
<x-button variant="primary">Click</x-button>

Template Linting

Verwende den design:lint-templates Command um Templates auf Component-Verwendung zu prüfen:

php console.php design:lint-templates

Der Linter erkennt:

• Direkte CSS-Klassen-Verwendung
• Deprecated admin-* Klassen
• Alte <component> Syntax

Modern Web Features

• Search Component - Semantisches <search> Element (Baseline 2023)
• Popover Component - Native Popover API (Baseline 2025)

Weitere Components

Weitere Components werden kontinuierlich hinzugefügt. Siehe die einzelnen Component-Dateien in src/Framework/View/Components/ für Details.