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.
1. AntFabric in one paragraph
Section titled “1. AntFabric in one paragraph”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.
2. Who uses it
Section titled “2. Who uses it”| 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.
3. The apps
Section titled “3. The apps”| 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.
4. The framework flow
Section titled “4. The framework flow”How a plugin gets from a folder to a screen in the shell:
- Pick. The organisation’s instance file lists its plugins and its branding (app name and primary colour) and default navigation layout.
- Check. Codegen reads every plugin’s manifest (
plugin.yaml) and checks the combination: required plugins present, compatible versions. - Generate. It writes registries: for each selected plugin, its menu entries (label, icon) and its screens, per app.
- Build and deploy. Each app compiles only the selected plugins.
- 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.
7. Navigation layouts
Section titled “7. Navigation layouts”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>.
8. Every app’s own screens
Section titled “8. Every app’s own screens”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.
States the shell shows
Section titled “States the shell shows”| 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.
Shared: getting in (both apps)
Section titled “Shared: getting in (both apps)”| 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 |
Shared: the frame (both apps)
Section titled “Shared: the frame (both apps)”| 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 |
User app
Section titled “User app”| 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) |
App Admin
Section titled “App Admin”| 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 |
10. Constraints a shell design must hold
Section titled “10. Constraints a shell design must hold”- Unknown plugins. Any number (1 to 20+), any label length, any icon from the Lucide set
(
hash,briefcase, …), any badge count (show99+,9+on the bell). - 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.
- No plugin-level top navigation. Plugins’ own tabs live inside their area.
- 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).
- 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.
- Light and dark follow the operating system. There is no in-app theme switch today.
- 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.
- Phone is its own pattern (bottom tabs, full-screen plugins), not a shrunk desktop.
- Permissions shape what appears. App Admin entries depend on permissions; plugins hide actions a person may not take.
- Accessible. Keyboard navigation, visible focus, screen-reader names (badges say “3 unread”), polite status messages.
- 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.
11. The design system: AntFabric UI
Section titled “11. The design system: AntFabric UI”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 atantfabric-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
NavRailandWebTopBarbelong 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.
12. Questions for the shell design
Section titled “12. Questions for the shell design”- 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.
13. Glossary
Section titled “13. Glossary”| 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 |
14. Where it lives in code
Section titled “14. Where it lives in code”| 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.