Piloti

Piloti is a small CUBE CSS framework and a DTCG-to-CSS integration for Terrazzo. It provides a reset, a typographic base, layout compositions, universal utilities, and opt-in generation from standard design tokens.

Install

npm install piloti

Import the core from your main stylesheet:

@import "piloti";

Piloti declares this layer order:

@layer settings, reset, base, compositions, utilities;

An application can insert its own component layer and override the default settings:

@layer settings, reset, base, compositions, components, utilities;

@import "piloti";
@import "./settings.css" layer(settings);
@import "./components.css" layer(components);

Type and space

Piloti provides a small fluid type scale. --step-0 is the smallest size and --step-1 is the body size:

font-size: var(--step-1);

The spacing scale takes its rhythm from the body size through --space-base:

--space-base: var(--step-1);
--space-3xs: calc(var(--space-base) * 0.25);
--space-2xs: calc(var(--space-base) * 0.5);
--space-xs: calc(var(--space-base) * 0.75);
--space-s: var(--space-base);
--space-m: calc(var(--space-base) * 1.5);
--space-l: calc(var(--space-base) * 2);
--space-xl: calc(var(--space-base) * 3);
--space-2xl: calc(var(--space-base) * 4);
--space-3xl: calc(var(--space-base) * 6);

Override --step-1 to change body type and spatial rhythm together. Override --space-base instead when the application needs independent spacing:

:root {
  --space-base: 1rem;
}

Form defaults

Piloti improves native text fields, selects, and textareas without turning them into branded components. Controls inherit the page typography and color and use the core spacing and border tokens. Their :where() selectors add no specificity.

Customize all textual controls with shared properties:

:root {
  --control-background: white;
  --control-border-color: currentcolor;
  --control-radius: 0;
}

Checkboxes, radios, range controls, file inputs, and buttons retain their native appearance. Projects remain responsible for designed button components.

Compositions

Compositions handle layout.

Every composition that controls spacing accepts data-space="none" when its structure is useful without a gap.

Box

The box provides configurable internal spacing and is borderless by default:

<section class="box">...</section>

Set --box-space to change its padding. Add data-border for a neutral border driven by the core border tokens:

<section class="box" data-border>...</section>

Container

<main class="container" data-width="content">...</main>

Available widths are the default container, content, and narrow. Override --container, --content, --narrow, or --gutter in the application settings.

Flow

<article class="flow">
  <h1>Title</h1>
  <p>First paragraph.</p>
  <p>Second paragraph.</p>
</article>

Set --flow-space on the element to change the rhythm.

Stack

<form class="stack">...</form>

Set --stack-space to change the gap.

Use the structure without a gap when needed:

<div class="stack" data-space="none">...</div>

Cluster

<nav class="cluster" data-justify="between">...</nav>

data-justify accepts between, center, or end. Set --cluster-space to change the gap.

Grid

<div class="grid">...</div>

The grid fills available space and wraps without breakpoint classes. Set --grid-min to control the minimum item width and --grid-space to control the gap.

Switcher

<div class="switcher">...</div>

The switcher changes from columns to a wrapped row when space allows. Set --switcher-threshold and --switcher-space to tune it.

Core utilities

Piloti includes a few utilities:

• .visually-hidden - hides an element visually while keeping it accessible to assistive technologies
• .measure - limits line length for readable text
• .text-end - aligns text with the logical end of its container

Put recurring visual rules in application components. Use the optional generator for isolated rules that do not belong to a composition or component.

Optional token and utility generator

Piloti reads DTCG tokens through Terrazzo. See the DTCG generation guide for token files, utility recipes, Figma import, generated layers, and contribution instructions.

Install the optional toolchain:

npm install --save-dev @terrazzo/cli @terrazzo/parser @terrazzo/plugin-css

Use Node.js 22.12 or newer for the Terrazzo toolchain. The standalone Piloti CSS framework continues to support Node.js 18 or newer.

Create a DTCG token file and Terrazzo config:

npx piloti init

The initializer creates a schema-only token file without project colors or spacing. Add the project's design decisions to that file; the DTCG generation guide includes a complete example.

Generate the CSS:

npx tz build

The starter writes four files to styles/generated/piloti/:

• variables.css
• utilities.css
• responsive.css
• index.css

Import the generated entry after the core:

@import "piloti";
@import "./styles/generated/piloti/index.css";

Utilities remain opt-in. DTCG tokens and utility recipes are separate:

piloti({
  utilities: [
    {
      prefix: "gap",
      property: "gap",
      tokens: ["space.*"],
      strip: "space.",
      responsive: true
    }
  ]
})

Piloti intentionally does not ship a static padding, margin, gap, or border utility matrix. Add only the logical properties the project repeatedly needs:

piloti({
  utilities: [
    { prefix: "p", property: "padding", tokens: ["space.*"], strip: "space." },
    { prefix: "pi", property: "padding-inline", tokens: ["space.*"], strip: "space." },
    { prefix: "mb", property: "margin-block-end", tokens: ["space.*"], strip: "space." },
    {
      prefix: "border",
      property: "border",
      values: {
        thin: "var(--border-width) var(--border-style) var(--border-color)",
        none: "0"
      }
    }
  ]
})

This generates classes such as .p-s, .pi-m, .mb-l, .border-thin, and .border-none. Prefer compositions such as .flow, .stack, and .box when they express the relationship directly.

Literal values such as fractions can share the same recipe system:

piloti({
  utilities: [
    {
      prefix: "w",
      property: "width",
      values: {
        "1/2": "50%",
        "2/3": "66.667%"
      },
      responsive: true
    }
  ]
})

Use the generated classes without escapes in HTML:

<div class="w-1/2 md:w-2/3"></div>

The generated selectors are .w-1\/2 and .md\:w-2\/3. HTML uses w-1/2 and md:w-2/3 without escapes.

Individual imports

Package exports are available for projects that do not want the complete core:

@import "piloti/settings.css";
@import "piloti/reset.css";
@import "piloti/base.css";
@import "piloti/compositions.css";
@import "piloti/utilities.css";

Migrating from 1.x

Version 2 changes the default package surface.

1. Replace node_modules/piloti/src/main.css imports with @import "piloti".
2. Remove the generated src/0-gen-settings import. Generated utilities are no longer part of the core.
3. Move project tokens to DTCG 2025.10 files with $type and $value.
4. Replace piloti.config.json with terrazzo.config.mjs and the piloti/terrazzo integration.
5. Add each desired generated utility explicitly to the integration's utilities array.
6. Replace fractional custom properties such as --size-1/2 with semantic token names. Keep fraction classes as literal utility values.
7. Define dark-mode colors through DTCG resolvers or application settings. Piloti no longer opts every page into color-scheme: light dark.

Development

The package ships CSS plus two pieces of JavaScript, both compiled from TypeScript sources in source/. The compiled output is committed so the package runs straight from a clone or an install.

| Source | Output | Format | | --- | --- | --- | | source/cli/piloti.ts | bin/piloti.js | CommonJS | | source/integration/terrazzo.mts | integration/terrazzo.mjs and integration/terrazzo.d.mts | ESM |

Do not edit anything in bin/ or integration/. The next build overwrites it.

npm install
npm run build

npm run build compiles both entry points, runs stylelint, and runs the tests. The individual steps:

• npm run build:ts - compile both entry points (build:cli and build:integration run them one at a time)
• npm run typecheck - check source/ without emitting
• npm run lint - stylelint over src/**/*.css and demo/**/*.css; npm run lint:fix writes the fixes
• npm test - compile, then run Node's test runner, so tests never run against stale output
• npm run test:unit - the test runner alone, when the output is already current
• npm run generate:example - rebuild examples/dtcg/generated/ from the maintained example

The CLI is CommonJS and the Terrazzo integration is ESM, so each gets its own emit config: tsconfig.cli.json and tsconfig.integration.json. Both extend tsconfig.json, which carries the shared compiler options and is what editors and npm run typecheck read.

Browser support

Piloti uses cascade layers, custom properties, clamp(), min(), flexbox, and grid. Use it with current evergreen browsers.

Development preview

The repository's index.html is a working v2 consumer. It imports the core, the generated DTCG example, and project-specific blocks from demo/styles.css.

npm install
npm run generate:example
npm run build

Serve the repository root with a local static server to inspect the framework at desktop and mobile widths.

License

MIT