Design Tokens

Design Tokens Overview

Explore Styleframe's comprehensive design token system. Create consistent, scalable design systems with composable functions for colors, typography, spacing, and more.

Design tokens are the foundation of any robust design system. They represent the visual design atoms of your application — the smallest, indivisible design decisions like colors, spacing values, typography scales, and more.

Styleframe's design token composables make it easy to create, manage, and scale these foundational elements with full type safety and minimal code.

Why Use Design Token Composables?

Styleframe's approach to design tokens offers several key advantages:

Automatic Variant Generation: Define base values and automatically generate tints, shades, and scale-based variants
Mathematical Consistency: Use proven ratios from music theory and mathematics for harmonious proportions
Type Safety: Full TypeScript support with auto-complete for all design token values
Flexible Theming: Override any token to create themes without rewriting your entire design system
Modern CSS: Leverages OKLCH color space, CSS custom properties, and relative color syntax
Composable: Mix and match composables to build exactly the design system you need

Quick Start

Here's a minimal example showing how design tokens work together:

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useColor, useSpacing, useFontSize } from '@styleframe/theme';

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

// Define base design tokens
const { colorPrimary } = useColor(s, { primary: '#006cff' } as const);
const { spacing } = useSpacing(s, { default: '1rem' } as const);
const { fontSize } = useFontSize(s, { default: '1rem' } as const);

// Use in your styles
selector('.button', {
    backgroundColor: ref(colorPrimary),
    padding: ref(spacing),
    fontSize: ref(fontSize),
});

export default s;

Composables

These composables form the core of your design system, providing the base values that other systems build upon.

Borders

Create comprehensive border systems with styles, widths, and colors.

Available composables:

useBorderStyle(): Define border styles (solid, dashed, dotted, etc.)
useBorderWidth(): Create border width values (thin, medium, thick)
useBorderColor(): Define semantic border colors that reference your color system

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useBorderStyle, useBorderWidth, useBorderColor, useColor } from '@styleframe/theme';

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

// Define colors first
const { colorPrimary } = useColor(s, { primary: '#006cff' } as const);
const { colorGray300 } = useColor(s, { gray300: '#d1d5db' } as const);

const { borderStyle, borderStyleDashed } = useBorderStyle(s);
const { borderWidth, borderWidthThin } = useBorderWidth(s);

// Border colors that reference your color system
const { borderColor, borderColorPrimary } = useBorderColor(s, {
    default: ref(colorGray300),
    primary: ref(colorPrimary),
} as const);

Learn more about Borders →

Border Radiuses

Create consistent rounded corner systems with mathematically harmonious scales.

Available composables:

useBorderRadius(): Define border radius values for rounded corners and circular elements

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useBorderRadius, useScale, useScalePowers, useMultiplier } from '@styleframe/theme';

const s = styleframe();

// Define base border radius
const { 
    borderRadius,
    borderRadiusFull,
} = useBorderRadius(s, { 
    default: '0.375rem',
    full: '9999px',        // Circular
});

// Or create a scale-based system for harmonious progressions
const { scale } = useScale(s);
const scalePowers = useScalePowers(s, scale);

const {
    borderRadiusSm,
    borderRadiusMd,
    borderRadiusLg,
} = useMultiplier(s, borderRadius, {
    sm: scalePowers[-1],   // Smaller corners
    md: scalePowers[0],    // Base corners
    lg: scalePowers[1],    // Larger corners
});

Learn more about Border Radiuses →

Box Shadows

Define elevation systems using carefully crafted shadow values for visual hierarchy.

Available composables:

useBoxShadow(): Create box shadow variables for different elevation levels

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useBoxShadow } from '@styleframe/theme';

const s = styleframe();

const {
    boxShadow,     // Default shadow
    boxShadowSm,   // Subtle elevation
    boxShadowMd,   // Standard elevation
    boxShadowLg,   // High elevation
    boxShadowXl,   // Maximum elevation
} = useBoxShadow(s);

Learn more about Box Shadows →

Breakpoints

Define responsive breakpoints for consistent media query behavior across your application.

Available composables:

useBreakpoint(): Create breakpoint variables for media queries

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useBreakpoint } from '@styleframe/theme';

const s = styleframe();

const { breakpointSm, breakpointMd, breakpointLg } = useBreakpoint(s, {
    sm: 576,
    md: 992,
    lg: 1200,
} as const);

const { media } = s;

// Use in media queries
media(`(min-width: ${breakpointMd.value}px)`, ({ selector }) => {
    selector('.container', {
        maxWidth: '960px',
    });
});

Learn more about Breakpoints →

Colors

Create comprehensive color systems with automatic variant generation using the OKLCH color space for perceptually uniform variations.

Available composables:

useColor(): Define base colors from hex, rgb, or any CSS color format
useColorLightness(): Generate lightness levels (e.g., 50, 100, 200...950)
useColorShade(): Create darker variants by subtracting lightness
useColorTint(): Create lighter variants by adding lightness

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useColor, useColorLightness } from '@styleframe/theme';

const s = styleframe();

const { colorPrimary } = useColor(s, { primary: '#006cff' } as const);

// Generate full lightness scale automatically
const {
    colorPrimary50,   // 5% lightness
    colorPrimary500,  // 50% lightness
    colorPrimary950,  // 95% lightness
} = useColorLightness(s, colorPrimary);

Learn more about Colors →

Fluid Design

Create fluid typography and spacing that scales smoothly across all viewport sizes without breakpoints. Based on the Utopia fluid type scale, this system uses mathematical precision and CSS calc() functions to create seamless transitions between minimum and maximum values.

Available composables:

useFluidViewport(): Define viewport range (min/max widths) and calculate the fluid breakpoint variable
useFluidClamp(): Generate fluid calc() calculations for any CSS property
useFluidFontSize(): Create complete fluid typography systems with modular scales

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useScale, useScalePowers } from '@styleframe/theme';
import { useFluidViewport, useFluidFontSize } from '@styleframe/pro';

const s = styleframe();

// Set up fluid viewport range (320px - 1440px)
useFluidViewport(s);

// Define scales for mobile and desktop
const { scaleMin, scaleMax } = useScale(s, { 
    min: '@minor-third',   // 1.2 ratio for mobile
    max: '@major-third'    // 1.25 ratio for desktop
});

// Calculate scale powers
const scaleMinPowers = useScalePowers(s, scaleMin);
const scaleMaxPowers = useScalePowers(s, scaleMax);

// Generate fluid font sizes that scale smoothly
const { fontSize, fontSizeSm, fontSizeMd, fontSizeLg } = useFluidFontSize(s, 
    { min: 16, max: 18 },  // Base font size range
    {
        sm: { min: scaleMinPowers[-1], max: scaleMaxPowers[-1] },
        md: { min: scaleMinPowers[0], max: scaleMaxPowers[0] },
        lg: { min: scaleMinPowers[1], max: scaleMaxPowers[1] },
        default: '@md'
    }
);

Learn more about Fluid Design →

Scales

Create harmonious proportional systems using mathematical ratios based on musical intervals and the golden ratio.

Available composables:

useScale(): Define scale ratios (Minor Third, Perfect Fourth, Golden Ratio, etc.)
useScalePowers(): Generate size multipliers by raising scales to powers
useMultiplier(): Create variable sets by multiplying base values by scale powers

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useScale, useScalePowers, useMultiplier } from '@styleframe/theme';

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

const { scale } = useScale(s);
const scalePowers = useScalePowers(s, scale);

const fontSize = variable('font-size', '1rem');

// Automatically generate proportional sizes
const { fontSizeSm, fontSizeMd, fontSizeLg } = useMultiplier(s, fontSize, {
    sm: scalePowers[-1],  // Smaller than base
    md: scalePowers[0],  // Base size
    lg: scalePowers[1],   // Larger than base
});

Learn more about Scales →

Spacing

Define consistent spacing systems for margins, padding, gaps, and layout spacing.

Available composables:

useSpacing(): Create spacing variables from explicit values or scale-based systems

styleframe.config.ts

import { styleframe } from 'styleframe';
import { useSpacing } from '@styleframe/theme';

const s = styleframe();

const { spacing } = useSpacing(s, { default: '1rem' } as const);

Learn more about Spacing →

Typography

Comprehensive typography composables for creating consistent text styles throughout your application.

Available composables:

useFontFamily(): Define font family stacks (base, mono, serif, display)
useFontSize(): Create font size scales (works great with useMultiplier())
useFontWeight(): Define font weight values (light, normal, bold, etc.)
useFontStyle(): Create font style variables (normal, italic, oblique)
useLineHeight(): Define line height values for optimal readability
useLetterSpacing(): Create letter spacing (tracking) variables

styleframe.config.ts

import { styleframe } from 'styleframe';
import {
    useFontFamily,
    useFontSize,
    useFontWeight,
    useLineHeight
} from '@styleframe/theme';

const s = styleframe();

const { fontFamily, fontFamilyMono } = useFontFamily(s);
const { fontSize } = useFontSize(s, { default: '1rem' });
const { fontWeightNormal, fontWeightBold } = useFontWeight(s);
const { lineHeightTight, lineHeightNormal } = useLineHeight(s);

Learn more about Typography →

Design Token Reference

Category	Composables	Purpose
Colors	`useColor`, `useColorLightness`, `useColorShade`, `useColorTint`	Define colors and generate variants
Scales	`useScale`, `useScalePowers`, `useMultiplier`	Create proportional systems
Spacing	`useSpacing`	Define layout spacing
Breakpoints	`useBreakpoint`	Responsive design breakpoints
Typography	`useFontFamily`, `useFontSize`, `useFontWeight`, `useFontStyle`, `useLineHeight`, `useLetterSpacing`	Complete type systems
Borders	`useBorderStyle`, `useBorderWidth`, `useBorderColor`	Border design tokens
Border Radiuses	`useBorderRadius`	Rounded corners and curves
Shadows	`useBoxShadow`	Elevation and depth
Fluid	`useFluidTypography` 🚧	Viewport-responsive sizing

Best Practices

Start with foundation tokens: Define colors and scales first, then build typography and spacing on top
Use the default key: Creates clean variable names like --spacing instead of --spacing--default
Leverage scales for consistency: Use modular scales for harmonious proportions across typography and spacing
Keep token counts reasonable: 5-8 options per category prevents decision paralysis
Use as const: Ensures TypeScript infers correct return types for better autocomplete
Integrate with themes: Design tokens work seamlessly with Styleframe's theme system
Combine composables: Mix and match to create exactly the system you need
Document your decisions: Explain why you chose specific ratios, colors, or scales

Next Steps

Ready to build your design system? Start with these guides:

New to design tokens? Begin with Colors and Spacing
Building a type system? Check out Typography and Scales
Creating visual hierarchy? Explore Box Shadows and Borders
Working on responsive design? Learn about Breakpoints

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

Edit this pageorReport an issue

Guides

Step-by-step tutorials and practical examples to help you get the most out of Styleframe

Borders

Create and manage border design tokens with CSS variables for consistent border styles, widths, and colors across your application.