Clone and Customize

How to set up Chassis CSS for your own team — clone the repository, connect your token build, and own the output.

Chassis CSS is designed to be cloned and owned. You don't configure it with a few Sass variables; you replace its token foundation with yours, adapt the settings to your needs, and ship a CSS build that belongs entirely to your product.

If you only need Chassis as a dependency in an existing project — without forking the framework — see Installation instead.

Prerequisites

Node.js 18 or later
pnpm (the project uses pnpm workspaces)
A built output from Chassis Tokens for your brand, or the default chassis brand to start

Extending the framework

To extend the framework, you clone the repository, connect your token build, configure the settings, and build your CSS. The resulting CSS is yours to ship and maintain as you see fit.

Clone the repository

git clone https://github.com/chassis-ui/css.git my-design-system
cd my-design-system
pnpm install

Connect your tokens

Chassis CSS loads design tokens from @chassis-ui/tokens via scss/_vendor.scss. This file contains a single import — the path to your token build's main.scss, and imported in several places across the framework's source Sass files (e.g. scss/chassis.scss, scss/test/**/*.scss):
```
// scss/_vendor.scss
@import "@chassis-ui/tokens/dist/web/{brand}/{app}/main";
```
The {brand} and {app} segments correspond to the brand and app names you configured when building Chassis Tokens. For example, a docs app build for the chassis brand:
```
@import "@chassis-ui/tokens/dist/web/docs/chassis/main";
```
The token file provides all the $cx-* Sass variables that scss/tokens/ maps to Chassis CSS's internal variable names. If you're starting without a custom token build, the default chassis brand tokens are included in the package and work out of the box.

Color modes

While Chassis CSS maps all light and dark color tokens using main.scss, the token build produces separate files for color modes if you want to customize the theming system beyond the default:
```
// Light and dark color palettes
@import "...dist/web/{brand}/{app}/color-light";
@import "...dist/web/{brand}/{app}/color-dark";
```

Configure the settings

scss/_settings.scss controls which framework features are active. All variables use !default, so you can override them in a file you import before the framework. The most commonly changed settings:

// your-settings.scss — import this before chassis.scss
$enable-dark-mode:          true;   // false to ship light mode only
$enable-exclude-strokes:    true;   // see Core Concepts > Box Model
$enable-rfs:                false;  // responsive font scaling
$color-mode-type:           data;   // 'data' (data-cx-theme attr) or 'media-query'

See Options for the full list.

Build your CSS

# Development build with source maps
pnpm build

# Watch mode
pnpm watch

# Production build (minified)
pnpm build:prod

The output goes to dist/css/. You can configure the output paths in package.js.

Importing in your project

If your project has its own SCSS build pipeline, import Chassis CSS as a source dependency rather than a compiled stylesheet. The correct import order is:

// 1. Your token overrides (optional — before everything else)
@import "@chassis-ui/tokens/dist/web/{brand}/{app}/main";

// 2. Your settings overrides (optional — before chassis.scss)
@import "your-settings";

// 3. Chassis CSS
@import "@chassis-ui/css/scss/chassis";

The @chassis-ui/tokens import must come before @chassis-ui/css/scss/chassis because the framework's _vendor.scss and _tokens.scss files consume the $cx-* variables that your token build provides.

If you use the compiled CSS distribution instead, you lose the ability to override settings and tokens at build time.