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

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, 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 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, 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) acts as a thin adapter over 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 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. 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.

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

// 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>

// 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 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, typography.ts, spacing.ts) that plug into the shared 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. 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 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.

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