Navigation layouts
An organisation chooses how its apps’ navigation looks: an icon rail, a sidebar with labels and groups, or a top bar. The choice belongs to the shell, never to plugins. Plugins describe what they offer — menu entries, screens, badges — and work unchanged in every layout.
Who decides
Section titled “Who decides”| Level | Where | When it applies |
|---|---|---|
| Default | Instance file: appearance.navigation |
From the first start, until an administrator changes it |
| The organisation’s choice | App Admin → Appearance, stored in instance_settings (appearance.navigation) |
From then on; overrides the instance file |
The same pattern as the instance file’s plugin configuration: the file sets the starting point, and
after that the organisation’s administrators own it. Every layout ships in every build, so changing
it needs no rebuild.
# instances/<id>.yamlappearance: navigation: sidebar # rail (default) | sidebar | topHow the apps pick it
Section titled “How the apps pick it”- Codegen writes the instance file’s value into
instance.generated.ts, so the first paint uses the default without waiting for the server. - On start-up the apps read the organisation’s choice from a public core endpoint (it is needed before sign-in), keep it for the next start, and switch if it differs.
- The shell renders the chosen layout around the routes:
const Navigation = NAVIGATION_LAYOUTS[appearance.navigation] ?? NAVIGATION_LAYOUTS.rail;<Navigation entries={entries} /> // the same entries for every layout<main>{routes}</main>Layouts
Section titled “Layouts”| Layout | Shows | Best for |
|---|---|---|
rail |
Icons with short labels in a narrow column; badges on icons | Few plugins; maximum room for workspace plugins (Chat, Sales) |
sidebar |
Wide column with labels; core screens, then plugins under “Apps”; counts as pills; the rail on windows narrower than 900 px | Many plugins; organisations that want grouping |
top |
Horizontal menu; the app’s name left, bell and profile right; entries that do not fit the window go into “More” (re-measured on resize); groups become dropdowns in step 4 | Organisations used to web portals |
All three show core’s own entries (home, notifications, profile) in the same places, and the same badges.
What plugins provide
Section titled “What plugins provide”Menu entries gain two optional fields, so existing plugins keep working:
surfaces: web: nav: - { id: sales.home, label: Sales, icon: briefcase, path: '', group: Work, order: 20, }| Field | Used by | Default |
|---|---|---|
group |
Sidebar sections, top-bar dropdowns | No group (top level) |
order |
Position within the group | The plugin order (below) |
Plugin order
Section titled “Plugin order”Every app lists plugins in one order: Home and the menu in the user app (web and desktop), the plugin pages in App Admin’s menu, and Home on the phone.
| Level | Where | When it applies |
|---|---|---|
| Default | The order of plugins: in the instance file |
From the first start, until an administrator changes it |
| The organisation’s choice | App Admin → Appearance → Plugin order, stored in instance_settings (appearance.pluginOrder) |
From then on; “Use the default” goes back to the file |
Dependencies do not change it: the server still loads a plugin after the plugins it depends on, but
what people see follows this order. A plugin installed after the order was saved goes last; one
removed drops out. The apps read the order with the layout (GET /api/v1/appearance, field
pluginOrder), so changing it needs no rebuild; the web apps redraw at once, the phone on its next
start.
Administrators may later hide entries in App Admin; the shell applies that over what plugins declare.
Rules for plugin screens
Section titled “Rules for plugin screens”- Never assume where the menu is or how wide the content area is. Use UI kit components that
adapt.
layout: 'workspace'means “the whole content area”, whatever its size. - No top-level navigation of your own. Tabs inside your plugin (Pipeline, Today, Meetings) belong to its content and are fine.
- Check every layout. Switch it in App Admin → Appearance (a development switcher is step 4).
Desktop and phone
Section titled “Desktop and phone”- Desktop wraps the user app and follows the same setting.
- Phone keeps its own pattern — home screen and bottom tabs — because a sidebar or top bar does
not suit a phone.
groupandorderorder its entries too.
Where it lives
Section titled “Where it lives”| Piece | Path |
|---|---|
| Instance file field and validation | libs/plugin-manifest (instanceSchema.appearance), written into INSTANCE.appearance by codegen |
| Shared type | @antfabric/contracts-core (NAVIGATION_LAYOUTS, Appearance) |
| Server | apps/backend/src/appearance/ (service, public and admin controllers), migration 0016_appearance.sql |
| Client | useNavigationLayout(default) and useOrderedPlugins(plugins, INSTANCE.plugins ids) in @antfabric/sdk-web (one request for both); NavigationLayoutView and layouts/ in @antfabric/app-shell: column.tsx (rail and sidebar), top.tsx (top bar) |
| Apps | apps/web (and the desktop app around it) passes INSTANCE.appearance.navigation; App Admin and the App Manager are fixed to the rail (navigation="rail") |
Server side
Section titled “Server side”| Piece | Is |
|---|---|
instance_settings key appearance.navigation |
The organisation’s choice; absent means the instance file’s default |
instance_settings key appearance.pluginOrder |
The organisation’s plugin order; absent means the instance file’s order |
| Public read endpoint | Returns the effective appearance (choice, else default); no sign-in |
| Admin endpoints | PUT /admin/appearance (layout), PUT /admin/appearance/plugin-order (every installed plugin once, or null); permission appearance:configure (role admin); audited |
| App Admin → Appearance | A preview of each layout and a save button; the plugin order with move up and down |
| Step | What | Visible change | State |
|---|---|---|---|
| 1 | Move today’s rail into libs/app-shell/src/layouts/rail.tsx; add appearance to the instance file schema and codegen; the setting, endpoints and permission |
None | Done |
| 2 | Sidebar layout; App Admin → Appearance | Organisations can switch to the sidebar | Done |
| 3 | Top bar layout with overflow | Third option | Done |
| 4 | Optional group and order on menu entries; development layout switcher; docs and review checklist |
Grouped sidebars and dropdowns | Next |