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, html, static page, static html, write html, css, style a page, page styling, cheat sheet, landing page, prefers-color-scheme, dark mode, dark by default, light mode toggle. NOTE: applies even to a single throwaway .html file, not just full apps — Adom is a dark system, so ANY page you write defaults to dark (see the bundled dark-default skill).

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.

Every file or folder path an Adom app shows in its UI is a link that reveals that file in the user's VS Code Explorer, never dead text they have to copy into a terminal. Covers the wiring (a button, not an anchor; POST to the app's own server; the server shells to `adom-vscode reveal`), the required tooltip and result toast, the visual treatment, reveal versus open, and the two traps that make this silently fail: the workspace-boundary footgun where `adom-vscode reveal` returns OK exit 0 for a path outside VS Code's open folders and the Explorer just does nothing (classic for anything downloaded to /tmp), and the dead-server case where the proxy returns a plain-text ECONNREFUSED body that blows up JSON.parse. Trigger words: clickable path, path link, clickable file path, reveal in vscode, reveal in explorer, open in explorer, show file in sidebar, adom-vscode reveal, path in the UI, file path label, reveal failed, nothing happens when I click the path, outside workspace, /tmp not revealable.

How an Adom app talks to the Hydrogen control API without CORS, without a hardcoded port, and without silently corrupting what it forwards. Proxy the two routes (/updater/status and /ai-threads/run-prompt) through your OWN server so the page stays same-origin, read the control port from ~/.adom/hydrogen-control-url at REQUEST time because it is dynamic per ah launch, answer 503-with-a-hint rather than 404 when ah is absent, and PASS THE RESPONSE THROUGH UNCHANGED - parse for what YOU decide, never for what you HAND BACK. A JSON round trip reorders keys, loses integer precision past 2^53, turns 1.0 into 1, and turns a non-JSON body into a fabricated error object, all while every status probe stays green. Ships proxy-fidelity.py to prove it byte-for-byte against a stub with no user machine involved. Also: a catch-all route and a blanket OPTIONS handler make three separate checks pass for the wrong reason. Read BEFORE wiring any app to the control API or the AI threads API. Trigger words: send to ai, ai-threads, run-prompt, updater status, control api, proxy route, CORS, same-origin, version gate, delivered_to, hydrogen-control-url, preflight, catch-all, 404.

Adom is a DARK system, so every page, panel, webview, artifact, and one-off .html file the AI writes defaults to dark mode — light is the opt-in override, never the base. Read this the instant you are about to write ANY HTML or CSS, even a throwaway cheat sheet or a two-minute static page that does not feel like "an app". The classic mistake is styling :root light and adding dark as a prefers-color-scheme override — that is BACKWARDS for Adom, whose surfaces (wv tabs, hd panels) render dark by default, so a light-base page flashes white and reads as off-brand. This is the 30-second rule; the parent adom-ui-design skill is the full design system (tokens, header, linter). Read BEFORE writing any HTML/CSS. Trigger words: html, write html, static page, static html, css, style a page, page styling, cheat sheet, landing page, webview page, wv page, dark mode, dark by default, light mode, prefers-color-scheme, theme, background color, off-brand, white flash, quick page, one-off html.

The demo contract for every dock bar dashboard: one guided demo alongside the sample AI prompts, driven by a step list where each step carries an action, a caption, and a pre-created adom-tts mp3. The player shows a play / pause / prev / next / exit toolbar while running; audio plays by DEFAULT with a mute/unmute button; captions are ab captions (Adom Bridge captions) perfectly synced to what is happening on screen, always at the bridge's default size and position so every app's demo feels identical. Read BEFORE building or restyling any dashboard demo, tour, or walkthrough. Trigger words: dashboard demo, guided demo, demo toolbar, demo player, tour player, ab captions, caption size, demo audio, tts narration demo, mute demo, demo steps, play pause demo.

One header grammar for every dock bar dashboard, extending the 44px three-zone adom-app-header. Human name never a slug echo, lowercase brand wordmarks live in the icon not the name, version NEVER inline in the bar (hover popover only, tap on mobile), the target box chip (which machine the bridge answers on) standard and in the same place on every app, gear upper right per settings-layout. Read when building or fixing a dashboard header. Trigger words: dashboard header, dash header, app name slug, version in header, target chip, box chip, header grammar, dock header.

Getting a NEW build of your app in front of the user, and proving it is the one they are looking at. Publishing is not installing, installing is not running, and running is not what the open page has loaded: "current" is THREE separate claims and any one of them can lie alone. Covers the dock installing a package without restarting the process, the "(deleted)" Binary LED that every dashboard already emits when it is stale, why a container-served app and a bridge-served app have completely different retirement paths, how to rehearse an upgrade against your REAL predecessor from the registry (the retirement path's input is the OLD build's output, so it cannot be tested by reading your own source), and why you must retire by PORT OWNERSHIP rather than argv - one app killed an unrelated dashboard because every instance of a tool has identical argv. Read BEFORE shipping a new version of any Adom app or dashboard. Trigger words: deploy my app, ship a new version, my changes are not showing, stale dashboard, restart the server, retire the old process, serve verb, upgrade path, which version is running, dock installed but nothing changed, port already in use.

Screenshot ONLY your dock dashboard's webview pane inside ah, not the whole Hydrogen window. A full-window hd_shot spends about 80% of its pixels on ah's rail, tab strip, editor and status bar, and after the Claude-safe resize your dashboard's 14px text is unreadable and its colours are resampled, so every measurement you try to eyeball from it is wrong. This skill gives the exact crop recipe (activate the tab by name, read the iframe rect AND the shell's CSS viewport width in one call, scale by that, crop), the ready-made script, and the traps: unforegrounded tabs report zero-height rects, and the capture is scaled so a hardcoded offset silently drifts. Read BEFORE capturing any dock dashboard frame for a review, an issue, or the shotlog. Trigger words: screenshot the dashboard, capture my panel, dock dashboard screenshot, hd_shot region, crop the webview, frame for the shotlog, show my dashboard in ah, webview only screenshot.

THE parent contract for every Hydrogen Dock Bar launch dashboard - the page a dock icon opens. One anatomy top to bottom (house header, say strip, status pill row, then the app's own content), two legitimate species (bridge launch pages vs full apps whose main UI is the dock target), and the shared token stub every dashboard copies. Born from the 2026-08-24 audit where seven dashboards shipped seven say-strips, five status dialects, and five version placements. Read BEFORE building or restyling any dock bar dashboard, and route to the sub-skills dash-header, say-strip, dash-demo, status-leds, newbie-graduation for each region. Trigger words: dock dashboard, launch dashboard, dock bar ui, dockbar dashboard, bridge launch page, dashboard anatomy, dashboard contract, dock bar consistency, dashboard tokens, brother from another mother.

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 icon, and the one look they all share: a simple LINE DRAWING, white (or currentColor), on a TRANSPARENT background. No filled silhouettes, no brand colors, no vendor logos, no emoji, no raster PNGs where an SVG belongs. Covers the drawing rules (24x24 viewBox, fill none, stroke 1.5-2, round caps and joins), where icons appear (in-app buttons, app header mark, webview TAB FAVICONS, dock cards, the wiki page icon), how to derive a line mark for an app that wraps a third-party product without shipping that vendor's logo, and the pre-publish audit. Read BEFORE drawing, choosing, or shipping ANY icon or favicon. Trigger words: icon, icons, favicon, tab icon, webview icon, app icon, line icon, outline icon, filled icon, brand color icon, logo in icon, svg icon, icon audit, dock icon, monochrome icon.

The acknowledgment doctrine: every interactive element must answer the human's INPUT itself - "yes, you just hovered me" (a subtle border/background shift) and "yes, you just pressed me" (a real mousedown/:active state), plus a keyboard :focus-visible ring - BEFORE and separate from whatever the action later does. Covers the three acknowledgment moments (hover, press, focus), copy-paste CSS recipes on the house tokens for buttons, icon buttons, pills, toggles, rows and inputs, the timing rules (hover ~150ms, press instant), touch behavior, disabled/busy states, the ralph-test checklist, and the anti-patterns (hover-only buttons, color-only shifts, outline:none). Read BEFORE shipping ANY clickable UI. Trigger words: input feedback, button feedback, press state, pressed state, mousedown state, active state, :active, hover state, hover effect, acknowledge click, acknowledge hover, button not responsive, buttons feel dead, click feedback, tap feedback, focus ring, focus-visible, tap highlight, button press animation, ui acknowledgment, responsive buttons.

The scaffolding-fade contract for dock dashboards: newbie helpers (expanded say strip, getting-started panel, prominent demos) exist in three states per app - Fresh (full scaffolding), Graduated (collapsed to one quiet line), and Recallable (the header's ? restores everything for a session). Graduation triggers: the user dismissed it, or N successful launches (default 3), or the bridge saw the user's AI drive the app once. Tracked in localStorage (each dashboard port is its own origin, so state is naturally per-app). The say strip collapses LAST because handing the user to the AI is the whole point; users graduating past the dock into pure AI prompts is success, not churn. Read when adding any onboarding/newbie UI to a dashboard. Trigger words: newbie, onboarding, getting started, graduation, scaffolding fade, progressive disclosure, first run, tour panel, dismiss forever, bring back help.

MOUNT THE MODULE, DO NOT BUILD THIS. adom-ui-design ships assets/module/newbie-panel.js, the ONE implementation of the newbie panel every dock dashboard uses: a full-width CARD at the top of the page (background #161b22, 1px border, 12px radius, 3px teal left edge) split into TWO COLUMNS - the demo button on the left, the sample AI prompts on the right as a quiet TABLE with the Copy and Send icons in one aligned column (never pills, which go ragged when phrases differ in length). The module owns every dimension, both icons, the clipboard and send-to-AI paths, the toasts, the tooltips, the X and the header ? toggle; you pass only your phrases, your trigger noun and your demo. Prove conformance with AdomNewbiePanel.selfCheck(). Read BEFORE building or restyling the prompts/demo area of any dashboard. Trigger words: newbie panel, sample prompts panel, prompts table, say it panel, demo button, copy button, send to ai button, prompt row, dismiss panel, bring back help, onboarding panel, AdomNewbiePanel, selfCheck.

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.

The ONE say strip every dock dashboard renders - the component that teaches a user to drive the app by talking to their AI instead of clicking. Canonical heading ("Say it"), one explainer sentence naming the app's noun, quoted phrases with the noun in teal, chips never monospace, exactly ONE Try-it treatment (ghost pill, copies to clipboard, success toast "Copied to clipboard. Paste it into any AI thread."), dismissible and wired to newbie-graduation. Ships the full copy-paste recipe including the unfocused-window clipboard fallback. Read BEFORE building or restyling any say strip / Try it row. Trigger words: say strip, say it, try it button, ai phrases, prompt chips, say it to your ai, copy prompt, teach the noun, dockbar say.

The Adom pretty scrollbar: thin, barely-visible, transparent track, pill thumb that only brightens on hover, and the fade-in-while-scrolling variant that disappears when you stop. Covers the copy-paste recipe (Chromium ::-webkit-scrollbar + Firefox scrollbar-width / scrollbar-color), where to scope it, the ROUNDED-CORNER inset problem (a scrollbar running the full height of a radius-12 dialog visually slices the curve off), scrollbar-gutter to stop layout shift, the never-scroll-the-outer-html rule, overlay/auto-hide behavior, and how to ralph-test it. Read BEFORE shipping any scrolling surface - panel, modal, list, console. Trigger words: scrollbar, pretty scrollbar, ugly scrollbar, scrollbar styling, custom scrollbar, thin scrollbar, hide scrollbar, fade scrollbar, auto-hide scrollbar, overlay scrollbar, webkit-scrollbar, scrollbar-width, scrollbar-color, scrollbar-gutter, scroll container, modal scroll, rounded corners scrollbar, scrollbar corner overlap.

The Adom settings surface, and the ONE look every Adom app shares. Most Adom apps are single-page dashboards whose settings open from a cog in the header as a DISMISSIBLE MODAL: that is the common case and the default this skill teaches. Covers the entry point (cog, upper right), the backdrop law (dim 20-30%, NEVER blur, because settings often change the very thing behind the modal), the four dismissal behaviors, the settings-card anatomy (elevated card, 3px teal left accent, title with inline status, descriptive prose, control rows, dividers), the descriptive-copy doctrine (every section EXPLAINS itself in full sentences), toggles not checkboxes, Install/Update/Uninstall rows with live consoles, the row anatomy (breadcrumb name with a teal last part, and a Default hint on every row), the type scale and tokens, the two-click Restore defaults footer, local-first optimistic saving, and what to do when settings outgrow one screen (a category sidebar with jump-to and scroll-spy). The full settings WINDOW is the rare variant, used by ah alone. Read BEFORE building any settings dialog, preferences pane, or config UI in an Adom app. Trigger words: settings dialog, settings modal, settings layout, preferences pane, config ui, settings card, options dialog, app settings, settings panel, mimic ah settings, cog wheel, gear icon, settings backdrop, dim the background, blur the background, settings sidebar, jump to section, scroll spy, restore defaults, dashboard settings, settings screenshots, native resolution capture, devicePixelRatio, on off pair, settings pitfalls.

Etiquette for driving a machine somebody else is using, and for handing it between agents. Two agents driving one desktop is how it gets crashed, so the shell is handed out one holder at a time - and a handoff is not complete when the holder lets go, it is complete when the next holder has been told BY THE HOLDER, addressed by a handle the coordinator published. Also covers the trap that put three clicks into a user's foreground apps: COORDINATES ARE NOT THE INPUT, FOCUS IS. desktop_click dispatches to whatever owns the foreground at that instant, while desktop_screenshot_window reads through occlusion by design, so a correct screenshot is not evidence a click will land. Use pup_assisted_click, verify focus IMMEDIATELY BEFORE EACH native event, and never steal focus from live work without asking. Read BEFORE clicking, typing or restarting anything on a machine a person is using. Trigger words: drive the desktop, click on his machine, foreground the window, steal focus, take the shell, hand off the slot, who has the machine, desktop_click, assisted click, real click.

One status language for every dock dashboard: a single compact LED pill row (the chip-fetcher pattern, canonized) instead of prose-heavy card grids, stacked rows, header nav dots, footer strips, or layer tables. LED dot + label + short state per pill; paragraph explainers move into tap-to-expand detail; a red LED always carries its next step (the UI cousin of the CLI Hint: rule); semantic color comes only from the led tokens, never from third-party brand colors. This row is ALSO what the dock bar's own health poll and hover preview mirror, so keeping it honest keeps the dock honest. Read BEFORE building any dashboard status area. Trigger words: status leds, led row, status pills, health row, dashboard status, led colors, status cards, red led hint, status dialect.

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.

How to know your check actually checked something. A green result carries "in the environment I happened to measure" and we keep reading it as "everywhere". Covers the discipline that caught eleven wrong conclusions in one day: NEGATIVE-control every check (a green you have never seen go red is a screenshot of a function that might always return true), break the property each row CLAIMS to watch rather than any property, POSITIVE-control a clean result (a metric that can only return one value on success is not evidence of success), refuse rather than degrade when an instrument's preconditions are unmet, test a fix by reproducing the failure instead of reading the diff, and ask whether a failing check is failing the CORRECT implementations. Also: a structural audit cannot see a missing function, a behavioural gate cannot see a deleted stylesheet, and zero is almost never a measurement. Read BEFORE trusting any check, audit, conformance run or clean pass. Trigger words: verify, negative control, self-test, is my check working, prove it, conformance, audit, ralph test, it passed but, green check, false positive, measurement artifact.