# How to Customize Instatic Core Framework Design Tokens: Complete Guide

> Customize Instatic Core Framework design tokens by editing CSS custom properties in globals.css. Ensure consistent theming by using var(--token-name) across your components.

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

---

**Customize Instatic Core Framework design tokens by modifying the CSS custom properties in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css)—the single source of truth—and consuming them via `var(--<token-name>)` in any component stylesheet to ensure consistent theming across the admin and UI layers.**

Instatic's visual styling is governed by a centralized token system that eliminates magic numbers and hard-coded values. The repository enforces strict architectural gates that require all stylesheets in `src/admin/` and `src/ui/` to reference tokens defined in the global stylesheet. Understanding how to extend and customize these tokens allows you to adapt the framework to new brand requirements while maintaining code quality and visual consistency.

## Where Design Tokens Are Defined

The entire design token catalog lives in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css). This file acts as the single source of truth for every visual value in the framework—from typography scales to z-index layers. Any stylesheet consuming these tokens must reference them via CSS custom properties using `var(--<token-name>)`. Hard-coded colors, fonts, sizes, or radii are explicitly blocked by architectural gate tests, ensuring that [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) remains the authoritative configuration file.

## The Complete Token Taxonomy

The token system is organized into nine logical groups. When you customize Instatic Core Framework design tokens, you must add new properties to the appropriate section to maintain semantic organization.

### Typography

Fluid type-scale tokens (`--text-*`) and base font families (`--font-sans`, `--font-mono`) define the typographic hierarchy across admin interfaces and content editors.

### Spacing

Fluid spacing tokens (`--space-*`) and the fixed hairline `--space-px` control layout density, padding, and component gutters.

### Surfaces and Text

Background surface tones (`--bg-*`), border tones (`--border-*`), and text tones (`--text-*`) implement the two-layer color model for UI surfaces.

### Overlays and Scrims

White overlay alpha series (`--overlay-*`) and black scrim alpha series (`--scrim-*`) handle modal backdrops, loading states, and emphasis layers.

### Identity Accents

Categorical accent colors (`--accent-1` through `--accent-10`) with corresponding 10% tints (`--accent-*-10`) provide brand-specific colorways for categorization and highlights.

### Semantic State

Danger, warning, success, and info palettes (`--danger`, `--warning`, `--success`, `--info-text`) communicate system status and validation states consistently.

### Canvas and Interaction

Selection rings, hover states, tree-drop helpers, and placeholder patterns define interactive affordances throughout the drag-and-drop interfaces.

### Radius and Shadows

Radius scale (`--radius-sm`, `--radius`, `--panel-radius`, etc.) and composite shadow tokens (`--shadow-panel`, `--shadow-input-focus`) control elevation and container shaping.

### Z-Index Layers

Global stacking tokens (`--z-dropdown`, `--tooltip-z-index`, `--toast-z-index`, `--spotlight-z-index`) prevent z-index wars and ensure predictable layering.

## Step-by-Step Customization Workflow

When a new design requirement arises—such as a new brand color, an extra radius step, or a custom z-index layer—follow this standardized workflow:

1. **Pick the correct group** – Locate the appropriate section in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) using the existing comments as guides.
2. **Add the custom property** – Write a one-line definition, optionally including a comment explaining its semantic purpose.
3. **Reference the token** – Use `var(--my-token)` in any CSS module under `src/admin/` or `src/ui/`; the architecture prohibits `!important` or fallback values.
4. **Update documentation** – Add a row to the markdown table in [`docs/reference/design-tokens.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md) so the token appears in generated documentation and passes the `css-token-policy` gate test.

## Working with Theme Overrides

The admin UI supports theme-aware overrides through data attributes. You can provide light-mode values inside the `[data-editor-theme='light']` block of [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css). The same token name is reused in both contexts, keeping component CSS theme-agnostic while allowing contextual value shifts.

## Practical Code Examples

### Adding a New Accent Color

To add a coral accent for a marketing category, edit the Identity Accents block:

```css
/* src/styles/globals.css – Identity accents section */
--accent-11: #ff7f50;           /* coral – marketing accent */
--accent-11-10: rgba(255,127,80,0.1);

```

Consume the token in a component module:

```css
/* src/ui/components/Widget/Widget.module.css */
.widgetMarketing {
  background: var(--accent-11-10);
  border: 1px solid var(--accent-11);
  color: var(--text);
}

```

Override for the light theme:

```css
/* src/styles/globals.css – Light theme block */
[data-editor-theme='light'] {
  --accent-11: #c14400;        /* darker coral for light surfaces */
  --accent-11-10: rgba(193,68,0,0.1);
}

```

### Adding a Radius Step

For ultra-rounded, pill-shaped buttons:

```css
/* src/styles/globals.css – Radius section */
--radius-xl: 24px;   /* extra-large radius for pill-shaped controls */

```

```css
/* src/ui/components/Button/Button.module.css */
.buttonPill {
  border-radius: var(--radius-xl);
}

```

### Adding a Custom Z-Index Layer

When introducing a new modal tier:

```css
/* src/styles/globals.css – Z-index section */
--modal-extra-z-index: 9500;

```

```css
/* src/ui/components/Modal/Modal.module.css */
.modalExtra {
  z-index: var(--modal-extra-z-index);
}

```

## Enforcement and Compliance

The repository maintains strict architectural standards through gate tests located in [`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts). These tests scan CSS modules for hard-coded values—such as hex codes, pixel values, or z-index integers—and fail the build if tokens are not used. This enforcement guarantees that customizing Instatic Core Framework design tokens in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) remains the only valid path for visual changes.

## Key Files Reference

- **[`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css)** – Central design-token definition (source of truth)
- **[`docs/reference/design-tokens.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md)** – Human-readable token catalog, kept in sync with the CSS file
- **`src/ui/components/`** – UI primitives consuming tokens via `*.module.css` files
- **`src/admin/pages/site/`** – Admin component styles consuming tokens
- **[`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts)** – Gate tests enforcing token usage

## Summary

- **Edit [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css)** to modify existing tokens or add new custom properties to the appropriate taxonomy group.
- **Reference tokens exclusively** via `var(--<token-name>)` in component stylesheets; hard-coded values trigger build failures.
- **Use `[data-editor-theme='light']` blocks** in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) for theme-specific overrides without changing component code.
- **Update [`docs/reference/design-tokens.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md)** whenever adding new tokens to maintain documentation parity and pass gate tests.
- **Gate tests enforce compliance**—the `css-token-policy` test suite ensures the token system remains the single source of truth.

## Frequently Asked Questions

### Where are Instatic 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). This file serves as the single source of truth for the entire application, including admin interfaces and UI primitives.

### How do I add a new color token to Instatic?

Add a CSS custom property to the appropriate section in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css)—such as the Identity Accents or Semantic State blocks—then reference it via `var(--your-token)` in your component's CSS module. Remember to document the new token in [`docs/reference/design-tokens.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md).

### Can I use hard-coded values instead of design tokens?

No. The repository includes architectural gate tests in [`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts) that specifically scan for hard-coded values like hex codes or pixel measurements. Builds will fail if stylesheets do not use the token system.

### How do I create light-mode specific token values?

Override the token inside the `[data-editor-theme='light']` block within [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css). Component stylesheets remain unchanged because they reference the token name (e.g., `var(--accent-11)`), while the runtime value swaps based on the data attribute present on the editor container.