Skip to content
Omicron

Development

Frontend guide

Working inside apps/frontend — SvelteKit structure, the Bits UI rules, and the theme tokens.

SvelteKit (Svelte 5, runes), Bits UI, Tailwind CSS v4, Tiptap, Lucide.

Directory map

Directory Responsibility
src/routes/ Pages (SSR) plus /api/[...path], the reverse proxy to the backend
src/lib/api/ Typed API client; response types come from packages/contract (below)
src/lib/components/ Application components; Icon.svelte is the single Lucide wrapper
src/lib/components/ui/ Bits UI (headless) wrappers
src/lib/editor/ Tiptap integration, lazy-loaded on /compose

The reverse proxy

The web UI calls the same-origin /api and uses normal session cookies. Caddy routes public API requests directly to the backend. /api/[...path] remains a development/SSR proxy and preserves CORS headers and preflights for independent bearer-token clients. OAuth token/revocation and metadata routes also proxy to their root backend paths during local development.

INTERNAL_API_URL tells the frontend how to reach the backend inside the container network.

API types and the backend contract

src/lib/types.ts re-exports the API’s types from @omicron/contract (packages/contract, linked into the app). That package holds a zod/mini schema for every payload the backend sends, with each field documented: which field to build a link from, which is null and when. It is the one definition of the API’s shapes, shared by the backend, the web app, and the mobile app.

Each app holds it to a different standard:

App How it uses the contract
Backend Routes use satisfies Reply<"SchemaName">; tests/contract/contract.test.ts checks serializer types and parses real output
Web Types only. It ships with the backend, so it trusts the payloads
Mobile Parses every response with its schema; a list item that does not fit is dropped, anything else is an error

A serializer change the contract does not describe fails the backend’s pnpm check, naming the pair, instead of surfacing at runtime in whichever component read the field.

The backend image is built from the repository root so it can include packages/contract. The frontend image is built from apps/frontend and uses type-only imports, so no contract runtime code enters its bundle. The contract itself imports nothing but zod/mini.

UI rules

These are strict, and they are what keeps the app visually coherent.

1. Use Bits UI for every primitive that has one

Button, Avatar, DropdownMenu, Tabs, Toolbar, Label, Separator, Dialog, Tooltip, and the rest. Fall back to native HTML only where Bits UI ships no equivalent — text <input>, <form>, headings, layout — because Bits UI is headless and has no such component.

2. Style with the ported theme tokens, never ad-hoc colours

Kind Tokens
Colours foreground, foreground-alt, muted, muted-foreground, background, background-alt, dark, dark-10, accent, destructive, border / border-input
Radii rounded-input, rounded-card, rounded-9px, rounded-button, …
Shadows shadow-mini, shadow-popover, shadow-btn, shadow-card

3. Copy the docs’ class strings verbatim

The Bits UI docs are the single source of truth for appearance. Copy each component page’s example classes as-is: the docs and this app both use Tailwind v4, so no syntax translation is needed.

Where the theme lives

  • Tokens (colours, radii, shadows, fonts) and the CSS variables, ported verbatim from the docs’ :root: the @theme block in apps/frontend/src/app.css. There is no tailwind.config.ts.

Keep them in sync with the Bits UI docs theme. Do not invent new design tokens.

Icons

One wrapper, Icon.svelte, around Lucide. Import icons through it rather than scattering direct Lucide imports — it keeps sizing and stroke width consistent and the bundle predictable.

The editor

Tiptap lives in src/lib/editor/ and is lazy-loaded on /compose only. It carries Markdown input rules, image upload on paste and drop, and corner-drag image resizing. It is the heaviest dependency in the app; keep it off every other route.

Typography and fonts

  • Inter (variable, self-hosted) for UI — no render-blocking third-party font request.
  • Source Sans 3 (variable, self-hosted) for rendered post content (font-content).
  • Twemoji as a self-hosted COLR colour font, scoped by unicode-range to emoji codepoints only, so every reader sees the same emoji artwork regardless of OS while the document keeps plain Unicode emoji — federation-friendly, selectable, copyable.

Rendered post content

.prose-omicron styles the HTML Tiptap produces. Media never overflows the reading column, and wide preformatted blocks are scaled to fit rather than pushing the page sideways.

Checks

cd apps/frontend
pnpm fmt
pnpm check         # oxfmt, svelte-check, oxlint, and Vitest

Tests live in tests/, mirroring src/; see the application repository’s AGENTS.md for the helpers (tests/fakeFetch.ts, tests/fixtures.ts, and the $app/* stand-ins).

Found a mistake?Edit this page on GitHub.