Synapse: Design Token Compiler

Synapse is a developer-centric Design Token Orchestrator. It compiles platform-agnostic JSON tokens into production-ready CSS artifacts. It is designed to enforce strict architectural hierarchy (Shared -> Core -> Semantic -> Component) and supports modern workflows like Tailwind CSS v4 out of the box.

🚀 Quick Start

Zero-Config Mode: Simply run the command in your project root. If you don't have a tokens/ folder, Synapse will offer to scaffold one for you.

npx synapse

This launches the Interactive Dashboard, where you can browse detected brands and configure your build.

✍️ Defining Tokens

Synapse is flexible with input. You can write tokens in three formats, and they can be mixed within the same project.

1. W3C Standard (Recommended)

Explicit types and values. Best for long-term stability and tool interoperability.

{
  "color": {
    "primary": {
      "$value": "#3b82f6",
      "$type": "color"
    }
  }
}

2. Legacy / Style Dictionary

Traditional format using value and type keys.

{
  "spacing": {
    "small": {
      "value": "0.5rem",
      "type": "dimension"
    }
  }
}

3. Implicit / Concise

Just key-value pairs. Synapse infers the type (Color, Dimension, etc.) automatically.

{
  "font": {
    "family": {
      "sans": "Inter, system-ui, sans-serif"
    }
  },
  "brand": {
    "blue": "#3b82f6"
  }
}

Aliasing

Reference other tokens using {dot.notation}.

{
  "button": {
    "bg": { "$value": "{color.primary}" }
  }
}

---

🎛 Usage Strategies

Synapse is flexible. Choose the strategy that matches your project's architecture.

1. The "Modern Stack" (Recommended)

Best for: Projects using Tailwind CSS v4. Goal: Keep tokens organized while leveraging Tailwind's native variable detection.

• Purpose: TailwindV4
• Structure: Detailed

Command:

npx synapse build --format tailwind --brands all

Output: Generates a theme.css that imports core.css and semantic.css. It includes an @theme block that maps your tokens to Tailwind utilities (e.g., --color-primary maps to --semantic-action-primary).

/* _generated/brands/neon-tech/theme.css */
@import "../../components/index.css";
@import "./core.css";
@import "./semantic.css";

@theme {
  --color-primary: var(--semantic-action-primary);
  --spacing-4: var(--space-4);
}

---

2. The "Traditionalist"

Best for: Vanilla CSS, SASS, or projects not using Tailwind. Goal: Strict separation of concerns using standard CSS Custom Properties.

• Purpose: CSS
• Structure: Detailed

Command:

npx synapse build --format css --brands all

Output: Generates an index.css acting as an aggregator. No @theme blocks, just pure standard CSS variables.

/* _generated/brands/neon-tech/index.css */
@import "../../components/index.css";
@import "./core.css";
@import "./semantic.css";

---

3. The "Quick Prototype" / "Drop-in"

Best for: Small projects, CodePens, or simple integrations where file management is overhead. Goal: One file, all tokens.

• Purpose: CSS or TailwindV4
• Structure: Single

Command:

# Flatten everything into vars.css
npx synapse build --format css --brands neon-tech
# OR with Tailwind support
npx synapse build --format tailwind --brands neon-tech

Output: A single vars.css file containing every variable from Core, Semantic, and Component tiers, plus the optional @theme block.

---

🖥 CLI Reference (CI/CD)

For headless environments (GitHub Actions, Vercel), use strict flags to bypass the interactive menu.

Flag	Default	Description
--brands <list>	all	Comma-separated list of brands to build (e.g., neon-tech,crimson-corp)
-f, --format <type>	css	css (Standard Variables) or tailwind (Tailwind v4 @theme)
--color-format <fmt>	hex	hex, rgb, hsl, oklch
--dimension-unit <unit>	px	px, rem, em

Example:

npx synapse build --brands neon-tech --format tailwind --color-format oklch --dimension-unit rem

📂 Directory Structure & Tiers

Synapse strictly determines a token's Tier (Shared, Core, Semantic, Component) based on the file's location within tokens/. This structure is critical for architecture enforcement.

Rules:

1. Shared: Default tier if not matched.
2. Core: File path contains core. (Rank 1)
3. Semantic: File path contains semantic. (Rank 2)
4. Component: File path contains component. (Rank 3)
5. Brand: File path starts with tokens/brands/<brand_name>/.

/tokens
├── /shared
│   ├── /core          # [Tier: Core] Primitives shared by all brands
│   └── /semantic      # [Tier: Semantic] Shared semantic aliases
├── /brands
│   ├── /neon-tech
│   │   ├── /core      # [Tier: Core] Brand-specific primitives (colors.json)
│   │   └── /semantic  # [Tier: Semantic] Brand overrides
│   └── /...
└── /components        # [Tier: Component] Component-level tokens (button.json)

Hierarchy Rule: A token in a specific tier cannot reference a token in a higher tier (e.g., Core cannot reference Component).

🛠 Development Features

• Architecture Enforcement:
  • Synapse throws an error if a Core token tries to reference a Component token.
  • Visual stack traces help you debug circular dependencies.