Installation

Overview

Byteion ships three distribution paths. They produce the same UI — the difference is how your build pipeline consumes the design system. Pick whichever matches your stack.

Choose a path

Requirements

• Tailwind CSS — v4.0+ (recommended) or v3.4+. @byteion/core works under both via the tailwindcss: >=3.0.0 <5.0.0 peer dependency.
• Modern browser — last two versions of evergreen browsers.
• Node 18+ — for ESM imports and either Tailwind toolchain.

Tailwind v4 (recommended)

Tailwind v4 uses a CSS-first configuration. Install the package matching your framework stack:

HTML / Vanilla JS

npm install tailwindcss@^4 @tailwindcss/vite @byteion/core@0.2.0-beta.1 @byteion/js@0.2.0-beta.1

React

npm install tailwindcss@^4 @tailwindcss/vite @byteion/core@0.2.0-beta.1 @byteion/react@0.2.0-beta.1

Vue

npm install tailwindcss@^4 @tailwindcss/vite @byteion/core@0.2.0-beta.1 @byteion/vue@0.2.0-beta.1

@byteion/core is always required for design tokens and styles. React and Vue projects manage their behavior using native framework components and typically do not require @byteion/js unless directly using vanilla primitives. HTML and vanilla JS projects require @byteion/js for behavior-driven interactive components.

Wire Tailwind into Vite

// vite.config.js
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

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

Single CSS entry

Create src/app.css. @import "tailwindcss" loads Tailwind v4. @import "@byteion/core" loads Byteion UI tokens, variables, and foundation styles. The @source directive helps Tailwind v4 detect classes used inside Byteion packages. Use the /src path for @byteion/js (which publishes source files directly) and the /dist path for @byteion/react and @byteion/vue (which ship precompiled files):

@import "tailwindcss";
@import "@byteion/core";

/* Optional brand themes */
@import "@byteion/core/theme/themes/acme.css";
@import "@byteion/core/theme/themes/midnight.css";

/* Tell Tailwind to scan packages for used classes */
@source "../node_modules/@byteion/js/src";       /* for vanilla JS */
@source "../node_modules/@byteion/react/dist";   /* if React */
@source "../node_modules/@byteion/vue/dist";     /* if Vue */

Tailwind v3

Install the package matching your framework stack:

HTML / Vanilla JS

npm install tailwindcss@^3 postcss autoprefixer @byteion/core@0.2.0-beta.1 @byteion/js@0.2.0-beta.1
npx tailwindcss init -p

React

npm install tailwindcss@^3 postcss autoprefixer @byteion/core@0.2.0-beta.1 @byteion/react@0.2.0-beta.1
npx tailwindcss init -p

Vue

npm install tailwindcss@^3 postcss autoprefixer @byteion/core@0.2.0-beta.1 @byteion/vue@0.2.0-beta.1
npx tailwindcss init -p

Configure Tailwind

ESM projects can use import, while CommonJS projects can use require. Ensure content paths include your app source plus whichever Byteion framework packages are being used:

// tailwind.config.js (ES Module)
import preset from '@byteion/core/preset';

/** @type {import('tailwindcss').Config} */
export default {
  presets: [preset],
  content: [
    './src/**/*.{html,js,jsx,ts,tsx,vue}',
    './node_modules/@byteion/js/src/**/*.js',            // if HTML/vanilla JS
    './node_modules/@byteion/react/dist/**/*.{js,cjs}',   // if React
    './node_modules/@byteion/vue/dist/**/*.{js,cjs}',     // if Vue
  ],
  darkMode: ['variant', ['&:is(.dark *)', '&:is([data-theme="dark"] *)']],
};

// tailwind.config.js (CommonJS)
const preset = require('@byteion/core/preset');

/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [preset],
  content: [
    './src/**/*.{html,js,jsx,ts,tsx,vue}',
    './node_modules/@byteion/js/src/**/*.js',
    './node_modules/@byteion/react/dist/**/*.{js,cjs}',
    './node_modules/@byteion/vue/dist/**/*.{js,cjs}',
  ],
  darkMode: ['variant', ['&:is(.dark *)', '&:is([data-theme="dark"] *)']],
};

CSS entry

Create src/app.css and import Byteion’s generated token CSS and runtime variables before Tailwind’s layers:

@import "@byteion/core/theme/generated/tokens.css";  /* primitives */
@import "@byteion/core/theme/variables.css";         /* semantic variables */
@import "@byteion/core/theme/themes/acme.css";       /* optional brand */

@tailwind base;
@tailwind components;
@tailwind utilities;

Initialize behavior runtime

For HTML/vanilla projects using interactive components driven by data-bi-* attributes, import and initialize the behavior runtime in your main JavaScript entry file:

import ByteionCore from '@byteion/js';

ByteionCore.init();

In framework projects (React/Vue), this step is only needed if you are directly using the vanilla behavior runtime rather than native component wrappers.

CDN bundle

The CDN build is published from @byteion/core and includes the precompiled CSS plus the behavior runtime. No build pipeline is required.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- Pre-compiled CSS - all utilities + default + dark + acme + midnight themes -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@byteion/core@0.2.0-beta.1/dist/byteion.min.css">

  <!-- JS behavior runtime - defines window.ByteionCore -->
  <script defer src="https://cdn.jsdelivr.net/npm/@byteion/core@0.2.0-beta.1/dist/byteion.min.js"></script>
  <script defer>
    document.addEventListener('DOMContentLoaded', () => ByteionCore.init());
  </script>
</head>
<body class="bg-background text-foreground font-sans">
  <button type="button" class="inline-flex h-10 items-center rounded-button bg-primary px-4 text-sm font-medium text-primary-foreground shadow-button hover:bg-primary/90 outline-none focus:ring-2 focus:ring-primary/20">
    Hello, Byteion!
  </button>
</body>
</html>

Package map

Verify the install

This test verifies both the token CSS and the behavior runtime. Drop this snippet into any page. The button should look styled, and clicking it should open a centred dialog with the overlay backdrop:

<button type="button"
  data-bi-modal-toggle="hello"
  class="inline-flex h-10 items-center rounded-lg bg-primary px-4 text-sm font-medium text-primary-foreground shadow-button outline-none focus:ring-2 focus:ring-primary/20">
  Open dialog
</button>

<div id="hello" data-bi-modal
  class="fixed inset-0 z-modal hidden items-center justify-center bg-background/60 p-4 backdrop-blur-sm">
  <div class="rounded-xl border border-border bg-card p-6 shadow-modal">
    <h2 class="text-lg font-semibold text-foreground">Hello, Byteion!</h2>
    <p class="mt-2 text-sm text-muted-foreground">If you see this, the install worked.</p>
    <button data-bi-modal-hide class="mt-4 inline-flex h-9 items-center rounded-lg border border-border px-3 text-sm font-medium text-foreground outline-none focus:ring-2 focus:ring-primary/20">Close</button>
  </div>
</div>

Troubleshooting

@import "tailwindcss";
@import "@byteion/core";

@import "@byteion/core/theme/generated/tokens.css";
@import "@byteion/core/theme/variables.css";

import ByteionCore from '@byteion/js';

ByteionCore.init();

document.addEventListener('DOMContentLoaded', () => ByteionCore.init());

@source "../node_modules/@byteion/react/dist";
@source "../node_modules/@byteion/vue/dist";

'./node_modules/@byteion/react/dist/**/*.{js,cjs}',
'./node_modules/@byteion/vue/dist/**/*.{js,cjs}'

darkMode: ['variant', ['&:is(.dark *)', '&:is([data-theme="dark"] *)']]

Next steps

• Quick start — build your first page end-to-end.
• Design tokens — learn what powers every component.
• Browse components — copy snippets straight into your project.
• Theming — change the brand color in one variable.