Styleframe Instance

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:

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

atRule

css

keyframes

media

modifier

ref

recipe

selector

theme

utility

variable

options

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 = {
    variables?: {
        name?: VariableNameFn;
    };
    utilities?: {
        selector?: UtilitySelectorFn;
    };
    theme?: {
        selector?: ThemeSelectorFn;
    };
};

import { styleframe } from 'styleframe';

const s = styleframe({
    variables: {
        name: ({ name }) => `--${name}`,
    },
    utilities: {
        selector: ({ name, value, modifiers }) => 
            `._${name}-${value}${modifiers.map(m => `:${m}`).join('')}`,
    },
    theme: {
        selector: ({ name }) => `[data-theme="${name}"]`,
    },
});

export default s;

Let's explore each configuration option in detail.

variables.name

type VariableNameFn = (options: { name: string }) => string;

utilities.selector

type UtilitySelectorFn = (options: {
    name: string;
    value: string;
    modifiers: string[];
}) => string;

theme.selector

type ThemeSelectorFn = (options: { name: string }) => string;

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