# Instatic Design Tokens and CSS Modules Conventions: A Complete Developer Guide

> Explore Instatic's strict token driven styling system. Discover how Instatic uses CSS custom properties and CSS Modules for consistent design and automated tests block hard-coded values and Tailwind.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: developer-guide
- Published: 2026-08-01

---

**Instatic enforces a strict, token-driven styling system where every visual property is defined as a CSS custom property in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) and referenced exclusively via CSS Modules, with automated tests blocking hard-coded values and Tailwind usage.**

The CoreBunch/Instatic repository implements a rigorous design tokens and CSS modules conventions architecture to ensure visual consistency across its admin interface. Every color, spacing value, and typographic scale is abstracted into reusable CSS custom properties, while component styles are isolated through adjacent CSS Modules. This approach guarantees a themable, maintainable UI that prevents accidental style drift through automated enforcement.

## Design Token Architecture in Instatic

### Centralized Token Definitions in globals.css

All design tokens reside in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css), serving as the single source of truth for the entire application. Adding a new token requires appending a `--your-token` definition to this file, which can then be accessed via `var(--your-token)` throughout the codebase. This centralization ensures that brand colors, spacing scales, and radius values remain synchronized across all admin components.

### Token Categories and Naming Patterns

Instatic organizes tokens by functional purpose rather than arbitrary values. **Color tokens** follow semantic grouping—`--bg-surface`, `--border-default`, `--text-bright`, and `--overlay-10`—with opacity variants using numeric suffixes (e.g., `--accent-1` and `--accent-1-10` for 10% opacity). **Radius tokens** differentiate contexts explicitly: `--editor-radius-sm`, `--editor-radius`, `--panel-radius`, and `--input-radius` each serve specific UI regions. **Spacing tokens** range from `--space-4xs` to `--space-12xl`, while **typography tokens** span `--text-xs` through `--text-xl`.

### Fluid Spacing and Typography Scales

Unlike static pixel values, Instatic's spacing and typography tokens use `clamp()` functions to create fluid, viewport-adaptive scales. This eliminates the need for media query breakpoints while maintaining readable proportions across device sizes. The fluid system applies consistently from `--space-4xs` (minimal gaps) to `--space-12xl` (major layout sections).

## CSS Modules Conventions and File Organization

### Adjacent Module Pattern

Components located in `src/admin/`, `src/admin/pages/site/`, and `src/ui/` directories must co-locate styles using the `[ComponentName].module.css` naming convention. For example, [`src/ui/components/Button/Button.module.css`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/components/Button/Button.module.css) contains all Button-specific styles, while [`src/ui/components/Card/Card.module.css`](https://github.com/CoreBunch/Instatic/blob/main/src/ui/components/Card/Card.module.css) houses card layouts. This adjacency pattern keeps styles discoverable and scoped to their respective components.

### camelCase Class Naming

Class selectors within modules use **camelCase** (e.g., `.primaryButton`, `.cardContainer`) rather than kebab-case or BEM methodology. This convention aligns with JavaScript object property access patterns when importing style objects into React components. The CSS Modules build step automatically scopes these classes to prevent global namespace pollution.

## Strict Enforcement: No Raw Values or Tailwind

### Automated Token Policy Testing

The repository includes [`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts), which fails any build containing raw hex codes, rgb/hsl values, or pixel literals in CSS Modules. This architectural test enforces 100% token adoption—every visual value must reference a custom property via `var(--*)`. Direct literals such as `color: #ff0000` or `margin: 16px` trigger immediate test failures.

### Tailwind Prohibition

Instatic explicitly forbids Tailwind CSS utilities and dependencies. The test suite includes [`noTailwindUtilities.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/noTailwindUtilities.test.ts) and [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) to prevent utility-class imports or Tailwind-related package dependencies. All styling must occur through CSS Modules referencing design tokens, ensuring the admin UI remains free from utility-class sprawl and specificity conflicts.

### Specificity and !important Rules

The codebase bans `!important` declarations except in two designated exceptions: [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) for reduced-motion accessibility handling and [`Button.module.css`](https://github.com/CoreBunch/Instatic/blob/main/Button.module.css) for specificity reset requirements. This restriction prevents brittle style overrides and maintains the cascade's predictability.

## Implementation Examples

### Adding a Color Token and Using It in a Component

First, define the token in the global stylesheet:

```css
/* src/styles/globals.css – add the token */
:root {
  --brand-primary: #4a90e2;
  --brand-primary-10: rgba(74,144,226,0.1);
}

```

Then reference it in a CSS Module:

```css
/* src/ui/components/Alert/Alert.module.css – reference the token */
.alert {
  background-color: var(--brand-primary-10);
  border: 1px solid var(--brand-primary);
  color: var(--text-bright);
  border-radius: var(--editor-radius);
  padding: var(--space-m);
}

```

### Using Fluid Spacing in Layout Components

```css
/* src/ui/components/Stack/Stack.module.css */
.stack {
  display: flex;
  flex-direction: column;
  gap: var(--space-s);   /* fluid spacing – no hard-coded pixels */
}

```

### Referencing Radius Tokens in Cards

```css
/* src/ui/components/Card/Card.module.css */
.card {
  background: var(--bg-surface);
  border-radius: var(--panel-radius);   /* 12 px radius – shared token */
  box-shadow: 0 2px 4px var(--overlay-10);
}

```

## Summary

- All design tokens are centralized in [`src/styles/globals.css`](https://github.com/CoreBunch/Instatic/blob/main/src/styles/globals.css) as CSS custom properties, categorized by semantic purpose (surface, border, text, accent)
- CSS Modules must use adjacent file naming ([`Component.module.css`](https://github.com/CoreBunch/Instatic/blob/main/Component.module.css)) and reside in approved directories (`src/admin/`, `src/ui/`)
- Automated tests in `src/__tests__/architecture/` block hard-coded values ([`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts)) and Tailwind usage ([`noTailwindUtilities.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/noTailwindUtilities.test.ts))
- Token references must use `var(--*)` syntax exclusively; no raw hex, rgb, or pixel values are permitted
- Class names follow camelCase conventions within modules, and `!important` is banned except in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) and [`Button.module.css`](https://github.com/CoreBunch/Instatic/blob/main/Button.module.css)

## Frequently Asked Questions

### Where are design tokens defined in Instatic?

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 centralized approach ensures that colors, spacing, typography, and radius values remain consistent across the admin interface and can be updated from a single location, as documented in [`docs/reference/design-tokens.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/reference/design-tokens.md).

### How does Instatic prevent hard-coded CSS values?

The repository uses [`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts) to scan CSS Modules for raw hex codes, rgb values, and pixel literals. Any module containing hard-coded values fails the test suite, enforcing the requirement that all visual properties reference tokens via `var()` notation.

### Why does Instatic ban Tailwind CSS?

Instatic prohibits Tailwind utilities and dependencies through [`noTailwindUtilities.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/noTailwindUtilities.test.ts) and [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) to maintain strict visual consistency and prevent utility-class sprawl. The architecture requires explicit token references through CSS Modules instead of utility composition, ensuring design system adherence.

### What naming convention should CSS Module class names follow?

Class names within CSS Modules use camelCase (e.g., `.buttonPrimary`, `.cardHeader`) rather than kebab-case or BEM. This convention aligns with JavaScript object property access patterns when importing styles into React components, and is enforced by the project's style guide in [`docs/design.md`](https://github.com/CoreBunch/Instatic/blob/main/docs/design.md).