Best Practices for Scaling Design Tokens in Instatic CMS

Maintaining visual consistency across dozens of marketing pages is a common challenge for web development teams. Closed visual builders often generate irregular styling values because designers apply custom offsets directly to elements.

Instatic CMS—the MIT licensed open-source visual page builder—resolves this by enforcing a strict class-based style system backed by design tokens. Under the hood, the Bun-powered compiler writes style configurations directly to the database backend (SQLite/PostgreSQL) and outputs static assets with zero framework runtime bloat.

In this guide, we outline best practices for structuring spacing, typography, and color tokens inside Instatic.

The Token Hierarchy Model

To build a design system that scales, structure your styles starting with base design variables and building up to utility classes:

graph TD
    Tokens[Design Tokens: HSL, PX scale] -->|Define| CSSVar[CSS Custom Properties: --accent-500]
    CSSVar -->|Reference| ComponentStyle[Utility Classes: .btn-primary, .card]
    ComponentStyle -->|Apply to| PageElements[DOM Canvas Elements]

By binding your visual selections to custom variables instead of applying static values, you ensure that adjustments to layout variables automatically update throughout the project.

Structuring the Core Selector Scale

When designing in Instatic, follow these rules:

1. Avoid Magic Numbers: Restrict your canvas selections to a spacing scale based on multiples of 4 or 8 (e.g., 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px).
2. Utilize semantic colors: Define your color variables by their function (--bg-surface, --text-ink2, --border-default) rather than visual values (--light-grey). This makes configuring dark mode toggles straightforward.
3. Keep selectors single-responsibility: Instead of building deep, compound classes (e.g., .feature-card-title-bold), combine basic typography styles and element utility wrappers (e.g., .text-h3 and .font-semibold).

Class Selector Auditing Checklist

Before publishing changes, use this class hygiene checklist inside the Selector Manager:

• Ensure all custom classes are prefixed or grouped by category (e.g., btn-, card-, nav-).
• Delete orphaned selectors containing no properties using the Selector Manager.
• Audit responsive styles at desktop, tablet, and mobile breakpoints simultaneously using Instatic’s multi-breakpoint canvas.
• Confirm all color selectors reference CSS variables (var(--...)) instead of static hex values.

Editor Workflow

Watch how class-based styling rules are managed inside the Instatic editor:

Key Takeaways & Alpha Warnings

• Class-Based Consistency: Shared stylesheets prevent page-specific visual regressions.
• Tokens Over Static Styling: Defining custom variables simplifies scaling site updates.
• Selector Cleanliness: Use the Selector Manager regularly to delete unused classes.
• Alpha Warnings: Instatic is currently in early alpha status, so always run layout updates on a local SQLite instance before deploying changes to active production sites.

Instatic CMS Architecture Guides

• Review the underlying Bun and compiler architecture in The Ultimate Architectural Guide to Instatic CMS.
• Compare visual builders in Instatic vs Webflow vs Framer: Which Visual Builder Should You Choose?.