Design Token System

Atomic CSS lets you define project design tokens in a .atomic.json file. When tokens are configured, they appear at the top of autocomplete with a ★ mark.

Overview

The Design Token System centrally manages your project's colors, spacing, font sizes, border radii, and font weights, and prioritizes them in autocomplete suggestions.

Token Configuration (.atomic.json)

Create a .atomic.json file at your project root and define tokens.

{
    "cssDirectoryPath": "/assets/css/common/",
    "tokens": {
        "colors": {
            "primary": "6366F1",
            "secondary": "A855F7",
            "danger": "EF4444",
            "success": "22C55E",
            "warning": "F59E0B",
            "text": "333333",
            "text-light": "999999",
            "bg": "FFFFFF",
            "bg-dark": "18181B",
            "border": "DDDDDD"
        },
        "spacing": [4, 8, 12, 16, 20, 24, 32, 40, 48, 64],
        "fontSize": [12, 14, 16, 18, 20, 24, 32, 40],
        "borderRadius": [4, 8, 12, 16, 50],
        "fontWeight": [400, 500, 600, 700]
    },
    "strict": false
}

Token Types

Each token type maps to specific CSS property prefixes.

colors — Color Palette

Applied to c, bg, bc prefixes. Define HEX 6-digit values as key-value pairs. When typing c, autocomplete shows c6366F1 ★ primary at the top.

"colors": {
    "primary": "6366F1",
    "secondary": "A855F7",
    "danger": "EF4444",
    "success": "22C55E",
    "warning": "F59E0B",
    "text": "333333",
    "text-light": "999999",
    "bg": "FFFFFF",
    "bg-dark": "18181B",
    "border": "DDDDDD"
}

spacing — Spacing Values (px)

Applied to gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr prefixes. Values under 20px use px, 20px and above are auto-converted to rem.

"spacing": [4, 8, 12, 16, 20, 24, 32, 40, 48, 64]

fontSize — Font Size (px)

Applied to the fs prefix. Same px→rem conversion rule as spacing.

"fontSize": [12, 14, 16, 18, 20, 24, 32, 40]

borderRadius — Border Radius (px)

Applied to the br prefix.

"borderRadius": [4, 8, 12, 16, 50]

fontWeight — Font Weight

Applied to the fw prefix. Classes are generated with raw numeric values (no units).

"fontWeight": [400, 500, 600, 700]

Strict Mode

The strict option lets you set token usage to free mode or team mode.

strict: false (default) — Free Mode

Tokens are boosted in autocomplete, but any value can still be used freely.

strict: true — Team Mode

Non-token values get a warning underline, and Quick Fix suggests the nearest token value.

Strict Mode Warning Examples

Using values not in the token list triggers a warning with a Quick Fix suggestion.

CSS Variable Synergy

Combine token names with CSS variables for consistent design. bg--primary uses var(--primary), while bg6366F1 uses #6366F1 — both reference the same design color through variables or direct values.

<!-- CSS variable approach -->
<div class="bg--primary c--text">
  Uses var(--primary) and var(--text)
</div>

<!-- Direct token value approach -->
<div class="bg6366F1 c333333">
  Uses #6366F1 and #333333 directly
</div>

<!-- Both reference the same design token "primary: 6366F1" -->
<!-- bg--primary = background-color: var(--primary) -->
<!-- bg6366F1   = background-color: #6366F1          -->

CSS Variable Autocomplete

Your project's CSS/SCSS files are automatically scanned for :root variables, which then appear in autocomplete.

/* Your project CSS/SCSS file */
:root {
  --primary: #6366f1;
  --secondary: #a855f7;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 32px;
  --radius: 8px;
}

/* Type "bg--" in HTML class → autocomplete shows: */
/* bg--primary       → background-color: var(--primary)     #6366f1  (from style.css) */
/* bg--secondary     → background-color: var(--secondary)   #a855f7  (from style.css) */

Tips & Cautions