Customize with SCSS

The Orbix design system (packages/foundry-ui) ships with its SCSS sources. Every npm run build compiles the Bootstrap 5 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,
);

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

src/styles/foundry/ is generated: do not edit it, it is replaced on every build. src/styles/engines/bootstrap.css imports it, and the bootstrap 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 bootstrap 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 bootstrap 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 Bootstrap 5.3. The SCSS sources of both engines are included, so you can compile the design system on Tailwind CSS instead. The pages use the same fd-* markup with either engine. Support for this item covers the Bootstrap 5 engine.

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

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