Tailwind Preset

Overview

@byteion/core is the bridge between Byteion's token system and Tailwind utility classes. The bridge takes a different shape in each Tailwind version:

Without one of these bridges, Byteion-specific utilities such as bg-primary, shadow-card, z-modal, and animate-fade-in will not be generated from the Byteion token system.

Which setup should I use?

• Use Tailwind v4 CSS-first for new projects. It is simpler (one CSS import, no JS config) and is the recommended setup for all new apps.
• Use Tailwind v3 preset for existing Tailwind v3 apps, older Laravel / Vite stacks, or projects that cannot upgrade yet.
• Do not mix the v3 preset and v4 CSS-first setup in the same app — they configure the same tokens through different mechanisms and will conflict.
• Keep app-specific extensions separate from Byteion's core token contract. Use @theme (v4) or theme.extend (v3) for app-only additions; do not modify Byteion's tokens directly.

Tailwind v4 (CSS-first)

v4 configures Tailwind in CSS rather than JS. Place this in your main CSS entry — for example src/app.css, resources/css/app.css, or app/globals.css:

@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 runtime-built class strings */
@source "../node_modules/@byteion/js/src";
@source "../node_modules/@byteion/react/dist";   /* if React */
@source "../node_modules/@byteion/vue/dist";     /* if Vue */

Adjust the @source relative paths based on where your CSS file lives. You need @source when class names live inside distributed Byteion runtime / framework packages that are not in your source tree.

The single @import "@byteion/core" expands to:

1. Primitive palette (--palette-* HSL triplets)
2. Semantic theme layer (--background, --primary, …)
3. v4 @theme inline adapter that maps both into v4 namespaces
4. Dark-mode @custom-variant dark (fires under .dark AND [data-theme="dark"])
5. Named z-index utilities (z-modal, z-tooltip, …)
6. v3-compatible base reset (border-color from --border)
7. Named border widths (border-sm, border-md, border-lg) and decorative backgrounds

Tailwind v3 (preset)

In v3 the bridge is a Tailwind preset (packages/core/tailwind.preset.cjs). Reference it from your tailwind.config.js:

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',           // always
    './node_modules/@byteion/react/dist/**/*.{js,cjs}', // if React
    './node_modules/@byteion/vue/dist/**/*.{js,cjs}',   // if Vue
  ],
  darkMode: ['class', '[data-theme="dark"]'],
};

The preset already sets darkMode: ['class', '[data-theme="dark"]'] so dark: variants fire under both .dark and [data-theme="dark"] selectors. You do not need to redeclare it unless you want to override.

For CommonJS environments (older Next.js, Laravel Mix):

const preset = require('@byteion/core/preset');

module.exports = {
  presets: [preset],
  content: ['./src/**/*.{html,js,jsx,tsx,vue}'],
  darkMode: ['class', '[data-theme="dark"]'],
};

Your CSS entry must load the token files that the preset's utility classes reference at runtime:

@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;

Generated utilities reference CSS variables at runtime, so the variables must be loaded in the browser before components render. Load Byteion defaults before @tailwind base and place app-specific overrides after Byteion defaults.

What gets configured

Extending Byteion

v3 — extend the preset in tailwind.config.js:

import preset from '@byteion/core/preset';

export default {
  presets: [preset],
  theme: {
    extend: {
      colors: { brand: { 50: '#faf5ff', 500: '#8b5cf6' } },
    },
  },
};

v4 — extend with @theme in your CSS:

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

@theme {
  --color-brand-50:  oklch(0.97 0.02 285);
  --color-brand-500: oklch(0.62 0.21 285);
}

Use extension for true app-specific additions. Do not use it to bypass Byteion's semantic token contract — prefer CSS variables for anything that should be themeable across modes or brands.

Common mistakes

Verification checklist

Developer tips

Related

• Installation — full v3 / v4 / CDN install matrix
• CSS Variables — the runtime token layer
• Quick Start — end-to-end project setup, both versions
• Theming Guide — override brand colors via semantic variables
• Dark Mode — class-based toggling and system preference fallback