# How Core Framework Integration Generates Design Tokens and Utility Classes in Instatic

> Discover how Instatic's Core Framework integration generates design tokens and utility classes. Learn how settings convert to CSS custom properties for consistent output.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: internals
- Published: 2026-07-28

---

**The Core Framework integration in Instatic converts user-defined design settings into CSS custom properties and utility classes through a centralized pipeline orchestrated by `buildFrameworkPlan`, ensuring byte-identical output between the `:root` variable block and locked utility definitions.**

Instatic leverages the Core Framework to transform site-specific design configurations—colors, typography, and spacing—into optimized CSS outputs. This **Core Framework integration** generates design tokens and utility classes through a sophisticated compilation pipeline that guarantees consistency between static stylesheets and dynamically injected page styles. The process centers on [`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts), where user preferences are resolved and converted into two distinct CSS artifacts.

## The Dual CSS Output Architecture

The generation system produces two complementary CSS structures that power every published Instatic site.

### CSS Custom Properties in :root

The framework emits a comprehensive `:root` variable block containing CSS custom properties for every design token. This includes definitions like `--text-xs`, `--color-primary`, and responsive color-theme overrides. The `generateFrameworkRootCss` function in [`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts) constructs this block by composing variable sets from specialized generators: `generateFrameworkColorVariableSets`, `generateFrameworkTypographyVariables`, and `generateFrameworkSpacingVariables`. To ensure deterministic output, `composeFrameworkRootCss` orchestrates the assembly, maintaining byte-identical results across separate generation calls.

### Locked Utility Classes

Alongside the variable block, the system generates a flat map of utility classes that reference these custom properties. These one-off definitions—such as `.text-xs { font-size: var(--text-xs); }`—are produced by `generateFrameworkUtilityClasses`, which merges utility maps from each design family via `generateFrameworkColorUtilityClasses`, `generateFrameworkTypographyUtilityClasses`, and `generateFrameworkSpacingUtilityClasses`. The result is a `Record<string, StyleRule>` object that the publisher injects directly into the page's `<style>` block.

## The Generation Pipeline Orchestration

The entire compilation process is managed by **`buildFrameworkPlan`**, which serves as the central dispatcher for token generation.

First, the pipeline invokes `resolveFrameworkPreferences` to normalize user settings. Then it executes family-specific plan functions:

1. `generateFrameworkColorPlan` → constructs a `FrameworkColorPlan` containing color variable sets and utility classes.
2. `generateFrameworkTypographyPlan` → builds typography variable lists and corresponding utilities using the shared scale engine.
3. `generateFrameworkSpacingPlan` → generates spacing tokens and utility mappings.

All families share a **single ordered token enumeration**, ensuring that expensive operations—sorting, slug deduplication, and variant expansion—execute only once per generation cycle. This synchronization guarantees that the `:root` block and utility classes remain perfectly aligned.

## Token Generation by Design Family

Each design domain implements specialized logic while adhering to the shared pipeline architecture.

### Color Token Processing

Located in [`src/core/framework/colors.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/colors.ts), the color system uses `planColorTokens` to sort and deduplicate tokens, build slug maps, and expand color variants. The function emits two critical structures: `FrameworkColorVariableSets` for the `:root` block via `colorVariableSetsFromPlan`, and utility class definitions through `colorUtilityClassesFromPlan`.

### Typography Scaling

The typography module ([`src/core/framework/typography.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/typography.ts)) acts as a thin adapter over [`src/core/framework/scaleModule.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/scaleModule.ts). It supplies family-specific callbacks—`getMinBaseSize`, `getMaxBaseSize`, and others—to the shared scale engine, which calculates fluid clamp values for responsive typography. This yields both CSS variables and corresponding utility classes like `.text-xs` and `.text-lg`.

### Spacing Systems

Following the typography pattern, [`src/core/framework/spacing.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/spacing.ts) utilizes the shared scale module to emit `--space-*` variables and `.space-*` utility classes. This ensures consistent mathematical scaling across both typography and spatial design tokens.

## Publishing Integration and Runtime Usage

During the **publish** phase, the server invokes `buildFrameworkPlan` via the publisher API defined in [`src/core/framework/frameworkUsage.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/frameworkUsage.ts). The resulting `rootCss` is written into the static stylesheet, while the `utilityClasses` map is serialized and injected into the page's `<style>` element. This dual-output approach ensures that published pages remain byte-compatible with Core Framework stylesheets configured with identical settings.

```typescript
// Example: generate the full framework CSS for a given site configuration
import { buildFrameworkPlan } from '@core/framework';

// `siteSettings` comes from the persisted site document
const plan = buildFrameworkPlan(siteSettings.framework);
const css = `${plan.rootCss}\n${Object.values(plan.utilityClasses)
  .map((rule) => `${rule.selector} { ${rule.declarations} }`)
  .join('\n')}`;

// `css` can now be written to the published stylesheet.

```

```typescript
// Example: only the utility classes (e.g. for an on-the-fly preview)
import { generateFrameworkUtilityClasses } from '@core/framework';

const utilities = generateFrameworkUtilityClasses(siteSettings.framework);
// `utilities` is a Record<string, StyleRule>

```

```typescript
// Example: custom color token handling (inside `colors.ts`)
const plan = planColorTokens(settings);
const variableSets = colorVariableSetsFromPlan(plan);
const utilityClasses = colorUtilityClassesFromPlan(plan);

```

## Summary

- **Dual Output System**: The Core Framework generates both a `:root` CSS variable block and a map of locked utility classes to ensure design token consistency across the application.
- **Centralized Orchestration**: `buildFrameworkPlan` in [`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts) coordinates token generation across colors, typography, and spacing via family-specific plan functions.
- **Shared Enumeration**: A single ordered token enumeration across all families prevents duplication of expensive sorting and slug resolution operations.
- **Modular Architecture**: Color, typography, and spacing each have dedicated modules ([`colors.ts`](https://github.com/CoreBunch/Instatic/blob/main/colors.ts), [`typography.ts`](https://github.com/CoreBunch/Instatic/blob/main/typography.ts), [`spacing.ts`](https://github.com/CoreBunch/Instatic/blob/main/spacing.ts)) that plug into the shared [`scaleModule.ts`](https://github.com/CoreBunch/Instatic/blob/main/scaleModule.ts) engine.
- **Publishing Integration**: The publisher consumes `rootCss` for static stylesheets and the `utilityClasses` record for dynamic injection, maintaining byte-compatibility across environments.

## Frequently Asked Questions

### What is the role of `buildFrameworkPlan` in the Core Framework integration?

`buildFrameworkPlan` serves as the central orchestrator that coordinates the entire design token generation pipeline. It resolves user preferences via `resolveFrameworkPreferences`, then delegates to specialized plan functions for colors, typography, and spacing to produce a unified `FrameworkPlan` containing both the `:root` CSS and utility class definitions.

### How does Instatic ensure that CSS variables and utility classes stay synchronized?

The framework uses a **single ordered token enumeration** shared across all design families. This ensures that sorting, slug deduplication, and variant expansion occur exactly once per generation cycle, guaranteeing that the variable names in the `:root` block match the `var()` references inside the utility classes.

### Where are the color design tokens processed in the source code?

Color token processing is handled in [`src/core/framework/colors.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/colors.ts). The module exports `planColorTokens` for token planning, `colorVariableSetsFromPlan` for generating CSS custom properties, and `colorUtilityClassesFromPlan` for creating the corresponding utility class definitions.

### Can utility classes be generated independently of the full CSS root block?

Yes, the `generateFrameworkUtilityClasses` function in [`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts) allows independent generation of the utility class map. This is particularly useful for on-the-fly previews or dynamic rendering scenarios where you need the class definitions without regenerating the entire `:root` variable block.