# How the Core Framework Design Token Engine Integrates with Instatic

> Learn how the Core Framework design token engine integrates with Instatic via a preset-to-CSS pipeline, mapping tokens to utility classes and custom properties for seamless UI integration.

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

---

**The Core Framework design token engine integrates with Instatic through a preset-to-CSS pipeline that maps seed tokens to CSS custom properties and utility classes, storing them in `site.settings.framework` for consumption across the admin UI, visual editor, and published site.**

Instatic embeds the **Core Framework** as a built-in design token engine that drives every visual aspect of the platform. According to the CoreBunch/Instatic source code, this integration follows a strict data-flow from preset configuration to runtime CSS variable consumption. The architecture ensures that seed tokens defined in TypeScript ultimately render as `var(--*)` references in the browser, eliminating external dependencies while maintaining a fluid design system.

## Mapping Core Framework Presets to Instatic Settings

The integration begins in [`src/core/framework/coreFrameworkPreset.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/coreFrameworkPreset.ts), which defines the `CoreFrameworkImportOptions` interface and a set of **seed tokens** called `CORE_COLOR_SEED`. These seeds mirror the default Core Framework project and serve as the immutable foundation for the system.

The exported builder function `buildCoreFrameworkSettings` transforms these seeds into Instatic’s `FrameworkSettings` shape. This object encapsulates colors, typography, spacing, and preferences, bridging the gap between the external framework and Instatic’s internal content model.

```ts
// Import the builder and create a full-utility framework preset
import { buildCoreFrameworkSettings } from '@core/framework';

const framework = buildCoreFrameworkSettings({ includeUtilities: true });

// Assign to the site’s settings (e.g. during site creation)
site.settings.framework = framework;

```

## Generating CSS Variables and Utility Classes

Once the preset is defined, the `generate` pipeline located in [`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts) walks the `FrameworkSettings` object and materializes it into CSS. The critical logic resides in the `genToUtilities` function, which determines whether a token should emit utility classes (`.text-*`, `.bg-*`, `.border-*`) based on the `includeUtilities` flag.

When **variables-only** mode is chosen, only `:root` CSS custom properties are emitted to [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css). When **full** mode is selected, the complete utility set is generated alongside the variables.

```ts
// Switch to variables-only mode (smaller CSS bundle)
import { buildCoreFrameworkSettings } from '@core/framework';

site.settings.framework = buildCoreFrameworkSettings({ includeUtilities: false });

```

## Storing Tokens in the Content Model

The resulting `FrameworkSettings` object is stored under `site.settings.framework`, which is part of Instatic’s unified content model (`data_tables` / `data_rows`). This structured storage allows the **publisher**, **editor**, and **UI primitives** to read token values consistently.

The barrel file at [`src/core/framework/index.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/index.ts) re-exports the builder and type definitions, ensuring the rest of the codebase imports from a single source of truth.

## Consuming Tokens in the UI

UI components reference tokens through standard CSS custom property syntax (e.g., `color: var(--text);`, `background: var(--bg-surface);`). The `generate` pipeline writes these variables into [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css), which acts as the single source of truth for all admin and editor CSS modules.

```css
/* Example of a component using a token */
.button {
  background: var(--bg-surface-2);
  color: var(--text);
  border-radius: var(--radius);
}

```

Framework-generated utility classes and variables are automatically available to the admin UI, the canvas editor, and the published site’s CSS. Specific UI primitives such as those in [`src/ui/railAccent.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/railAccent.ts) and [`src/ui/pillAccent.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/pillAccent.ts) consume these generated tokens (e.g., `--accent-1`) to maintain visual consistency.

## Fluid Scales and Dynamic Updates

Preferences such as root font size, screen breakpoints, and `rem` usage are defined in [`coreFrameworkPreset.ts`](https://github.com/CoreBunch/Instatic/blob/main/coreFrameworkPreset.ts) via `buildCoreFrameworkPreferences`. These drive the fluid type-scale (`--text-*`) and spacing scale (`--space-*`) used throughout the UI.

Because the framework data lives in the content model, editing a token in the **Preferences** panel writes a new `FrameworkSettings` record. The next render of the editor or a publish triggers a rebuild of [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css), instantly reflecting the change across the entire site.

```tsx
// React component that changes a token via Preferences UI
import { useSiteStore } from '@/store';
import { setFrameworkPreferences } from '@core/framework';

function FontSizeSelector() {
  const setPrefs = useSiteStore((s) => s.setFrameworkPreferences);
  return (
    <select onChange={(e) => setPrefs({ rootFontSize: Number(e.target.value) })}>
      <option value={10}>10 px</option>
      <option value={12}>12 px</option>
    </select>
  );
}

```

Runtime helpers in [`src/core/framework/frameworkUsage.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/frameworkUsage.ts) apply the generated framework configuration during publishing and editor rendering, ensuring the active token set is always synchronized with the stored settings.

## Summary

- **[`src/core/framework/coreFrameworkPreset.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/coreFrameworkPreset.ts)** maps Core Framework defaults to Instatic’s `FrameworkSettings` shape, handling color seeds and preferences.
- **`genToUtilities`** and the **generate** pipeline in [`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts) emit CSS custom properties and optional utility classes to [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css) and [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css).
- **Variables** are stored in `site.settings.framework` within the unified content model, accessible throughout the admin UI, editor, and published site via `var(--*)`.
- **Dynamic updates** trigger immediate CSS rebuilds when preferences change, enabling real-time design token editing without external dependencies.

## Frequently Asked Questions

### What file defines the Core Framework seed tokens in Instatic?

The seed tokens are defined in [`src/core/framework/coreFrameworkPreset.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/coreFrameworkPreset.ts). This file exports the `CORE_COLOR_SEED` constant and the `buildCoreFrameworkSettings` function, which transforms Core Framework presets into Instatic’s internal `FrameworkSettings` type.

### How does Instatic decide whether to generate utility classes or just CSS variables?

The decision logic resides in the `genToUtilities` function within [`src/core/framework/coreFrameworkPreset.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/coreFrameworkPreset.ts). When `buildCoreFrameworkSettings` is called with `{ includeUtilities: true }`, the generator emits utility classes (`.text-*`, `.bg-*`, etc.) alongside CSS variables. When set to `false`, only `:root` custom properties are generated, producing a smaller CSS bundle.

### Where are the generated design tokens stored in Instatic's data model?

The tokens are stored under `site.settings.framework` as part of the unified content model utilizing `data_tables` and `data_rows`. This allows the design tokens to be treated as first-class content that can be queried, versioned, and updated through the same API as other site content.

### How does Instatic apply design token changes in real-time?

Because `site.settings.framework` lives in the reactive content model, updating a preference in the UI writes a new `FrameworkSettings` record. The framework usage helpers in [`src/core/framework/frameworkUsage.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/frameworkUsage.ts) detect these changes and trigger a rebuild of [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css), immediately making the new token values available to the editor canvas and published site through updated CSS custom properties.