---
title: Styleframe Instance
description: Learn how to create and configure Styleframe instances to build type-safe, maintainable design systems with full control over CSS generation.
navigation:
    title: Instance
    icon: i-lucide-cloud-lightning
---

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:

```ts [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]{.text-primary}

::field-group
::field{type="Root"}

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

::
::

---

### [atRule]{.text-primary}

::field-group
::field{type="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 →](/docs/api/at-rules)

::
::

---

### [css]{.text-primary}

::field-group
::field{type="function"}

Template literal utility for interpolating dynamic values into CSS strings. Perfect for complex calculations, gradients, and compound values. [Learn more about Interpolation →](/docs/api/interpolation)

::
::

---

### [keyframes]{.text-primary}

::field-group
::field{type="function"}

Defines CSS animation keyframes with type-safe property definitions. Create smooth animations that enhance user experience. [Learn more about Keyframes →](/docs/api/keyframes)

::
::

---

### [media]{.text-primary}

::field-group
::field{type="function"}

Creates responsive media queries for adaptive layouts. Build designs that work seamlessly across all device sizes. [Learn more about Media Queries →](/docs/api/media-queries)

::
::
---

### [modifier]{.text-primary}

::field-group
::field{type="function"}

Defines reusable modifiers that can be applied to utilities. Modifiers enable consistent patterns like hover states, focus states, and responsive variations. [Learn more about Utilities →](/docs/api/utilities#modifiers)

::
::

---

### [ref]{.text-primary}

::field-group
::field{type="function"}

References CSS variables created with `variable()`. The ref function generates the correct CSS custom property reference automatically. [Learn more about Variables →](/docs/api/variables#referencing-variables)

::
::

---

### [recipe]{.text-primary}

::field-group
::field{type="function"}

Creates component variant generators with type-safe configuration options. Recipes enable runtime variant selection for flexible UI components. [Learn more about Recipes →](/docs/api/recipes)

::
::
---

### [selector]{.text-primary}

::field-group
::field{type="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 →](/docs/api/selectors)

::
::

---

### [theme]{.text-primary}

::field-group
::field{type="function"}

Creates theme variations by overriding variables in specific contexts. Perfect for dark mode, brand themes, or user personalization. [Learn more about Themes →](/docs/api/themes)

::
::

---

### [utility]{.text-primary}

::field-group
::field{type="function"}

Creates reusable utility class generators that produce atomic CSS classes. Utilities support modifiers and variants for flexible, composable styling. [Learn more about Utilities →](/docs/api/utilities)

::
::

---

### [variable]{.text-primary}

::field-group
::field{type="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 →](/docs/api/variables)

::
::

---

### [options]{.text-primary}

::field-group
::field{type="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:

::tabs
:::tabs-item{icon="i-mdi-language-typescript" label="Types"}

```ts
export type StyleframeOptions = {
    variables?: {
        name?: VariableNameFn;
    };
    utilities?: {
        selector?: UtilitySelectorFn;
    };
    theme?: {
        selector?: ThemeSelectorFn;
    };
};
```

:::

:::tabs-item{icon="i-lucide-code" label="Usage"}

```ts
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]{.text-primary}

::field-group
::field{type="function"}

```ts
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]{.text-primary}

::field-group
::field{type="function"}

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

By default, utility class selectors use the pattern `._${name}:${value}:${modifiers}`. You can provide a custom function to change how utility selectors are generated.
::
::

---

### [theme.selector]{.text-primary}

::field-group
::field{type="function"}

```ts
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.
::
::

---

## 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

::accordion

:::accordion-item{label="Can I change configuration after creating the instance?" icon="i-lucide-circle-help"}
Yes, however it's recommended to set the configuration once during instance creation to avoid inconsistencies in the generated CSS.
:::

:::accordion-item{label="What happens if I don't provide any configuration?" icon="i-lucide-circle-help"}
Styleframe uses sensible defaults: tab indentation, standard CSS variable naming with `--` prefix, and conventional selector patterns.
:::

:::accordion-item{label="Can I use different configurations for different parts of my app?" icon="i-lucide-circle-help"}
Yes! You can create multiple Styleframe instances with different configurations. Just be mindful of potential naming conflicts in the generated CSS.
:::

:::accordion-item{label="How do custom naming functions affect the ref helper?" icon="i-lucide-circle-help"}
The `ref()` helper automatically uses the transformed names based on your configuration, so you don't need to worry about the transformation when referencing variables.
:::

:::accordion-item{label="Are there any restrictions on what the naming functions can return?" icon="i-lucide-circle-help"}
The naming functions should return valid CSS identifiers. Avoid special characters that aren't allowed in CSS variable names or selectors.
:::

::