UI Style Guide

This document is the canonical style reference for Clapilot UI and bundled modules. It is written for anyone building or reviewing web app pages and module UIs; native iOS/macOS work should read the Apple Native Style Guide alongside it.

For design-to-implementation reviews, use this page together with the Design QA + Redesign Prep workflow. AI-generated mockups are reference material only; final UI must still map to existing Clapilot components, tokens, and agent/tool expectations.

Visual reference page: /clapilot-styleguide.html. Apple native companion: Apple Native Style Guide and /clapilot-ios-styleguide.html.

Core principles

• Prefer clean outlined surfaces over elevated boxes.
• Avoid full-page outer rectangle borders.
• Keep visual hierarchy through spacing, radius, fill, and subtle borders first; reserve shadow for true overlays such as dialogs, menus, floating launchers, and drag previews.
• Keep control styles consistent across app pages and module UIs.
• Build work surfaces, not marketing pages: headers stay compact, controls stay close to the data they affect, and the main workflow should be visible in the first viewport.
• New UI should feel first-party next to Dashboard, E-Mails, Dokumente, Aufgaben, Kalender, Spezial-Agenten/Agents, and Einstellungen.

Localization

• Web UI strings live in the keyed translation map in src/lib/i18n.ts; client components should read the current language through useUiLanguage() and use t("key") instead of inline German copy.
• Apple native UI strings live in clients/apple/ClapilotApple/Sources/Clapilot/Support/L10n.swift; views should resolve copy with L10n.text(_:language:) using model.currentUser?.uiLanguage ?? .de.
• Supported UI languages are German (de), English (en), and Italian (it). German remains the default and should preserve existing wording when migrating strings.
• Before handing off localization work, run npm run i18n:audit to measure remaining likely hardcoded UI strings across the web and Apple clients. The audit is intentionally conservative and may include prompt/demo/provider literals that need human triage.
• Generated email replies default to the detected sender message language across the supported language set. In the email detail view, prepared-answer drafts can be regenerated between the sender language and the user's current UI language.

Surface pattern

• Primary shell class for app pages: clapilot-surface-card.
• Soft supporting shell class: clapilot-soft-panel.
• Segmented control shell class: clapilot-segmented-control.
• Field shell class: clapilot-field.
• Required visual behavior:
  • standard rounded corners (14px)
  • white surface
  • subtle neutral 1px outer border
  • no default shadow

Use this for:

• page-level content shells (tables, kanban columns, panel wrappers)
• module outer containers (workspace shells, canvas wrappers, side panels)

Do not use this for:

• destructive/warning alert boxes (keep semantic alert styling)
• fine-grained internal grid lines (for example calendar or spreadsheet cell separators)

Borders and separators

• Outer panel borders: use the shared subtle neutral surface border by default.
• Internal separators: keep subtle neutral lines where needed (border-border/70 style intensity).
• Stacked entity lists should default to separate outlined row blocks instead of one big heavily divided container.
• Only use row dividers when the UI is intentionally a dense data table or grid, not for normal module list rows.
• Input and control borders are allowed and should remain light/neutral.

Typography

• Use one UI text system by default: Inter, system UI, and platform sans-serif fallbacks.
• Use Avenir Next / SF Pro Display style type only for top-level page and module titles.
• Do not use Avenir/display typography for card headings, row titles, labels, buttons, badges, body copy, or metadata.
• Keep display titles modest:
  • page titles around 24px
  • module/workspace titles around 27-30px
  • regular weight (400)
  • slight positive tracking only (0.012em)
• Section/card headings use Inter/system semibold at compact sizes (17-18px for sections, 14-15px for small card headings).
• Body copy uses Inter/system around 14px; metadata uses 12-13px muted text; labels use 12px semibold.
• Reading text for generated email/document content uses Inter/system at 14px / 1.6 with pre-wrap. Never render user-facing content (email bodies, drafts, summaries) in monospace; monospace is reserved for code, IDs, and prompt blocks.
• Uppercase group labels (section markers inside cards such as CONTEXT / REPLY EMAIL, and sticky list group headers) use 11px semibold, 0.06em letter spacing, uppercase, muted color.
• Do not introduce new font families inside modules. Imported web fonts, serif display faces, condensed fonts, and highly stylized type are not first-party Clapilot defaults.

Spacing

• Use a compact 4px-based spacing scale: 4, 8, 12, 16, 20, 24, 32.
• Default page/module shell gap: 18-24px.
• Default panel padding: 16-18px.
• Default form row gap: 16px.
• Default compact group/card/list gap: 12px.
• Default toolbar/action gap: 8px.
• Default label-to-field gap: 6px.
• In forms, the row-to-row gap must be visibly larger than the label-to-field gap so labels read as belonging to the field below, not the field above.

Color and controls

• Brand primary color is navy blue (primary token).
• Default module branding should stay in the primary/navy + neutral palette.
• Primary text buttons use the navy-rim style: navy fill, darker navy 2px rim, white label/icon, compact radius, and subtle top highlight.
• Secondary text buttons use the outline-quiet style: white fill, fine navy hairline, navy text/icon, and no heavy shadow.
• Primary and secondary text buttons must share the same compact 32px height, padding rhythm, radius, and text size; only fill, border color, weight, and elevation should change.
• Primary and secondary text buttons must support both text-only and leading-icon variants. Use a leading icon only when it improves recognition of the command.
• Segmented controls use a white outlined shell with the same 10px control radius as fields/dropdowns, and the inner selected tab/button boxes use that same radius rather than pill rounding. Selected tabs use the deeper navy action color (#466197) rather than the brighter legacy primary blue.
• Avoid hardcoded custom action colors where tokenized classes exist.
• Do not use beige / amber / yellow as the default visual identity for a new module surface; reserve warm tones for actual warning states.
• Avoid oversized pill buttons with extra-bold labels in standard CRUD/module flows.
• Single-object actions such as edit, save, delete, archive, refresh, close, and more-options should default to iOS-like circular icon buttons.
• Circular icon buttons should be compact (40px in main toolbars; smaller only inside dense repeated rows), outlined by default, and include accessible labels/tooltips. Use lucide-react icons in React app surfaces and inline SVG icons in plain bundled-module HTML.
• Binary settings should use app-styled on/off toggles. Use checkboxes only when the UI is intentionally a form checklist, not when the user is turning a feature, connection, automation, or visibility state on/off.
• Inputs, selects, and textareas should read like Clapilot fields:
  • white fill
  • light neutral border
  • tighter 10px corner radius, distinct from the 14px box/panel radius
  • no default shadow
  • subtle primary focus state
• Semantic colors are allowed only for semantic meaning:
  • green/success for completed, healthy, or positive fit states
  • amber/yellow only for warnings or pending attention
  • red only for destructive/error states
  • blue/navy remains the default action and selection language
• Calendar provider colors are normalized into restrained Clapilot shades before rendering or storing; do not display raw external neon colors in event chips.
• Repeated boxes may use subtle shared background tints when it helps users distinguish module families or work states. Prefer neutral/blue utilities such as clapilot-box-bg-field, clapilot-box-bg-navy-wash, clapilot-box-bg-ice-blue, and clapilot-box-bg-slate-blue for non-semantic differentiation.
• Use clapilot-box-bg-success-soft, clapilot-box-bg-warning-soft, and clapilot-box-bg-danger-soft only when the box itself carries completed/healthy, pending/warning, or overdue/error meaning.

AI gradient surfaces

• Use subtle blue header gradients for normal widget and workspace headers instead of repeating the lavender AI gradient everywhere.
• The static styleguide previews candidate neutral header variants named Ice, Deeper Navy, Softer Indigo, Slate Blue, and Blue Gray. Treat these as visual options until one or more are promoted into shared app utilities.
• The static styleguide also previews non-gradient blue tint options, including the current primary only as a comparison and clearer blue candidates such as App Blue, Azure, Sky, Cyan Blue, and Ice Blue. Use these when a flat header/background tint feels calmer than a gradient.
• The static styleguide previews box background tint utilities separately from header gradients. These are meant for cards, task rows, widget bodies, and grouped box backgrounds rather than page-scale bands.
• Dashboard widget headers, Tasks Kanban column headers, and the Documents page toolbar use the flat Ice Blue tint (rgba(96, 165, 250, 0.14)) with a subtle Ice Blue border (rgba(96, 165, 250, 0.26)) via clapilot-widget-header-ice-blue.
• When a neutral gradient is the top band inside a bordered card, it should keep the top radius and avoid duplicate top/side borders, matching the clapilot-ai-header structure.
• Use the clapilot-ai-surface treatment for AI-assisted search/header rows, smart inbox controls, AI summaries, recommendations, and agent-assisted work areas.
• The AI gradient is pale blue/lavender, not a marketing hero. It should stay attached to functional controls or contextual AI content.
• Use this treatment for compact headers like the E-Mails and Mandanten search/filter bar: search field on the left, mode/filter controls on the right.
• Keep the gradient subtle:
  • no saturated rainbow gradients
  • no dark hero banners
  • no module-specific brand gradients
  • no warm beige/orange/yellow AI surfaces
• Use clapilot-ai-badge or clapilot-ai-highlight for small AI labels, prepared draft states, or generated-summary callouts.

Asset and image generation

Use generated images sparingly. Clapilot is a productivity workspace, so assets should support recognition, empty states, module thumbnails, documentation, onboarding, or generated user content. They should not turn module screens into marketing pages.

For standard UI icons, prefer lucide-react in app code and inline SVG icons in bundled module HTML. Generate custom icons only for module/app identity, store thumbnails, empty-state art, or domain-specific symbols that do not exist in the icon set.

Asset generation prompt

Use this prompt as the base when generating Clapilot images, icons, module thumbnails, or empty-state illustrations:

Create a first-party Clapilot visual asset for a quiet professional SaaS workspace.

Style: clean, restrained, premium productivity UI; white and soft-neutral surfaces; deep navy action color (#466197), Clapilot primary blue (#5b6ff8) only as a controlled accent, pale blue/lavender AI glow only when the asset represents AI assistance.

Geometry: softly rounded shapes, subtle depth, compact composition, clear silhouette, no heavy outlines, no cartoon style, no glossy 3D mascot, no marketing hero treatment.

Typography: do not render text inside the image unless explicitly requested. If text is required, use short Inter/system-style labels only.

Icons: simple, flat, vector-like shape language with a clear silhouette, 2px rounded stroke, balanced optical weight, and no decorative extras. Use the existing navigation icons for Kunden, Kalender, Aufgaben, Dokumente, and Notizen as the quality reference.

Navigation/sidebar icons: fill the icon canvas/border. The symbol should occupy roughly 90-96% of the artboard, with no decorative empty margin and no floating miniature object in the middle. Keep the stroke safely inside the canvas so it is not clipped, but use the full available size.

Module and utility icons: center on transparent or white background, works at 16-32px for UI icons and 64-128px for module icons.

Images/illustrations: light, airy, work-focused, document/email/task/agent/productivity context; no stock-photo look, no people posing, no decorative blobs, no saturated rainbow gradients.

Background: transparent for icons and cutouts; white or very pale neutral for thumbnails and empty states. For thumbnails and empty states, keep enough padding so the asset is not clipped in rounded cards. For navigation/sidebar icons, do not add extra padding beyond the safe stroke inset.

Avoid: orange, beige, amber/yellow brand palettes, black outline cards, dark hero banners, loud gradients, fake app screenshots that conflict with Clapilot UI, unreadable tiny UI text, logos from other brands, 3D shopfronts/mascots/scenes, sparkles or badges unless explicitly requested for AI assistance, and decorative assets that do not clarify the workflow.

Reference patterns

Use these existing screens as the default visual source when creating new work:

• Dashboard: compact metric widgets, functional cards, practical first viewport, no marketing hero.
• E-Mails: dense split-pane workspace, compact tabs/filters, soft list rows, focused detail pane.
• Dokumente: card/list views, search/filter toolbar, restrained empty/loading states, compact file metadata.
• Aufgaben: kanban/list cards with clear state, priority, owner, and due-date hierarchy.
• Kalender: toolbar-first planning surface with app-styled segmented controls and subtle grid separators.
• Spezial-Agenten/Agents: list + dialog management pattern with compact rows, scoped actions, and soft settings panels.
• Einstellungen panels: grouped settings surfaces, label + helper text + control rhythm.

Layout patterns

Page or module shell

• Root background uses the app dot pattern or the host app background.
• Root gutter is around 24-32px on desktop and 10-16px on mobile so bordered surfaces have enough breathing room.
• The first row is a compact title/description plus primary actions, not a tall hero.
• Main content should use one of:
  • toolbar + table/list
  • list/detail split view
  • kanban/grid + detail drawer
  • settings groups

Toolbar and filters

• Keep filters and actions in a compact outlined row.
• Use segmented controls for view modes and tab-like state.
• Search fields should use clapilot-field behavior.
• Primary create/run/send actions use the raised navy-rim button; secondary filters, imports, cancel, and load actions use the outline-quiet button.
• Primary and secondary buttons can be text-only or use a leading icon. Do not replace named text buttons with icon-only controls unless the action is a compact repeated utility.
• Use circular icon buttons for repeated utility actions in toolbar rows, especially edit, save, delete, archive, refresh, and close.
• Use an on/off toggle for enabled/disabled settings in toolbars, rows, dialogs, and settings panels.

Lists and rows

• Mailbox/customer-style data lists may use one divided surface with sticky date/status group headers, compact rows, and subtle dividers.
• Divided list rows should follow the E-Mails/Mandanten rhythm: optional unread dot, avatar/icon, title + subject, one muted metadata line, and time/status/actions at the end.
• Normal work-item lists use separated outlined rows with small gaps.
• Rows should be compact and scannable: title, one metadata line, status/owner/date, and a small action cluster.
• Use table dividers only for truly dense spreadsheet-like data.
• Use sticky uppercase group headers for temporal buckets such as Heute, Gestern, Diese Woche when a list benefits from grouping.
• Avoid expanding large detail content inline inside rows; use a detail pane, full page, dialog, or sheet.

Details and forms

• Detail panes use a clapilot-surface-card shell with a compact header.
• Form groups use labels, helper text where needed, and soft fields.
• Long content scrolls inside the content region while bottom action/composer bars remain visible when applicable.

Empty, loading, and error states

• Empty states are compact panels inside the normal workspace, not full-page illustrations.
• Loading states should preserve the expected layout size.
• Generic web UI loading states use the shared LoadingAnimation, and native Apple loading states use ClapilotLoadingAnimation. Both render the Clapilot logo with a clockwise fill. Chat assistant answer/work indicators use the profile activity selection: the compact animated three-dot bubble is the default, and an explicitly selected Profile Pet replaces it. Neither should be replaced by the generic loader.
• Errors use inline banners or app-styled overlays/toasts; do not use browser-native dialogs for normal UX.
• Toast notifications use the shared top-center pattern for transient success, error, and status feedback. On web, place the stack at the viewport top center and keep each toast around 300-450px wide (420px default, constrained on mobile) so copy can wrap into multiple rows.
• Toast surfaces use the same pale blue/white/lavender gradient as AI-assisted headers, with the shared 14px continuous box radius. Keep semantic color on the icon only; do not use full green/red alert boxes for transient notifications.
• Toast content should prefer a left icon in a white circular well, a short title, and optional secondary message text. Use inline banners only for contextual validation or persistent page-level errors that must stay attached to a form or panel.

Radius and shadow

• Standard box radius: 14px, exposed through --radius and rounded-lg/rounded-md/rounded-sm.
• Form controls, dropdown controls, segmented-control shells, and segmented selected boxes use the tighter 10px control radius exposed through --clapilot-control-radius.
• Use the standard box radius for cards, panels, rows, dialogs, and larger rectangular controls.
• Keep true circles, avatars, icon wells, and pill/capsule controls on rounded-full/circle/capsule shapes.
• Standard content panels use borders instead of box shadows. Reserve shadows for true overlays such as dialogs, menus, floating launchers, and drag previews.

Bundled modules

Bundled module UIs must follow the same shell pattern as app pages:

• outer cards/panels use bordered, shadowless surfaces
• avoid stacked section borders as primary grouping
• row-based module lists should use compact outlined rows with spacing, not heavy list wrappers with horizontal separators
• use spacing and surface blocks for grouping
• keep module controls aligned with the app’s primary/secondary button language
• avoid custom visual systems per module unless the feature explicitly needs one
• do not ship black outline cards, oversized bold action pills, or custom orange primary buttons as defaults
• do not ship beige / amber / yellow hero gradients or outlined stat tiles as the default module shell
• keep a root page gutter (around 24-32px) so bordered surfaces have enough breathing room at iframe edges
• do not use browser-native dialogs (window.alert, window.confirm, window.prompt) for normal module UX
• use app-styled overlays, sheets, inline banners, or toasts for errors and confirmations instead
• model new module structure after Dashboard, E-Mails, Dokumente, Aufgaben, and Agents when no feature-specific first-party reference exists
• do not create standalone app-style navigation, marketing hero pages, or strong custom brand themes inside an iframe module

When scaffolding bundled modules, templates should start with this style by default.

Module host pages must not add an extra rounded/filled outer wrapper around the embedded module iframe.