@byteion/core

Tailwind-first design system foundation: tokens, preset, schemas, governance, and reference HTML markup. Behavior lives in @byteion/js; primitive values live in @byteion/tokens.

What's in here

| Path | Purpose | | ----------------------------- | -------------------------------------------------------- | | tailwind.preset.cjs | The Tailwind preset every consumer extends. | | theme/variables.css | Semantic CSS variables (light + dark + reduced-motion). | | theme/generated/tokens.css | Auto-generated primitive variables (do not edit). | | theme/themes/<brand>.css | Optional brand themes (apply via [data-theme]). | | src/components/* | Reference markup, schemas, snippets per component. | | schemas/component.schema.json | Strict JSON schema every component must satisfy. | | scripts/validate-*.mjs | Tokens, schemas, structure, lint, a11y validators. |

Install

npm install @byteion/core @byteion/js @byteion/tokens

Install paths

@byteion/core ships three distribution paths. Pick the one that matches your toolchain.

| Path | When to use | Trade-off | |---|---|---| | Tailwind v4 (recommended) | Greenfield projects, fast builds | Newest Tailwind; one CSS import, no JS config | | Tailwind v3 | Existing v3 codebase, no migration capacity yet | Familiar setup; ships the v3 preset | | CDN bundle | Prototype, demo, codepen, static HTML with no build step | Pre-compiled — can't add custom Tailwind utilities |

Tailwind v4 (recommended)

One CSS import — no JS config:

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

/* If you also installed @byteion/react or @byteion/vue (or use @byteion/js
   directly), tell Tailwind to scan their published sources so any class
   strings built at runtime — e.g. tooltip arrow positioning, toast container
   — get compiled into the output. */
@source "../node_modules/@byteion/react/dist";  /* if React */
@source "../node_modules/@byteion/vue/dist";    /* if Vue   */
@source "../node_modules/@byteion/js/src";      /* always — runtime-built DOM */

That single @byteion/core import wires up:

• primitive palette + semantic vars (light/dark)
• the @theme inline adapter that maps everything into v4's expected namespaces
• dark: variant for both .dark and [data-theme="dark"]
• named z-index utilities (z-modal, z-tooltip, …) and a base border-color reset

Tailwind v3

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

export default {
  presets: [preset],
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
    // Scan published component class strings + JS-driven DOM classes:
    './node_modules/@byteion/react/dist/**/*.{js,cjs}', // if React
    './node_modules/@byteion/vue/dist/**/*.{js,cjs}',   // if Vue
    './node_modules/@byteion/js/src/**/*.js',           // always
  ],
};

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

CDN bundle (no build step)

For prototypes, codepens, or static HTML pages where you don't want a build pipeline. Two files — a pre-compiled Tailwind v4 stylesheet and an IIFE JS bundle that exposes window.ByteionCore.

<!-- pre-compiled CSS: all utilities used by every component, plus the
     default + dark + acme + midnight themes. -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@byteion/[email protected]/dist/byteion.min.css">

<!-- JS behavior runtime — sets window.ByteionCore -->
<script defer src="https://cdn.jsdelivr.net/npm/@byteion/[email protected]/dist/byteion.min.js"></script>
<script defer>
  document.addEventListener('DOMContentLoaded', () => ByteionCore.init());
</script>

After loading, write standard component markup directly:

<button class="bg-primary-600 text-white rounded-button px-4 h-10 shadow-button hover:bg-primary-700 transition">
  Primary
</button>

Brand themes apply via the data-theme attribute — both acme and midnight are bundled, no extra <link> needed:

<html data-theme="acme">

Trade-off: The CSS bundle contains every utility class used by the shipped components (≈140 KB minified). You cannot add custom Tailwind utilities — for that, use the v4 or v3 build-step install path above.

The bundle paths are also accessible via the package exports map for bundler-based consumers who want the pre-compiled output instead of running Tailwind themselves:

import '@byteion/core/cdn/css';
import '@byteion/core/cdn/js';

Multi-theme

<!-- default -->
<html>

<!-- default dark -->
<html class="dark">

<!-- brand "acme" -->
<html data-theme="acme">

<!-- brand "acme" in dark -->
<html data-theme="acme" class="dark">

See THEME_SYSTEM.md for the full contract.

Authoring rules

This package is governed by normative standards:

• COMPONENT_API_STANDARD.md — variant × tone × size × state
• ACCESSIBILITY_STANDARD.md — keyboard, focus, ARIA
• TOKEN_GUIDELINES.md — primitives vs semantic aliases
• VERSIONING.md — SemVer, deprecation, status lifecycle
• QUALITY_CHECKLIST.md — pre-PR checklist
• CONTRIBUTING.md — how to add a component

CI

# Warnings only (advisory)
npm run validate

# Strict — fails the build on any issue (run in CI)
npm run validate:strict

# Runtime tests (needs Playwright installed)
npm test

| Script | Catches | | ------------------ | -------------------------------------------------------------------- | | validate:tokens | Duplicate variables, dark-mode parity, generated-vars existence | | validate:schemas | Strict JSON schema (additionalProperties:false, enums, patterns) | | validate:components | Required folder structure | | lint:components | Hardcoded hex / arbitrary values / numeric z-index, missing aria-label, schema↔markup drift | | check:a11y | Inputs without label, dialog without aria-modal, onclick on non-interactive |

Decisions

See DECISIONS.md. The short version: tokens are CSS variables (runtime theming), components ship as raw HTML (framework-agnostic), JS is data-attribute-driven (decoupled from styling), every standard is enforced by a script.