Skip to content

context.md

Latest commit

 

History

History
143 lines (109 loc) · 6.9 KB

context.md

File metadata and controls

143 lines (109 loc) · 6.9 KB

Synapse: Low Level Design & Implementation Context

Date: February 5, 2026 Version: 0.5.0 (Enhanced Normalization & Tier Inference)

0. Project Summary

Synapse is a specialized Design Token Orchestrator bridging design systems and engineering workflows. Built with a compiler-first mindset, it transforms platform-agnostic JSON—supporting W3C, legacy, and implicit formats—into optimized, production-ready CSS. Its strength lies in architectural enforcement, utilizing a strict hierarchical tier system (Shared, Core, Semantic, Component) to prevent circular dependencies and design debt. With native Tailwind CSS v4 support and multi-brand capabilities, Synapse ensures design decisions remain scalable and consistent across complex applications. By automating normalization, resolution, and generation through a robust dependency graph, it delivers high-performance artifacts with zero-runtime overhead.

1. System Overview

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.

Core Philosophy:

  • Compiler Architecture: Ingest $\rightarrow$ Normalize $\rightarrow$ Graph $\rightarrow$ Resolve $\rightarrow$ Generate.
  • Zero-Runtime: Generates standard, static CSS/JSON artifacts.
  • Separation of Concerns: Component structure is shared; Brand themes are distinct.

2. Architecture

2.1 The Compiler Pipeline

The system follows a strict unidirectional data flow:

flowchart TD
    Input[Raw JSON Files] --> Ingest[Ingestion & Normalization]
    Ingest --> Validate[Zod Validation]
    Validate --> Graph[Dependency Graph]
    
    subgraph The Brain
        Graph --> Cycle[Cycle Detection]
        Cycle --> Hierarchy[Hierarchy Enforcement]
        Hierarchy --> Sort[Topological Sort]
        Sort --> Resolve[Alias Resolution]
    end
    
    Resolve --> Split{Pipeline Split}
    
    Split -->|Filter: Component| Struct[Structural Pipeline]
    Split -->|Filter: Core/Semantic| Theme[Thematic Pipeline]
    
    Struct --> GenCSS1[Generator]
    Theme --> GenCSS2[Generator]
    
    GenCSS1 --> File1[_generated/components/index.css]
    GenCSS2 --> File2[_generated/brands/{brand}/theme.css]
Loading

2.2 Data Flow Stages

  1. Ingestion & Normalization (src/core/normalizer.ts):

    • Multi-Format Support: The normalizer accepts three input formats, converting them all into a unified SynapseToken structure:
      • W3C Standard: {"$value": "#fff", "$type": "color"}
      • Legacy: {"value": "#fff", "type": "color"}
      • Implicit Primitive: {"blue": "#00f"} (Type inferred via src/core/infer.ts)
    • Recursive Flattening: Nested objects are flattened into dot-notation IDs (e.g., color.primary.500).
    • Tier Inference (src/adapters/local-file.ts): Tiers are strictly determined by the file path relative to tokens/.
      • shared brand is default.
      • Path contains core $\rightarrow$ Tier: core
      • Path contains semantic $\rightarrow$ Tier: semantic
      • Path contains component or components $\rightarrow$ Tier: component
    • Brand Inference: Files within tokens/brands/{brandName}/... are tagged with that brand.

  2. Validation (src/core/schema.ts):

    • Schema: Zod schema verifies strict typing.
    • Token ID: Must match regex ^[a-zA-Z0-9.-]+$.
    • Values: Must be resolvable strings (no objects allowed after normalization).

  3. The Graph (src/core/graph.ts):

    • Adjacency List: Maps dependencies (Dependency $\rightarrow$ Dependent).
    • Cycle Detection: DFS traversal throws CircularDependencyError if loops exist.
    • Hierarchy Check: Enforces TIER_RANK:
      • Shared (0) -> Core (1) -> Semantic (2) -> Component (3)
      • Rule: A token at Rank $N$ cannot depend on a token at Rank $M$ where $M > N$. (e.g., Core cannot depend on Component).
    • Resolution: Uses Kahn's Algorithm (Topological Sort) to resolve aliases ({color.slate.500} $\rightarrow$ #64748b).

  4. Generation (src/generators/css.ts):

    • Consolidated Logic: Handles both standard CSS and Tailwind v4 outputs.
    • Tailwind Mapping: Intelligent renaming for @theme block:
      • --semantic-color-primary $\rightarrow$ --color-primary
      • --core-spacing-4 $\rightarrow$ --spacing-4

3. The Atomic Compilation Pipelines

Synapse runs two distinct pipelines during a build to optimize for multi-brand systems.

3.1 Pipeline A: Structural (Components)

  • Source: Shared Token Graph.
  • Filter: tier === 'component'.
  • Goal: Generate the shared "Skeleton" of the design system.
  • Output: _generated/components/index.css.

3.2 Pipeline B: Thematic (Brands)

  • Source: Shared Graph + Brand Graph (Merged).
  • Logic: Brand tokens override Shared tokens if IDs match.
  • Filter: tier === 'core' || tier === 'semantic'.
  • Goal: Generate the "Skin" of the system.
  • Output: _generated/brands/{brand}/.

4. Component Details

4.1 Core Modules (src/core/)

  • normalizer.ts: The "Lexer". Converts chaos into order. Supports W3C, Legacy, and Implicit formats.
  • schema.ts: The "Gatekeeper". Defines SynapseTokenSchema and TierEnum.
  • graph.ts: The "Processor". Manages dependency graph and TIER_RANK enforcement.
  • infer.ts: The "Guesser". Infers types (color, dimension) from values when not explicitly provided.

4.2 CLI (src/cli/)

  • commands.ts: Orchestrates the build. Supports flags: --format, --color-format, --dimension-unit.
  • menu.ts: Interactive TUI for user-friendly configuration.

5. Directory Structure (Output)

5.1 Detailed Structure (Default)

Optimized for complex systems.

/_generated
├── /components
│   └── index.css       # Shared structural logic
└── /brands
    ├── /neon-tech
    │   ├── core.css      # Primitives
    │   ├── semantic.css  # Semantic tokens
    │   └── theme.css     # Entry point (Tailwind v4 @theme OR standard @import aggregator)
    └── ...

6. Export Configurations

6.1 Export Purpose

  • CSS: Generates standard CSS Custom Properties (:root).
  • TailwindV4: Generates a native Tailwind v4 CSS file including an @theme block.

6.2 Export Structure

  • Detailed: Splits output into core.css and semantic.css.
  • Single: Flattens all tokens into a single vars.css.

7. Future Roadmap

  1. Style Dictionary Compatibility: Add an adapter to read config.json directly.
  2. Plugin System: Allow custom transforms (e.g., saturate()).
  3. Figma Sync: Direct API integration to fetch variables.