kazma-ui-conventions

name	kazma-ui-conventions
description	Kazma Web UI conventions for editing kazma-ui templates and JS. Use when changing the Kazma web UI (dialogs, toasts, Alpine panels, grids).

Kazma Web UI Conventions

Apply these rules whenever editing files under kazma-ui/kazma_ui/ (templates, static/js/).

Dialogs — never native browser dialogs

Use the unified Promise-based helpers:

• window.kazmaConfirm(opts) → Promise<boolean>
• window.kazmaAlert(opts) → Promise<void>
• window.kazmaPrompt(opts) → Promise<string|null>

All are backed by $store.modal (static/js/modules/stores.js + components/modal.html) with a native fallback if Alpine hasn't booted. The modal is single-instance — do not create a parallel dialog system.

Toasts — one system only

Use window.showToast(msg, type, duration) or Alpine.store('toast').add(...). streaming.js's KazmaStream.toast delegates to $store.toast. Never invent a second toast stack.

x-cloak is GLOBAL — do not reintroduce the blink

[x-cloak] { display: none !important; } lives once in kazma.css. Every x-show-gated panel MUST also carry x-cloak, or it flashes visible before Alpine evaluates.

Never put display:flex (or any display) in an inline style on an x-show element — the inline declaration beats Alpine's display:none toggle. Put layout in a CSS class (see .system-alerts-banner).

Responsive grids

Use class="two-col-grid" (collapses to one column ≤768px via kazma.css) instead of bare inline grid-template-columns:1fr 1fr;, which does not collapse and crushes mobile.

After any change

• JS: syntax-check with node --check <file>.
• Verify no new native alert()/confirm()/prompt() calls were added.