Themes – the colours of the application¶
A theme recolours nexxcite: the window, the app bars, buttons, inputs, states and the Admin Studio. Themes are assigned to roles, so different groups of users can work with different colours. This chapter describes how themes, the light and dark colour scheme, custom colour tokens and custom style sheets work together.
It is intended for administrators who adapt nexxcite to a corporate design.
1. Themes at a glance¶
nexxcite draws every colour of its frame from a set of colour tokens – named colours such as "Primary", "Surface" or "Danger". Every token has a built-in value for the light and one for the dark colour scheme.
A theme holds nothing but overrides of these tokens. A colour the theme does not override keeps its built-in value. A theme that only replaces the brand colour is therefore a theme with a single entry.
| Part | What it is | Where it is set |
|---|---|---|
| Built-in colour tokens | 50 colours of the frame, each with a light and a dark value | fixed |
| Custom colour tokens | Additional colours of your installation, offered in every colour picker | Admin Studio → System → Settings, section "Custom color tokens" (see Global settings) |
| Theme | Overrides of built-in and custom tokens, separately for light and dark, plus the default row height of grids | Admin Studio → Design → Themes |
| Role | Which theme its users get | Role editor, tab "Custom Styling", "Theme" |
| Colour scheme | Light, dark or following the operating system | Every user in the user menu |
| Custom styles | Your own CSS for the whole application, forms, dashboards, query results or per role | Global settings and role editor (section 7) |
Themes are managed with the permissions "Open Theme Manager", "Add Theme", "Edit Theme" and "Delete Theme" (granted by "System Administrator").
2. Light and dark¶
Every user chooses the colour scheme in the user menu (their name or picture at the top right) under "Appearance":
| Choice | Effect |
|---|---|
| "Light" | Always the light colours |
| "Follow the system setting" | Light or dark, as the operating system or browser says |
| "Dark" | Always the dark colours |
The choice is remembered in the browser and in the user's profile, so it also applies on another device after signing in.
A theme sets the light and the dark value of a token independently. A colour that reads well on white rarely reads well on a dark surface. If a theme only sets the light value of a token, the dark scheme keeps the built-in dark colour – and vice versa.
3. Creating a theme¶
- Open Admin Studio → Design → Themes and create a theme.
- Find the colour you want to change. The list is grouped by category and can be searched.
- Pick the light and/or the dark value.
- Save with "Save & Close".
- Select the theme as "Theme" of one or more roles (Admin Studio → Access → Roles, tab "Custom Styling").
The theme editor¶
Every colour is one row with two swatches: light on the left, dark on the right.
- A dashed swatch means: the theme keeps the built-in colour for this scheme. It still shows what that colour looks like.
- Pick a colour to override it; the cross next to a value goes back to the built-in colour.
- The line above the list says how many colours the theme overrides, for example "3 of 50 colors overridden." – or "This theme keeps every built-in color."
- "Reset all colors" removes every override of the theme after a confirmation.
- Colours are entered as hex values (
#1D4ED8,#18F). Colour names,rgb()values or references to other tokens are not accepted in a theme.
The last category, "Grids", holds the one setting of a theme that is not a colour: "Grid density" – the row height of the data grids for users of this theme (Compact, Default, Comfortable). A grid or list block can set its own density; this is the default for all others, including the query result page. Default: Default.
4. The colour tokens¶
| Category | Colours (as named in the editor) | Used for |
|---|---|---|
| Surfaces | "Window Background", "Surface", "Work Area", "Quiet Fill", "Active Fill" | The window, app bars, cards and dialogs, the work area and the left app bar, hover and selection fills |
| Lines | "Line", "Soft Line" | Borders and dividers |
| Text | "Text", "Text (Strong)", "Text (Muted)", "Text (Quiet)" | Main text down to hints and placeholders |
| Brand | "Primary", "Primary (Hover)", "Primary (Soft)", "Primary (Text On)", "Secondary", "Secondary (Soft)", "Accent", "Accent (Soft)" | Primary buttons, links, active markers, accents |
| States | "Success", "Warning", "Danger", "Info", "AI", "Open Sketch" – each with "(Soft)" and "(Text On)" | Confirmations, warnings, errors, information, AI features, the open sketch |
| Overlays | "Search Highlight", "Search Highlight (Text On)", "Background Wash A", "Background Wash B", "Dialog Scrim" | Search hits in text, the decorative background of the window, the darkening behind dialogs |
| Fields | "Input Field", "Focus Ring", "Invalid Value", "Required Value Missing", "Required Value Missing (Soft)" | Inputs |
| Administration | "Admin Studio Frame", "Admin Studio Marker", "Grid Dot" | The Admin Studio, so it can be told apart from the application |
| Custom tokens | The tokens of the global settings | Your own colours (section 5) |
The rows carry a tooltip that explains each colour. Some rules of thumb:
- "Primary" is the brand colour and usually the first one to change. Check "Primary (Text On)" with it: text and icons on primary buttons must stay readable.
- The "(Soft)" variants are light tints for backgrounds, the "(Text On)" variants the text drawn on the full colour.
- "Open Sketch" marks that a sketch is open. Keep it clearly different from the brand colours.
5. Custom colour tokens¶
Custom colour tokens are additional colours of your installation, for example "Brand blue" or "Status: escalated". They are defined once in the global settings with a name, a description and a light and dark value (see Global settings).
- Every colour picker of the application offers them by name – in forms, dashboards, grids and wherever a colour can be chosen – next to the built-in tokens.
- A theme can recolour them, separately for light and dark. In the theme editor they are listed under "Custom tokens". A dashed swatch there means "the value of the global settings".
- A theme cannot add or remove a token. The list belongs to the whole installation, so that a colour chosen in a form resolves for every user, whatever theme their role carries.
How a dark value is found for a custom token: the dark value of the theme; otherwise the dark value of the token; otherwise the light value of the theme; otherwise the light value of the token.
Why pick a token instead of a fixed colour¶
When a user picks a token in a colour picker, nexxcite stores a reference to the token, not the colour. The colour then follows the theme of the user and the colour scheme. A colour picked from the colour wheel or typed as a hex value stays fixed – the same in light and dark, for every role.
Recommendation: for colours with a meaning (a status, the brand), create a custom token and pick it. Use fixed colours only where the colour must never change.
6. Which theme a user sees¶
The roles of the user are taken in the order of their "Priority" (lowest value first). The first role that links a theme decides. A theme always applies as a whole – the colours of two themes are never mixed.
| Situation | Result |
|---|---|
| No role of the user links a theme | The built-in colours (and the defaults of the custom tokens) |
| One role links a theme | That theme |
| Several roles link themes | The theme of the role with the highest priority |
Example: "Clerk" (priority 20) links the theme "Blue", "Partner portal" (priority 5) links the theme "Partner". A user with both roles sees "Partner".
The logo is decided the same way, with "Logo (Light Mode)" and "Logo (Dark Mode)" of the role (see Roles and permissions).
7. Custom styles¶
For what a theme cannot express – a font, a spacing, the look of a single block – you can add your own CSS:
| Where | Setting | Applies to |
|---|---|---|
| Global settings | "Global Styles" | The whole application |
| Global settings | "Form Styles", "Dashboard Styles", "Search Result Styles" | Forms, dashboards, query result pages |
| Role editor, tab "Custom Styling" | "Custom Styles" | Users with this role |
| Dashboard | "Stylesheet" in the dashboard properties | This dashboard |
| Form | "Stylesheet" in the form properties | This form |
Each of these settings is an expression whose result is the style sheet.
Order: the colours of the theme come first, the custom styles afterwards. A custom style therefore wins over the theme where both set the same thing. The custom styles of several roles are all added; those of the role with the highest priority come last.
Use the tokens in your CSS so that your styles follow the theme and the colour scheme. The tokens
are CSS variables that hold the three colour channels, so they are written with rgb():
.my-highlight {
background: rgb(var(--nx-primary-soft));
color: rgb(var(--nx-primary));
border: 1px solid rgb(var(--nx-line) / 0.5);
}
The variable of a built-in token is --nx- followed by its technical name, for example
--nx-primary, --nx-surface-1 or --nx-danger-soft. The variable of a custom token is shown on its
card in the global settings.
8. When changes take effect¶
| Change | Takes effect |
|---|---|
| Theme saved | Users with this theme get the new colours with their next page load at the latest |
| Theme of a role changed | When the user reloads the page or signs in again |
| Custom colour token changed in the global settings | With the next page load at the latest |
| Colour scheme switched by the user | Immediately |
While a sketch is open, a changed theme is collected in the sketch and takes effect when the sketch is published (see Sketches and publishing).
9. Limitations¶
- A theme changes colours and the default grid density. Fonts, spacing and shapes need custom styles.
- Colours in a theme must be hex values. Other notations are ignored as if the value were empty.
- Charts on dashboards follow the light or dark scheme, but not the colours of a theme.
- Parts of the user interface that are drawn by third-party components may follow the theme only in part.
10. Frequently asked questions¶
Can a user choose a theme? No. The theme comes from the roles of the user. The user only chooses light, dark or the system setting.
I changed "Primary", but some buttons keep their colour. Check whether a custom style of the global settings or of a role sets that colour by hand; custom styles win over the theme. Also check that the button uses the style "Primary" and not a fixed colour.
Can a theme override only the dark colours? Yes. Leave the light values empty; the light scheme keeps the built-in colours.
What happens to colours that use a custom token when the token is removed? Everything that uses the token falls back to no colour. The global settings ask for confirmation before a token is removed.