Navigation, profiles, and themes

Navigation, profiles, and themes connect screens to a specific portal experience. They remain separate resources so one definition can compose different experiences from the same screens. Store navigation resources under portal/navigations/. A navigation contains ordered entries for a supported web or mobile context. Entries that target authored screens use screen file slugs.

Portal navigation is separate from the other two kinds of navigation in Fluid. A storefront’s website navigation menus are the site’s navigation bars and footers. The Fluid mobile app has its own mobile app navigation. In the API reference, portal navigation is under Portal navigation, and each navigation’s platform is web, for browsers, or mobile.

Use the current screen picker or a pulled definition for system-screen targets. Do not invent or maintain a separate list of system slugs. Each file has a name, a platform of web or mobile, and a navigation_items array. Copy a sibling item from a pulled file and change its values. An item that opens one of your screens looks like this:

{
  "label": "Rewards",
  "slug": "rewards",
  "screen": "rewards",
  "icon": "globe",
  "source": "user",
  "position": 4,
  "parent_id": null,
  "children": []
}

screen is the slug of the screen file, portal/screens/rewards.json. slug is the route, so this item opens /rewards.
Don’t write screen_id. That’s the server’s format. Pull turns it into screen, and push turns screen back into the server’s ID. The schema rejects a hand-written screen_id.
Leave out id on a new item. Fluid assigns it when you push. Keep the id on items you pulled.
Put items in children to make a group that opens and closes.
A profile shows only the navigations it points to. Add the item to the navigation of every profile that should see the page, and to the profile’s mobile_navigation too if it should appear on phones.

System screens with extra rules

Most system screens appear wherever a navigation item points to them. A few follow extra rules:

Screens	Rule
`messages`, `contacts`	Opt-in. They render only when the viewer’s navigation, web or mobile, has an item with their slug. Without one, the route shows Page not found.
`messages`, `my-site`	Rep-only. They render only for members whose member type has Can act as rep turned on in the admin’s member type settings. Fluid hides the navigation item from everyone else, and the route shows Page not found. This is by design.
`profile`, `orders`, `subscriptions`	Core. The Portal Builder won’t remove their navigation items.

A custom page in your portal’s code can replace a system screen at its slug. A custom page for a member type can’t get past the rep-only rule. See Custom pages and route order.

Profile resources

Store profile resources under portal/profiles/. A profile connects matching or permission rules to navigation and theme selections. A profile file names its web navigation and its mobile_navigation by slug, lists its themes, and says whether it’s the default. Its permissions object needs all four arrays, even when they’re empty:

{
  "name": "Japan reps",
  "default": false,
  "navigation": "japan-web",
  "mobile_navigation": "japan-mobile",
  "themes": ["company-theme"],
  "permissions": {
    "countries": [109],
    "ranks": [],
    "roles": ["rep"],
    "platform": []
  }
}

countries holds country IDs and ranks holds rank IDs.
roles holds member type slugs, such as rep or customer, plus admin for company admins.
platform is part of the file format, but the Portal Builder doesn’t set it. Leave it empty.

Use the company’s real member type slugs, rank IDs and country IDs. A value that doesn’t exist matches nobody.

How the portal picks a profile

The deployed portal asks Fluid for the live version of your active portal. Fluid picks one profile for the signed-in viewer:

It checks each profile’s ranks, member types and countries against the viewer: their rank, their member type (or admin for a company admin) and their country. Without a country on the viewer, it uses the company’s default country.
An empty list matches everyone. A list that doesn’t include the viewer’s value rules the profile out.
Of the profiles left, the most specific one wins. A list with one value beats a list with several, and both beat an empty list.
If no profile matches, the viewer gets the default profile.
If no profile matches and none is the default, the viewer gets no screens and Fluid’s built-in sidebar.

The viewer receives only the screens that their profile’s navigations point to.

A viewer who matches no profile falls back to the default profile without any error. If your changes seem to have vanished, check that the profile you edited matches the person who’s looking. Leave member types empty while you build, and add rules once the experience works.

Which profile local preview shows

fluid portal dev doesn’t check permissions. It always shows the profile marked as default. If no profile is the default, it shows the first profile file. Edits to any other profile never show locally, whoever is signed in. The signed-in member still counts for rep-only screens. Verify profile rules on the deployed portal.

Theme resources

Store theme resources under portal/themes/. A theme file contains the complete structured theme configuration. A partial theme is invalid. When you need the current full shape, pull an existing theme and edit the required values. Use the theme schema for color modes, semantic tokens, typography, spacing, borders, radii, focus, and chart configuration. A theme file has a name, an active flag and a config. Never create a theme with only a name. Copy a pulled theme and change its id, name and tokens. The config needs all of these:

Key	What it holds
`id`, `name`	The theme’s identity.
`light`	All seven color roles: `background`, `foreground`, `primary`, `secondary`, `accent`, `muted` and `destructive`. Each role has a `base` and a `foreground` color, each as OKLCH `l`, `c` and `h` numbers.
`dark`	Only the roles you want to change in dark mode. It can be `{}`, and the other roles come from `light`.
`fontSizes`	`extraSmall`, `small`, `regular`, `large`, `extraLarge` and `giant`.
`fontFamilies`	`header` and `body`.
`spacing`	One base spacing value, such as `"0.25rem"`.
`radii`	`small`, `medium`, `large` and `extraLarge`.

"primary": {
  "base": { "l": 0.55, "c": 0.18, "h": 255 },
  "foreground": { "l": 0.98, "c": 0.01, "h": 255 }
}

The schema doesn’t allow extra keys. Edit the existing tokens instead of adding new ones.

Check cross-resource links

Before push:

Confirm each navigation target matches a screen slug.
Confirm each profile points to existing navigation and theme slugs.
Confirm the intended default profile is explicit.
Validate every theme as a complete resource.
Preview representative routes under the intended profile and theme.

See PortalNavigation, PortalProfile, and PortalTheme for the current resource contracts.

Get started

Sites

Mist apps

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Navigation, profiles, and themes

Navigation resources

Navigation items

System screens with extra rules

Profile resources

How the portal picks a profile

Which profile local preview shows

Theme resources

Check cross-resource links