How to Customize Instatic Core Framework Design Tokens: Complete Guide

Customize Instatic Core Framework design tokens by modifying the CSS custom properties in 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. 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 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 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 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. 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:

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

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

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

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

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

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

/* 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. 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 remains the only valid path for visual changes.

Key Files Reference

• src/styles/globals.css – Central design-token definition (source of truth)
• 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 – Gate tests enforcing token usage

Summary

• Edit 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 for theme-specific overrides without changing component code.
• Update 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. 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—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.

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

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