Skip to main content

Design & Styling Guide

Guidelines for building Connected Apps that look and feel native to the Facilio platform.

Design Principles#

  1. Blend in — Your widget should feel like a natural part of Facilio, not a foreign embed.
  2. Keep it light — Use whitespace, subtle borders, and a neutral color palette.
  3. Be responsive — Widgets appear in panels, sidebars, and dialogs of varying sizes. Design for flexible widths.
  4. Prioritize readability — Use clear typography, adequate contrast, and logical information hierarchy.

Recommended: a shadcn-style UI + Lucide icons#

Aim for a shadcn-style look

Build a shadcn-style UI — compact, clean, and aesthetic: neutral surfaces, subtle borders, consistent spacing and radius — paired with Lucide icons. This look reads as polished and native to Facilio; hand-improvised CSS tends to look off (inconsistent spacing, weak contrast, mismatched states).

The preset theme#

The primary color is a Facilio-aligned violet, with neutral surfaces and a 0.45rem radius. Drop the :root / .dark blocks into your stylesheet and reference them as plain CSS custom properties (background: var(--primary)) — or as Tailwind theme variables (bg-primary, border-border) if you use Tailwind.

globals.css
:root {  --background: oklch(1 0 0);  --foreground: oklch(0.145 0 0);  --card: oklch(1 0 0);  --card-foreground: oklch(0.145 0 0);  --popover: oklch(1 0 0);  --popover-foreground: oklch(0.145 0 0);  --primary: oklch(0.496 0.265 301.924);  --primary-foreground: oklch(0.977 0.014 308.299);  --secondary: oklch(0.967 0.001 286.375);  --secondary-foreground: oklch(0.21 0.006 285.885);  --muted: oklch(0.97 0 0);  --muted-foreground: oklch(0.556 0 0);  --accent: oklch(0.97 0 0);  --accent-foreground: oklch(0.205 0 0);  --destructive: oklch(0.577 0.245 27.325);  --border: oklch(0.922 0 0);  --input: oklch(0.922 0 0);  --ring: oklch(0.708 0 0);  --chart-1: oklch(0.879 0.169 91.605);  --chart-2: oklch(0.769 0.188 70.08);  --chart-3: oklch(0.666 0.179 58.318);  --chart-4: oklch(0.555 0.163 48.998);  --chart-5: oklch(0.473 0.137 46.201);  --radius: 0.45rem;  --sidebar: oklch(0.985 0 0);  --sidebar-foreground: oklch(0.145 0 0);  --sidebar-primary: oklch(0.558 0.288 302.321);  --sidebar-primary-foreground: oklch(0.977 0.014 308.299);  --sidebar-accent: oklch(0.97 0 0);  --sidebar-accent-foreground: oklch(0.205 0 0);  --sidebar-border: oklch(0.922 0 0);  --sidebar-ring: oklch(0.708 0 0);}
.dark {  --background: oklch(0.145 0 0);  --foreground: oklch(0.985 0 0);  --card: oklch(0.205 0 0);  --card-foreground: oklch(0.985 0 0);  --popover: oklch(0.205 0 0);  --popover-foreground: oklch(0.985 0 0);  --primary: oklch(0.438 0.218 303.724);  --primary-foreground: oklch(0.977 0.014 308.299);  --secondary: oklch(0.274 0.006 286.033);  --secondary-foreground: oklch(0.985 0 0);  --muted: oklch(0.269 0 0);  --muted-foreground: oklch(0.708 0 0);  --accent: oklch(0.269 0 0);  --accent-foreground: oklch(0.985 0 0);  --destructive: oklch(0.704 0.191 22.216);  --border: oklch(1 0 0 / 10%);  --input: oklch(1 0 0 / 15%);  --ring: oklch(0.556 0 0);  --chart-1: oklch(0.879 0.169 91.605);  --chart-2: oklch(0.769 0.188 70.08);  --chart-3: oklch(0.666 0.179 58.318);  --chart-4: oklch(0.555 0.163 48.998);  --chart-5: oklch(0.473 0.137 46.201);  --sidebar: oklch(0.205 0 0);  --sidebar-foreground: oklch(0.985 0 0);  --sidebar-primary: oklch(0.627 0.265 303.9);  --sidebar-primary-foreground: oklch(0.977 0.014 308.299);  --sidebar-accent: oklch(0.269 0 0);  --sidebar-accent-foreground: oklch(0.985 0 0);  --sidebar-border: oklch(1 0 0 / 10%);  --sidebar-ring: oklch(0.556 0 0);}

To support dark mode, toggle the .dark class on the root element.

Font

Use Roboto as the typeface — it's what the Facilio platform uses, so your widget blends in. Load it from Google Fonts and set it as the base font with a system fallback:

<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" rel="stylesheet" />
body {  font-family: Roboto, "SF Pro Display", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, sans-serif;}
Icons

Use Lucide everywhere for consistent stroke weight and sizing. Size icons to match their adjacent text and let them inherit its color so they pick up the theme.

Best practices in Connected Apps#

A widget runs as an externally-hosted page inside a Facilio iframe / webview. A few things follow from that:

  • The iframe isolates your CSS. Tailwind's Preflight reset and your styles can't leak into — or collide with — the Facilio host. This is why shadcn/Tailwind drop in cleanly with no scoping.
  • Render around the SDK lifecycle. The iframe mounts before the SDK handshake; show a skeleton/loading state and render real content only after app.loaded fires.
  • Design for variable sizes. Facilio sizes the iframe (panel, sidebar, dialog, mobile), not the viewport — use fluid widths and @container queries; avoid fixed px widths and vw/vh.
  • Popovers are clipped to the iframe. Dialog, Select, Popover, and Tooltip portal within the frame — in small containers, prefer inline/expanding patterns over dropdowns that would overflow the widget.
  • Keep the bundle lean. Pull in only the Lucide icons you use so they tree-shake; the iframe loads cold each time the widget opens.
  • Match the platform theme. Read the host's light/dark state (or prefers-color-scheme) and toggle .dark so the widget flips with Facilio instead of being stuck on one mode.
On This Topic