Variables

Overview

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. Variables are reusable, composable, and become CSS custom properties in your generated styles.

Why use variables?

Variables help you:

• Centralize your design decisions: Define a color, spacing value, or font once, and reference it everywhere.
• Enable easy theming: Quickly override variables to create dark mode, brand themes, or user personalization.
• Prevent mistakes: Change a value in one place, update your whole app — with zero risk of typos or missed selectors.

Defining Variables

You define a variable using the variable() function from your styleframe instance:

import { styleframe } from 'styleframe';

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

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

export default s;

:root {
    --color--primary: #006cff;
    --spacing--md: 1rem;
}

Each variable gets a name (used for the CSS custom property) and a value.

Naming Convention (Dot Notation)

Styleframe allows you to use the dot notation for variable names, which provides a clean, readable way to organize your design tokens into logical groups. When compiled to CSS, dots (.) are automatically converted to double dashes (--).

Why Dot Notation?

• Readability: Dots are more natural to read and type than double dashes in JavaScript/TypeScript code.
• Namespacing: Easily group related variables (e.g. color.primary, color.secondary, color.accent).
• Autocomplete-friendly: IDEs can provide better autocomplete suggestions for dot-separated names.
• CSS Compatibility: The compiled double-dash format (e.g. --color--primary) is valid CSS and clearly distinguishes namespace separators from the standard -- prefix.

Default Values

You can also define a variable with a default value. The default value will be used only if the variable is not already defined in the styleframe instance:

import { styleframe } from 'styleframe';

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

function useDefaultVariables() {
    variable('spacing', '1rem', { default: true }); 
}

variable('spacing', '2rem');

useDefaultVariables(); // This will not override the previous value

export default s;

:root {
    --spacing: 2rem;
}

Referencing Variables

To use a variable in other style definitions, pass its reference using the ref() helper:

a. Within Variables

import { styleframe } from 'styleframe';

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

const colorBlue = variable('color.blue', '#006cff')

const colorPrimary = variable('color.primary', ref(colorBlue));

export default s;

:root {
    --color--blue: #006cff;
    --color--primary: var(--color--blue);
}

b. Within Selectors

import { styleframe } from 'styleframe';

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

const colorPrimary = variable('color.primary', '#006cff');

selector('.button', {
    backgroundColor: ref(colorPrimary),
});

export default s;

:root {
    --color--primary: #006cff;
}

.button {
    background-color: var(--color--primary);
}

This tells styleframe to inject the actual variable value (as a CSS custom property) in the generated CSS.

c. String Reference Shorthand (@)

As a shorthand, you can reference another variable by prefixing its name with @. This automatically creates a ref() to that variable, making your code more concise:

import { styleframe } from 'styleframe';

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

const colorBlue = variable('color.blue', '#006cff');

// These two are equivalent:
const colorPrimary = variable('color.primary', '@color.blue');
// const colorPrimary = variable('color.primary', ref(colorBlue));

export default s;

:root {
    --color--blue: #006cff;
    --color--primary: var(--color--blue);
}

The @ shorthand works anywhere a variable value is accepted, including within selector declaration blocks:

import { styleframe } from 'styleframe';

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

const colorPrimary = variable('color.primary', '#006cff');

selector('.button', {
    backgroundColor: '@color.primary',
});

export default s;

:root {
    --color--primary: #006cff;
}

.button {
    background-color: var(--color--primary);
}

Referencing Variables with Fallback Values

You can also provide a fallback value when referencing a variable. This is useful if you want to ensure a default value is used if the variable is not defined:

import { styleframe } from 'styleframe';

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

const colorSecondary = variable(
    'color.secondary', 
    ref('color.purple', '#ff5733') // Fallback to #ff5733 if not defined
);

export default s;

:root {
    --color--secondary: var(--color--purple, #ff5733);
}

Best Practices

• Use variables for all design tokens (colors, font sizes, spacing, radii, etc.).
• Avoid hardcoding values in selectors, always referencing a variable where possible.
• Group related variables in separate files with composables for clarity (e.g., useColorDesignTokens, useSpacingDesignTokens).
• Document your variable choices for your team — explain why you chose certain values.

FAQ