How the Core Framework Design Token System Is Integrated into Instatic

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. This file declares the custom properties that drive the entire visual system, from fluid type scales to surface hierarchies.

/* 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) 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, 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 and transforms token definitions into CSS custom properties and utility classes.

Entry Points and Configuration

• src/core/framework/index.ts – Re-exports the public API for token generation.
• 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, the system normalizes color slugs and builds both CSS variable blocks and utility classes:

// 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 – Generates spacing variables and utility classes like .p-m and .gap-l.
• src/core/framework/typography.ts – Creates fluid type scale variables and classes such as .text-xl.
• src/core/framework/scale.ts – Handles the mathematical interpolation for responsive values.

Build Orchestration

The src/core/framework/generate.ts module orchestrates the entire process, producing the final 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 invokes the generator functions and concatenates the results:

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

Render Pipeline Injection

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 uses surface, radius, and shadow tokens:

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

// 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 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.
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 automatically produces:

: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 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 bundles tokens into framework.css, injected by 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. 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.

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 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 generates a complete 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 for color palettes, spacing.ts for layout rhythms, and typography.ts for type scales. The main orchestration happens in generate.ts, while index.ts provides the public API consumed by the publisher and build tools.

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