Quick Start

Overview

Get a Byteion UI project running in a few minutes. This guide helps you create a plain HTML + Vite project using @byteion/core (the core CSS and Tailwind preset foundation). We also show how to optionally register @byteion/js for vanilla behavior to power HTML-driven interactive components (such as modals, dropdowns, tabs, accordions, drawers, tooltips, and toasts). React and Vue projects usually do not need @byteion/js when using @byteion/react or @byteion/vue components, because framework components provide their own behavior layer.

Choose your Tailwind version (select only one path). Use Path A for new projects. Use Path B only when your app already uses Tailwind v3.

• Tailwind v4 — recommended for new projects. CSS-first setup with no JS config file.
• Tailwind v3 — use this if your project is already on Tailwind v3. Requires tailwind.config.js and PostCSS.

Step 1: Create a project

mkdir my-app && cd my-app
npm init -y
npm install -D vite

Step 2A: Configure Tailwind v4 (recommended)

Install

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

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 tells Tailwind to scan the package files so it can detect and compile utility classes used inside Byteion packages. Note: @byteion/js distributes source code directly under src with no compile step, so it uses the /src subpath. React and Vue packages compile components to dist/, so their paths use /dist.

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

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

/* Scan runtime-built class strings in @byteion/js */
@source "../node_modules/@byteion/js/src";

Step 2B: Configure Tailwind v3

Tailwind v3 requires a tailwind.config.js, PostCSS config, and CSS token imports.

Install

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

Configure Tailwind

// tailwind.config.js
import preset from '@byteion/core/preset';

/** @type {import('tailwindcss').Config} */
export default {
  presets: [preset],
  content: [
    './index.html',
    './src/**/*.{html,js,jsx,ts,tsx,vue}',
    './node_modules/@byteion/js/src/**/*.js',
  ],
  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. The Tailwind preset maps token variables to utilities, while the CSS imports provide runtime variables. The @tailwind directives are required for v3:

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

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

To override a brand variable, add it under :root — semantic vars use short names (no --color- prefix):

:root {
  --primary: 270 100% 50%;   /* violet brand */
  --ring:    270 100% 50%;
}

Step 3: Build a page

Create index.html using Byteion UI semantic token classes:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My Byteion App</title>
  <link rel="stylesheet" href="/src/app.css">
</head>
<body class="bg-background text-foreground antialiased font-sans">
  <div class="mx-auto max-w-4xl p-8">
    <h1 class="mb-6 text-3xl font-semibold">Hello Byteion UI</h1>
    <div class="rounded-xl border border-border bg-card p-6 shadow-card">
      <p class="mb-4 text-muted-foreground">Your first Byteion UI component.</p>
      <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">
        Get started
      </button>
    </div>
  </div>
  <script type="module" src="/src/main.js"></script>
</body>
</html>

Create src/main.js to import the CSS and register Byteion UI's optional behavior layer for interactive components (modal, dropdown, tabs, accordion, drawer, tooltip, toast):

import './app.css';
import '@byteion/js';

Run npx vite and open the printed local URL.

Starting with React or Vue?

The steps above create a plain HTML + Vite project. If you are starting a new React or Vue app, create the project with the official Vite framework template first:

npm create vite@latest my-app -- --template react
npm create vite@latest my-app -- --template vue

Then apply the same Byteion UI core setup: install @byteion/core, configure Tailwind v4 or v3, and import the CSS entry. You usually do not need @byteion/js when using @byteion/react or @byteion/vue components. After that, install the framework-specific packages shown below.

React add-on

After completing the core setup, install @byteion/react:

npm install @byteion/react@0.2.0-beta.1

Create src/main.tsx — imports the CSS entry:

import './app.css';

Create src/App.tsx — uses components with bare package imports:

import { Button, Card } from '@byteion/react';

export function App() {
  return (
    <Card className="p-6">
      <h1 className="mb-4 text-2xl font-semibold">Hello Byteion UI</h1>
      <Button variant="primary">Get started</Button>
    </Card>
  );
}

If using Tailwind v4, add the React @source line to src/app.css below the core imports so Tailwind scans the compiled React components for used utility classes:

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

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

Vue add-on

After completing the core setup, install @byteion/vue:

npm install @byteion/vue@0.2.0-beta.1

Create src/main.ts — imports the CSS entry:

import './app.css';

Create src/App.vue — uses components with bare package imports:

<script setup lang="ts">
import { Button, Card } from '@byteion/vue';
</script>

<template>
  <Card class="p-6">
    <h1 class="mb-4 text-2xl font-semibold">Hello Byteion UI</h1>
    <Button variant="primary">Get started</Button>
  </Card>
</template>

If using Tailwind v4, add the Vue @source line to src/app.css below the core imports so Tailwind scans the compiled Vue components for used utility classes:

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

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

Verify it works

After running npx vite, confirm the following:

• The card has a border, rounded corners, card background, and drop shadow from Byteion tokens
• The button uses Byteion UI primary colors (bg-primary, text-primary-foreground) and displays a primary glow ring on focus
• The page body uses --background and --foreground token values
• Dark mode works after adding class="dark" to the <html> element
• Interactive components (modal, dropdown, etc.) work after importing @byteion/js
• The production build (npx vite build) does not miss any generated Tailwind classes

Common issues

• Package installed but styles missing — confirm that @import "@byteion/core" (v4) or the token CSS imports (v3) are present in your CSS entry
• React or Vue components render but look unstyled — confirm that ./app.css is imported in your framework entry (main.tsx or main.ts)
• Classes missing in production — confirm that Tailwind content paths (v3) or @source directives (v4) include your app files and Byteion packages
• Dark mode not changing — confirm .dark is applied to the <html> element, not a child wrapper
• Interactive components not working — ensure @byteion/js is imported in your JavaScript entry point
• Build errors with Tailwind v4 — make sure you have tailwindcss@^4 and @tailwindcss/vite, not v3 packages

Related

• Installation — full v3 / v4 / CDN install matrix
• Tailwind Preset — how tokens map to utility classes
• Theming — customize brand colors, dark mode, and motion
• React Guide — use Byteion UI in React projects
• Vue Guide — use Byteion UI in Vue projects
• JavaScript API — initialize interactive components