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

Instatic's Core Framework centralizes all visual styling—colors, typography, spacing, radii, and shadows—as CSS custom properties in 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 (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 and 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

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, the implementation follows this pattern:

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

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

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 demonstrates this approach:

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

The corresponding CSS module then references the injected token:

.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 (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 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 scan component stylesheets to detect hard-coded color values or pixel measurements, while 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 remains the sole authority for visual values.

Summary

• Single source of truth: All design tokens reside in 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 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 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 (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 and 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, 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.

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