How CSS Custom Properties Are Organized in Instatic's globals.css

Instatic's design system uses a single source of truth in src/styles/globals.css where flat, purpose-grouped CSS custom properties follow strict naming conventions for typography, spacing, colors, overlays, and accents.

The Instatic repository implements a token-based architecture that centralizes all visual design decisions in one global stylesheet. Understanding how these CSS custom properties are structured allows developers to maintain consistency across components without hard-coding values. Every variable uses the -- prefix and follows a flat hierarchy, making them predictable and easy to reference throughout the React-based UI components.

Typography Tokens

Font Families

The foundation starts with font stack definitions that establish the sans-serif and monospace families used across the application. According to the Instatic source code, these are declared at lines 21–22 in src/styles/globals.css:

• --font-sans sets the primary typeface for UI text
• --font-mono defines the monospace stack for code and data display

Responsive Type Scale

Instatic implements a fluid type scale using CSS clamp() functions that scale automatically with viewport width. The system provides two naming patterns for each size (xs, s, m, l, xl, 2xl through 7xl):

• -base variants contain the raw clamp calculations
• Plain size tokens serve as the public API for components

These definitions occupy lines 26–51 in src/styles/globals.css, ensuring text remains readable across devices without media query breakpoints.

Spacing System

The spacing layer follows a geometric progression from px to 12xl, all implemented with fluid clamp() values for responsive margins and paddings. As defined in lines 54–73 of src/styles/globals.css:

• --space-px provides a hard 1-pixel fallback for hairline borders
• --space-4xs through --space-12xl create a consistent rhythm that mirrors the type scale

This approach allows components like cards and grids to maintain proportional breathing room whether viewed on mobile or desktop displays.

Color Hierarchy

Background and Border Colors

Surface colors follow a numbered hierarchy while borders use semantic intensity names. Lines 76–87 in src/styles/globals.css define:

• Backgrounds: --bg-body, --bg-surface, --bg-surface-2 through --bg-surface-5 for layered depth
• Borders: --border-subtle, --border-muted, --border, and --border-strong for varying emphasis

Text Colors

Five levels of text contrast support accessibility and information hierarchy. Lines 90–94 expose:

• --text-bright for high-contrast headings
• --text for primary body content
• --text-muted, --text-subtle, and --text-disabled for secondary and inactive states

Overlays and Scrims

For modal backdrops and focus states, Instatic provides semi-transparent layers in 10% increments. These variables appear at lines 97–119:

• Overlays (--overlay through --overlay-90): White-based translucency for light-mode scrims
• Scrims (--scrim through --scrim-90): Black-based darkness for overlays and shadows

Accent Palette

The interactive color system consists of eight curated accent colors plus opacity variants. Defined at lines 122–137:

• --accent-1 through --accent-8 for brand and action colors
• --accent-X-10 variants providing 10% opacity versions for hover states and subtle backgrounds

Practical Usage Examples

Components consume these tokens directly without fallback values, assuming the global stylesheet is always loaded:

/* Responsive typography */
.article-title {
  font-size: var(--text-2xl);
}

/* Fluid spacing */
.card {
  margin: var(--space-m);
  padding: var(--space-l);
}

/* Surface layering */
.panel {
  background: var(--bg-surface-2);
  border: 1px solid var(--border-subtle);
}

/* Text hierarchy */
.caption {
  color: var(--text-muted);
}

/* Modal backdrop */
.modal-overlay {
  background: var(--scrim-60);
}

/* Brand accent with transparency */
.tag-highlight {
  background: var(--accent-4-10);
  color: var(--accent-4);
}

Summary

• Single source of truth: All design tokens live in src/styles/globals.css with flat -- prefixed variables
• Fluid by default: Typography and spacing use clamp() for intrinsic responsiveness without media queries
• Semantic naming: Colors use functional names (bg-surface, text-muted) rather than hex values or emotional labels
• Systematic opacity: Overlays, scrims, and accents provide 10% increment variants for consistent translucency
• Component agnostic: Tokens are defined independently of React components, enabling theme changes by modifying one file

Frequently Asked Questions

What naming convention does Instatic use for CSS custom properties?

Instatic uses a flat naming structure with lowercase kebab-case and double-dash prefixes. Typography uses --text-{size}, spacing uses --space-{scale}, and colors use --{property}-{variant} patterns (e.g., --bg-surface-3, --border-strong). This convention appears consistently across lines 21–137 of src/styles/globals.css.

How does Instatic handle responsive font sizing without media queries?

The repository leverages CSS clamp() functions within custom properties. Each text size token (like --text-m or --text-xl) contains a clamp(min, preferred, max) calculation that scales fluidly between minimum and maximum viewport widths, eliminating the need for breakpoint-specific overrides.

Where are the 10% opacity accent colors defined?

Translucent accent variants appear immediately after their solid counterparts in src/styles/globals.css at lines 122–137. For every --accent-{number} token (1 through 8), there exists a corresponding --accent-{number}-10 token containing the same hue with 10% opacity for subtle backgrounds and hover states.

Can I modify the color palette without changing component files?

Yes. Because components reference tokens like var(--accent-4) or var(--text-muted) rather than hard-coded values, updating the CSS custom property values in src/styles/globals.css immediately propagates changes across the entire UI, including components like Button.module.css and Widget.module.css.

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