Skip to content
AntFabric Corev1.0.0local

Designer guide

This page is written for a designer working on the shell: the frame every AntFabric app puts around its screens. It is self-contained on purpose: copy the whole page into Claude (or another assistant) to give it the context, then start designing.

AntFabric is a platform that organisations run their work on. It has a core that every product needs and nobody should rebuild (sign-in, people, files, live updates, notifications, background work, settings, an audit trail), and plugins that bring every product feature: Chat, Sales, and whatever an organisation needs next (HR, knowledge, AI tools). Each organisation gets its own instance, with its own database, users, branding and choice of plugins. Nothing is shared between organisations. The goal is an open framework: anyone can build a plugin, and it appears in every app without anyone changing core.

What this means for the shell: the shell never knows in advance which plugins it shows, how many there are, or what they are called. It must look right with one plugin or twenty.

Person Uses Cares about
Member (most people) User app on web, desktop and phone Getting to their work fast, notifications, staying signed in
Organisation administrator App Admin (web) People, roles, sign-in, plugin settings, appearance, audit
AntFabric operator App Manager (web) Creating, running and removing organisations’ instances
Plugin developer Builds screens that sit inside the shell Predictable space and rules; never re-implementing navigation

Roles are the organisation’s own. What a person sees depends on permissions (for example sales:manage), never on role names. Administrators sign in with an authenticator code as a second step.

App Platform Who Built with
User app Browser Every member React
Desktop app Mac and Windows Every member The user app inside a native window (Tauri)
Phone app iOS and Android Every member React Native (Expo)
App Admin Browser The organisation’s administrators React
App Manager Browser The AntFabric team React; sits above all instances

All of them share one shell library (@antfabric/app-shell) on the web and desktop, and one design system, AntFabric UI.

How a plugin gets from a folder to a screen in the shell:

  1. Pick. The organisation’s instance file lists its plugins and its branding (app name and primary colour) and default navigation layout.
  2. Check. Codegen reads every plugin’s manifest (plugin.yaml) and checks the combination: required plugins present, compatible versions.
  3. Generate. It writes registries: for each selected plugin, its menu entries (label, icon) and its screens, per app.
  4. Build and deploy. Each app compiles only the selected plugins.
  5. Run. The shell reads the registry and draws one menu entry per plugin, in the organisation’s layout, and mounts the plugin’s screens under /<plugin>/….

A plugin declares what it offers; the shell decides how it looks. A plugin never draws its own top-level navigation. Try it in the simulator.

5. What the shell owns, what a plugin owns

Section titled “5. What the shell owns, what a plugin owns”
The shell owns A plugin owns
The navigation (rail, sidebar or top bar) and its entries Its menu entries’ label, icon and badge count
Home Everything inside its content area
The notification bell and inbox panel The notifications it sends (text, and which screen a tap opens)
The profile (photo, presence, details, sign-out) Tabs and sub-navigation inside its own area (e.g. Sales: Today, Board, Meetings)
Sign-in, activation, recovery, session restore and expiry Its own empty, loading and error states
“Update required”, “No access”, page background, light and dark Its admin screens inside App Admin
Brand colour and app name from the instance —

6. Anatomy of the shell (user app, web and desktop)

Section titled “6. Anatomy of the shell (user app, web and desktop)”
┌──────┬──────────────────────────────────────────────────────────────┐
│ Logo │ │
│ │ │
│ Home │ Plugin area │
│ Chat │ · workspace layout: the whole area (Chat, Sales) │
│ Sales│ · content layout: a standard content frame │
│ … │ │
│ │ │
│ 🔔 3 │ │
│ (Me) │ │
└──────┴──────────────────────────────────────────────────────────────┘
rail layout shown; sidebar and top bar hold the same pieces
Piece Today
Logo / app name The instance’s app name and a mark built from its first letter, in the brand colour
Home “Good afternoon, Ada.” and a card per plugin. With no plugins: “Nothing here yet”
Plugin entries One per plugin: icon, label, badge count (e.g. Sales’ due follow-ups, Chat’s unread)
Bell Unread count; opens the inbox panel beside the navigation
Profile Avatar with presence dot; opens details and Sign out
Plugin area workspace layout: the plugin gets the whole area. Otherwise a standard content frame

Inbox panel: list of notifications (text, time, read state), Mark all read, Delete per item, Show older, a link to Notification settings, and an empty state. A tap opens the screen the notification points to, in whichever app the person is using.

Notification settings: per notification type, which channels a person wants (inbox, push, email, desktop), grouped by plugin.

An organisation chooses the user app’s layout. The default comes from the instance file; an administrator can change it in App Admin → Appearance (with a preview of each), and the user app and desktop app switch without a rebuild. App Admin itself always uses the rail.

Layout Looks like Best for
Rail Narrow column of icons with short labels; badges on icons Few plugins; maximum room for Chat or Sales
Sidebar Wide column with labels; core screens, then plugins under “Apps”; counts as pills. Below 900 px wide it becomes the rail Many plugins; grouping
Top bar Horizontal menu; app name left, bell and profile right; entries that don’t fit go into More (re-measured on resize) Organisations used to web portals

All three show the same entries, badges, home, bell and profile, in consistent places.

Coming next (step 4): plugins may give entries a group (sidebar sections, top-bar dropdowns) and an order; administrators may later reorder or hide entries; development builds get a layout switcher.

Desktop follows the same setting. Phone keeps its own pattern: bottom tabs Home, Inbox and Settings; plugins appear on Home and open full screen under /p/<plugin>.

User app: Home, then the instance’s plugins (Example locally; Chat and Sales when an instance adds them).

App Admin (in this order): Overview, Users, Roles, Sign-in, Appearance, Notifications, Plugins, Storage, Workflows, Audit, then each plugin’s admin pages (e.g. Sales settings and team). Each screen needs a permission; an administrator sees only what they may use.

App Manager: companies and their instances (create, start, disable, remove after a grace period, emergency access). Always uses the rail.

Phone: Home (plugin list), Inbox, Settings (including notification settings), sign-in, sign-up, onboarding, and each plugin’s screens.

State Shown when
Sign in “Sign in to {app name}”: email and password, a button per SSO provider the organisation set up, “Administrator? Use your password” when local sign-in is off for others, then an authenticator code step for administrators
Activate your account From an invitation link: set a password; administrators also scan a QR code for their authenticator app. Variants: “Checking your link”, “This link is invalid or has expired”
Restoring your session On start-up while the saved session is checked
Signed out everywhere Signing out in one tab, or the session ending, signs out every tab
No access “You don’t have access” with Sign out (e.g. a member opening App Admin)
Update required The organisation’s plugins need a newer desktop or phone app
Recovery access “Starting recovery access”: a temporary administrator session issued by the App Manager
Errors Inline banners that explain what went wrong and how to fix it
Loading Skeletons, not spinners, where content is coming
Reconnecting Live updates drop and resume; screens reload what changed (no full-page message today)

9. Screens to build: user app and App Admin

Section titled “9. Screens to build: user app and App Admin”

The open-source framework ships two apps on top of core: the user app (browser, and the desktop app around it) and App Admin. The App Manager and the phone app are out of this scope. Status: built exists today and needs a design pass; partial exists but is incomplete; new has to be designed and built.

Screen Purpose and contents States Status
Sign in “Sign in to {app name}”: email, password, one button per SSO provider; “Administrator? Use your password” when password sign-in is off for members Wrong details (one message for every failure), locked out, provider error Built
Authenticator code Second step for administrators: 6-digit code Wrong or expired code Built
SSO return Back from the provider, then on to the app Provider refused, account not linked Built
Activate your account From an invitation: set a password (twice); administrators scan a QR code and enter a code Checking the link, invalid or expired link, weak password Built
Restoring your session On start, while the saved session is checked — Built
No access Signed in, but this app isn’t for you; Sign out — Built
Recovery access Temporary administrator session started by the operator Starting, failed Built
Forgot password Request a reset link, then set a new password Sent, invalid link New
Change password Current and new password, from the profile Wrong current password New
Set up authenticator again After an administrator resets it — New
Screen or part Purpose and contents Status
Navigation User app: rail, sidebar (rail below 900 px) or top bar with “More”, as the organisation chooses. App Admin: always the rail. Core entries, then plugin entries with badges Built
Grouped navigation Entries in groups and an order (sidebar sections, top-bar dropdowns) New (step 4)
Profile panel Photo, name, email, presence; Sign out Partial: no editing, password or sessions
Edit profile Name, photo, status New
My sessions Signed-in devices; sign out one or all New (the server side exists)
Connection state Live updates lost and back New (silent today)
Page states Loading, empty, error and not found, for core pages and around every plugin page Partial
Screen Purpose and contents Status
Home Greeting, a card per plugin; “Nothing here yet” with no plugins Built
Plugin area The frame around each plugin’s screens: workspace (whole area) or content frame Built
Inbox panel Notifications: open, mark read, delete, mark all read, show older, empty state Built
Notification settings Per notification type and channel (in-app, push, email, desktop); browser and desktop permission Built
Update required The desktop app is too old for the organisation’s plugins Built
Search One search across plugins New (to decide)
Language Choose a language New (planned)
Theme Light, dark or system New (follows the OS today)
Screen Purpose and contents Status
Overview The instance, its plugins and versions Built
Users: people Search, filter by status, page through; deactivate, reactivate, sign out everywhere, change role Built
Users: invitations Invite people (name, email, role); pending invitations; send a new link Built
Roles Create, rename, delete roles; grant permissions; assign people; guardrails (system roles, last superadmin) Built
Sign-in SSO providers (issuer URL, client id, button name, allowed email domains, create accounts for new people); allow or block password sign-in Built
Appearance The user app’s navigation layout with a preview of each, and the order plugins appear in; reset either to the default Built
Notifications Providers (email, push), sender, templates per type with reset, instance defaults, delivery log Built
Plugins Installed plugins and versions; settings and secrets per plugin; reset to the plugin’s default Built
Plugin admin pages Each plugin’s own admin screens inside App Admin (e.g. Sales settings and team) Built
Storage Usage per plugin, quota per plugin, largest upload Built
Workflows Background work and its status (view only) Built
Audit Filter by action, person and date; entry details; retention Built
Branding App name, brand colour, logo (today only in the instance file) New
Navigation order Reorder and hide menu entries for the organisation New (planned)
Reset someone’s authenticator From the person’s row in Users New
  1. Unknown plugins. Any number (1 to 20+), any label length, any icon from the Lucide set (hash, briefcase, …), any badge count (show 99+, 9+ on the bell).
  2. Three layouts, one set of entries. A design that works only in the rail is not done. Plugins never know which layout is used or how wide their area is.
  3. No plugin-level top navigation. Plugins’ own tabs live inside their area.
  4. Workspace plugins (Chat, Sales) need the whole area: dense, with their own side panels (Chat’s channel list and thread panel; Sales’ board, lead page, agenda).
  5. Brand per organisation. Only the app name and primary colour change per instance today; the design must work with any reasonable primary colour, in light and dark.
  6. Light and dark follow the operating system. There is no in-app theme switch today.
  7. Platform feel. AntFabric UI adapts by platform: controls are 36 px on the web and 34 px on the desktop app; macOS 26 gets Liquid Glass, Windows gets square corners; shortcuts show the right glyphs per OS.
  8. Phone is its own pattern (bottom tabs, full-screen plugins), not a shrunk desktop.
  9. Permissions shape what appears. App Admin entries depend on permissions; plugins hide actions a person may not take.
  10. Accessible. Keyboard navigation, visible focus, screen-reader names (badges say “3 unread”), polite status messages.
  11. Coming soon, design for it now: translations (each plugin its own strings, RTL-ready), entry groups and order, administrator reordering, plugin slots (a plugin adding a component to another’s screen), lazy-loaded plugin screens with their own loading and error state.

Every screen, core or plugin, gets its components from one import, @antfabric/ui-kit, which is AntFabric UI: @antfabric-ui/core (tokens, stylesheet, brand helpers, the Figtree font), @antfabric-ui/react (web and desktop) and @antfabric-ui/react-native (phone).

  • Repository: git.geekyants.com/antfabric/antfabric-ui. Its catalogue (every component, its states, tokens) is at antfabric-ui.blr-alpha.workspaces.build (ask the library owner for the login).
  • Body font: Figtree. Headline font Satoshi is not shipped yet (licence question); headlines fall back to Figtree.
  • What core draws itself: the shell’s navigation (rail, sidebar, top bar) is built from the library’s basic pieces (icon, icon button, badge, avatar, menu). The library’s own NavRail and WebTopBar belong to its chat product (fixed destinations, its own logo, search, “Report a bug”), so they can’t take plugins’ entries. A generic shell spec that the library can provide is one of the most useful outcomes of this design work.
  • The mark and app name: what an organisation can supply (logo, colours), and how it sits in each layout.
  • Groups and order: how grouped entries look in the sidebar and top bar; what “Apps” means.
  • Search: is there a shell-level search across plugins?
  • The bell and inbox: panel, page or both; how actions inside a notification look.
  • Profile: what it holds beyond details and sign-out (sessions, notification settings, theme).
  • Home: a launcher of cards today; what an organisation would want there.
  • Desktop title bar and window controls per OS; how the shell meets the native window.
  • Phone home: list, grid or something else as plugins grow.
  • Empty, loading, offline and error patterns the shell provides for every plugin.
Term Means
Core The platform part every product needs (sign-in, people, files, notifications…)
Plugin A product feature in one folder, with screens for each app it supports
Instance One organisation’s AntFabric: its data, users, branding and plugins
Shell The frame around every screen: navigation, home, bell, profile, sign-in, states
Surface A plugin’s screens for one app (web, desktop, phone, admin)
Workspace layout A plugin screen that takes the whole area next to the navigation
Badge A count on a menu entry, supplied by the plugin
Deep link Opening a screen by its route id, from anywhere (another plugin, a notification)
App Admin The organisation’s administration app
App Manager The AntFabric team’s tool for running many instances
What Path
Shell libs/app-shell/src (app-frame.tsx, layouts/, inbox-panel.tsx, login-screen.tsx, activate-screen.tsx, update-gate.tsx, shell-root.tsx)
User app, App Admin apps/web, apps/admin
Phone shell apps/mobile/app (tabs, sign-in) and apps/mobile/components/shell
UI kit libs/ui-kit (AntFabric UI from vendor/antfabric-ui, plus core’s extras)
Plugins’ screens plugins/<name>/web, admin, mobile
Instance branding and layout instances/<id>.yaml (branding, appearance.navigation)

Related pages: Navigation layouts, UI kit, Clients, Screens, App Admin, Phone app.