Z-Index & Overlays

Cały stacking w aplikacji idzie przez tokeny --vista-z-* i util-klasy .vista-z-*.

Drabinka Z-Index

Zdefiniowane w src/styles/design/surfaces.css:

Layout (0–30)

Token	Wartość	Użycie
`--vista-z-background`	0	Background layer
`--vista-z-base`	1	Base content
`--vista-z-sidebar`	10	Sidebar
`--vista-z-topbar`	20	Top navigation
`--vista-z-sticky`	30	Sticky elements

Floating UI (200–700)

Token	Wartość	Użycie
`--vista-z-hovercard`	200	Hover cards
`--vista-z-tooltip`	300	Tooltips
`--vista-z-dropdown`	400	Dropdown menus
`--vista-z-popover`	500	Popovers
`--vista-z-contextmenu`	550	Context menus
`--vista-z-floating-ui`	600	General floating UI
`--vista-z-toast`	650	Toast notifications
`--vista-z-notification`	700	Notifications

Overlays / Modale (995–1100)

Token	Wartość	Użycie
`--vista-z-overlay-backdrop`	995	Pełnoekranowy backdrop
`--vista-z-modal`	1000	Kontenery modali/drawerów
`--vista-z-modal-content`	1050	Karta/treść modala
`--vista-z-modal-floating`	1075	Elementy pływające nad modalem (EntitySelector)
`--vista-z-critical-modal`	1100	Krytyczne potwierdzenia

Asystent / AI (1500–2000)

Token	Wartość	Użycie
`--vista-z-assistant-dock`	1500	AI assistant dock
`--vista-z-assistant-floating`	1600	AI floating panels
`--vista-z-assistant-overlay`	1800	AI overlay
`--vista-z-assistant-priority`	2000	AI priority elements

System (3000)

Token	Wartość	Użycie
`--vista-z-system-alert`	3000	Panic alerts, system critical

Wzorce Użycia

// Overlay (backdrop)
<div className="fixed inset-0 vista-overlay-strong vista-z-overlay-backdrop" />

// Modal content
<div className="vista-z-modal-content vista-card rounded-2xl">
  {/* content */}
</div>

Referencja: src/components/ui/Modal.tsx

2. Sheet / Drawer

Korzystają z tej samej warstwy overlayowej:

Root overlay: vista-z-overlay-backdrop
Panel/drawer: dziedziczy stacking z kontenera

3. EntitySelector w Modalach

Scenariusz: dialog otwiera EntitySelector (pacjent/wizyta).

// EntitySelector dropdown
<div className="vista-z-modal-floating vista-dropdown vista-card">
  {/* options */}
</div>

Portal target: Gdy EntitySelector jest wywołany z wnętrza modala, przekazujemy portalTarget (root tego modala).

Referencje:

src/components/selectors/EntitySelector.tsx
src/components/tasks/TaskDrawer.tsx
src/components/tasks/PatientSelector.tsx

4. Floating UI / Tooltips / Dropdowns

Element	Klasa
Tooltips	`.vista-z-tooltip`
Dropdowny	`.vista-z-dropdown`
Popovery	`.vista-z-popover`
Floating tools	`.vista-z-floating-ui`

Przykłady:

FieldTooltip, TermTooltip – tooltips
ExportKebabMenu – dropdown
VisitSummaryCard – popover
ToolsTray, AI chat DnD overlay – floating-ui

5. Asystent / AI

Wszystkie warstwy asystenta używają dedykowanych utili:

// AI diagnostics drawer
<div className="vista-z-assistant-overlay">
  {/* AI content */}
</div>

Zasady i Guardrails

Nie używaj z-[…] w komponentach produkcyjnych
- Wyjątek: definicje w utilities.css / surfaces.css
Używaj najbliższej pasującej klasy:
- tooltip → .vista-z-tooltip
- dropdown → .vista-z-dropdown
- modal overlay → .vista-z-overlay-backdrop
Nowy poziom? Dodaj token:
- Dopisz --vista-z-* w surfaces.css
- Dodaj .vista-z-* w utilities.css
- Dopiero potem użyj
W modalach używaj portalTarget:
- Preferuj portalTarget + vista-z-modal-floating
- Zamiast ścigania się z overlayami na document.body

Przyszły Lint

Pliki źródłowe

Plik	Zawartość
`src/styles/design/surfaces.css`	Tokeny `--vista-z-*`
`src/styles/design/utilities.css`	Klasy `.vista-z-*`

Vibrancy & Liquid Glass

Vista wykorzystuje natywne efekty przezroczystości (vibrancy) na macOS i Windows dla efektu “Liquid Glass”.

Fundamenty vibrancy

Wymagane ustawienia (już zaimplementowane):

/* index.html + tailwind.css */
html, body, #root {
  background: transparent;
  height: 100vh;
  border-radius: 8px;
  overflow: hidden;
}

/* vista-window-root / vista-window-shell */
/* Full-screen wrappy bez background */

Profil szkła (Rust/Tauri)

macOS - NSVisualEffectView z wyborem materiału:

Profil	Materiał	Użycie
`Hud`	`HudWindow`	Legacy/pro
`Sidebar`	`Sidebar`	Panele boczne
`Appearance`	`AppearanceBased`	Domyślny - system wybiera
`WindowBg`	`WindowBackground`	Fallback

Windows - Acrylic z fallback na blur:

// apply_acrylic z fallbackiem apply_blur

Komenda `vista_apply_glass`

Dla detached windows (np. AI Assistant popup):

if (isTauriEnv) {
  await safeInvoke('vista_apply_glass', {
    label: DETACHED_WINDOW_LABEL
  });
}

Klasy CSS vibrancy

Klasa	Użycie
`vista-vibrancy-high`	Titlebar, intensywne szkło
`vista-vibrancy-medium`	Sidebar, panele boczne
`vista-vibrancy-card`	Karty, popovery, wizardy

Czego NIE robić:

Zero pełnoekranowego, kryjącego tła (background: #000)
Nie tworzymy “drugiego okna w oknie”
Nie zakładamy że blur jest zawsze włączony (Reduce Transparency)

Co robić ZAWSZE:

Budować na .vista-window-root + .vista-window-shell
Używać istniejących klas vibrancy
Przy overlayach: rgba(..., alpha < 1) - nigdy pełne krycie

Przykład: Wizard/Modal

// Overlay (backdrop) - półprzezroczysty
<div className="fixed inset-0 bg-black/25 vista-z-overlay-backdrop" />

// Główna karta - szklana
<div className="vista-vibrancy-card vista-z-modal-content rounded-2xl">
  {/* content */}
</div>

Tahoe Liquid Glass (macOS 26)

Przy projektowaniu pamiętaj:

Apple HIG sekcja “Materials” - semantyczne materiały
Użytkownik może mieć “Reduce Transparency” włączone
UI musi być czytelny bez blur

/* Top titlebar */
.vista-titlebar-glass {
  @apply vista-vibrancy-high;
  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
}

/* Sidebar */
.vista-sidebar-panel {
  @apply vista-vibrancy-medium;
  border-right: 1px solid rgba(255, 255, 255, 0.08);
}

Powiązane dokumenty

Frontend Overview - Architektura frontendu
Components - Struktura komponentów
Data Flow - Przepływ danych