rainbowindex

The core CSS compiler for Rainbow Index. This package handles parsing, transformation, and generation—everything needed to turn utility classes into CSS.

The compiler has zero runtime dependencies and uses a custom CSS parser. Most projects will interact with Rainbow Index through the Vite plugin or CLI, but direct access to the compiler is useful for building custom tooling or understanding how the system works.

Installation

npm install rainbowindex

Usage

Compile Classes

The most common operation: turn a list of utility class names into CSS.

import { compileClasses, createDesignSystem } from "rainbowindex";

const designSystem = createDesignSystem();

const result = compileClasses(["p-4", "bg-blue-500", "hover:bg-blue-600"], {
    designSystem,
});

console.log(result.css);
// .p-4 { padding: 1rem; }
// .bg-blue-500 { background-color: oklch(55.3% 0.213 253.075); }
// .hover\:bg-blue-600:hover { background-color: oklch(47.4% 0.195 251.802); }

Parse and Print CSS

The parser produces an AST that can be inspected, transformed, or printed back to a string. This is useful for tools that need to analyze or modify CSS programmatically.

import { parse, print } from "rainbowindex";

const { ast } = parse(`
  .button {
    padding: 1rem;
    background: blue;
  }
`);

const output = print(ast);

Transform CSS with Theme

When processing CSS that contains Rainbow Index directives (@theme, @apply, etc.), use transformCSS to expand them.

import { parse, transformCSS, createDesignSystem, print } from "rainbowindex";

const designSystem = createDesignSystem();

const { ast } = parse(`
  @theme {
    --color-primary: oklch(0.6 0.2 250);
  }

  .button {
    background: var(--color-primary);
  }
`);

const transformed = transformCSS(ast, { designSystem });
const output = print(transformed);

Directive Handling

Rainbow Index processes @rainbowindex directives as injection points for generated styles. Unknown at-rules (including @tailwind) are preserved and pass through unchanged, rather than being treated as migration inputs.

API Reference

compileClasses(candidates, options)

Compile utility class names into CSS.

interface CompileOptions {
    designSystem: DesignSystem;
}

interface CompileResult {
    css: string;
    classes: string[];
}

createDesignSystem()

Create a design system instance with the default theme, utilities, and variants. The design system is the central registry that maps class names to CSS output.

interface DesignSystem {
    theme: Theme;
    utilities: Utilities;
    variants: Variants;
    parseCandidate(candidate: string): Candidate[];
    compileAstNodes(candidate: Candidate): AstNode[];
    getClassOrder(classes: string[]): [string, bigint | null][];
}

parse(css, options?)

Parse a CSS string into an AST.

interface ParseOptions {
    from?: string; // Source file path for source maps
}

interface ParseResult {
    ast: AstNode[];
}

print(ast, options?)

Convert an AST back to a CSS string.

interface PrintOptions {
    minify?: boolean;
    indent?: string;
}

transformCSS(ast, options)

Transform a CSS AST, processing @theme, @apply, and other directives.

interface TransformOptions {
    designSystem: DesignSystem;
}

Default Theme

The default theme provides a comprehensive set of design tokens:

Colors — Full OKLCH palette: gray, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

Spacing — Scale from 0 to 96: 0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96.

Typography — Font sizes, weights, and line heights.

Breakpoints — Numeric (rem-based) and named.

Utilities

Core utilities included:

• Spacing: p-*, m-*, gap-*, space-*
• Sizing: w-*, h-*, min-w-*, max-w-*, min-h-*, max-h-*
• Colors: bg-*, text-*, border-*
• Typography: font-*, text-*, leading-*, tracking-*
• Layout: flex, grid, block, inline, hidden
• Flexbox: flex-*, items-*, justify-*, grow-*, shrink-*
• Grid: grid-cols-*, grid-rows-*, col-span-*, row-span-*
• Effects: shadow-*, opacity-*, blur-*
• Borders: rounded-*, border-*

Variants

Built-in variants:

• Pseudo-classes: hover, focus, active, visited, disabled, first, last, odd, even
• Pseudo-elements: before, after, placeholder, selection
• Media: dark, numeric breakpoints (48:, 64:, etc.)
• Compound: group-*, peer-*
• Data/Aria: data-*, aria-*

License

MIT