# Global Rules

Diese Datei enthaelt Regeln, die fuer alle Komponenten gelten koennen.
Sie ist nicht fuer Vokabular gedacht; Vokabular steht in [[03_Benennung]].
Gruppenspezifische visuelle Regeln stehen in [[04_Gruppenregeln]].

## Component API

### Regel: Props folgen einer Prioritaets-Hierarchie

Status: Entschieden

Props werden nach ihrer visuellen und funktionalen Ueberschreibungsstaerke eingeordnet.
Je staerker eine Prop andere Darstellung ueberschreiben kann, desto hoeher steht sie in der Reihenfolge.

| Prioritaet | Kategorie              | Bedeutung                                                  | Beispiele                                                                                                         |
| ---------- | ---------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 1          | Zustand                | Ueberschreibt andere Styles am staerksten                  | `disabled`, `error`, `loading`, `checked`, `indeterminate`, `selected`                                            |
| 2          | Erscheinung            | Legt visuelle Grundidentitaet fest                         | `variant`, `tone`, `color`, `primary`, `secondary`, `neutral`, `destructive`, `success`, `warning`, `information` |
| 3          | Groesse                | Veraendert Hoehe, Padding, Schriftgroesse oder Dichte      | `size`                                                                                                            |
| 4          | Layout-Sonderfaelle    | Veraendert Struktur oder Rahmenbedingungen                 | `fillContainer`, `borderless`, `noPadding`, `border`, `square`                                                    |
| 5          | Sichtbarkeit / Toggles | Blendet Teile ein oder aus                                 | `showLabel`, `hideLabel`, `dismissible`, `noAction`                                                               |
| 6          | Inhalt / Slots         | Liefert Inhalt, aber steuert nicht die visuelle Prioritaet | `children`, `icon`, `image`, `actions`, `actionChildren`, Textwerte                                               |


Innerhalb einer Kategorie wird nach Ueberschreibungsstaerke sortiert.
Beispiel: `disabled` steht vor `error`, weil disabled die Komponente vollstaendig inaktiv macht.

## Edge Cases

### Regel: Props nach Funktion sortieren, nicht nach Namen

Status: Entschieden

Ein Prop-Name allein entscheidet nicht ueber die Kategorie.
Die Bedeutung des Props entscheidet.

Beispiel:

| Prop | Bedeutung | Kategorie |
| --- | --- | --- |
| `state` bei echtem UI-Zustand | disabled, error, loading | Zustand |
| `state` bei Progress-Status | uploading, success, error als visuelle Erscheinung | Erscheinung |

Leitfrage: Ueberschreibt es alles als Zustand, oder beschreibt es die Grunderscheinung?

### Regel: Technische Primitive haben Vorrang vor idealer Sortierung

Status: Entschieden

Bei Subframe- oder Core-Primitives koennen Props technisch vorgegeben sein.
Wenn eine Prop als `cannot be modified` oder technisch fixiert gilt, wird sie nicht erzwungen umsortiert.
Der Rest der Props wird um diese technische Vorgabe herum sortiert.

Beispiele:

- `checked`
- `indeterminate`
- `open`
- `value`

Semantisch koennen diese Props trotzdem in Kategorie 1 gehoeren.
Die technische Reihenfolge hat aber Vorrang, wenn eine Umsortierung das Primitive bricht.

### Regel: Slot-Props gehoeren zu Inhalt

Status: Entschieden

Slot-Props und React-Nodes gehoeren zur niedrigsten Prioritaet.
Sie erzeugen Inhalt, sind aber keine Style-Treiber.

Beispiele:

- `children`
- `actions`
- `actionChildren`
- `icon`
- `image`

### Regel: Komponenten duerfen Kategorien auslassen

Status: Entschieden

Eine Komponente muss nicht Props aus jeder Kategorie haben.
Wenn eine Komponente keine Zustands-Props hat, beginnt ihre API-Hierarchie einfach bei der naechsten passenden Kategorie.

Beispiel: Avatar, Badge oder Tag koennen ohne `disabled` oder `error` trotzdem regelkonform sein.

### Regel: Subkomponenten folgen derselben Logik

Status: Entschieden

Subkomponenten und interne Parts folgen derselben Prop-Prioritaet im Kleinen.

Beispiele:

- `Switch.Thumb`
- `Progress.Indicator`
- `Select.Trigger`