Product UI

HQBase should feel like one calm, practical product everywhere. The public site explains it, setup gets a workspace running, and the installed app helps people work with shared mail without hiding important state or permissions.

At a glance

Area	Rule
Brand	Use the complete official HQBase mark; never redraw or simplify it.
Appearance	Offer explicit Light and Dark modes with strong contrast and visible focus.
Layout	Keep desktop efficient and compact screens touch-friendly from 320px upward.
Feedback	Explain what happened, what remains safe, and what the person can do next.
Privacy	Never expose credentials or email content through logs, notifications, previews, or errors.
Accessibility	Use real labels, keyboard support, reduced motion, safe areas, and meaning beyond color.

Visual foundation

The official asset is the transparent SVG at hqbase/public/logo.svg. Its orange letterforms and orange-to-white baseline form one complete mark. Product, authentication, offline, and public pages render it without adding a background or changing its geometry.
Favicons use a transparent square canvas with a small optical inset. Apple touch and installable icons use a full-bleed near-black background with safe padding. Maskable icons keep the complete mark inside the platform safe zone. Every copy and derivative changes together.
Use self-hosted Geist Sans for product text and Geist Mono only for stable identifiers. The app must not depend on Google Fonts, Vercel, or another remote font host.
Use near-black neutrals, quiet borders, compact type, visible focus, restrained shadows, 8px default corners, and 6px controls. Avoid decorative gradients in the installed app.
Use direct headings without eyebrow or overline copy. Keep labels visible and use badges only when they communicate useful status.
Cards group related secondary information. Alerts hold persistent feedback. Primary, outline, and ghost buttons express action priority.
Use the existing Lucide outline icons with a restrained stroke. Disclosure, selection, and account icons remain visually lighter than their labels.

Cloudflare-owned deployment, authorization, and consent screens keep Cloudflare’s design. The HQBase OAuth relay uses the product logo, typography, colors, focus treatment, and compact controls, but remains a small confirmation page rather than a marketing page. Its actions stay intrinsic and do not become oversized or full-width on phones.

Public website and documentation

The public site presents one free and open-source team email workspace running in the customer’s Cloudflare account. One deployment owns both / and /docs.

Landing page

Keep the page to a compact header, hero, product features, and one footer. Do not add pricing, fabricated adoption proof, or a separate hosted-product story.
Lead with Your team’s workspace. On your Cloudflare infrastructure. Show the desktop workspace as live interface markup rather than a screenshot or decorative browser window. Use clearly illustrative data without invented customers, usage totals, locations, or performance claims.
The first view should remain level and undistorted, with roughly half the workspace preview near the lower edge of the viewport. A subtle orange-to-amber dot field may sit behind it. Scrolling may shift the field and enlarge the preview by no more than about 7.5 percent. Reduced-motion visitors receive the same static resting composition.
The header begins as a flat transparent row containing the logo, compact navigation, and a small deployment action. After scrolling, it may become a narrower translucent pill with a quiet border and shadow.
Features use one centered heading and six compact cards. The cards cover MCP, multiple domains, mailbox access levels, PWA and Web Push, customer-owned Cloudflare resources, and signed updates. Their copy must not imply that MCP administers the workspace or that HQBase ships separate native apps.
Feature cards use short copy, simple Lucide icons, a small neutral grid, and a soft theme-aware halo. Hover may lift the card and bring orange into the grid, but the section does not use miniature product scenes, broad gloss, shader backgrounds, or elaborate animation.
The footer keeps brand context, licensing, primary links, and the appearance control in one band.
Compact navigation has a labelled menu button, traps focus, closes after navigation, prevents background scrolling while open, and restores scrolling afterward.

Appearance and documentation

The landing page and documentation share one Light or Dark preference. On the first visit they follow the operating-system preference; afterward they remember the visitor’s explicit choice. A change applies immediately to the page, workspace preview, and browser chrome.
Both use the same compact sun-or-moon button. The landing page places it in the footer. Documentation places it at the bottom-right of the Starlight sidebar, optically centered between the footer divider and browser edge.
Documentation aligns its logo and GitHub icon to matching outer insets. The GitHub icon has no trailing divider. The header product label is 14px; previous and next navigation uses 12px direction labels with 18px titles and compact icons.
Header links point only to real sections and public destinations. The primary action starts the official Deploy to Cloudflare flow, the source action opens HQBase/hqbase, and Getting started uses Cloudflare’s official deployment-button asset.
Every link uses the pointer cursor on mouse-capable devices. Public pages keep visible focus, reduced-motion support, and readable layouts from 320px through desktop.

Installed app layout

Desktop

Use the complete HQBase logo. The header keeps bounded search on the left and mailbox selection plus Compose on the right.
The persistent sidebar lists folders first, then Connect MCP, Settings, and appearance. The account menu sits at the bottom behind a second quiet divider.
The installed app offers explicit Light and Dark modes. Dark is the initial mode until the person chooses otherwise. The choice updates browser chrome, persists locally, and does not follow later operating-system changes.
A fine-pointer device keeps the desktop shell even when its window narrows. Below 1024 by 600 CSS pixels, show a quiet request to enlarge the window rather than switching to the phone layout.
The sidebar may be hidden and restored without changing the route or draft. Sidebar/content and conversation-list/reader dividers support pointer and keyboard resizing, useful limits, double-activation reset, and locally remembered widths.

Phones and compact layouts

A hamburger immediately before search opens a left-side drawer; Compose remains the trailing header action. The drawer shows workspace identity, mailbox selection, folders, Connect MCP, Settings, appearance, and the account menu in that order.
The drawer keeps the current destination clear, uses touch-friendly targets, traps focus, returns focus to its trigger, and closes after selection, Escape, or backdrop dismissal.
All mailboxes and each accessible mailbox show their unread Inbox count, including zero. The Inbox count follows the active mailbox filter. Catch-all remains an unfiltered workspace count.
The shell, drawers, sheets, and full-screen composers respect top and bottom safe areas and the dynamic viewport. Their background extends beneath device cutouts; a dimmed backdrop does not paint the status bar, Dynamic Island, home indicator, or browser-bar regions.
The mail header stays fixed outside the scrolling list or reader. Pull-to-refresh starts only from a mail list or conversation already at its top, moves that area rather than the entire app, and refreshes only after a deliberate release threshold. A completion message clears after two seconds.
Tapping the app-owned top safe-area strip scrolls the visible mail list or reader to the top when the operating system allows it. After meaningful scrolling, a labelled floating up-arrow offers the same action near the lower-right corner and clears after use.
Disable browser-level scroll chaining and pull-to-refresh around the app shell. Prevent accidental double-tap zoom and focused-field zoom while keeping pinch zoom and operating-system magnification available.

MCP and Compose

Connect MCP opens a compact dialog that identifies the signed-in user and switches between the read-only /mcp and Mail actions /mcp/full profiles. It shows one explanation and absolute Streamable HTTP endpoint at a time, stays inside compact safe areas, and never asks for a manual token. See Connect AI tools with MCP for authorization and tool behavior.

New-message Compose is a non-modal bottom-right window on desktop with labelled minimize, expand/restore, and close controls. It becomes full-screen on compact layouts. Reply and Forward open after the conversation on desktop and above the conversation context on compact layouts; they do not create a pop-up or separate browser tab.

Every layout preserves recipients, sending identity, reply or forward context, attachments, formatting, autosave, submission state, durable recovery, dismissal behavior, visible focus, and focus return. A reply prefers the exact authorized address that received the selected message and keeps labelled, editable To, Cc, and Bcc fields. Minimizing, resizing, or changing layout never recreates the draft. The complete persistence and sending rules live in Writing and sending mail.

Reading mail

HTML messages

HQBase displays a message’s HTML version when available and falls back to plain text. Untrusted HTML is sanitized and rendered in a sandboxed iframe.

Preserve safe formatting, tables, links, and a limited inline-style set.
Make the message feel native to the reader: no extra card, border, corner radius, background, inner padding, or minimum iframe height.
Keep the document transparent. Apply HQBase theme colors only where the sender did not provide a safe explicit color or background.
Fit the iframe to its content without an internal vertical scrollbar. Preserve safe authored widths and allow horizontal scrolling for content wider than the reader.
Remove scripts, forms, frames, objects, active controls, redirects, event handlers, unsafe URLs, and CSS that can load resources.
Resolve cid: images only to allowed raster attachments from the same message.
Block remote media until the person chooses Load images. Always load from this sender is a per-user, per-address preference and does not restore other removed content.

The original HTML remains in customer storage; sanitization happens when the message is displayed.

Conversation lists

Each list contains at most one row per accessible thread. The latest matching accessible message provides the sender, subject, snippet, and time. The row also shows a thread count above one, whether any accessible message has an attachment, and unread state when any accessible inbound message remains unread.
A new inbound or outbound reply updates and moves the existing row instead of creating another row.
Load the newest 50 matching threads first. Approaching the end loads the next page, while Load more conversations remains as a keyboard-accessible fallback, loading label, retry action, or disappears at the final page.
The header always shows the exact total for the active folder, mailbox, and search filters. That total does not change as older pages load.
Changing a filter returns to the newest page. Opening a conversation and returning preserves loaded pages and scroll position. Background refresh updates the newest page without discarding older loaded pages. Paging cursors stay opaque and never bypass mailbox access.

Conversation reader

Show accessible messages in chronological order. Begin with the first and final message; when messages sit between them, one labelled divider reports the hidden count and expands or collapses them in place.
Collapse quoted reply history behind a labelled ellipsis while preserving safe formatting and the remote-image choice. A manually forwarded message remains visible as message content even when a sender wraps it in markup commonly used for reply quotes.
Keep subject, read/unread, star, archive, and Trash actions at the top. Put compact Reply and Forward actions after every expanded message and larger conversation-level actions after the final message.
Opening an unread conversation marks its accessible unread inbound messages read. Star and unstar affect every accessible message in the thread. Archive moves accessible Inbox and Catch-all messages without moving Sent copies. Trash moves the accessible messages represented by the active folder.
No list, reader, or conversation action may read or change a mailbox outside the person’s current access. See Mailbox access for the permission levels.

Setup and Settings

Setup

Setup uses one quiet resumable page. Installation and authorization appear as a compact vertical timeline. After temporary Cloudflare access is verified, progress becomes Domain → Owner account → Mailboxes, with Mailboxes owning the final setup action.

Forms stay left-aligned with visible labels, nearby errors, aria-invalid, and no nested card around the step. Mailboxes use one compact editable table with Support and Privacy defaults for each domain and an owner-named mailbox as the final editable row. Default From mailbox records the owner’s initial choice.

The development-only /__ui/setup gallery uses deterministic fixtures without Cloudflare access, D1 changes, or deployed resources and is excluded from production.

Shared Settings patterns

Tabs open directly onto their content. Add and create forms use labelled dialogs.
Tables use one rounded, bordered scrolling container with quiet headers, compact rows, bounded controls, right-aligned actions, and a calm full-width empty row.
Do not add search, sorting, pagination, or selection before the behavior needs it.
Settings contains only active workspace and infrastructure destinations.

Settings areas

Notifications explains current-device support, subscription state, cross-device effects, and privacy before one explicit enable or disable action. Permission is requested only after the person activates Enable notifications, never on load, sign-in, navigation, or incoming mail.
Users places accessible role guidance beside the Role heading: owners and administrators manage the workspace, only owners change owner membership, and administrators and members still need mailbox access.
Updates shows installed and available stable versions in one compact line with Check updates. It reveals installation only when an update exists, then replaces it with one progress area containing a spinner, target version, build reference, and reassurance that HQBase remains available. See Updates for the update rules.
Domains separates Domain, Receive, Send, DNS, Status, and actions. Compact screens keep the domain and combined readiness visible while hiding individual readiness columns.
Mailboxes uses a compact master-detail layout. Selecting an address or access summary opens a side panel on desktop and full-screen sheet on compact layouts. Lead with People with access and Manage access; put uncommon controls under More settings and call aliases Additional email addresses.
Every signed-in user with a sending identity can choose a personal Default From mailbox from active mailboxes where they have Agent or Manager access. New messages and forwards use that choice; replies continue to prefer the mailbox that received the original message.
Mailbox access remains part of Mailboxes rather than becoming a separate Settings page. Bulk access appears only after row selection, names the exact number and addresses affected, and writes explicit mailbox permissions. Domain filtering never implies inherited future access.
Cloudflare-backed actions never display an API-token field. When authorization is needed, the action opens a labelled modal and starts OAuth with PKCE. An old session asks for the current HQBase password in that modal, resumes the exact action, and never exposes a raw API error. Cancellation changes nothing. Organizations blocking the public OAuth app receive a link to the customer-managed setup without a manual-token fallback. See Cloudflare OAuth for the security rules.
Debug contains deployment diagnostics in one large read-only monospaced field. Domain controls remain under Domains.

Every field has a persistent label and associated inline error. Compact editable fields use at least 16px text on iOS to avoid focus zoom; desktop text may remain smaller.
Loading buttons keep an operation-specific label and prevent duplicate submission. Errors remain limited and free of secrets. Success messages say what happened, what remains safe, and what to do next.
Keep focus visible, use 44px targets where practical, avoid clipping on narrow screens, and never rely on color alone for meaning.
Primary routes are /inbox, /sent, /starred, /archived, /trash, and /catch-all; a message ID appends to its folder route. Private drafts use /drafts and /drafts/<draft-id>. Drafts appears only when the person has drafts or is already on that page.
Settings routes are /settings/mailboxes, /settings/users, /settings/domains, /settings/notifications, /settings/updates, and /settings/debug. / and unknown app paths normalize to /inbox.
Back and forward restore the represented route. Permission-gated Settings routes normalize only after the current role is known. Compose remains local UI state.
Desktop keeps list and reader side by side. Compact folder routes show only the list; selecting a conversation replaces it with the reader. Back returns to the same filters, loaded pages, and scroll position. The compact list uses one header with the active folder and conversation count.

Audible feedback

Sounds are quiet, generated locally, and always supplemental to visible feedback. They never use a remote audio host or block an action when browser audio is unavailable.

Play one send sound only after the server confirms success; do not add a second toast sound.
Play one incoming sound for a batch of newly discovered messages. Initial loading, navigation, filter changes, and repeated polling of known messages remain silent.
Pull-to-refresh plays one cue when it reaches the release threshold and a distinct completion cue only after a successful fetch.
Success, information, warning, and error toasts have distinct quiet sounds; loading remains silent.
Honor browser autoplay restrictions and prefers-reduced-motion, use restrained volume, and fail silently when audio is unavailable.

PWA, updates, and notifications

Installation, offline use, and updates

The manifest launches Inbox in standalone mode and uses product colors, official installable icons, and stable shortcuts only.
The service worker caches only the public shell and versioned static assets. It never caches API, authentication, email, attachment, remote-media, setup, notification, or other user-specific responses.
Navigation prefers the network and falls back to a branded offline page. A waiting service worker activates only after a deliberate reload.
After an update starts, the app checks for the replacement service worker at a short limited interval and shows Update in progress instead of another installation action. When ready, it shows A new version of HQBase is ready. with a deliberate reload action and one quiet local sound when audio is available.
Lifecycle metadata revalidates or uses no-cache; hashed assets may be immutable. Background mail synchronization or offline message storage requires a separate privacy and delivery design.

Web Push and unread state

Web Push is optional and progressive. iPhone and iPad require a Home Screen web app; Android may derive launcher state from visible notifications; unsupported devices retain the complete in-app unread experience without a dead control.

Subscription is explicit and per device. A user may subscribe several devices, and disabling one removes only that device.
The installation owns its VAPID keys. The private key remains a Worker secret; subscription endpoints and encryption keys remain in D1, are never logged, and are removed when the push service reports them expired or gone.
A new non-duplicate inbound message schedules notifications only for subscribed users who currently have read access. Delivery failure never delays or rolls back accepted mail.
Every push displays a visible notification. Its encrypted payload contains only an opaque app route, thread replacement tag, and the recipient’s unread total—never sender, recipient, subject, snippet, body, attachment, session, or Cloudflare data.
Activating a notification focuses or opens the represented message. Authentication and current mailbox access remain authoritative; a notification never grants access.
The unread total counts accessible unread inbound messages in Inbox and Catch-all. Navigation, document title, and supported app badges update from that total and clear at zero. The open app refreshes after mail actions, focus, foreground push, and limited polling.
Android launcher badges remain operating-system controlled where numeric badging is unavailable. HQBase still provides a visible notification and exact in-app count.
Push handling does not cache authenticated notification, unread, message, or subscription data. Closing a notification does not mark mail read.

Testing requirements and repository ownership live in Engineering Standards.