How ECSS Compiles

ECSS works at build time. The language has no heavy runtime: an .ecss file is turned into plain static CSS plus a small typed JS module. Understanding this dispels the feeling of "magic".

What turns into what

A single @block produces three things:

1. Static CSS — all of the block's rules, including the @if branches, emitted as plain CSS.
2. A typed JS module — the blocks object and the adapter components (EButton).
3. Type declarations (.d.ts) — so that the .ecss import is typed (see TypeScript Integration).

Example (schematic)

@block Button {
  @param --variant Variant;

  padding: 8px 16px;

  @if (--variant == "primary") {
    background: #646cff;
  }
}

Compiles into roughly this CSS:

.Button-x7 {
  padding: 8px 16px;
}

.Button-x7[data-variant='primary'] {
  background: #646cff;
}

And at render time the component simply sets the class and the right data attributes based on the params value:

<button class="Button-x7" data-variant="primary">Click me</button>

TIP

The class and attribute names here are shortened for clarity — in a real build they are unique (with a hash) so that styles don't conflict between blocks.

This way each @if branch becomes a plain CSS rule, "switched on" via a data attribute. No style computation happens in the browser — only a tiny helper that assembles the class and attributes reaches the bundle.

The pipeline

1. The compiler parses the .ecss and produces CSS, JS, and types.
2. The adapter wraps the blocks into components for your framework.
3. The bundler plugin (@ecss/vite-plugin and others) attaches the CSS to the page and links the .ecss imports.

Next steps

• Core API: blocks — exactly what the compiled module exports
• Configuration — controlling the build
• TypeScript Integration — type generation