styleengine

styleengine

Typed, composable, fast Go-native CSS construction and emission.

styleengine replaces ad-hoc text/template or string concatenation with a structured intermediate representation (IR) that validates inputs at construction time, deduplicates rules, enforces a byte-size safety ceiling, and emits either pretty-printed or minified CSS through a single Render call.

It is a great building block for design system compilers, theme engines, plugin and customization systems, and server-side rendering pipelines.

Who calls it

• Design-system token compilers — emit :root custom-property sheets from design-token sources.
• Theme / experience composers — assemble layered overrides (brand, customer, user) into a single merged Sheet.
• Untrusted CSS validators — call [Sanitize] on user-, plugin-, or customer-supplied CSS fragments before accepting them.
• Server renderers and email generators — build and emit CSS safely without template string hacks.
• Custom tooling and CLIs that need reproducible, validated CSS output.

Hello world

package main

import (
	"fmt"
	"github.com/septagon-oss/styleengine"
)

func main() {
	sheet, err := styleengine.New().
		Var("font-display", "swap").
		Var("motion-duration-marquee", "8s").
		Rule(":root").
			Decl("font-display", styleengine.VarRef("font-display", "swap")).
			Done().
		Rule(".marquee").
			Decl("animation-duration", styleengine.VarRef("motion-duration-marquee", "6s")).
			Decl("overflow", styleengine.Literal("hidden")).
			Done().
		Build().
		Render(styleengine.RenderOptions{Pretty: true})
	if err != nil {
		panic(err)
	}
	fmt.Println(sheet)
}

Var registers a --font-display custom property in :root. VarRef emits var(--font-display, swap). Both enforce the [a-z][a-z0-9_-]* naming rule at call time, so mis-spellings are caught immediately rather than silently emitted.

Public API surface

RenderOptions

type RenderOptions struct {
	Pretty   bool  // emit indented multi-line output
	Minify   bool  // run tdewolff/minify (mutually exclusive with Pretty; both returns error)
	MaxBytes int64 // 0 → DefaultMaxBytes (1 MiB)
}

Render enforces a byte ceiling (negative MaxBytes disables). When MaxBytes is zero it falls back to DefaultMaxBytes (1 MiB = 1 << 20). If the rendered output exceeds the limit Render returns an error rather than a truncated string, so callers cannot silently serve corrupt CSS.

Variable safety

Var and VarRef both enforce [a-z][a-z0-9_-]* on the custom-property name and panic immediately if the constraint is violated. The leading -- is added automatically — callers never write it.

UndefinedVars() []string scans the sheet for var(--x) references that have no matching Var registration and returns the sorted list of undefined names. Use this in compiler pipelines to surface missing token definitions before emitting CSS to a browser.

Sanitize

Before accepting CSS text from untrusted sources (user input, customer overrides, third-party plugins, etc.), pass it through Sanitize:

clean, err := styleengine.Sanitize(userInput)
if err != nil {
	// reject the request
}

Sanitize trims whitespace and rejects (case-insensitively) any fragment containing dangerous patterns that could break out of the expected stylesheet context or introduce security issues.

Parse roundtrip

Parse(css string) (*Sheet, error) ingests a CSS string via github.com/tdewolff/parse/v2/css and reconstructs a Sheet IR.

For the rule + custom-property subset supported in v1, the roundtrip is idempotent. This property is verified in the test suite and is useful for overlay / customization pipelines.

At-rules supported

Nested at-rules are composed via closures that receive a child Sheet.

Performance

Both pretty and minified render are well under the 500 µs target for a full-page token sheet. See benchmarks in the package for current numbers on your hardware.

Dependencies

Both are pure Go with no cgo requirements.

Status

The core library (IR, builder, render, parse, sanitize, variables, at-rules) is stable and suitable for general use.

The package has comprehensive tests, fuzzing, and benchmarks. It has minimal dependencies.

See the godoc for the full API and the Example functions (including roundtrips and at-rule usage) that render in documentation and pass go test -run Example.