API Overview

Styleframe provides a powerful, type-safe API for building modern CSS design systems. The API is designed around composability, type safety, and maintainability, enabling you to create scalable styling architectures that grow with your application.

Every Styleframe feature works together seamlessly, allowing you to build sophisticated design systems while maintaining clean, organized code.

Getting Started

All Styleframe features are accessed through a styleframe instance. Use the styleframe() function to create a new instance:

import { styleframe } from 'styleframe';

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

// Start building your design system
const colorPrimary = variable('color--primary', '#006cff');

selector('.button', {
    backgroundColor: ref(colorPrimary),
    padding: '0.5rem 1rem',
});

export default s;

Learn more about Instances →

Core Building Blocks

These fundamental features form the foundation of every Styleframe design system.

Variables

Variables are the foundation of your design system. They let you define design tokens such as colors, spacing, typography, and more, with full type safety and auto-complete.

Key capabilities:

• Define reusable design tokens
• Reference variables in other styles
• Enable easy theming and customization
• Become CSS custom properties

import { styleframe } from 'styleframe';

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

const colorPrimary = variable('color--primary', '#006cff');
const spacingMd = variable('spacing--md', '1rem');

Learn more about Variables →

Selectors

Selectors allow you to create CSS rules with type-safe property definitions. They provide a powerful way to style your components with full TypeScript support.

Key capabilities:

• Write type-safe CSS with auto-complete
• Nest selectors for better organization
• Support all CSS selectors and pseudo-classes
• Compose with variables and other features

import { styleframe } from 'styleframe';

const s = styleframe();
const { selector } = s;

selector('.button', {
    padding: ref(spacingMd),
    backgroundColor: ref(colorPrimary),
    
    '&:hover': {
        opacity: 0.9,
    },
});

Learn more about Selectors →

At-Rules

At-rules enable you to use modern CSS features like container queries, feature detection, font loading, and CSS layers with full type safety.

Key capabilities:

• Support all CSS at-rules (@supports, @font-face, @layer, @container, etc.)
• Progressive enhancement with feature detection
• Custom font loading with optimal characteristics
• CSS cascade organization with layers

import { styleframe } from 'styleframe';

const s = styleframe();
const { atRule } = s;

atRule('supports', '(display: grid)', ({ selector }) => {
    selector('.layout', {
        display: 'grid',
        gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
    });
});

Learn more about At-Rules →

Media Queries

Media queries enable responsive design with type-safe breakpoint definitions. Create adaptive layouts that work seamlessly across all device sizes.

Key capabilities:

• Define responsive breakpoints
• Support all media query features
• Nest media queries within selectors
• Use inline or callback-based syntax

import { styleframe } from 'styleframe';

const s = styleframe();
const { media } = s;

media('(min-width: 768px)', ({ selector }) => {
    selector('.container', {
        width: '750px',
        margin: '0 auto',
    });
});

Learn more about Media Queries →

Keyframes

Keyframes enable you to create smooth CSS animations with type-safe property definitions. Build engaging motion effects that enhance user experience.

Key capabilities:

• Define animation sequences
• Reference in any selector
• Combine with variables for consistency
• Support all animatable CSS properties

import { styleframe } from 'styleframe';

const s = styleframe();
const { keyframes, selector } = s;

const fadeIn = keyframes('fade-in', {
    '0%': { opacity: 0, transform: 'translateY(20px)' },
    '100%': { opacity: 1, transform: 'translateY(0)' },
});

selector('.animated', {
    animation: `${fadeIn.name} 0.3s ease-out`,
});

Learn more about Keyframes →

Interpolation

The css template literal utility enables dynamic value insertion with full type safety. Create flexible, maintainable CSS values that adapt to your design system.

Key capabilities:

• Combine variables with static values
• Create complex CSS calculations
• Build dynamic gradients and transforms
• Maintain type safety in template literals

import { styleframe } from 'styleframe';

const s = styleframe();
const { css, ref, selector } = s;

selector('.gradient', {
    background: css`linear-gradient(135deg, ${ref(colorPrimary)} 0%, ${ref(colorSecondary)} 100%)`,
    padding: css`clamp(${ref(spacingSm)}, 5vw, ${ref(spacingLg)})`,
});

Learn more about Interpolation →

Utilities

Utilities provide reusable, single-purpose CSS classes with full type safety and modifier support. Build consistent, maintainable styling systems with atomic design patterns.

Key capabilities:

• Create atomic CSS classes
• Define reusable modifiers (hover, focus, responsive)
• Generate variants automatically
• Support compound modifier combinations

import { styleframe } from 'styleframe';

const s = styleframe();
const { utility, modifier } = s;

const createMarginUtility = utility('margin', ({ value }) => ({
    margin: value,
}));

const hover = modifier('hover', ({ declarations }) => ({
    '&:hover': declarations,
}));

createMarginUtility(
    { sm: '0.5rem', md: '1rem', lg: '1.5rem' },
    [hover]
);

Learn more about Utilities →

Themes

Themes provide powerful design system theming capabilities with type-safe variable overrides. Create consistent variations like dark mode, brand themes, or user personalization.

Key capabilities:

• Override variables in specific contexts
• Create multiple theme variations
• Apply themes with data attributes
• Maintain consistency across variations

import { styleframe } from 'styleframe';

const s = styleframe();
const { theme } = s;

theme('dark', (ctx) => {
    ctx.variable(colorBackground, '#18181b');
    ctx.variable(colorText, '#ffffff');
});

Learn more about Themes →

Recipes 🚧

Recipes provide component variants with type-safe configuration options. Create flexible, reusable UI components with runtime variant selection.

Key capabilities:

• Generate runtime variant functions
• Leverage existing utility classes
• Support compound variants
• Define default configurations

Learn more about Recipes →

Organization & Composition

Structure and scale your design system with these organizational features.

Composables

Composables are reusable functions that provide design system components. They enable modular, consistent styling patterns across your application.

Key capabilities:

• Create reusable design system modules
• Group related variables and styles
• Build configurable styling functions
• Compose design systems from building blocks

export function useColorVariables(s: Styleframe) {
    const { variable } = s;
    
    const colorPrimary = variable('color--primary', '#006cff', { default: true });
    const colorSecondary = variable('color--secondary', '#64748b', { default: true });
    
    return { colorPrimary, colorSecondary };
}

Learn more about Composables →

Merging

The merge() function combines multiple Styleframe instances into a single unified configuration. Perfect for composing design systems and building modular architectures.

Key capabilities:

• Combine multiple styleframe instances
• Share configurations across projects
• Override and extend base configurations
• Organize large codebases into modules

import { merge } from 'styleframe';
import base from './base';
import theme from './theme';
import components from './components';

const s = merge(base, theme, components);

Learn more about Merging →

API Reference Summary

Next Steps

Ready to dive deeper? Explore specific API features:

• New to Styleframe? Start with Variables and Selectors
• Building a design system? Check out Composables and Themes
• Need utilities? Learn about Utilities and modifiers
• Working on responsive design? Explore Media Queries and At-Rules
• Want to share code? Discover Merging patterns

Each API feature is designed to work seamlessly with the others, giving you the flexibility to build exactly the design system your project needs.