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
@supports, @font-face, @layer, and @container. Use at-rules for progressive enhancement and advanced CSS capabilities. Learn more about At-Rules →css
keyframes
media
modifier
ref
variable(). The ref function generates the correct CSS custom property reference automatically. Learn more about Variables →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 = {
indent?: string;
strict?: boolean;
variables?: {
name?: VariableNameFn;
};
utilities?: {
selector?: UtilitySelectorFn;
};
themes?: {
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('')}`,
},
themes: {
selector: ({ name }) => `[data-theme="${name}"]`,
},
});
export default s;
Let's explore each configuration option in detail.
indent
indent?: string;
\t). Set this to spaces or any other string to match your project's formatting conventions.strict
strict?: boolean;
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@tokenin a recipe, a utility value or acsstemplate literal, and aref()anywhere. A plain@tokenstring in a selector or theme declaration is checked when you define it, and still throws there.undefined-theme-override: a themevariable()whose name isn't defined at root, so it overrides nothing.duplicate-variable: twovariable()calls with the same name and withoutdefault: true, so the first value is lost.
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
type VariableNameFn = (options: { name: string }) => string;
-- prefix if not present. You can provide a custom function to transform variable names.utilities.selector
type UtilitySelectorFn = (options: UtilitySelectorOptions) => string;
interface UtilitySelectorOptions {
name: string;
value: string;
modifiers: string[];
}
_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
type ThemeSelectorFn = (options: { name: string }) => string;
[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:
| Field | Each entry holds |
|---|---|
variables | The root variables: name, the CSS custom property it emits, and its value as emitted, like var(--color--brand) |
themes | name, the selector the theme emits under, and its overrides, each a { name, value } |
utilities | name, the values it was created with, every class name it emits in classNames (modifier variants included), and the modifiers applied to it |
modifiers | The modifier's key, a list of the names it registers |
recipes | name, 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
-- prefix, and conventional selector patterns.ref() helper automatically uses the transformed names based on your configuration, so you don't need to worry about the transformation when referencing variables.Overview
Explore Styleframe's comprehensive API for building type-safe, maintainable design systems. From variables and selectors to themes and composables, discover how to create scalable styling architectures.
Variables
Styleframe variables are the foundation of your design system. They let you define design tokens such as colors, spacing, typography, and more.