# Leadity App-Shell-Vertrag Status: freigegebenes Komponentenpaket für Header, Footer, globale Navigation, Kontextleiste und Breadcrumbs. Dieser Vertrag verdichtet die belegten Figma-Varianten mit dem repository-bestätigten Öffnen- und Schließen-Verhalten. `DESIGN.md` bleibt die kanonische Regelquelle; das vollständige Menüinventar steht in `navigation-contract.md`. Fokus, Tastatur, Trefferflächen und Reduced Motion folgen zusätzlich `interaction-accessibility-contract.md`. Foundation-Bereiche, kompakte Headerbelegung, Sidebar-Reflow und Overflow folgen zusätzlich `responsive-overflow-contract.md`. ## Quellen und Entscheidungsrang - Header-Komponente: Figma `2147:1502`. - Gemeinsamer Unternehmens-/Jahrestrigger mit vollständiger Zustandsmatrix: Figma `2459:8603`; Basiszustand `2459:8600`; zugehörige Auswahlkomponente `2474:7357`, Zeilenfamilie `2467:5931`. - Kontextmenü-Komponente mit horizontaler und vertikaler Ausrichtung: Figma `2376:24662`. - Footer-Komponente: Figma `2147:1518`. - Globale Navigation und Zustände: Figma `2147:498`; vollständige Children-Struktur: Figma `2947:12213`. - Breadcrumb-Komponentenfamilie: Figma `5370:14390`, Komponente `8080:6468`. - Vollständiges Schließen und Wiederöffnen der Navigation: repository-belegter Shell-Vertrag in `navigation-contract.md`. - Figma zeigt zusätzlich eine geschlossene 60-px-Minivariante. Sie ist nicht der Vertrag der drei Seitentemplates und wird dort nicht eingesetzt. Das Mandanten-Theme bleibt dynamisch: Der Header verwendet `--mainColor` und `--secondColor`. Weder der Runtime-Standard noch Figma-Grün werden als fester Komponentenwert in Templates geschrieben. Die operative UI-Primary bleibt davon getrennt. ## 1. Responsive Shell-Matrix | Region | Desktop | Tablet | Mobil | |---|---:|---:|---:| | Globaler Header | 50 px | 50 px | 50 px | | Header-Aktion | 48 × 48 px, Icon 20 px | 48 × 48 px, Icon 20 px | 48 × 48 px, Icon 20 px | | Globaler Footer | 50 px | 50 px | 256 px | | Navigation geöffnet | 344 px breit | 344 px breit beziehungsweise Overlay | geschlossen startendes Overlay | | Kontextleiste | 48 px breit | 48 px breit | nur im belegten Seitenkontext | ## 2. Globaler Header - Die Höhe beträgt an allen Breakpoints 50 px. - Globale Header-Aktionen besitzen 48 × 48 px Treffer- und Sichtfläche; das Icon ist 20 px groß. - Die linke Headergruppe verwendet zwischen Hamburger, Home und Unternehmenskontext keinen zusätzlichen Gruppengap. Unternehmensname und Berichtsjahr bilden einen gemeinsamen 40-px-Kontexttrigger mit 16 px horizontalem Padding, 12 px Innenabstand, Full-Radius und 20-px-Chevron. Zwei getrennte Controls für Unternehmen und Berichtsjahr sind im globalen Header nicht zulässig. - Der Trigger folgt exakt der Figma-Matrix `2459:8603`: geschlossen ohne Hover transparent, geschlossen mit Hover `on-primary-15`, geöffnet ohne Hover `on-primary-15` und geöffnet mit Hover transparent. `aria-expanded` ist die kanonische Active-Quelle; im geöffneten Zustand rotiert das 20-px-Chevron um 180 Grad. Der sichtbare Fokusindikator bleibt von dieser Hovermatrix unabhängig erhalten. - Die Textdarstellungsaktion verwendet `fa-light fa-text-size`; `fa-heading` ist in dieser Rolle nicht zulässig. Der Benachrichtigungs-Badge misst mindestens 16 × 16 px und sitzt mit 8 px oberem und rechtem Innenabstand vollständig in der 48-px-Aktionsfläche. - Auf Mobil bleibt der Unternehmenskontext sichtbar und wird bei Platzmangel gekürzt. Nutzername und Berichtsjahr werden ausgeblendet. - Alle vier globalen Header-Aktionen bleiben auch mobil sichtbar. Die reduzierte Informationsdichte darf keine dieser Aktionen entfernen. - Der Header ist eine dynamische Mandantenfläche. Farbe und Kontrast kommen aus dem Runtime-Theme; Figma-Grün wird nicht fest verdrahtet. - Header-Aktionen benötigen einen zugänglichen Namen. Der Fokusindikator muss auf der Theme-Fläche sichtbar bleiben. ### 2.1 Unternehmens-, Rollen- und Vorgangskontext - `data-component="leadity-account-context-switcher"` ist die kanonische Headerkomposition. Markup, Auswahlzustand, Persistenz, Fokusführung und Events gehören ausschließlich `app-shell-navigation.js`; Templates liefern genau ein valides eingebettetes JSON unter `data-account-context`. Fehlt es, ist es syntaktisch ungültig oder fehlen `enabled`, `year` beziehungsweise explizite Accounts mit ID und Bezeichnung, rendert die Runtime ausschließlich „Kontext nicht verfügbar“ und markiert den Fehler fail-closed. Ein synthetischer Account-Fallback ist unzulässig. - Die Komponente wird in Phase 1 eines Prototyps ausdrücklich aktiviert oder bleibt mit `enabled: false` eine gemeinsame statische Anzeige aus Unternehmen und Jahr. Der Default ist nicht interaktiv. Eine lokale Ersatzrolle oder ein zweiter Rollenumschalter außerhalb des Headers ist unzulässig. - `accounts` unterstützt eine beliebig tiefe Baumstruktur. Jeder auswählbare Knoten bindet genau die für diesen Account beziehungsweise Standort geltende Rolle. Verbraucher übergeben `id`, `label`, `role` und optional `children`; konkrete Hierarchien und Rollen gehören ausschließlich in Previews oder Produktdateien. Die visuelle Einrückung wird nach vier Stufen begrenzt, während `aria-level` die vollständige Hierarchietiefe bewahrt, damit tiefe Bäume keinen horizontalen Seitenüberlauf erzeugen. - Der aktive Account wird über `current.accountId` gesetzt. Mit einem prototypspezifisch eindeutigen `storageKey` bleibt die Auswahl lokal im Browser erhalten. Persistenzfehler dürfen die aktuelle Auswahl nicht blockieren. - `processes` ist optional und standardmäßig leer. Ohne modulspezifische Vereinbarung wird keine rechte Vorgangsspalte gerendert und kein Vorgangswechsel simuliert. Ein- und zweispaltige Varianten wachsen inhaltshoch bis maximal 554 px; bei langen Account- oder Vorgangslisten scrollt die jeweilige Liste innerhalb der Schale. Ein Modul darf `id`, `label`, optional `meta`, `disabled` und `actionLabel` konfigurieren; Navigation, Statusänderung oder Abschlusslogik bleiben Eigentum des konkreten Moduls. - Account- oder Vorgangswahlen lösen `leadity:accountcontextchange` mit Account-, Rollen- und Vorgangsdaten aus. Eine konfigurierte Vorgangsaktion löst `leadity:processaction` aus; die App-Shell erfindet dafür keine Fachlogik. - Der Trigger führt `aria-expanded`, `aria-haspopup="dialog"` und `aria-controls`. Das Popover besitzt einen sichtbaren Titel, Light Dismiss, Escape, explizites Schließen und Fokuswiederherstellung. Die 40-px-Schließen-Aktion liegt einschließlich Hoverfläche über den sticky Spaltenüberschriften, erhält ihren zugänglichen Namen über `aria-label` und verwendet kein natives `title`-Tooltip. Die Accountliste verwendet Tree-Semantik mit `aria-level` und `aria-selected`; Pfeil hoch/runter sowie Home/End bewegen den Fokus. - Auf Mobil bleibt der gemeinsame Trigger erhalten. Das Jahr wird gemäß kompakter Headerbelegung visuell ausgeblendet, bleibt aber im zugänglichen Namen enthalten. Das Popover wird einspaltig und viewportgebunden; Accountbaum und optionale Vorgänge scrollen innerhalb der Schale. ## 3. Globaler Footer - Desktop und Tablet verwenden 50 px Höhe. - Links steht das weiße Leadity-Logo auf transparenter Fläche. Für HTML-Artefakte ist `assets/brand/leadity-logo-white-transparent.svg` verbindlich; der unveränderte Figma-Rohdownload bleibt ausschließlich als Quellenartefakt erhalten. - Das sichtbare Footer-Logo misst 69 × 17,162 px. Zwischen Logo und Claim liegen 24 px. Die Aktionsgruppe besitzt keinen zusätzlichen Gruppengap; jede Aktion ist 40 px hoch und verwendet 16 px horizontales Padding, 12 px Abstand zwischen 20-px-Icon und Text sowie Roboto Regular 16/18. - Mobil verwendet 256 px Höhe. Die vorhandenen Kontaktmöglichkeiten bleiben sichtbar, werden untereinander gestapelt und nicht aus der mobilen Variante entfernt; der Leadity-Absender folgt anschließend. - Der Footer bleibt eine globale Shell-Region und darf nicht als lokaler Content-Slot verwendet werden. ## 4. Globale Navigation und Kontextleiste - Die geöffnete Sidebar ist 344 px breit und beginnt mit 32 px Abstand unterhalb des Headers beziehungsweise am oberen Shell-Rand des Contentbereichs. - Zwischen Sidebar und der 48 px breiten Kontextleiste liegen 16 px Abstand. - Logo und Schließen-Aktion liegen im festen 168-px-Panelkopf. Das Logo misst 162 × 40 px und sitzt im nach 48 px beginnenden, 120 px hohen Logorahmen; ausschließlich die bei 168 px beginnende Menüliste scrollt vertikal. - Für das Sidebar-Logo ist `assets/brand/leadity-logo-primary-transparent.svg` verbindlich. Der rohe Figma-Frame `leadity-logo-primary.svg` enthält eine graue Exportfläche und einen violetten Auswahlrahmen und darf nicht als Runtime-Asset verwendet werden. - Navigationseinträge bleiben mindestens 44 px hoch. Ebene 2 ist um 24 px, Ebene 3 um 48 px eingerückt. - Navigationseinträge folgen der Zustandsmatrix aus `navigation-contract.md`: Hover wechselt Light 300 auf Regular 400, lässt die Zeile transparent und färbt bei ausklappbaren Einträgen ausschließlich die 40-px-Pfeilfläche mit `neutral-20`. - Sämtliche Icons innerhalb der geöffneten Navigation verwenden `neutral-60` (`#829ba0`): 16-px-Chevrons, 32-px-Arbeitsphasenicons und das Schließen-Symbol. Sie erben nicht die dunklere Textfarbe der Menüeinträge. - Bereichsüberschriften verwenden Montserrat Bold 21/1,3 auf `text/dark`; der 68-px-Kopfrahmen richtet die 40-px-Iconfläche rechts aus und hält die maskierte Iconfläche bei 32 × 32 px. - Die monochromen 32-px-Arbeitsphasen-SVGs bleiben unveränderte Quellen. `.nav-group-icon` bindet sie über `--nav-group-icon` als CSS-Maske an `neutral-60`; direkte schwarze ``-Ausgabe ist in der Shell unzulässig. - Das X schließt die Sidebar vollständig. Das Hamburger-Menü im globalen Header bleibt erreichbar und öffnet sie erneut. Die in Figma vorhandene 60-px-Minivariante ersetzt dieses repository-belegte Verhalten in den drei Seitentemplates nicht. - Toggle, Close-Button, Escape-Verhalten, Fokus-Rückgabe sowie die Synchronisierung von `data-nav-open`, `aria-expanded`, `aria-hidden` und `inert` gehören ausschließlich `app-shell-navigation.js`. Der über `data-nav-storage-key` adressierte Zustand bleibt über Seitenwechsel erhalten; Persistenzfehler blockieren die Navigation nicht. Templates und Previews binden dafür keine lokalen Listener oder eigenen `setNavigation`-Funktionen. - Die Kontextleiste enthält ausschließlich reale, seitenspezifische Produktaktionen. Ihre Länge folgt der Anzahl vorhandener Aktionen; sie wird nicht künstlich auf eine feste Anzahl aufgefüllt. - Die Kontextleiste unterstützt die Figma-Varianten vertikal und horizontal. Zwischen den 48 × 48 px großen, weißen Aktionsflächen liegen 12 px. Die Position bleibt bei Hover unverändert. - Reguläre Kontexticons verwenden eine 20-px-Glyphenfläche; das Hilfe-Icon ist die belegte 24-px-Ausnahme. Der KI-Assistent verwendet `assets/icons/custom/ai-assistant/20/ai-assistant.svg` in seiner unveränderten 24-px-Assetgeometrie innerhalb der 48-px-Aktionsfläche und wird nicht durch `fa-sparkles` oder eine globale 20 × 20 px Bildregel ersetzt. - Die sechs belegten Defaultaktionen der Template-3-Unterseite heißen KI-Assistent, Einführung, Hilfe, Suche, Nachrichten und Modul wechseln und verwenden die in der Icon-Registry zugeordneten Symbole. Solange ihr konkretes Ziel nicht festgelegt ist, werden sie als normale Launcher-Buttons ohne `aria-pressed`, gegenseitig ausschließende Togglelogik oder positionsverändernde Hoverbewegung behandelt. - Zieltyp, Berechtigung, Verfügbarkeit und passende ARIA-Semantik werden je Kontextaktion mit dem konkreten Produktziel festgelegt; Dialog-, Popover-, Drawer- oder Navigationssemantik wird nicht pauschal vorweggenommen. - Fokusübergabe, `aria-controls` und synchrones `aria-expanded` folgen `navigation-contract.md`. - Interaktive Elemente im dunklen beziehungsweise grünen globalen Header verwenden den weißen Fokusindikator. Reduced Motion entfernt die dekorative Chevron-Drehung, ohne den offenen Zustand zu verbergen. ## 5. Breadcrumbs - Es gibt eine gemeinsame Breadcrumb-Komponente mit drei Surface-Typen: auf der dynamischen Headerfläche, auf weißer Card-Fläche und auf dem grauen Content-Canvas. Die Surface-Variante verändert Kontrast und Darstellung, nicht Semantik oder Pfadstruktur. - Auf der Headerfläche verwendet die Komponente 14 px Schriftgröße bei 21 px Zeilenhöhe. - Auf Content-Flächen verwendet sie 16 px Schriftgröße bei 24 px Zeilenhöhe. - Unterstützt werden bis zu fünf Textebenen sowie optional ein vorgestelltes Home-Icon. - Alle Vorfahren sind echte Links. Der letzte Eintrag ist nicht interaktiv und trägt `aria-current="page"`. - Hover verändert nur die Unterstreichung; Schriftgewicht und Textfarbe springen nicht. - Lange Pfade umbrechen auf regulären Breiten. Im kompakten Mobile-Bereich bleibt der Pfad einzeilig und horizontal scrollbar; die aktuelle Ebene wird in den sichtbaren Ausschnitt gebracht. Reale Bezeichnungen werden nicht durch Ellipsis oder erfundene Kurzformen ersetzt. Diese Regel ist implementation-belegt. - `content-breadcrumb_OUTDATED` bleibt gesperrt. ## 6. Noch offene Detailzustände Folgende Punkte sind nicht aus der freigegebenen Evidenz abzuleiten und bleiben bis zu einem eigenen Zustandsabgleich offen: - die widersprüchliche Figma-Kombination `Active + Hover` bei Header-Aktionen, - exakte Hover-, Pressed- und Disabled-Flächen sämtlicher Header-Aktionen, - komponentengenaue Tokenwerte der drei Breadcrumb-Surface-Typen außerhalb der bereits belegten Theme-/Surface-Semantik, - Zieltyp, Berechtigung, Verfügbarkeit und passende ARIA-Semantik je variabler Kontextaktion. ## 7. Ausführbare Referenz `ui_kits/components/app-shell.html` ist ausschließlich ein dünner Vorschau-Wrapper, der `ui_kits/app/app-shell-seed.html` direkt einbettet. Er enthält keine zweite Header-, Navigations- oder Footerimplementierung. Die drei Seitentemplates und der neutrale Shell-Seed bleiben die einzigen ausführbaren Shell-Quellen.