⚠️ ARCHIVED — No longer maintained

This repository has been archived and is frozen. No new features, bug fixes, or commits will be made. It is preserved here for historical reference only.

---

Token Dependency Visualizer

An interactive visualization tool for exploring and understanding design token dependencies in Style Dictionary configurations. See how your design tokens reference each other in a clear, interactive graph.

What It Does

Style Dictionary tokens can reference other tokens using {dot.path.notation}. As design systems grow, these reference chains become complex and hard to reason about. This app makes those relationships visually explorable.

Key capabilities:

• Upload .json or .zip Style Dictionary files — single or multiple files are deep-merged automatically
• Graph View — Force-directed D3 graph with color-coded layers (primitive, core, semantic, component), zoom/pan, and a minimap navigator
• Tree View — Hierarchical selector (layer → category → token) showing complete upstream/downstream dependency chains
• Search & Filter — Real-time search dims non-matching nodes; layered graph adds layer and category dropdowns
• Dependency Highlighting — Click any token node to highlight its direct connections and dim everything else
• Token Detail Panel — Slide-in panel showing token value, layer, type, references, and dependents
• Issue Detection — Automatically detects circular dependency chains (DFS) and broken references, visually flagged with amber/rust styling
• Export — Downloads the current graph state as an .svg file
• Demo Mode — Built-in sample token system (primitive → core → semantic → component) loads without any file upload

Getting Started

Prerequisites: Node.js (v18+ recommended)

# Install dependencies
npm install

# Start the development server
npm run dev

Open your browser at http://localhost:5173.

Scripts

Command	Description
npm run dev	Start Vite development server with HMR
npm run build	Production build (tsc -b --noCheck && vite build)
npm run preview	Preview the production build locally
npm run lint	Run ESLint with TypeScript and React hooks rules
npm run optimize	Pre-bundle dependencies via vite optimize
npm run kill	Kill process on port 5000 (Spark hosted environment utility)

Usage

Loading Tokens

1. Drag and drop one or more .json or .zip files onto the upload zone, or click to browse
2. ZIP archives are extracted recursively — all JSON files inside are found and merged
3. Multiple files are deep-merged preserving token hierarchy
4. Or click Load Demo to explore with the built-in sample token system

Supported Format

Standard Style Dictionary JSON with token references using {dot.path.notation}:

{
  "color": {
    "primitive": {
      "blue-500": { "value": "#3B82F6", "type": "color" }
    },
    "semantic": {
      "brand-primary": { "value": "{color.primitive.blue-500}", "type": "color" }
    }
  }
}

Token Layers

The app recognizes four token layers based on path conventions:

Layer	Convention	Role
primitive	Path contains primitive	Raw values (hex colors, px sizes)
core	Path contains core	Aliased primitives
semantic	Path contains semantic	Contextual meanings (brand, state)
component	Path contains component	Component-specific tokens

Navigating the Graph

• Zoom: Scroll wheel or pinch gesture
• Pan: Click and drag the background
• Select token: Click any node to highlight its connections and open the detail panel
• Move nodes: Drag individual nodes to reposition them
• Minimap: Click or drag the viewport rectangle in the bottom-right minimap to navigate

Tree View

Select a token via the three-step hierarchical selector (layer → category → token name). The tree then shows:

• Parent dependencies (tokens this token references, recursively)
• Child dependents (tokens that reference this token, recursively)

Project Structure

src/
├── App.tsx                        # Root component, global state
├── main.tsx                       # React entry point
├── ErrorFallback.tsx              # Global error boundary
├── lib/
│   ├── token-parser.ts            # Core parsing engine: Style Dictionary → TokenGraph
│   └── utils.ts                   # cn() utility (clsx + tailwind-merge)
├── hooks/
│   └── use-mobile.ts              # Responsive breakpoint hook (768px)
└── components/
    ├── FileUpload.tsx             # Drag-and-drop / file picker
    ├── GraphVisualization.tsx     # Force-directed D3 graph
    ├── LayeredGraphVisualization.tsx  # Layered graph with column layout + filters
    ├── TreeVisualization.tsx      # Hierarchical tree selector
    ├── TokenDetailPanel.tsx       # Slide-in token detail panel
    ├── Minimap.tsx                # Graph minimap navigator
    └── ui/                        # 46 shadcn/ui components

Core Engine: token-parser.ts

parseStyleDictionary(json) takes a merged JSON object and:

1. Flattens nested token objects into a flat Token[] array
2. Detects each token's layer from its path (primitive / core / semantic / component)
3. Extracts {reference} links and resolves them to token IDs
4. Builds a bidirectional referencedBy map
5. Runs DFS to detect circular dependency chains
6. Identifies broken references (pointer to a non-existent token)
7. Returns a TokenGraph ready for visualization

Tech Stack

Category	Technology
Framework	React 19 + TypeScript 5.7
Build	Vite 7 + SWC
Visualization	D3 v7 (force simulation, zoom, SVG)
Animation	Framer Motion 12
UI Components	shadcn/ui (new-york) + Radix UI primitives
Styling	Tailwind CSS v4
Icons	Phosphor Icons, Heroicons, Lucide
File Parsing	JSZip (ZIP extraction)
Platform	GitHub Spark

Fonts: Space Grotesk (UI) + JetBrains Mono (token names/values)

Design System

Colors (oklch):

• Primary: Deep Indigo oklch(0.35 0.12 270)
• Accent: Electric Cyan oklch(0.70 0.15 210)
• Circular dependency warning: Amber oklch(0.65 0.20 35)
• Broken reference: Rust oklch(0.55 0.22 15)

Node color-coding by layer:

• Primitive — blue
• Core — violet
• Semantic — teal/cyan
• Component — indigo

Platform

This app was built on GitHub Spark, a platform for building and sharing micro-apps. The runtime.config.json and spark.meta.json files contain Spark platform metadata.

License

See LICENSE.