name: app-creator description: > Use when the user wants to build a new Adom "app" — a mini web server that renders its UI in a Hydrogen webview tab. Covers architecture (server in any language: Rust+tiny_http, Node, Python, Go), required conventions (Adom brand, custom SVG favicon, proxy URL, webview safety), and publish flow (GitHub repo + wiki app page for discovery and install). Trigger words: make an app, create an app, build an app, new app, adom app, build an adom app, mini web app, mini web server, webserver app, build a webview app, webview app, hydrogen app, build a widget, create mini app, tiny app, tool with a UI, cli with a UI, app needs an icon, favicon for an app, app branding, app icon, app standards, how to make an adom app, app conventions, app template, webview-hosted app, first-class app, app page on wiki.

Adom App Creator

🛑 STEP 0 — MANDATORY before writing one line of UI code

Before authoring any HTML, CSS, JS, SVG, or webview content:

1. Read gallia/skills/brand/SKILL.md end-to-end. Palette tokens (#0d1117 page bg, #161b22 panels, #00b8b1 accent), Familjen Grotesk + Satoshi + JetBrains Mono fonts, monochrome icons only (#e6edf3 or currentColor — never emoji, never coloured favicons, never coloured tab-strip icons), 0.15 s transitions, frosted- glass card pattern, dark theme always.
2. Read gallia/skills/human-ui-patterns/SKILL.md end-to-end. Tooltips (rule 1d — body-appended position:fixed div, z 99999, NEVER title="" or CSS ::after), HUDs (draggable + collapsible + dismissible), NEVER ALL CAPS, click previews, hero images, provenance captions, AI-drivability, the full pre-publish checklist.

Both skills are <500 lines each. Reading them takes ~30 s and prevents the #1 user complaint on every UI build: "have you even bothered to look at the brand guide skill and ui design skill?" (verbatim, 2026-04-26 on the aci library dashboard).

Rule of thumb: if you've just typed <div> or :root { without having the open contents of those two files in your context window in the last two minutes, stop and Read them. The rules are easy to half-remember and half-violate at the same time — emoji icons, the wrong shade of background grey, a teal favicon, title="" tooltips. Every one of those has shipped from a Claude Code session that "knew the rules" but didn't re-read.

No exceptions for "quick prototypes" or "internal tools." This skill, aci library, every chip-fit HUD, every wiki page hero — they all started as "I'll just throw something together and polish later." The polish phase has never come; the violations ship.

Adom "apps" are mini web servers that render their UI inside a Hydrogen webview panel tab (not the Adom Viewer). They look and feel like native Hydrogen panels to the user, but under the hood they're just HTTP servers the AI drives. Any future Adom user can discover them via wiki triggers and install them via the standard app install prompt.

This skill covers:

1. What counts as an "app" (vs a CLI-only tool or an AV widget)
2. The required conventions every app must follow (brand, favicon, proxy URL)
3. The mini web server pattern (any language / any HTTP library)
4. How to ship: GitHub repo, wiki app page, install prompt
5. Where apps fit in the broader skill ecosystem

What is an Adom app?

An Adom app is:

• A mini web server that runs on the Adom Docker container (or the user's own machine, for desktop integrations). The server listens on a TCP port.
• Its UI is HTML + CSS + JavaScript served by that server, rendered in a Hydrogen webview panel tab. Not the Adom Viewer. Not a Tauri window. Not a browser tab the user opens manually, a first-class Hydrogen panel.
• The server can be a single page or a multi-page site, the app's author decides based on what fits the feature.
• The implementation language is the AI's choice. Rust with embedded tiny_http works great for tools that also expose a CLI (e.g., video-post). Node/Python/Go/anything else is fine if it better matches the workflow.
• The app is discoverable via wiki triggers. A user says something like "speed up my demo recording" and Claude Code suggests the matching app from the wiki, with a paste-into-Claude install prompt.

An app is NOT:

• A CLI-only tool (those belong in adom-cli-design / tool-publisher without the web UI)
• An Adom Viewer widget (those use av-creator and push HTML to the AV server, which is a different render surface)
• A Hydrogen built-in panel like 3D Editor or Schematic Editor (those are Tauri native + ship with Hydrogen itself)

Read adom-app-model first for the bigger picture (repo layout, wiki publishing, Tier A vs Tier B distribution, service containers, version discipline). This skill only covers the client-side UI conventions; the model skill covers "where does this app live and how does it ship?"

Also read adom-cli-design. Every app ships a CLI surface (at minimum <app> install, <app> serve, and whatever subcommands the AI drives the server with). That CLI must follow the Adom CLI conventions — Rust + clap, OK: / ERROR: / Hint: output lines, isatty-aware colors, the skill-file pattern. Apps with a half-finished CLI surface annoy everyone downstream; don't skip this read.

Does your app need a service container?

If the app has a backend that holds API keys, caches third-party responses, or otherwise wants to be shared across users, it needs a private service container on the default-light image. See standalone-service skill for the full setup, but the short version:

• Add service/{deploy.sh, watchdog.sh, service.json} to your repo root
• Deploy once with adom-cli carbon containers create --image-id <default-light> --repo-id <REPO_ID> --ssh followed by ssh ... bash service/deploy.sh (the CLI requires --repo-id)
• The watchdog cron auto-pulls origin/main every 2 min and rebuilds + restarts — you don't redeploy after releases, just git push
• The user's container points <APP>_API at the service container's public URL for shared-cache benefits

If the app is a pure client (no backend state worth sharing), skip the service/ directory and let it run locally per-user.

Each app ships a BUILD-SKILL.md

Every app's release process is the same shape (bump VERSION → cargo build → git tag → gh release → adom-wiki asset upload → adom-wiki page update → verify). Bundle this as <repo>/BUILD-SKILL.md and deploy it from the binary's install subcommand to ~/.claude/skills/<slug>-build/SKILL.md. See adom-app-model for the template. Trigger words like "release X", "bump X", "publish X" route Claude to it.

Required conventions

Every Adom app MUST follow these rules. They exist so apps feel like first-class Hydrogen panels, not random HTML pages someone served on a port.

1. Use the Adom brand guide

Source: ~/project/gallia/skills/brand/SKILL.md, read it first.

Minimum requirements for every app's UI:

• Fonts: Familjen Grotesk (headlines) + Satoshi (body) + JetBrains Mono (code). Load from https://adom.inc/fonts/ via @import url(...) in your CSS. Never fall back to Inter, Arial, Helvetica, or system fonts as primary.
• Color palette: full :root CSS token block at tab-wiring-reference.md § Brand CSS tokens. Use --accent (#00b8b0 teal) for primary actions, --green for success, --red for destructive.
• Dark theme by default. The Hydrogen workspace is dark, so any white panel looks jarring. Start from --bg: #0d1117 and only go lighter when you need contrast.
• Adom teal accent (#00b8b0) for primary actions, focus rings, and highlights. Green (#3fb950) only for success states, red (#f85149) only for destructive actions.
• 8px / 12px / 16px spacing grid. No random 13px margins.
• Border radius 8px for cards and buttons, 12px for larger containers. No sharp corners unless you have a specific reason.

See the video-post voiceover UI (src/voiceover/ui.html in the adom-inc/video-post repo) for a working example that follows every rule above.

1b. 🛑 EVERY icon is monochrome white — no exceptions, no favicon carve-out

Per brand/SKILL.md: every icon in an Adom app is monochrome white (#e6edf3) or currentColor inheriting from a white-text context. This includes:

1. In-app icons — header logo, button glyphs, tooltip icons, sidebar icons, empty-state art.
2. The Hydrogen tab-strip icon — docs/icon.svg, both as the HTML <link rel="icon"> favicon AND as the base64-encoded data URL passed to adom-cli hydrogen workspace add-tab --display-icon. The tab strip is Adom UI chrome; every app dropping a colored icon in there turns the strip into a clown car.
3. Every other rendering of the app icon inside the Adom UI — panel catalog, discovery list, start-menu equivalents, etc.

The only place brand color is allowed is wiki marketing art — the hero image and thumbnail on the app's wiki page. Those are screenshots-of-branded-products, not Adom UI elements.

Past Claudes (including the author of this app) have missed this rule three times. If you are auditing an app and your instinct is "the skill says favicons CAN be teal, so my teal docs/icon.svg is fine" — you are reading a stale cache of this skill. There is no favicon carve-out. Delete that belief and re-read this section.

Pre-publish audit — gate every release on this returning empty: see tab-wiring-reference.md § Icon audit grep commands for the two grep commands and the wrong/right SVG HTML examples.

Both must return zero. The docs/icon.svg hit is the most common one because authors assume favicons are exempt. They are not. Prefer MDI icons (already monochrome, work with currentColor) or custom 24x24 SVGs with fill="currentColor". Never use colored icon sets. If using currentColor, verify the parent's color is var(--text) or #e6edf3 — a teal parent silently turns the icon teal.

No favicon carve-out. (Earlier revisions of this skill said docs/icon.svg could be colored. That was wrong — the favicon renders in the Hydrogen tab strip, which is UI chrome, not a marketing surface.)

2. Ship a custom SVG favicon

Code samples for serving /favicon.svg and referencing it in HTML, icon design tips, and icon generation guidance: see tab-wiring-reference.md § SVG favicon implementation.

Requirements:

• SVG format, square viewBox (0 0 64 64 or 0 0 24 24), transparent background.
• Monochrome white only — single fill="#e6edf3" (or currentColor). NO teal, no gradients. See §1b.
• Saved at docs/icon.svg in the repo; serve it at /favicon.svg with Content-Type: image/svg+xml.
• Reference with a relative href="favicon.svg" (no leading slash — see §7a).

3. Use the Adom proxy URL, not 127.0.0.1

The Hydrogen webview iframe cannot load http://127.0.0.1:PORT/ directly — the browser blocks it as cross-origin. Always point the tab at the Coder proxy URL: https://<slug>.adom.cloud/proxy/<PORT>/.

Read VSCODE_PROXY_URI from the environment and substitute {{port}}. Rust code sample and 127.0.0.1 fallback for terminal testing: see tab-wiring-reference.md § Proxy URL substitution.

4. Open the webview tab via adom-cli

Full adom-cli hydrogen workspace add-tab command, --display-icon forms (MDI string vs base64 data URL), Rust embed pattern, and tab-cleanup command: see tab-wiring-reference.md § Opening and closing the webview tab.

Key points:

• Panel type UUID for Web View: adom/a1b2c3d4-0031-4000-a000-000000000031.
• Get leaf-id with adom-cli hydrogen workspace get | jq -r '.focusedPanelId'.
• Pass docs/icon.svg as a data:image/svg+xml;base64,... URL via --display-icon (Hydrogen does not auto-pick up the <link rel="icon"> favicon).
• Always call adom-cli hydrogen workspace remove-tab on exit.

5. Handle browser requirements

The webview is a real Chromium-based iframe. Everything browser-native works (MediaRecorder, WebAudio, Canvas, WebGL, fetch, etc.) but remember:

• Permissions (mic, camera, geolocation) go through Hydrogen, not the iframe. If your app needs the mic, use adom-cli hydrogen audio enable from the CLI and let Hydrogen capture, don't try getUserMedia inside the iframe, it'll fail on permissions.
• File downloads trigger Hydrogen's download handler, which saves to ~/project/ paths on the container. Use those paths in subsequent CLI commands, not browser Downloads/.
• Range requests, support them on any endpoint that streams large files (video, audio, big JSON blobs). Hydrogen's video player uses Range by default; if your server 404s on Range it breaks seeking.
• No cookies / no localStorage expectations, webviews are fresh every session. Persist state to disk via your CLI, not the browser.

6. Graceful shutdown

Apps should have a /shutdown endpoint (or equivalent) that the UI can call when the user is done. On receiving it, the server:

1. Finishes any pending work (file writes, ffmpeg mux, etc.)
2. Removes the Hydrogen webview tab
3. Exits the CLI process cleanly

Never leave the server running after the user is done, it holds a port, shows a zombie tab, and confuses future invocations.

7a. Always use relative URLs inside the webview (CRITICAL)

Apps hosted through the Coder /proxy/<port>/ prefix MUST use relative URLs for every fetch, href, src, and link. A leading slash resolves to the origin (hydrogen.adom.inc) and bypasses the proxy entirely, so your fetches hit the wrong server and fail silently.

Wrong/right HTML examples: see tab-wiring-reference.md § Relative URL wrong vs right examples.

Every fetch(), <a href>, <link rel="icon">, <img src>, <script src>, every CSS url(). If it's in the HTML or JS your app serves, no leading slash. Ever.

Symptom when you get this wrong: the UI loads (since the top-level HTML comes from the proxy), but every button click silently does nothing, the video player stays blank, and your /console log stays empty because the JS console forwarding is also hitting the wrong URL. You can spend hours chasing "why isn't this working" before realizing every network request is going to the wrong host. This is the single most common bug when wiring up a new Adom app.

7. 2-way HTTP communication (CRITICAL)

Every action the UI can trigger MUST be independently triggerable via plain HTTP from outside the UI. This is the single most important rule for Adom apps and is what makes them AI-drivable.

Why: the AI building/testing/operating the app has to be able to drive it without a human clicking buttons. If the Record button is wired to a JS function that only the UI calls, the AI is stuck. If the Record button POSTs to /start-recording (the same endpoint the AI can hit with curl), the AI can test, debug, and automate the app by itself.

Rules:

• Every user-visible action has a server endpoint. Not just a JS function. The JS onClick handler is a thin wrapper that POSTs to the endpoint; it does NOT contain the logic.

• State changes go through the server, not through in-memory JS state. If the UI needs to know something, it reads it from the server via GET /state (or SSE / websocket for live updates).

• The AI can drive the full app lifecycle via curl. Before shipping, you MUST be able to script a full user session from bash. If any step requires clicking a DOM element with no HTTP equivalent, that's a bug. See webview-conventions-detail.md § 7 for the curl-driven test sequence.

• Always expose GET /state (or similar) returning the app's current state as JSON so the AI can check progress without scraping HTML.

• Return structured JSON on all POST endpoints, not just HTML redirects. The AI parses the response to decide what to do next.

This is NOT a nice-to-have, it's the defining property of an Adom app. A web server that can only be driven by clicking a human's mouse is just a website. An Adom app is an AI-drivable surface with a human-friendly UI layered on top.

Server state is the single source of truth. The UI must not keep its own copy of state like "am I recording?". Instead: poll GET /state at 300-500ms, compare phase against the last seen value, and drive UI transitions on every change. Buttons fire POST commands to the server only — they do NOT update local state. Full state-poller JS pattern and curl-driven happy-path test sequence: see webview-conventions-detail.md § 7. 2-way comms — state poller pattern.

The test: if the AI curl-driven flow and the human-click flow look identical in the UI, the wiring is correct. If they diverge, the UI is keeping local state that should live on the server.

7c. Every button needs a hover-delayed tooltip

Full tooltip implementation (CSS pattern, clipping rules, edge-anchored positioning, eval channel, console forwarding), plus mini web server patterns (Rust/Node/Python): see webview-conventions-detail.md.

Rule: every button (and any label whose meaning is not obvious to a first-time user) must have a tooltip. The tooltip must be gentle: it appears only after the pointer has been still on the target for about 500 ms, and it fades in smoothly, not instantly. A moved pointer that passes over many buttons must not cause any tooltip to show.

Why: buttons in an AI-built app have to be self-explaining, because the user may not have read any docs and the AI cannot be standing next to them. At the same time, tooltips that pop in on every movement are aggressively noisy and make the UI feel twitchy. The 500 ms hover delay is the standard tradeoff: intentional hovers get the explanation, casual passes do not.

Required content of a button tooltip:

1. What the button does, in plain English.
2. What will change in the app after you click it.
3. For destructive or irreversible-seeming actions, what is and is not preserved (files on disk, state in memory, etc.).
4. For actions that use technical jargon in the button label (for example, "EBU R128", "Auto-level", "Mux"), an explanation of the jargon, written for a non-expert. Never assume the user has the vocabulary; always define the terms.

Required content of a non-button label tooltip (for example, a waveform meta line that says "EBU R128 -16 LUFS / -1.5 dBTP"):

1. What the label means, in human terms, no jargon.
2. A breakdown of any technical parameters, one by one, each with a plain-English explanation and what it means for the user's outcome ("quieter moments got slightly louder", "no audio will clip on playback", etc.).
3. Whatever the practical effect is on the thing the user was looking at. Do not just define terms; explain the consequence.

Implementation pattern, clipping rules, and edge-anchored positioning CSS: see webview-conventions-detail.md § 7c.

Key: use data-tooltip attribute with 500ms CSS transition delay. Do NOT use HTML title= attributes. See reference file for full CSS and edge-anchoring pattern.

7e. Diagnostic views NEVER auto-correct — show the truth

Diagnostic views must show source data, never an auto-corrected prettier version. Compute corrections, display them with a clear signal, but never silently apply them. Full rule, forbidden examples, and the wrapper.position.z = -minZ trap: see webview-conventions-detail.md § 7e.

7d. Provide a live "now playing" / "current state" indicator for any media or document being viewed

When an artifact exists in multiple versions (raw/normalized/preview/committed), the UI must always show which version is currently visible or playing. Labeled pill overlay pattern and color-keyed dot details: see webview-conventions-detail.md § 7d.

7b. Always expose a frontend eval channel so the AI can hot-patch the UI

Full implementation (server ring-buffer, UI setInterval poller, AI curl usage, and caveats): see webview-conventions-detail.md § 7b.

Key points:

• Ship POST /eval + GET /eval/:id endpoints so the AI can push JS snippets into the running UI.
• Gate behind --dev / DEV_MODE=1 — this is a full remote-code-execution primitive.
• Results route through /console or a dedicated /eval-result endpoint; never just "ok": true.
• Catch and return exceptions as {error, stack} so the AI can diagnose snippet failures.

7a. AI drives the frontend via state mutations

The flip side of 2-way comms is that the AI is an equal citizen to the human user. When the AI wants to drive the UI, it:

1. POSTs to a command endpoint (/start-recording, /play, /seek)
2. The server updates its state
3. The UI's state poller sees the change and reflects it

There is no separate "AI remote control" channel. The same POST /start-recording that your UI's Record button fires is what the AI fires. The UI's state poller is what turns the server state change into visual feedback the human sees.

This means your server's command endpoints double as AI automation hooks. Test that during development: before shipping, curl -X POST .../start-recording from the terminal and watch the UI animate without touching the browser. If it doesn't animate, the state poller is broken or the UI is keeping local state.

8. JavaScript console forwarding

Full <script> snippet, server ring-buffer implementation, and AI debug workflow: see webview-conventions-detail.md § 8.

Key points:

• Override console.log/warn/error to POST /console as JSON; keep a bounded ring buffer server-side (500 entries).
• Catch window.onerror and unhandledrejection and forward them too.
• Expose GET /console so the AI can read all UI-side log output without DevTools access.
• Never ship an app without this — it is the only way to debug UI-side bugs in the webview.

9. Use Hydrogen's built-in recording countdown

Hydrogen's recording start --countdown 3 shows a native 3-2-1 countdown overlay before starting capture. Use this instead of writing your own JS countdown in the app's UI. The native overlay is:

• Visually consistent with the rest of Hydrogen
• Reliable (runs in the parent window, can't be broken by iframe issues)
• Works for mic-only sessions too (disable screen, enable audio, still get countdown)

If your app needs a countdown before capturing audio, trigger adom-cli hydrogen recording start --countdown 3 --audio-only (or whatever the current flag spelling is, check adom-cli hydrogen recording start --help) from your server's /start-recording endpoint. Don't roll your own JS timer; it'll drift, miss the first click, and look different from every other countdown in the system.

Mini web server patterns

Full code templates for Rust (tiny_http), Node.js, and Python: see webview-conventions-detail.md § Mini web server patterns.

Pick whichever language the CLI is already using. Embed UI assets at compile time (Rust include_str!) or load them from disk (Node.js / Python). Always serve /favicon.svg with Content-Type: image/svg+xml and implement /shutdown for clean exit.

Before publishing: show the user the working app

Never publish an app to GitHub or the wiki before the user has seen it working. The user has to click through the UI (or watch the AI click through the 2-way HTTP endpoints) and confirm it behaves correctly before any git push, gh release create, or adom-wiki page create runs.

This is a hard rule because:

• The AI cannot judge UI correctness by reading code. Fonts load wrong, layouts break, animations stutter, and the code still compiles.
• Publishing means other users will find it via wiki discovery. Shipping a broken app wastes every future user's time.
• Git history and wiki publish dates are public. A bad v0.1.0 is embarrassing.

Correct flow:

1. Build the app locally
2. Start it (my-app run or equivalent)
3. Show the user a screenshot of the UI or ask them to click through it
4. Drive the 2-way HTTP endpoints yourself to verify the happy path works
5. Fix whatever the user or the verification surfaces
6. Only after the user gives explicit approval, publish to GitHub + wiki

If the user says "build an app that does X", the default end state is a running app with a screenshot shown to the user, NOT a published GitHub repo. The publish step comes after a separate "ship it" from the user.

CLI surface

Follow adom-cli-design for the app's CLI — output conventions (OK: / ERROR: / Hint:), isatty-aware colors, the skill-file pattern, and the Rust + clap defaults. All of those apply in full to apps; this skill doesn't restate them.

Publishing an app to the wiki

Follow the tool-publisher skill for the full lifecycle. The short version:

1. Create the GitHub repo (adom-inc/<app-name>, private by default).
2. Push v0.1.0 with Cargo.toml / package.json / setup.py + SKILL.md + README.md + docs/icon.svg.
3. Create a GitHub release with the binary (or install script) attached.
4. Publish a wiki page of type app at apps/<app-name> with type, slug, title, brief, and metadata fields including repo, version, releases.adom_docker, discovery_triggers, and discovery_pitch. Full JSON template: see tab-wiring-reference.md § Wiki page metadata template.
5. Verify the wiki page renders the install prompt correctly (adom-wiki page get apps/my-app-name).

The wiki's /discover aggregator picks up discovery_triggers on next regeneration and adds them to adom-wiki-discover, so any Claude Code session that hears a matching trigger will suggest your app automatically.

Relationship to other skills

• tool-publisher, how to publish any CLI tool (including apps) to the wiki. Apps are a specific kind of tool: CLI + embedded HTTP server + webview UI.
• adom-cli-design, the output conventions (OK: / ERROR: / Hint:) that apply to the app's CLI surface, before and after the server runs.
• brand, the visual identity (colors, fonts, spacing) that every app's HTML must follow.
• adom-panels / adom-panels-webview, the Hydrogen webview panel API, including navigate, refresh, and proxy mode.
• adom-workspace-control, adding/removing tabs, finding panel leaf IDs, activating tabs.
• adom-wiki, the CLI for publishing wiki pages and uploading assets (including the app's wiki page + icon + install prompt).
• av-creator — DEPRECATED. The Adom Viewer is no longer the canonical display surface. Build new visual content (3D models, diagrams, widgets, charts) as apps via this skill, not as AV widgets. Only consult av-creator if you're maintaining an existing un-ported AV view.

Reference apps

• video-post (adom-inc/video-post), Rust CLI + tiny_http server, voiceover recording UI, ffmpeg mux pipeline. Demonstrates the full pattern: brand-compliant UI, SVG favicon, proxy URL, Hydrogen audio integration, graceful shutdown.
• adom-desktop demo server (adom-desktop/skills/demo/server.cjs) - Node.js HTTP server that drives the step-by-step demo webview. Uses the same webview tab + proxy URL pattern.

Checklist before publishing

Full checklist (UI + brand, server wiring, 2-way comms, CLI output, verification, repo + wiki): see publish-checklist.md.

The two blocking categories are 2-way comms (every action must be curl-scriptable, GET /state must exist, GET /console must be wired) and verification (user must have seen the running UI and given explicit approval before any git push, gh release create, or wiki publish runs).