# Instatic's Core Framework Design Tokens for Styling: Complete Reference

> Explore Instatic's Core Framework design tokens for consistent styling. Learn about colors, typography, spacing, and more centralized as CSS custom properties. Ensure unified design across your projects.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: api-reference
- Published: 2026-07-31

---

**Instatic's Core Framework centralizes all visual styling—colors, typography, spacing, radii, and shadows—as CSS custom properties in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css), with enforcement via automated tests that prohibit hard-coded values in components.**

The CoreBunch/Instatic repository implements a strict, token-driven design system that governs every visual aspect of the admin interface and visual editor. By defining all design values as CSS custom properties in a single source file, the Core Framework ensures that UI components remain consistent, themeable, and maintainable across the entire application.

## What Are Core Framework Design Tokens?

Design tokens in Instatic are **CSS custom properties** (variables) that serve as the single source of truth for visual styling. Located in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) (lines 14-202), these tokens encompass every visual primitive from fluid typography scales to semantic state colors. The repository enforces a strict policy—validated by tests such as [`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts) and [`admin-typography-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/admin-typography-token-policy.test.ts)—that requires every component to reference tokens via `var(--token-name)` rather than hard-coded hex, rgb, or pixel values.

## Token Categories in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css)

The Core Framework organizes design tokens into semantic categories. Each category uses fluid scales where appropriate, utilizing `clamp()` functions for responsive typography and spacing.

### Typography Tokens

Typography tokens define a fluid type-scale that mirrors the Core Framework's "text steps." These tokens adapt to viewport width using `clamp()` calculations:

- `--text-xs`, `--text-m`, `--text-xl` — Fluid font sizes ranging from small labels to large headings

### Spacing Tokens

Spacing tokens provide a fluid scale for margins, paddings, gaps, and grid layouts:

- `--space-xs`, `--space-s`, `--space-m`, `--space-l` — Incremental spacing values that scale with viewport size

### Surface Tokens

Surface tokens control background layers for different UI planes:

- `--bg-body` — Main canvas background
- `--bg-surface` — Primary card and panel backgrounds  
- `--bg-surface-2` — Elevated surface layers

### Border Tokens

Border tokens define divider and outline colors with varying emphasis levels:

- `--border-subtle`, `--border-muted`, `--border`, `--border-strong` — Graduated border intensities for different hierarchical needs

### Text Color Tokens

Semantic text colors ensure proper contrast and state communication:

- `--text-bright` — High-emphasis text
- `--text` — Default body text
- `--text-muted`, `--text-subtle` — De-emphasized content
- `--text-disabled` — Inaccessible/inactive state text

### Overlay and Scrim Tokens

Semi-transparent layers for modals, tooltips, and darkening effects:

- `--overlay-5` through `--overlay-90` — Black overlays at various opacity percentages
- `--scrim-10` through `--scrim-90` — Backdrop darkening values

### Identity Accent Tokens

Distinct categorical colors for branding elements like tags and pills:

- `--accent-1` through `--accent-10` — Base accent colors
- `--accent-1-10` through `--accent-10-10` — Alpha variants at 10% opacity

### Semantic State Tokens

Colors for feedback and interactive states:

- `--danger`, `--danger-light`, `--danger-20` — Error states with light and 20% opacity variants
- `--warning` — Warning states
- `--success` — Success states  
- `--info-text` — Informational messaging

### Syntax Highlighting Tokens

Colors for the code editor's GitHub-dark-inspired theme:

- `--syntax-keyword`, `--syntax-string`, `--syntax-comment` — Language-specific token colors

### Chart Tokens

Visualization-specific colors for data representation:

- `--chart-default-tint`, `--chart-series-min`, `--chart-series-max` — Line colors, glows, and track backgrounds

### Radius Tokens

Corner rounding values for different UI primitives:

- `--radius-sm`, `--radius` — Standard corner radii
- `--card-radius`, `--panel-radius`, `--input-radius`, `--tooltip-radius` — Component-specific rounding

### Scrollbar Tokens

Custom scrollbar styling dimensions:

- `--scrollbar-size`, `--scrollbar-radius`, `--scrollbar-track` — Scrollbar geometry and appearance

## How Tokens Are Consumed in Components

The Core Framework employs three primary consumption patterns, ensuring tokens remain the exclusive styling mechanism across the React component library.

### CSS Modules Usage

Component stylesheets reference tokens directly via CSS custom properties. In [`src/ui/components/Button/Button.module.css`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/components/Button/Button.module.css), the implementation follows this pattern:

```css
.button {
  background: var(--bg-surface);
  color: var(--text);
  padding: var(--space-s) var(--space-m);
  border-radius: var(--radius);
}

```

Every [`.module.css`](https://github.com/CoreBunch/Instatic/blob/main/.module.css) file in `src/ui/components/**/*.module.css` must adhere to this token-only convention, importing values from the global scope defined in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css).

### Dynamic Values with Inline Styles

When runtime values are required, components inject tokens as CSS custom properties through inline styles. The `TagPill` component in [`src/ui/components/TagPill/TagPill.tsx`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/components/TagPill/TagPill.tsx) demonstrates this approach:

```tsx
return (
  <span
    className={styles.pill}
    style={{ '--pill-bg': color } as React.CSSProperties}
  />
);

```

The corresponding CSS module then references the injected token:

```css
.pill {
  background: var(--pill-bg);
  color: var(--text-bright);
}

```

### Iframe Token Injection

When the visual editor renders pages inside iframes, the `EditorChromeInjector` copies required root tokens—such as `--chrome-text-subtle` and `--chrome-radius`—onto the iframe's `:root` element. According to [`docs/features/canvas-iframe-per-frame.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/features/canvas-iframe-per-frame.md) (lines 126-134), this ensures embedded pages can safely use Core Framework variables without colliding with the host site's own CSS variables.

## Adding New Design Tokens

Extending the design system requires adherence to a strict three-step workflow:

1. **Define the token** in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) under the appropriate categorical section (e.g., adding a new color under "Identity accents")

2. **Validate via design-token tests** by running `bun test src/__tests__/design-token` — the test suite automatically verifies that the token is referenced only via `var(--*)` syntax

3. **Consume the token** in component CSS modules or inline styles; no additional configuration is required because the global CSS variables are automatically available across the application

## Enforcement and Testing

The Core Framework maintains integrity through automated policy tests. Files like [`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts) scan component stylesheets to detect hard-coded color values or pixel measurements, while [`admin-typography-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/admin-typography-token-policy.test.ts) specifically validates that typography adheres to the fluid type-scale tokens. These tests prevent style drift and ensure that [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) remains the sole authority for visual values.

## Summary

- **Single source of truth**: All design tokens reside in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css), defining colors, typography, spacing, radii, and effects as CSS custom properties.
- **Strict enforcement**: Automated tests in [`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts) prohibit hard-coded values, requiring `var(--token-name)` usage throughout the codebase.
- **Fluid responsiveness**: Typography and spacing tokens use `clamp()` functions for viewport-adaptive scaling without media queries.
- **Multiple consumption patterns**: Components access tokens via CSS Modules, runtime injection through React.CSSProperties, or iframe chrome injection for the visual editor.
- **Extensible workflow**: New tokens require only definition in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) and validation through the design-token test suite.

## Frequently Asked Questions

### Where are Instatic's Core Framework design tokens defined?

All design tokens are defined as CSS custom properties in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) (lines 14-202). This file serves as the centralized registry for every visual value used in the admin interface and visual editor, including colors, typography scales, spacing units, border radii, and semantic state indicators.

### How does the Core Framework prevent developers from using hard-coded values?

The repository includes automated policy tests such as [`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts) and [`admin-typography-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/admin-typography-token-policy.test.ts) that scan component stylesheets. These tests fail if they detect hard-coded hex colors, rgb values, or pixel measurements, enforcing the rule that all styling must reference tokens via `var(--token-name)` syntax.

### Can components use dynamic colors with the token system?

Yes. Components can inject dynamic values at runtime by setting CSS custom properties through inline styles using React.CSSProperties type assertions. The component passes the value as a CSS variable (e.g., `style={{ '--badge-bg': color }}`), and the CSS module references it via `var(--badge-bg)`, maintaining token-based architecture while allowing runtime customization.

### How are design tokens handled in the visual editor's iframe?

The `EditorChromeInjector` utility copies essential root tokens from the parent window into the iframe's `:root` element. As documented in [`docs/features/canvas-iframe-per-frame.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/features/canvas-iframe-per-frame.md), this ensures that content rendered inside the visual editor iframe can access Core Framework variables like `--chrome-text-subtle` without conflicting with the embedded site's own CSS variables.