API Reference

Styleframe Instance

Learn how to create and configure Styleframe instances to build type-safe, maintainable design systems with full control over CSS generation.

The Styleframe instance is the core of your design system. It provides all the tools you need to define variables, create selectors, build utilities, manage themes, and generate CSS—all with full TypeScript support and type safety.

Overview

When you create a Styleframe instance, you get access to a complete API for building your design system:

Create a Styleframe instance by calling the styleframe() function, optionally with configuration options:

styleframe.config.ts
import { styleframe } from 'styleframe';

const s = styleframe();

// Access all Styleframe features
const { 
    variable,   // Define design tokens
    selector,   // Create CSS rules
    utility,    // Build utility classes
    modifier,   // Define reusable modifiers
    recipe,     // Create component variants
    theme,      // Manage theme variations
    atRule,     // Use modern CSS at-rules
    keyframes,  // Define animations
    media,      // Create media queries
    ref,        // Reference variables
    css,        // Interpolate dynamic values
    root,       // Access the style tree
    options     // Configuration settings
} = s;

export default s;

The instance serves as your central hub for design system development, providing consistent patterns and type safety across all your styling needs.

Instance Properties

Every Styleframe instance provides the following properties and methods:

root

Root
The root style tree containing all defined styles, variables, and rules. This is used internally by Styleframe and when generating CSS output.

atRule

function
Enables modern CSS features like @supports, @font-face, @layer, and @container. Use at-rules for progressive enhancement and advanced CSS capabilities. Learn more about At-Rules →

css

function
Template literal utility for interpolating dynamic values into CSS strings. Perfect for complex calculations, gradients, and compound values. Learn more about Interpolation →

keyframes

function
Defines CSS animation keyframes with type-safe property definitions. Create smooth animations that enhance user experience. Learn more about Keyframes →

media

function
Creates responsive media queries for adaptive layouts. Build designs that work seamlessly across all device sizes. Learn more about Media Queries →

modifier

function
Defines reusable utility modifiers that can be applied to utilities. Modifiers enable consistent patterns like hover states, focus states, and responsive variations. Learn more about Utility Modifiers →

ref

function
References CSS variables created with variable(). The ref function generates the correct CSS custom property reference automatically. Learn more about Variables →

recipe

function
Creates component variant generators with type-safe configuration options. Recipes enable runtime variant selection for flexible UI components. Learn more about Recipes →

selector

function
Creates CSS rules with type-safe property definitions. Use selectors to style components, define layouts, and create complex CSS structures. Learn more about Selectors →

theme

function
Creates theme variations by overriding variables in specific contexts. Perfect for dark mode, brand themes, or user personalization. Learn more about Themes →

utility

function
Creates reusable utility class generators that produce atomic CSS classes. Utilities support modifiers and variants for flexible, composable styling. Learn more about Utilities →

variable

function
Creates CSS custom properties (variables) that form the foundation of your design system. Variables can be referenced throughout your styles and overridden in themes. Learn more about Variables →

options

StyleframeOptions
The configuration options passed when creating the instance. Access this property to inspect or reference the current configuration.

Configuration Options

The Styleframe instance accepts configuration options that allow you to customize how your styles are generated. These options give you fine-grained control over indentation, variable naming conventions, utility class selectors, and theme selectors — ensuring the generated CSS matches your project's conventions and requirements.

Configuration helps you:

  • Match your code style: Set custom indentation to align with your project's formatting rules.
  • Follow naming conventions: Customize how CSS variable names are generated to match your design system.
  • Control selector output: Define how utility classes and theme selectors are generated.
  • Ensure consistency: Maintain consistent patterns across your entire codebase.

You configure Styleframe by passing an options object when creating an instance:

export type StyleframeOptions = {
    indent?: string;
    strict?: boolean;
    variables?: {
        name?: VariableNameFn;
    };
    utilities?: {
        selector?: UtilitySelectorFn;
    };
    themes?: {
        selector?: ThemeSelectorFn;
    };
};

Let's explore each configuration option in detail.


indent

string
indent?: string;
Controls the indentation used in the generated CSS output. Defaults to a tab character (\t). Set this to spaces or any other string to match your project's formatting conventions.

strict

boolean
strict?: boolean;
Fails the build when validate() finds a problem. Each build checks the finished instance once and reports every problem it finds in one pass:
  • unresolved-reference: a reference that resolves to no variable, with the closest token name when one is within two edits. That covers an @token in a recipe, a utility value or a css template literal, and a ref() anywhere. A plain @token string in a selector or theme declaration is checked when you define it, and still throws there.
  • undefined-theme-override: a theme variable() whose name isn't defined at root, so it overrides nothing.
  • duplicate-variable: two variable() calls with the same name and without default: true, so the first value is lost.
Without strict, these are warnings: the build emits as before, and transpile() returns them as diagnostics beside files. With strict: true, transpile() throws one error that lists them all. It defaults to false, so existing builds keep working while you fix what it reports.
import { styleframe, validate } from 'styleframe';

const s = styleframe({ strict: true });

// validate() returns the same diagnostics without building
const diagnostics = validate(s);

export default s;

variables.name

function
type VariableNameFn = (options: { name: string }) => string;
By default, variable names are converted to CSS custom properties by adding the -- prefix if not present. You can provide a custom function to transform variable names.

utilities.selector

function
type UtilitySelectorFn = (options: UtilitySelectorOptions) => string;

interface UtilitySelectorOptions {
    name: string;
    value: string;
    modifiers: string[];
}
By default, utility class names follow the _modifiers:name:value format (e.g., _hover:margin:sm). Provide a custom function to change how class names are generated. The transpiler handles CSS escaping internally. If you use the scanner, set the same function in both places.

themes.selector

function
type ThemeSelectorFn = (options: { name: string }) => string;
By default, theme selectors use the pattern [data-theme="${name}"]. You can provide a custom function to change how theme selectors are generated.

Inspecting an instance

An agent or a script that edits your design system needs to know what it already defines before it adds a token or picks a class name. The inspect() function answers that in one call: it returns a plain snapshot of the instance, with names and values as the CSS output emits them.

import { styleframe, inspect } from 'styleframe';

const s = styleframe();
const { variable, ref } = s;

const colorBrand = variable('color.brand', '#6366f1');
variable('color.accent', ref(colorBrand));

const snapshot = inspect(s);
// snapshot.variables[1] → { name: 'color.accent', property: '--color--accent', value: 'var(--color--brand)' }

The snapshot holds no functions and no circular references, so JSON.stringify(snapshot) gives you all of it. It follows the variables.name, utilities.selector and themes.selector options you set. Its fields:

FieldEach entry holds
variablesThe root variables: name, the CSS custom property it emits, and its value as emitted, like var(--color--brand)
themesname, the selector the theme emits under, and its overrides, each a { name, value }
utilitiesname, the values it was created with, every class name it emits in classNames (modifier variants included), and the modifiers applied to it
modifiersThe modifier's key, a list of the names it registers
recipesname, its variants as each axis and its option names, and its defaultVariants

Note that inspect() reads the instance as it is when you call it, so call it after every composable and recipe has run, the way the CLI loads your finished config.

Best Practices

  • Define configuration once: Create a single configured instance and export it for use across your project.
  • Match your project conventions: Align the configuration with your existing CSS and naming conventions.
  • Document your choices: Add comments explaining why specific configuration options were chosen.
  • Use consistent patterns: Ensure your naming functions produce predictable, consistent results.
  • Test generated output: Verify that the generated CSS matches your expectations after configuration changes.

FAQ