Styling System

The Members Portal uses Bootstrap 5.3 with SCSS customisation, CSS Modules for component-scoped styles, and CSS custom properties for runtime theming. This page explains how these layers work together and how to make changes at each level.

Architecture overview

┌──────────────────────────────────────────────────────┐
│  Runtime branding tokens (per-location)              │  ← Highest priority
│  <style> written by src/theme/ThemeTokens.tsx        │
├──────────────────────────────────────────────────────┤
│  _user.scss                                          │  ← Project-level overrides
├──────────────────────────────────────────────────────┤
│  _branding.scss — Bootstrap rules on tokens          │
├──────────────────────────────────────────────────────┤
│  Component styles (.module.scss + global SCSS)       │
├──────────────────────────────────────────────────────┤
│  custom/ — Bootstrap component extensions            │
├──────────────────────────────────────────────────────┤
│  _variables.scss — Theme colour palette              │
├──────────────────────────────────────────────────────┤
│  _defaults.scss — Base colour defaults               │
├──────────────────────────────────────────────────────┤
│  Bootstrap 5.3 core                                  │  ← Lowest priority
└──────────────────────────────────────────────────────┘

Styles are compiled into a single CSS bundle at build time by Vite, and that bundle is the same for every location. Per-location colours are CSS custom properties written at runtime (see Runtime branding). The compilation order in style.scss determines which layer can override which.

Folder structure

All SCSS source files live under src/assets/scss/:

src/assets/scss/
├── style.scss              # Main entry – imports everything in order
├── _defaults.scss          # Default colour palette ($primary, $secondary, …)
├── _variables.scss         # Derived theme colours, contrast values, CSS vars
├── _branding.scss          # Bootstrap rules re-declared on the branding tokens
├── _variables-dark.scss    # Dark-mode variable overrides
├── _dark-mode.scss         # Dark-theme component rules
├── _mobile.scss            # Mobile-only responsive overrides
├── _user.scss              # Project-level custom rules (safe to edit)
├── icon.css                # Icon font definitions
├── custom/                 # Bootstrap component extensions
│   ├── _utilities.scss     # Extra utility classes
│   ├── _buttons.scss
│   ├── _card.scss
│   ├── _navbar.scss
│   ├── forms/
│   │   ├── _form-check.scss
│   │   └── _form-control.scss
│   └── …
└── components/             # Global component styles
    ├── _general.scss
    ├── _avatar.scss
    ├── _navbar-mobile.scss
    ├── _sidebar-admin.scss
    ├── _utilities.scss
    ├── _stepper.scss
    └── vendor/             # Third-party library overrides
        ├── dayPicker.scss
        ├── flatpickr.scss
        └── …

Default colour palette

Default colours are defined in _defaults.scss using the !default flag, which means they can be overridden by any value set before the import:

// _defaults.scss
$primary:   #ff5b13 !default;
$secondary: #0f0d76 !default;
$success:   #008d42 !default;
$danger:    #dc2626 !default;
$warning:   #da7500 !default;

_variables.scss then derives contrast colours, subtle variants, and border colours from these base values and exports them as a $theme-colors map. Bootstrap uses this map to generate CSS custom properties like --bs-primary, --bs-primary-bg-subtle, etc. These defaults are what the bundle is compiled with; each location’s own values replace them in the browser (see Runtime branding), so src/theme/tokens.ts keeps a copy of them and a test fails if the two drift.

How components are styled

Components use one of three patterns (often combined):

CSS Modules (scoped styles)

Component-specific styles live in a .module.scss file next to the component. Class names are locally scoped at build time so they never leak.

// ArkSmallCard.tsx
import styles from './ArkSmallCard.module.scss'

export default function ArkSmallCard({ image }: Props) {
  return <img className={styles.fullImage} src={image} />
}

// ArkSmallCard.module.scss
.fullImage {
  height: calc(100% - 100px);
  object-fit: cover;
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}

Use CSS custom properties inside .module.scss files to reference theme colours: color: var(--bs-primary);

Bootstrap utility classes

Most layout and spacing is handled with Bootstrap 5 utility classes directly in JSX:

<div className="d-flex justify-content-between align-items-center mt-3 px-4">
  <h5 className="text-truncate fs-5 fw-bold text-body">{title}</h5>
</div>

The project extends Bootstrap’s utility API in custom/_utilities.scss with additional helpers such as fixed-pixel heights (h-40px), viewport heights (vh-100), and more.

Global SCSS (unscoped)

Some components import a plain .scss file for global styles. These affect the entire page and are typically used for animation keyframes or third-party library overrides:

import './Typewriter.scss'

Prefer CSS Modules over global imports for new components. Global styles can cause unintended side-effects.

Runtime branding (per-location colours)

Each location sets its brand colours in the Nexudus dashboard (Theme.PrimaryColor, Theme.SecondaryColor, Theme.Success, Theme.Info, Theme.Warning, Theme.Alert, and their dark-mode twins). The stylesheet is compiled once, at build time, and is identical for every location. Everything that depends on the palette is a CSS custom property, and the browser fills the values in:

LocationSettingsProvider fetches /api/sys/businesses/{id}/colors?mode=light|dark for the effective colour mode.
ThemeTokens (src/theme/ThemeTokens.tsx) computes the tokens with src/theme/tokens.ts and writes them into a <style id="nexudus-theme-tokens"> at the end of <head>, where they win over the static bundle. That takes about a millisecond, so theme toggles and editor previews (?Theme.PrimaryColor=...) apply instantly.
index.html carries a theme-fallback block with the default primary colour for the splash screen. ThemeTokens removes it once the real tokens are in.

There is no server-side compilation, no Blob storage and no CSS version constant. Shipping a stylesheet change is just a deploy: the bundle is a hashed, immutable Vite asset.

Where a branded value can live

Layer	File	What it does
Bootstrap variables that are only interpolated	`_variables.scss`	Point straight at a token, e.g. `$component-active-bg: var(--#{$prefix}primary)`. Bootstrap never runs colour maths on these.
Rules Bootstrap derives with colour maths	`_branding.scss`	Re-declares Bootstrap’s button, outline button, table and coloured-link rules on top of `--bs-<colour>-btn-hover-bg` and friends, and defines those tokens with the default palette so the bundle is complete on its own.
Values a custom property cannot express	`src/theme/tokens.ts`, `rules`	SVG data URIs that embed a colour (accordion chevron, validation icons). Emitted as whole rules at runtime, with the same selector as Bootstrap’s rule.

src/theme/tokens.ts is the runtime twin of _branding.scss: it computes the same token names with the same formulas, using the Bootstrap colour functions ported in src/theme/color.ts.

Token names

For a theme colour <c> (primary, secondary, success, info, warning, danger, plus the derived $theme-colors entries such as primary-contrast and primary-bg-subtle):

Token	Meaning
`--bs-<c>`, `--bs-<c>-rgb`	Bootstrap’s base colour and its `r, g, b` triplet
`--bs-<c>-contrast`	`color-contrast(<c>)`: the text colour to put on a `<c>` background
`--bs-<c>-text-emphasis`, `--bs-<c>-bg-subtle`, `--bs-<c>-border-subtle`	Bootstrap’s own, with light and dark values
`--bs-<c>-bg-subtle-contrast`	Text colour on a `<c>` subtle background, light and dark
`--bs-<c>-btn-hover-bg`, `-btn-hover-border-color`, `-btn-hover-color`, `-btn-active-bg`, `-btn-active-border-color`, `-btn-active-color`, `-btn-focus-shadow-rgb`	Bootstrap `button-variant()` maths
`--bs-<c>-link-hover-rgb`	`.link-<c>:hover` colour
`--bs-<c>-table-bg`, `-table-color`, `-table-border-color`, `-table-striped-bg`, `-table-striped-color`, `-table-active-bg`, `-table-active-color`, `-table-hover-bg`, `-table-hover-color`	Bootstrap `table-variant()` maths (theme colours only)
`--bs-primary-shade-10`, `--bs-primary-tint-70`	One-off mixes (accordion active colour, range thumb)

Using a branded colour

Never write $primary (or any tenant colour variable, or a Sass function of one) into a rule. That bakes the default palette into the bundle for every location. Use the token:

// SCSS or .module.scss
.my-badge {
  background-color: var(--bs-primary);
  color: var(--bs-primary-contrast);
  border-color: rgba(var(--bs-primary-rgb), 0.5);
}

// TSX
<div style={{ color: 'var(--bs-success)' }} />

If you need a mix that does not exist yet (say tint-color($primary, 25%)), add a token rather than computing it in Sass.

Adding a new token

Define it for the default palette in _branding.scss

Add the formula to the :root block (and to the color-mode(dark) block if it has a dark-mode value):

--#{$prefix}primary-tint-25: #{tint-color($primary, 25%)};

Compute it at runtime in src/theme/tokens.ts

Add the same formula to buildThemeTokens, under the same name, in light (and dark if applicable):

light[`${PREFIX}primary-tint-25`] = toHex(tint(p.primary, 0.25))

src/theme/color.ts has tint, shade, shift, mix, colorContrast, toHex and toRgbTriplet, all ports of the Sass functions Bootstrap uses.

Use it

var(--bs-primary-tint-25) in any stylesheet or component.

Run the theme tests

npx vitest run src/theme

tokens.test.ts compiles the real SCSS with several palettes and fails if a TypeScript value differs from the Sass one. branding.test.ts fails if anything in the bundle still bakes a tenant colour (it names the selector and property), if a runtime token has no static twin, or if a runtime rule targets a selector the bundle does not contain.

Making a Bootstrap variable follow the tenant colour

If a Bootstrap variable such as $pagination-hover-bg is only interpolated into CSS, set it to a token in _variables.scss: $pagination-hover-bg: var(--#{$prefix}primary);. If Bootstrap runs tint-color, shade-color, mix or color-contrast on it (buttons, tables, coloured links), leave the variable alone and re-declare the generated rule in _branding.scss on tokens, the way .btn-#{$name} is done. The bundle guard tells you which case you are in: it lists the compiled rule that still changes with the palette.

Colours embedded in SVG data URIs

var() does not work inside url(). Bootstrap embeds $success and $danger in the validation icons and the primary emphasis colour in the accordion chevron. Those are emitted as whole rules by buildThemeTokens (the rules array) with the same selector as Bootstrap’s rule. Add to that list if you introduce another one.

Border radius

Each location also picks a corner style with the Theme.BorderRadius setting (editor previews can pass ?Theme.BorderRadius=...). It takes one of three presets; empty or unknown values mean Default:

Preset	`--bs-border-radius`	`-sm`	`-lg`	`-xl`	`-xxl`	Buttons (`--bs-border-radius-btn`, `-btn-sm`, `-btn-lg`)
`sharp`	0	0	0	0	0	0
`default`	0.5rem	0.375rem	1rem	1.5rem	2rem	same as base, sm, lg
`rounded`	1rem	0.75rem	1.5rem	2rem	2rem	50rem (pill)

_variables.scss derives the scale from $border-radius and seeds the custom properties with the Default preset; ThemeTokens emits the location’s preset from src/theme/radius.ts alongside the colours. Component variables ($btn-border-radius, $input-border-radius, $card-border-radius, …) point at the tokens, so Bootstrap components follow the preset on their own. .btn-close and kbd bake $border-radius through a mixin default and are re-declared in _branding.scss. Never write $border-radius, $border-radius-lg & co. into a rule: use var(--bs-border-radius), var(--bs-border-radius-lg), or the rounded-* utilities. tokens.test.ts compiles the SCSS with each preset and checks radius.ts against it, and the bundle guard in branding.test.ts names any rule that still bakes a radius.

Dark mode

Dark mode is controlled via the data-bs-theme attribute on the <html> element. The _dark-mode.scss file redefines CSS custom properties when this attribute is set:

[data-bs-theme='dark'] {
  --bs-body-bg: #222529;
  --bs-body-color: #b0b0b8;
  --bs-border-color: rgba(255, 255, 255, 0.07);
  // … full dark palette
}

Theme switching is managed by the useLayoutContext hook:

const { updateTheme } = useLayoutContext()
updateTheme('dark')  // 'light' | 'dark' | 'auto'

The preference is saved to localStorage and restored on load.

When writing component styles, always use CSS custom properties (var(--bs-body-bg)) instead of hard-coded colour values. This ensures your styles work in both light and dark modes.

Extending Bootstrap utilities

Custom utility classes are registered in custom/_utilities.scss using Bootstrap’s utility API. To add a new utility:

// custom/_utilities.scss
$utilities: map-merge(
  $utilities,
  (
    "my-custom-util": (
      property: opacity,
      class: custom-opacity,
      values: (
        25: .25,
        50: .5,
        75: .75,
      )
    ),
  )
);

This generates classes like .custom-opacity-25, .custom-opacity-50, etc. with responsive variants if you add responsive: true.

Overriding Bootstrap component styles

Bootstrap component customisations live in custom/ as partial SCSS files (e.g., _buttons.scss, _card.scss). These are imported after Bootstrap core, so they can override default styles. To adjust a Bootstrap component:

Find the right partial

Look in src/assets/scss/custom/ for an existing file that matches the component (e.g., _buttons.scss for buttons).

Add your overrides

Write your SCSS rules in that file. You can use Bootstrap variables and mixins:

// custom/_buttons.scss
.btn {
  font-weight: 600;
}

Verify the import

Make sure the file is imported in style.scss. All existing partials are already imported.

Adding styles to a new component

Create a CSS Module file

Add a .module.scss file next to your component:

src/components/MyComponent/
├── MyComponent.tsx
└── MyComponent.module.scss

Write scoped styles

// MyComponent.module.scss
.wrapper {
  padding: 1rem;
  border: 1px solid var(--bs-border-color);
  border-radius: var(--bs-border-radius);
  background: var(--bs-body-bg);
}

Import and use in the component

import styles from './MyComponent.module.scss'

export default function MyComponent() {
  return (
    <div className={styles.wrapper}>
      <p className="text-body fs-6 mb-0">Content</p>
    </div>
  )
}

Combine CSS Modules for component-specific layout with Bootstrap utilities for spacing and typography. This keeps styles scoped while reusing the design system.

The `_user.scss` file

_user.scss is imported last in style.scss and is intended for project-level custom rules that don’t belong to a specific component or Bootstrap override. It currently contains helpers like .sticky-top-20, .no-select, and .disabled-component. Add rules here when you need a global utility that doesn’t fit into Bootstrap’s utility API or a component module.

Key conventions

Practice	Rationale
Use CSS Modules for new components	Prevents style leaking between components
Use `var(--bs-*)` for colours	Ensures light/dark mode and branding compatibility
Never hard-code colour values in components	Runtime branding would not apply
Never use `$primary` & co., or a Sass colour function of them, in a rule	The bundle is shared by every location; use the `var(--bs-*)` tokens from Runtime branding
Never use `$border-radius` & co. in a rule	Same reason: use `var(--bs-border-radius*)` so the location’s radius preset applies
Put Bootstrap overrides in `custom/`	Keeps overrides organized and discoverable
Put vendor/library overrides in `components/vendor/`	Separates third-party concerns from project styles
Use `!default` for new SCSS variables	Allows theme-level overrides

Overview

Editor Interface

Components

Styling

For Developers

Architecture overview

Folder structure

Default colour palette

How components are styled

CSS Modules (scoped styles)

Bootstrap utility classes

Global SCSS (unscoped)

Runtime branding (per-location colours)

Where a branded value can live

Token names

Using a branded colour

Adding a new token

Making a Bootstrap variable follow the tenant colour

Colours embedded in SVG data URIs

Border radius

Dark mode

Extending Bootstrap utilities

Overriding Bootstrap component styles

Adding styles to a new component

The `_user.scss` file

Key conventions

​Architecture overview

​Folder structure

​Default colour palette

​How components are styled

​CSS Modules (scoped styles)

​Bootstrap utility classes

​Global SCSS (unscoped)

​Runtime branding (per-location colours)

​Where a branded value can live

​Token names

​Using a branded colour

​Adding a new token

​Making a Bootstrap variable follow the tenant colour

​Colours embedded in SVG data URIs

​Border radius

​Dark mode

​Extending Bootstrap utilities

​Overriding Bootstrap component styles

​Adding styles to a new component

​The _user.scss file

​Key conventions

Architecture overview

Folder structure

Default colour palette

How components are styled

CSS Modules (scoped styles)

Bootstrap utility classes

Global SCSS (unscoped)

Runtime branding (per-location colours)

Where a branded value can live

Token names

Using a branded colour

Adding a new token

Making a Bootstrap variable follow the tenant colour

Colours embedded in SVG data URIs

Border radius

Dark mode

Extending Bootstrap utilities

Overriding Bootstrap component styles

Adding styles to a new component

The `_user.scss` file

Key conventions