How the Core Framework Design Token Engine Integrates with Instatic

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, 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.

// 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 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. When full mode is selected, the complete utility set is generated alongside the variables.

// 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 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, which acts as the single source of truth for all admin and editor CSS modules.

/* 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 and 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 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, instantly reflecting the change across the entire site.

// 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 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 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 emit CSS custom properties and optional utility classes to framework.css and 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. 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. 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 detect these changes and trigger a rebuild of framework.css, immediately making the new token values available to the editor canvas and published site through updated CSS custom properties.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}