CSS VarGraph

Interactive dependency graph for CSS custom properties — a VS Code extension.

Visualize every --custom-property definition and var() usage in your project as a live, interactive D3 force-directed graph. Understand how your design tokens flow, spot broken references, detect cycles, and experiment with value changes — all without leaving VS Code.

Table of Contents

• Features
• Interface Guide
• Usage
• Configuration
• Development
• How It Works
• Requirements
• License

Features

Core

• Automatic scanning — parses CSS, SCSS, and LESS files across your workspace on load and after every save.
• Directed dependency graph — each node is a custom property. Edges connect dependents (who uses me) → dependencies (what I use).
• File grouping — variables from the same file appear inside colored boundary rectangles, with file name labels.
• Sidebar details — click any node to see its definition value, file location, scope, dependents, and ancestors.

Node labels with usage counts

Every node label shows the number of dependents (other variables using this one) in parentheses:

--color-primary (12) → 12 other variables reference --color-primary.

A legend at the bottom-left explains this notation.

Informational overlay

A ℹ info panel (top-right corner, collapsed by default) explains what each warning type means:

• Broken references — variables used via var() but never defined in the workspace (often from external libraries, frameworks, or browser defaults).
• Unused variables — defined but never referenced by other custom properties (may still be used in plain CSS properties like color: var(--x)).
• Dependency cycles — circular references (e.g. A→B→A) that can cause unpredictable or cascading values.

Click the blue ℹ button to toggle the info panel.

What-If Sandbox

Override a variable's value locally in the sidebar and see affected nodes change color — without modifying any source file. Available for defined variables only; hidden for plain property usage nodes.

Warnings sidebar

A collapsible ⚠️ Warnings section in the sidebar lists:

• Broken references (red) — variables used but never defined.
• Dependency cycles (yellow) — mutually-referencing variables.
• Unused variables (grey) — defined but not referenced.

The header shows the total count: ⚠️ Warnings (7) ▸. Click to expand/collapse.

Navigation

• Double-click a node to open its source file at the definition line.
• Click a dependent or ancestor badge in the sidebar to drill into that variable's details.
• Use the ← Back link to return to the previously selected variable.
• Zoom & pan — scroll to zoom, drag to pan, drag individual nodes to reposition.
• Escape — deselect the current node.
• Click the graph background to deselect.

Anti-overlap layout

File-group rectangles dynamically avoid overlapping — if two groups' bounding boxes intersect, their nodes are gently pushed apart on every simulation tick until they settle without overlapping.

Status bar

The status bar shows the total number of custom properties scanned, with a warning icon if issues are present.

Interface Guide

Color legend

Usage

1. Open a workspace containing CSS, SCSS, or LESS files.
2. Run CSS VarGraph: Show Dependency Graph from the Command Palette (Ctrl+Shift+P).
3. The graph panel opens with all detected custom properties and their relationships.
4. Click nodes to explore dependencies in the sidebar.
5. Double-click a node to open its source file.
6. Hover for quick info tooltips.
7. Type a new value in the What-If Sandbox and click Apply to see the effect.

Keyboard shortcuts

Configuration

Development

# Clone
git clone https://github.com/Moa1er/css-vargraph.git
cd css-vargraph

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run in Extension Development Host
# Press F5 in VS Code

# Watch mode
npm run watch

Project structure

css-vargraph/
├── src/
│   ├── extension.ts          # Entry point
│   ├── types.ts              # Shared TypeScript interfaces
│   ├── config.ts             # Configuration & settings
│   ├── statusBar.ts          # Status bar item
│   ├── graph/
│   │   └── DependencyGraph.ts # Graph builder + cycle detection
│   ├── scanner/
│   │   └── CssVarScanner.ts   # CSS/SCSS/LESS parser
│   ├── watcher/
│   │   └── FileWatcher.ts     # File change monitoring
│   └── webview/
│       ├── contentProvider.ts # HTML/JS/CSS for the graph panel
│       └── panelManager.ts    # Webview panel lifecycle
├── media/
│   └── interface-example.png # Screenshot for README & marketplace
├── package.json              # Extension manifest
├── tsconfig.json              # TypeScript config
└── README.md                  # This file

How It Works

1. Scanner (CssVarScanner) parses all files matching the include globs. It strips comments, extracts --name: value definitions and var(--name) usages with their file/line/scope context.

2. Graph builder (DependencyGraph) creates a node for each variable definition and usage. Edges connect dependent → dependency (i.e. if --text uses var(--primary), the edge goes --text → --primary). Plain CSS property usages (e.g. color: var(--x)) create synthetic [prop] nodes so they still count as dependents.

3. Cycle detection uses depth-first search with a recursion stack to find circular dependency chains.

4. Webview (contentProvider) renders the graph as an embedded HTML page using D3.js force simulation. File groups are positioned in a grid with grouping forces, and an anti-overlap step pushes intersecting rectangles apart.

5. What-If sandbox works purely in the webview — when a value override is applied, affected nodes update their color without any file writes.

Requirements

• VS Code ≥ 1.85.0
• Workspace containing CSS, SCSS, or LESS files

License

MIT — see LICENSE for details.