Adom UI Design System

The Adom UI Design System: how the AI builds AND tests interfaces people love to use in the Adom ecosystem. The AI writes the app, shows it to the user (in the user's own already-signed-in native browser via Adom Desktop, in pup for the logged-out experience, or in a Hydrogen webview), drives the front-end over a live SSE/WebSocket channel to exercise every path (auto-click buttons, show/hide floaty toolbars, load a different symbol or footprint, click send-to-kicad), and ralph-loops with screenshots until the UI is perfect. Covers the user-first interaction rules (instant feedback, controls that explain themselves, toasts that double as the AI's live narration channel to the user, forgiving errors), responsive and touch (mobile layouts, tooltips without hover), the 44px app header, AI-drivability (state on the server, GET /state + /console, the live channel, CLI driving commands), the OK/ERROR/Hint Rust CLI contract, Babylon 3D viewers, hero rules, and the polish tokens (colors, fonts, icons) last. Read BEFORE building or testing any Adom UI. Trigger words: ui design, design system, build an app, build a ui, test the ui, ralph test, ralph loop, drive the front-end, ai-drivable, ai drivable app, live channel, sse, websocket, server-sent events, show app in native browser, show app in pup, webview vs pup, auto-click, auto click buttons, toast, ui toast, app header, 44px header, tooltip, mobile tooltip, responsive, mobile layout, on-brand, color tokens, theme tokens, cli design, hints, 3d viewer, hero image, ui linter, make my app a joy to use.

How the AI builds, shows, drives, and tests an Adom app. In Adom the AI writes the app, shows it to the user (in their own already-signed-in native browser via Adom Desktop, in pup for the logged-out experience, or in a Hydrogen webview), drives the front-end over a live SSE or WebSocket channel to exercise every path (auto-click buttons, show and hide floaty toolbars, load a different symbol or footprint, click send-to-kicad), reads back state, console, and screenshots, and ralph-loops until the UI is right. Covers state-on-the-server, GET /state, GET /console, the live channel, the CLI driving commands, the three display surfaces and when to use each, and the ralph-test loop. Read BEFORE building or testing any Adom web app. Trigger words: ai-drivable, ai driven app, drive the front-end, drive the ui, live channel, SSE, server-sent events, websocket, GET /state, GET /console, ralph test, ralph loop, auto-click buttons, test the ui, show app in native browser, show app in pup, webview vs pup, native browser auth, logged out testing, ui click.

How to lay out the shell of an Adom single-page app: a full-height column with a fixed 44px header, a scrollable body that fills the rest, and an optional footer or status bar, built so it sizes correctly and reshapes responsively instead of overflowing or collapsing. Covers the full-height flex column, the intrinsic-sizing traps (min-height:0, minmax(0,1fr), position:fixed on the app root), where HUDs and toasts mount, fluid panels and split layouts, and the footer / status-bar convention. Read BEFORE laying out a new app or when an app overflows, scrolls the whole page, or a canvas will not fill its pane. Trigger words: app shell, app layout, single page app layout, SPA layout, full height layout, fluid layout, header body footer, status bar, footer, app footer, scroll container, min-height 0, minmax 0 1fr, canvas wont fill, page scrolls, sticky header layout.

How to build floaty tool windows and HUDs in an Adom app: draggable side panels and overlays that hold tools, inspectors, and controls without blocking the main content. Covers the drag grip, never clamping to a screen edge, max-height with internal scroll and a pinned header and footer, minimize / close / double-click-to-collapse, the z-index ladder slot (--z-hud), remembering position, and driving show/hide from the AI over the live channel for testing. Read BEFORE adding a floating panel, inspector, toolbar overlay, or HUD. Trigger words: floating window, floaty window, floaty toolbar, HUD, draggable panel, tool window, inspector panel, overlay panel, floating toolbar, drag handle, collapse panel, minimize panel, show hide toolbar, z-index hud.

How to make an Adom app adapt from phone to desktop: a rich, dense layout on a large screen and a lean, thumb-friendly one on a phone, the same app reshaped rather than a desktop layout shrunk until it is unusable. Covers a breakpoint set, reshape-not-shrink, what to show on desktop versus collapse on mobile, 44px minimum touch targets, safe-area insets and the soft keyboard, and the big one: tooltips on touch, where hover does not exist, so you replace hover tooltips with visible labels, tap-to-reveal sheets, or long-press. Read BEFORE building any UI that a phone might open. Trigger words: responsive, responsive design, mobile layout, mobile UI, phone layout, adapt to screen, breakpoint, breakpoints, media query, touch target, mobile tooltip, hover none, pointer coarse, tap to reveal, long press, safe area, soft keyboard, desktop vs mobile, container query.

How to do toasts in an Adom app: the transient, non-blocking confirmation that tells the user what just happened. Covers position (bottom center), the three types (success green, error red, info teal), durations (about 4s for a confirmation, sticky for errors, pause on hover), stacking newest on top with a cap, dismiss, carrying an action (above all Undo for destructive actions), ARIA, and the POST /ui/toast hook. In Adom a toast does double duty: it is also how the AI, which is driving the front-end, narrates to the user live during a test or demo ("file downloaded", "running test 3 of 8"). Read BEFORE adding any confirmation, snackbar, or status popup. Trigger words: toast, toasts, snackbar, notification popup, confirmation message, status toast, ui toast, POST /ui/toast, show a toast, undo toast, success message, error toast, ai narration, file downloaded toast.

How to build great desktop tooltips in an Adom app: extensive, well-written content, a 600ms hover-reveal delay so cursor fly-bys stay quiet, a body-appended position:fixed div at z-index 99999 (never a ::after pseudo that gets clipped), cursor-relative placement that never covers the thing you are hovering, and edge-aware flipping so a tooltip never renders off-screen. Read BEFORE adding a tooltip to any hoverable or icon-only control. Includes the canonical z-index ladder, one-tooltip-at-a-time suppression, the no-all-caps rule, and full working CSS and JS. For touch and phones (where hover does not exist) see the responsive-ui skill. Trigger words: tooltip, tooltips, hover tooltip, hover preview, data-tooltip, tooltip placement, tooltip off-screen, tooltip clipped, tooltip z-index, z-index ladder, tooltip delay, hover delay, icon button label, explain this control, tooltip covers cursor, tooltip not showing, title attribute, ::after tooltip.