config.jsonc Config

The .overlay/config.jsonc file tells the Overlay VS Code extension which CSS files to scan for color tokens (and which fonts and stylesheets to load into the editor). Overlay reads CSS custom properties from those files and injects the matching tokens into the editor.

INFO

This file is a CSS/token import config. It does not store hand-authored token groups like typography, spacing, borders, or shadows.

File Location

Create the file at the root of your workspace:

your-project/
└── .overlay/
    └── config.jsonc

TIP

You can commit this file to share design token sources with collaborators. If you prefer not to, add .overlay to your .gitignore.

INFO

Older workspaces may have a .overlay/tokens.jsonc file instead — this was the previous filename. Overlay migrates it to config.jsonc automatically the next time it scans for tokens.

Root Structure

{
  "version": 1,
  "cssFiles": [
    "./src/styles/globals.css",
    {
      "path": "./src/styles/theme.css",
      "include": ["--background-*", "--foreground"],
      "exclude": ["--background-muted"],
      "excludeSelectors": [".dark"],
    },
  ],
}

Top-level keys:

Field	Required	Type	Description
version	Yes	1	Config schema version
cssFiles	Yes	array	CSS files to scan for color token values (or inject as raw CSS)
fonts	No	array	Fonts detected in the project, offered in the editor's font picker

INFO

tokenFiles is still accepted as an alias for cssFiles for backward compatibility with older config files, but new files always use cssFiles. If both are present, cssFiles wins.

---

CSS File Entries

Each cssFiles entry can be a string path, or an object for token-extraction filters or raw-CSS injection.

String Entry

Use a string when Overlay should scan all color-like CSS variables from a file.

{
  "version": 1,
  "cssFiles": ["./src/styles/globals.css"],
}

String entries use these defaults:

Option	Default
include	["--*"]
exclude	[]
excludeSelectors	[]

Object Entry (token extraction)

Use an object when you need to include or exclude specific variable names or selectors. This is the default mode for object entries — omit extractVariables or set it to true.

{
  "version": 1,
  "cssFiles": [
    {
      "path": "./src/styles/theme.css",
      "include": ["--color-*", "--background", "--foreground"],
      "exclude": ["--color-debug"],
      "excludeSelectors": [".dark"],
    },
  ],
}

Object fields:

Field	Required	Type	Description
path	Yes	string	CSS file path, relative to the workspace root or absolute
extractVariables	No	boolean	true (default) scans the file for tokens. false injects it as raw CSS instead — see below
include	No	string[]	Variable name patterns to include. Defaults to ["--*"]. Not allowed when extractVariables is false
exclude	No	string[]	Variable name patterns to exclude after include matching. Not allowed when extractVariables is false
excludeSelectors	No	string[]	Selector blocks to skip. Supports ":root" and ".dark". Not allowed when extractVariables is false

include and exclude patterns match CSS variable names. Use * as a wildcard.

{
  "include": ["--color-*", "--background"],
  "exclude": ["--color-debug", "--color-temp-*"],
}

Object Entry (raw CSS, no token extraction)

Set extractVariables: false to have Overlay load a stylesheet as-is into the canvas, without scanning it for design tokens. This is useful for third-party stylesheets or component CSS the editor needs in order to render registered components correctly.

{
  "version": 1,
  "cssFiles": [
    "./src/styles/globals.css",
    { "path": "./src/styles/vendor-datepicker.css", "extractVariables": false },
  ],
}

A render-only entry only accepts path and extractVariables: false — include, exclude, and excludeSelectors don't apply and are rejected.

---

CSS Scanning

Overlay scans only CSS custom properties from :root and .dark blocks:

:root {
  --background: 0 0% 100%;
  --foreground: 20 14.3% 4.1%;
  --radius: 1rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

In this example, --background and --foreground are imported. --radius is ignored because it is not a color-like value.

Overlay treats :root variables as light mode tokens and .dark variables as dark mode tokens. When both blocks define the same variable name, Overlay can provide both light and dark values to the editor.

Color-Like Values

Overlay imports custom properties whose values look like colors:

Value type	Example
Hex	#0f172a
Raw HSL components	222.2 84% 4.9%
Color functions	hsl(222.2 84% 4.9%), oklch(0.7 0.14 250)
CSS variable references	var(--brand-primary)
Color keywords	transparent, currentColor
Composite color values	linear-gradient(...), shadows with colors

Non-color values such as spacing, border radius, transition durations, and font settings are ignored.

---

Fonts

Overlay can detect fonts loaded via next/font/google in your project and lists them in the fonts array so the editor's font picker can offer them. This array is auto-populated on scan — you don't need to write it by hand, but you can adjust it manually.

{
  "fonts": [
    { "family": "Inter", "cssVariable": "--font-sans", "weights": [400, 600] },
  ],
}

Field	Required	Type	Description
family	Yes	string	Font family name
cssVariable	No	string	CSS custom property the font is bound to (e.g. --font-sans), used to map it onto the editor's font tokens
weights	No	number[]	Font weights to load from the Google Fonts CDN

---

Generated Config

When you scan for color tokens from the extension, Overlay writes a config like this:

// File generated with Overlay Studio, a code-first UI design editor.
// Learn more: https://overlay.studio

// Note: you can commit this file to the repo if you want to collaborate with others (and share design system tokens).
// If not, add `.overlay` to your `.gitignore` file
{
  "version": 1,
  "cssFiles": ["./src/styles/globals.css"],
}