Frontend conventions

Applies to both embedded interfaces. PRODUCT.md owns product intent; DESIGN.md owns visual tokens and interaction guidance. Toolchain versions and runtime behavior follow the live code and lockfile.

Structure and build

Both apps use Svelte 5 runes, strict TypeScript, Vite, and Tailwind v4's Vite plugin. ui/client and ui/operator share components, fonts, and tokens under ui/shared. One package and lockfile build separate entry points with shared assets. See ui/README.md for development commands.

Vite emits HTML, JavaScript, and CSS. Go embeds and serves that output and owns APIs, authentication, and distributed-system behavior. The UI package does not import domain packages. Preserve existing browser URLs and diagnostic endpoints.

Styling and components

Use Tailwind utilities for layout, spacing, responsive rules, and states. Keep custom CSS to shared tokens, fonts, and global behavior. Reuse shared buttons, shell, scroll regions, and input classes before adding local variants.

Use the warm dark palette and local fonts recorded in DESIGN.md. Keep assets and dependencies small: these pages ship inside the binary. Share assets across apps and measure size when changing the build or adding dependencies.

Interaction and content

Prioritize data and actions. Use short labels and scoped feedback; put optional help and long errors behind disclosure controls. Navigation should change views or provide useful movement, not decorate a small page.

Keep draft input separate from request results. Cancel obsolete reads, guard concurrent mutations, and preserve useful snapshots after refresh failures. Distinguish configuration, publication, connectivity, and unknown state.

Use semantic controls, visible focus, a skip link, keyboard-accessible scroll regions, and reduced-motion support. Narrow layouts must not overflow the page.

Validation

Run npm run check for frontend code changes and build when asset output changes. Use focused browser checks for affected interactions. Documentation-only changes need link and syntax checks, not application test suites.