Customize with SCSS

The Orbix design system (packages/foundry-ui) ships with its SCSS sources. Every npm run build compiles the Tailwind CSS engine from those sources with the settings of one small file, src/scss/brand.scss. With the file as shipped (every line commented out) the result is exactly the default Orbix design.

Use it to set your brand color, radius and fonts once for the whole application, to give any design token a fixed value, or to leave out components you do not use.

The brand file

// src/scss/brand.scss
$theme: (
  brand: #0f766e,     // brand color: the whole palette is derived from it
  radius: lg,         // none | sm | md | lg | full
  font: humanist,     // foundry | system | humanist | geometric | serif
);

$tokens: (
  font-sans: ("Poppins", system-ui, sans-serif),
  radius-control: 8px,
);

$components: (
  calendar: false,
  datagrid: false,
);

Map	What it does
`$theme`	Default appearance, with the keys of the theme customizer: `brand` (a `#rrggbb` color), `preset`, `neutral`, `mode`, `radius`, `density`, `elevation`, `layout`, `motion`, `font` (values in Theming). The theme runtime builds the full palette from `brand` (hover and active states, subtle tints, readable text colors, dark mode and chart colors, with AA contrast). Your visitors can still choose another preset or mode in the customizer.
`$tokens`	A fixed value for any `--fd-*` token, written without the `--fd-` prefix: fonts (`font-sans`, `font-mono`), radii (`radius-control`, `radius-surface`, `radius-overlay`), spacing (`space-4`) and more. Fixed values win over the radius, density and font presets of the customizer. For colors use `$theme` (`brand`, `neutral`), so that light and dark mode stay consistent.
`$components`	Components to leave out of the CSS, by file name in `packages/foundry-ui/scss/components` (for example `calendar`, `datagrid`, `wizard`). Only remove components that none of your pages use. An unknown name stops the build with a clear message.

Settings in $theme take precedence over the defaults in src/main.ts (initTheme({ product: … })); the choices a visitor makes in the customizer take precedence over both.

Rebuild

Command	What it does
`npm run build`	Compiles the design system from SCSS into `src/styles/foundry/foundry.tailwind.css`, then builds the app into `dist/tailwind` (`ng build`)
`npm run build:css`	Compiles the design system only (useful while you try settings with `npm start` running: the Angular dev server picks up the new styles and reloads)
`npm start`	Compiles the design system once, then starts the Angular dev server (`ng serve`)
`npm test`	Compiles the design system once, then runs the unit tests (`ng test`)

src/styles/foundry/ is generated: do not edit it, it is replaced on every build. src/styles/engines/tailwind.css imports it, and the tailwind configuration of angular.json loads that entry as its first global stylesheet. A visitor who already chose a theme keeps it; clear the site data of your browser (or use a private window) to see your new defaults.

Structure of the SCSS sources

packages/foundry-ui/
├── scss/
│   ├── foundry.scss           the core: tokens, base styles, components and layouts
│   ├── _config.scss           the settings read from your brand file ($theme, $tokens, $components)
│   ├── _overrides.scss        the CSS written from those settings (loaded last)
│   ├── _base.scss             base layer: fonts, reset, typography
│   ├── _components.scss       component layer: the load order of every component and layout
│   ├── abstracts/             functions, mixins and maps (token(), space(), rem(), focus-ring, up() …), no CSS
│   ├── tokens/                token values: _orbix.scss (Sass variables), _orbix-properties.scss (--fd-* properties)
│   ├── base/                  @font-face, reset, typography, small utilities, keyframes
│   ├── components/            one partial per fd-* component (_button.scss, _card.scss, _modal.scss …)
│   └── layouts/               app shell, sidebar, topbar, navigation, page header, auth pages, grid
├── engines/
│   ├── bootstrap/scss/        Bootstrap 5.3 engine: foundry.scss, Bootstrap settings from the tokens, bridge, utilities
│   └── tailwind/css/          Tailwind CSS v4 engine: foundry.css (@theme from the tokens, layers, utilities)
├── tokens/                    the design token sources (base.json, skins/orbix.json), for reference
├── cli/                       the build command used by scripts/build.mjs (foundry-ui css …)
└── dist/                      precompiled stylesheet, scripts, fonts and token files

Every component reads design tokens at runtime (var(--fd-…)), and every partial uses logical properties (margin-inline-start, never margin-left), so light and dark mode and right-to-left languages keep working with your changes.

Your own SCSS

You can write your own components on the same API. Add a stylesheet to src/styles/ as plain CSS (imported from src/styles/index.css), or write SCSS with the functions and mixins of the design system. The Angular CLI compiles any .scss file listed in the styles of the tailwind configuration in angular.json (Orbix keeps styles global: no styles or styleUrl in the component metadata, and the test suite checks it):

// src/styles/reports.scss  (add "src/styles/reports.scss" to "styles" of the tailwind configuration in angular.json)
@use "../../packages/foundry-ui/scss/abstracts" as fd;

.reports-summary {
  padding: fd.space(4);
  border-radius: fd.token(radius-surface);
  @include fd.focus-visible;
  @include fd.up(lg) { padding: fd.space(6); }
}

You can also edit the partials in packages/foundry-ui/scss directly. Keep a note of those changes: an Orbix update replaces packages/foundry-ui, while src/scss/brand.scss stays yours.

Switch the engine

This item is built on Tailwind CSS v4. The SCSS sources of both engines are included, so you can compile the design system on Bootstrap 5 instead. The pages use the same fd-* markup with either engine. Support for this item covers the Tailwind CSS engine.

Install the Bootstrap SCSS sources: npm install --save-dev bootstrap (you can remove the Tailwind CSS compiler with npm uninstall tailwindcss @tailwindcss/cli).
Rename src/styles/engines/tailwind.css to src/styles/engines/bootstrap.css and change its first line to @import "../foundry/foundry.bootstrap.css";.
In angular.json rename the tailwind configuration of build to bootstrap and change its paths: "index": { "input": "src/generated/index.bootstrap.html", … }, "styles": ["src/styles/engines/bootstrap.css", "src/styles/index.css"] and "outputPath": { "base": "dist/bootstrap", … }. Then change "defaultConfiguration" of build to "production,bootstrap", the serve configuration to "bootstrap": { "buildTarget": "orbix:build:development,bootstrap" } (and its "defaultConfiguration" to "bootstrap"), and the buildTarget of test to "orbix:build:development,bootstrap".
In package.json change the build script to node scripts/assets.mjs && node scripts/build.mjs bootstrap.
Run npm run build: the app is written to dist/bootstrap (npm run preview -- bootstrap serves it).

The test suite (npm test after npm run build) checks that the build of the engine in src/styles/engines is complete.