Quick Start

Initialize your Design System infrastructure.
Choose your preferred integration path below.

Experimental Library - Not Production Ready
UXDSL is currently under active development and should be considered experimental. It is not yet recommended for production environments. APIs and features may change without prior notice. Use at your own discretion.

UX-DSL is framework-agnostic but offers first-class support for modern build tools.

Supported Integrations

Vite

Recommended. Best for React, Vue, Svelte. Supports HMR and optimized builds.

Next.js

Supported via PostCSS or Webpack loader. Good for App Router projects.

Webpack / CLI

Universal fallback for any other environment (Angular, Static Sites).

Starter Template

The fastest way to get started is using our official React starter template:

git clone https://github.com/rsantoyo-dev/uxdsl-react-starter.git my-uxdsl-app
cd my-uxdsl-app
npm install
npm run dev

Option 1: Vite (Recommended)

Install Plugin

Add the Vite plugin and core engine.

npm install -D vite-plugin-uxdsl uxdsl-core

Configure Vite

Add the plugin to your vite.config.ts.

import { defineConfig } from 'vite';
import vitePluginUxdsl from 'vite-plugin-uxdsl';

export default defineConfig({
plugins: [
  vitePluginUxdsl()
]
});

Import & Style

Import your .uxdsl file directly in your app entry point.

// main.tsx
import './styles.uxdsl';

VS Code Support

Enable syntax highlighting by updating .vscode/settings.json:

{
"files.associations": {
  "*.uxdsl": "scss"
}
}

Option 2: Next.js (App Router)

Install Packages

Install the CLI, PostCSS plugin, and concurrently (for running scripts together).

npm install -D postcss-uxdsl uxdsl-cli concurrently

Initialize

Scaffold configuration and entry file.

npx uxdsl init

Connect & Run

Import ./src/uxdsl.css in your root layout.tsx.
Update your package.json dev script:

"scripts": {
"dev": "concurrently \"npx uxdsl build --watch\" \"next dev\""
}

Workflow

When you add new .uxdsl files, register them automatically:

npx uxdsl generate-entry

Theme Configuration Reference

A complete example of a uxdsl.theme.json configuration file:

{
"fonts": {
  "google": [
    "Inter:wght@400;500;600;700"
  ],
  "families": {
    "ui": "Inter, sans-serif",
    "code": "monospace"
  }
},
"breakpoints": { "xs": 0, "sm": 480, "md": 768, "lg": 1024, "xl": 1280 },
"palette": {
  "primary": {
    "main": "#7e22ce",
    "light": "#a855f7",
    "dark": "#581c87",
    "contrast": "#ffffff"
  },
  "secondary": {
    "main": "#db2777",
    "light": "#f472b6",
    "dark": "#be185d",
    "contrast": "#ffffff"
  },
  "surface": {
    "main": "#ffffff",
    "light": "#f8fafc",
    "dark": "#e2e8f0",
    "contrast": "#0f172a"
  },
  "tertiary": {
    "main": "#94a3b8",
    "light": "#cbd5e1",
    "dark": "#475569",
    "contrast": "#000000"
  },
  "success": {
    "main": "#15803d",
    "light": "#16a34a",
    "dark": "#14532d",
    "contrast": "#ffffff"
  },
  "info": {
    "main": "#0284c7",
    "light": "#38bdf8",
    "dark": "#0369a1",
    "contrast": "#ffffff"
  },
  "warning": {
    "main": "#d97706",
    "light": "#fbbf24",
    "dark": "#b45309",
    "contrast": "#ffffff"
  },
  "error": {
    "main": "#dc2626",
    "light": "#ef4444",
    "dark": "#b91c1c",
    "contrast": "#ffffff"
  },
  "dark": {
    "main": "#0f172a",
    "light": "#1e293b",
    "dark": "#020617",
    "contrast": "#ffffff"
  },
  "neutral": {
    "main": "#64748b",
    "light": "#cbd5e1",
    "dark": "#334155",
    "contrast": "#ffffff"
  },
  "light": {
    "main": "#f1f5f9",
    "light": "#ffffff",
    "dark": "#e2e8f0",
    "contrast": "#0f172a"
  }
},
"modes": {
  "dark": {
    "palette": {
      "primary": {
        "main": "#c084fc",
        "light": "#d8b4fe",
        "dark": "#a855f7",
        "contrast": "#000000"
      },
      "secondary": {
        "main": "#f472b6",
        "contrast": "#000000"
      },
      "surface": {
        "main": "#020617",
        "light": "#0f172a",
        "dark": "#000000",
        "contrast": "#f8fafc"
      },
      "neutral": {
        "main": "#94a3b8",
        "light": "#cbd5e1",
        "dark": "#475569",
        "contrast": "#000000"
      },
      "tertiary": {
        "main": "#94a3b8",
        "contrast": "#000000"
      },
      "success": {
        "main": "#4ade80",
        "contrast": "#000000"
      },
      "info": {
        "main": "#38bdf8",
        "contrast": "#000000"
      },
      "warning": {
        "main": "#fbbf24",
        "contrast": "#000000"
      },
      "error": {
        "main": "#f87171",
        "contrast": "#000000"
      },
      "light": {
        "main": "#1e293b",
        "contrast": "#f8fafc"
      },
      "dark": {
        "main": "#000000",
        "contrast": "#f8fafc"
      }
    }
  }
},
"spacing": {
  "1": "0.125rem",
  "2": "0.25rem",
  "3": "0.5rem",
  "4": "0.75rem",
  "5": "1rem",
  "6": "1.5rem",
  "7": "2rem",
  "8": "2.5rem",
  "9": "3.125rem",
  "10": "3.875rem",
  "11": "4.875rem",
  "12": "6.125rem",
  "13": "7.75rem",
  "14": "9.75rem",
  "15": "12.25rem",
  "16": "15.375rem"
},
"typography": {
  "font-code": "\"JetBrains Mono\", \"SF Mono\", Menlo, monospace"
  },
	  "typography_details": {
	    "h1": { "fontSize": "xs(space(7)) md(space(8)) lg(space(9)) xl(space(10))", "fontWeight": "700", "lineHeight": "1.1", "letterSpacing": "-0.02em" },
	    "h2": { "fontSize": "xs(space(6)) sm(space(7)) lg(space(8)) xl(space(9))", "fontWeight": "700", "lineHeight": "1.2", "letterSpacing": "-0.01em" },
	    "h3": { "fontSize": "xs(space(6)) md(space(7)) xl(space(8))", "fontWeight": "600", "lineHeight": "1.3", "letterSpacing": "normal" },
	    "h4": { "fontSize": "xs(space(5)) md(space(6)) xl(space(7))", "fontWeight": "600", "lineHeight": "1.4", "letterSpacing": "normal" },
	    "h5": { "fontSize": "xs(space(5)) xl(space(6))", "fontWeight": "600", "lineHeight": "1.4", "letterSpacing": "normal" },
	    "h6": { "fontSize": "xs(space(5))", "fontWeight": "600", "lineHeight": "1.4", "letterSpacing": "normal" },
	    "p": { "fontSize": "xs(space(5))", "fontWeight": "400", "lineHeight": "1.6", "letterSpacing": "normal" },
	    "body": { "fontSize": "xs(space(5))", "fontWeight": "400", "lineHeight": "1.6", "letterSpacing": "normal" },
	    "caption": { "fontSize": "xs(space(4))", "fontWeight": "400", "lineHeight": "1.4", "letterSpacing": "0.01em" }
	  }
}