🌈 TokiForge

Framework-agnostic design token engine for React, Vue, Angular, Svelte & vanilla JS

Documentation • Examples • Report Bug • Request Feature

---

✨ Features

• 🚀 Framework-agnostic - Works with React, Vue, Angular, Svelte, Next.js, Remix, Solid, Qwik, or vanilla JS
• 🎨 Runtime theme switching - Change themes instantly without page reload
• 📦 Lightweight - Less than 3KB gzipped
• 🔒 Full TypeScript support - Type-safe tokens with autocomplete
• 🛠️ Powerful CLI - Initialize, build, validate, and analyze tokens
• 🎯 CSS custom properties - Native browser support with smart fallbacks
• 🌓 Dark mode ready - Built-in light/dark theme support
• 🔄 Token versioning - Track versions, deprecations, and migrations
• 🎭 Component theming - Scoped themes for individual components
• 🔌 Plugin system - Extensible with custom exporters and validators
• ♿ Accessibility - Built-in WCAG compliance checking and contrast analysis
• 📱 Responsive tokens - Breakpoint and state-aware token variations
• 🔍 Figma sync - Compare and sync tokens with Figma designs
• ✅ CI/CD ready - Automated validation for PRs and pipelines
• 📊 Analytics - Token usage tracking and bundle impact analysis
• 📚 Multi-team support - Versioned token registry for design systems
• 💻 IDE support - Autocomplete and hover previews (VSCode ready)
• 🎨 Tailwind integration - Generate Tailwind config from tokens

---

🚀 Quick Start

Installation

# React
npm install @tokiforge/core @tokiforge/react

# Vue
npm install @tokiforge/core @tokiforge/vue

# Angular
npm install @tokiforge/core @tokiforge/angular

# Svelte
npm install @tokiforge/core @tokiforge/svelte

# Vanilla JS / Any Framework
npm install @tokiforge/core

Basic Usage

1. Define your tokens (tokens.json):

{
  "color": {
    "primary": { "value": "#7C3AED", "type": "color" },
    "accent": { "value": "#06B6D4", "type": "color" },
    "text": {
      "primary": { "value": "#1F2937", "type": "color" },
      "secondary": { "value": "#6B7280", "type": "color" }
    }
  },
  "spacing": {
    "sm": { "value": "8px", "type": "dimension" },
    "md": { "value": "16px", "type": "dimension" },
    "lg": { "value": "24px", "type": "dimension" }
  },
  "radius": {
    "sm": { "value": "4px", "type": "dimension" },
    "lg": { "value": "12px", "type": "dimension" }
  }
}

2. Use in React:

import { ThemeProvider, useToken } from '@tokiforge/react';
import tokens from './tokens.json';

function App() {
  return (
    <ThemeProvider tokens={tokens} defaultTheme="light">
      <Button />
    </ThemeProvider>
  );
}

function Button() {
  const primaryColor = useToken('color.primary');
  const spacing = useToken('spacing.md');
  const radius = useToken('radius.lg');
  
  return (
    <button
      style={{
        backgroundColor: primaryColor,
        padding: spacing,
        borderRadius: radius,
      }}
    >
      Click me
    </button>
  );
}

3. Switch themes at runtime:

import { useTheme } from '@tokiforge/react';

function ThemeSwitcher() {
  const { setTheme, currentTheme } = useTheme();
  
  return (
    <button onClick={() => setTheme(currentTheme === 'light' ? 'dark' : 'light')}>
      Switch to {currentTheme === 'light' ? 'dark' : 'light'} mode
    </button>
  );
}

👉 View full documentation →

---

🎯 Why TokiForge?

Feature	TokiForge	Others
Runtime theme switching	✅	⚠️ Often requires rebuild
Framework-agnostic	✅	❌ Usually framework-specific
TypeScript support	✅	⚠️ Partial or manual
Bundle size	✅ <3KB	❌ Often larger
CSS custom properties	✅	⚠️ JS-heavy runtime
Zero JS overhead (static mode)	✅	❌ Always requires JS

---

📦 Packages

Package	Description	npm
@tokiforge/core	Core engine (works with any framework)
@tokiforge/react	React adapter with hooks
@tokiforge/vue	Vue 3 composables
@tokiforge/angular	Angular service with Signals
@tokiforge/svelte	Svelte stores
tokiforge-cli	CLI tool for token management

---

🏗️ Architecture

┌──────────────────────────────┐
│      Design Tokens (JSON)    │
│   (colors, spacing, etc.)    │
└─────────────┬────────────────┘
              │
┌─────────────▼───────────────┐
│   TokiForge Core Engine     │
│  - Token Parser/Validator    │
│  - Runtime CSS Generator     │
│  - Theme Manager             │
└─────────────┬───────────────┘
              │
┌─────────────▼───────────────┐
│   Framework Adapters        │
│ (React/Vue/Angular/Svelte)  │
└─────────────┬───────────────┘
              │
┌─────────────▼───────────────┐
│   Your Application          │
│   Using Design Tokens       │
└──────────────────────────────┘

---

🎨 Framework Examples

React

import { ThemeProvider, useToken } from '@tokiforge/react';

function App() {
  return (
    <ThemeProvider tokens={tokens}>
      <Component />
    </ThemeProvider>
  );
}

Vue

<script setup>
import { useToken } from '@tokiforge/vue';

const primaryColor = useToken('color.primary');
</script>

Angular

import { ThemeService } from '@tokiforge/angular';

constructor(private themeService: ThemeService) {
  const primaryColor = this.themeService.getToken('color.primary');
}

Svelte

<script>
  import { useToken } from '@tokiforge/svelte';
  const primaryColor = useToken('color.primary');
</script>

Vanilla JS

import { ThemeRuntime } from '@tokiforge/core';

const runtime = new ThemeRuntime(tokens);
const primaryColor = runtime.getToken('color.primary');
runtime.applyTheme('dark');

👉 View complete examples →

---

🛠️ CLI Tool

Install the CLI globally:

npm install -g tokiforge-cli

Commands:

# Initialize a new token file
tokiforge init

# Build tokens to CSS/SCSS/JS
tokiforge build

# Start development server with live preview
tokiforge dev

# Validate token schema
tokiforge lint

# Validate tokens for CI/CD
tokiforge validate [--strict] [--figma]

# Compare Figma ↔ Code tokens
tokiforge figma:diff --token TOKEN --file-key KEY

# Generate token analytics
tokiforge analytics

---

📚 Documentation

• Getting Started - Quick setup guide
• Installation - Framework-specific setup
• React Guide - React integration
• Vue Guide - Vue integration
• Angular Guide - Angular integration
• Svelte Guide - Svelte integration
• Examples - Complete example projects

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. ⭐ Star the project - It helps others discover TokiForge
2. 🐛 Report bugs - Open an issue on GitHub
3. 💡 Suggest features - Share your ideas
4. 🔧 Submit PRs - Fix bugs or add features
5. 📖 Improve docs - Help make documentation better

See CONTRIBUTING.md for guidelines.

Quick start for contributors:

# Clone the repo
git clone https://github.com/TokiForge/tokiforge.git
cd tokiforge

# Install dependencies
npm install

# Build all packages (including playground and docs)
npm run build:all

# Or build core + framework packages only
npm run build

# Run tests
npm test

---

❓ FAQ

What is TokiForge?

TokiForge is a framework-agnostic design token and theming engine that enables runtime theme switching using CSS custom properties. It works with React, Vue, Svelte, Angular, and any other JavaScript framework.

How does TokiForge compare to Style Dictionary?

TokiForge provides runtime theme switching capabilities that Style Dictionary doesn't offer. While Style Dictionary focuses on build-time token transformation, TokiForge adds a lightweight runtime engine (<3KB) for dynamic theme management.

Does TokiForge support dark mode?

Yes! TokiForge has built-in support for light/dark themes and can automatically generate dark themes from light theme tokens.

Is TokiForge production-ready?

Yes, TokiForge is production-ready with support for React, Vue, Svelte, and Angular. It's optimized for performance with a <3KB gzipped runtime footprint.

Can I use TokiForge with TypeScript?

Absolutely! TokiForge is written in TypeScript and provides full type safety for design tokens and theme configurations.

Does TokiForge work with SSR?

Yes, TokiForge is SSR-safe and works with Next.js, Remix, Angular SSR, and other SSR frameworks.

---

🗺️ Roadmap

✅ Completed (v1.1.2)

• Core engine + React adapter
• Vue/Svelte/Angular adapters
• CLI tooling
• TypeScript support
• Token versioning & deprecation
• Component theming
• Plugin system
• Accessibility dashboard
• Responsive & state-aware tokens
• Figma sync & diff tool
• CI/CD integration
• Token analytics
• Versioned token registry
• IDE support (API ready)
• Tailwind CSS integration

🚧 In Progress (v1.1.2+)

• Enhanced semantic tokens & aliasing
• Multi-platform exporters (iOS, Android, React Native)
• Type generation CLI (generate:types)
• Enhanced Tailwind plugin format
• CLI enhancements (migrate, watch)
• Zero-JS + SSR improvements
• Enhanced Figma integration (Tokens Studio)

📋 Planned

• VS Code extension
• Visual playground enhancements
• CI/Visual regression integration
• Enhanced usage analytics
• Community plugin examples

📖 View Full Roadmap →

---

📄 License

MIT License — free for personal and commercial use.

---

🙏 Acknowledgments

Built with 💜 by the TokiForge Community.

Inspired by the intersection of design and code.

---

⭐ If you find TokiForge useful, please consider giving it a star on GitHub! ⭐

Made with ❤️ by TokiForge Community