# How the Core Framework Design Token System Is Integrated into Instatic

> Learn how Instatic integrates the Core Framework design token system. Discover token definition CSS generation utilities and injection into admin UI and static sites.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: how-to-guide
- Published: 2026-07-27

---

**Instatic consumes the Core Framework design token system by defining tokens in a single CSS file, generating framework-wide variables and utility classes through a TypeScript build pipeline, and injecting them into both the admin UI and published static sites.**

The CoreBunch/Instatic repository implements a unified design language where every visual value—colors, spacing, typography—originates from centralized token definitions. This architecture ensures consistency across the visual editor, administrative interface, and final exported static sites while enforcing strict architectural policies that prevent hard-coded values.

## Token Definitions and the Single Source of Truth

All design tokens live exclusively in **[`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css)**. This file declares the custom properties that drive the entire visual system, from fluid type scales to surface hierarchies.

```css
/* src/styles/globals.css */
--font-sans: "Inter Variable", system-ui, sans-serif;
--text-s: 11px → 12px;           /* fluid type scale */
--space-m: 8px → 10px;           /* fluid spacing */
--bg-surface-2: #282828;        /* surface hierarchy */
--accent-4: #ffc7a8;            /* identity accent */

```

The **[[`docs/reference/design-tokens.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md)](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md)** documentation enforces a critical architectural rule: every CSS module across the admin UI and visual editor must reference tokens via `var(--*)` rather than raw hexadecimal or pixel values. This policy is automatically verified by **[`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts)**, which fails the build if any hard-coded values are detected.

## Framework Engine Architecture

The Core Framework generation logic resides under `src/core/framework/`. The engine parses [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) and transforms token definitions into CSS custom properties and utility classes.

### Entry Points and Configuration

- **[`src/core/framework/index.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/index.ts)** – Re-exports the public API for token generation.
- **[`src/core/framework/describe.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/describe.ts)** – Acts as the "single source of truth for what design tokens this site exposes", defining the contract between the source definitions and generated output.

### Color Token Generation

In **[`src/core/framework/colors.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/colors.ts)**, the system normalizes color slugs and builds both CSS variable blocks and utility classes:

```ts
// src/core/framework/colors.ts
export function generateFrameworkColorVariableSets(settings) {
  // Generates :root variable blocks from globals.css definitions
}

export function generateFrameworkColorUtilityClasses(settings) {
  // Creates .text-primary, .bg-primary-10, etc.
}

```

### Spacing and Typography Scale

Fluid design tokens are processed by complementary modules:
- **[`src/core/framework/spacing.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/spacing.ts)** – Generates spacing variables and utility classes like `.p-m` and `.gap-l`.
- **[`src/core/framework/typography.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/typography.ts)** – Creates fluid type scale variables and classes such as `.text-xl`.
- **[`src/core/framework/scale.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/scale.ts)** – Handles the mathematical interpolation for responsive values.

### Build Orchestration

The **[`src/core/framework/generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/framework/generate.ts)** module orchestrates the entire process, producing the final [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css) bundle that contains all custom property definitions and utility classes ready for consumption.

## Publishing Pipeline Integration

When publishing a site, the Core Framework tokens must appear in the final CSS bundle without requiring runtime JavaScript.

### Framework CSS Generation

**[`src/core/publisher/frameworkCss.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/publisher/frameworkCss.ts)** invokes the generator functions and concatenates the results:

```ts
// src/core/publisher/frameworkCss.ts
const frameworkCss = generateFrameworkCss(site);
return [fontsCss, frameworkCss];

```

### Render Pipeline Injection

**[`src/core/publisher/render.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/publisher/render.ts)** inserts the CSS bundles in a strict order to ensure correct cascade:

1. Reset styles
2. **Framework CSS** (design tokens and utilities)
3. Module-specific styles
4. User custom styles

This injection strategy allows published pages to reference tokens directly via `var(--text-s)` or apply utility classes like `class="text-primary"` without any additional runtime overhead.

## Admin UI and Visual Editor Consumption

The administrative interface and visual editor consume the same token system through CSS Modules, ensuring the editing chrome matches the published site appearance.

### Component-Level Usage

UI primitives reference tokens directly in their module files. For example, **[`src/ui/components/Button/Button.module.css`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/components/Button/Button.module.css)** uses surface, radius, and shadow tokens:

```css
/* src/ui/components/Button/Button.module.css */
background: var(--bg-surface-2);
border-radius: var(--radius);
box-shadow: var(--shadow-panel);

```

Similarly, **[`src/ui/components/Spacing/Spacing.module.css`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/components/Spacing/Spacing.module.css)** relies on spacing tokens like `var(--space-m)` to maintain consistent rhythm across layout components.

### Visual Editor Integration

The visual editor toolbar located at **[`src/admin/pages/site/toolbar/Toolbar.module.css`](https://github.com/CoreBunch/Instatic/blob/main/src/admin/pages/site/toolbar/Toolbar.module.css)** imports the same tokens, ensuring the editing interface visually aligns with the site being edited. Components can also access tokens dynamically via CSS-in-JS:

```ts
// src/admin/pages/site/toolbar/Toolbar.tsx
import { css } from '@linaria/core';

const toolbarStyle = css`
  background: var(--bg-surface);
  border-bottom: 1px solid var(--border);
`;

```

## Workflow for Adding New Tokens

Extending the design system follows a standardized three-step process:

1. **Define the token** in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) within the appropriate group (colors, spacing, typography, etc.).
2. **Rebuild the framework** using `bun run build`. The generator automatically creates the corresponding `:root` variable and utility classes in [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css).
3. **Reference the token** in any CSS module via `var(--my-token)` or use the generated utility class (`class="my-token"`). No additional TypeScript or configuration changes are required.

For example, adding `--brand-primary: #1e90ff;` to [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) automatically produces:

```css
:root { --brand-primary: #1e90ff; }
.text-brand-primary { color: var(--brand-primary); }
.bg-brand-primary { background: var(--brand-primary); }
.border-brand-primary { border-color: var(--brand-primary); }

```

## Summary

- **Single source of truth**: All tokens are defined in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) with strict architectural enforcement via automated tests.
- **Automated generation**: The Core Framework engine (`src/core/framework/`) transforms token definitions into CSS custom properties and utility classes.
- **Publishing integration**: [`src/core/publisher/frameworkCss.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/publisher/frameworkCss.ts) bundles tokens into [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css), injected by [`render.ts`](https://github.com/CoreBunch/Instatic/blob/main/render.ts) into every published site.
- **Unified consumption**: Both the admin UI (`src/ui/components/`) and visual editor (`src/admin/pages/`) consume tokens through CSS Modules, ensuring visual consistency.
- **Zero-runtime overhead**: Published sites use static CSS variables and classes without requiring JavaScript token resolution.

## Frequently Asked Questions

### How does Instatic enforce that developers only use design tokens?

Instatic enforces token usage through an architectural test suite located at **[`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts)**. This test scans all CSS modules and fails the build if it detects hard-coded color values, pixel values, or other raw CSS declarations that should instead reference the centralized tokens in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css).

### Can I use design tokens in dynamic TypeScript components?

Yes. While the primary consumption method is through CSS Modules using `var(--token-name)`, you can also reference tokens in CSS-in-JS solutions. The [`src/admin/pages/site/toolbar/Toolbar.tsx`](https://github.com/CoreBunch/Instatic/blob/main/src/admin/pages/site/toolbar/Toolbar.tsx) example demonstrates using `@linaria/core` to interpolate token variables directly into styled components, maintaining type safety and token consistency.

### What happens to unused tokens when I publish a site?

The publishing pipeline in **[`src/core/publisher/frameworkCss.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/publisher/frameworkCss.ts)** generates a complete [`framework.css`](https://github.com/CoreBunch/Instatic/blob/main/framework.css) bundle containing all token definitions and utility classes defined in the Core Framework. Currently, the system generates the full token set regardless of usage to ensure that dynamic content or future edits remain styled correctly without requiring republishing.

### Where is the Core Framework token generation code located?

The token generation engine lives under **`src/core/framework/`**, with specific modules handling different token categories: [`colors.ts`](https://github.com/CoreBunch/Instatic/blob/main/colors.ts) for color palettes, [`spacing.ts`](https://github.com/CoreBunch/Instatic/blob/main/spacing.ts) for layout rhythms, and [`typography.ts`](https://github.com/CoreBunch/Instatic/blob/main/typography.ts) for type scales. The main orchestration happens in [`generate.ts`](https://github.com/CoreBunch/Instatic/blob/main/generate.ts), while [`index.ts`](https://github.com/CoreBunch/Instatic/blob/main/index.ts) provides the public API consumed by the publisher and build tools.