Project Structure

Understand the Byteion monorepo layout and where each piece lives.

Overview

Byteion is organized as an npm workspaces monorepo. The structure separates shared design system packages from applications that consume them. Packages are the source of truth — every component, token, and behavior module lives in a package first.

Workspace layout

byteion/
  packages/
    tokens/      → Design token source of truth
    core/        → HTML primitives, Tailwind preset, CSS variables, schemas
    js/           → Optional vanilla JS behavior runtime
    react/       → React component wrappers
    vue/         → Vue 3 component wrappers
  apps/
    docs/          → Documentation site (this site)
  scripts/
      check-links.js → Broken link checker
      audit-package.js → Package audit utility

Optional / reference workspaces

These workspaces are included in the repository but are not required for consuming Byteion UI in your own projects. They serve internal validation or asset-management purposes.

apps/dashboard-erp/ → Reference dashboard app used internally to validate complex admin workflows
apps/brand/          → Brand assets workspace (logos, colors, fonts)
apps/react-demo/     → Demo app showcasing @byteion/react
apps/vue-demo/       → Demo app showcasing @byteion/vue
apps/react-dashboard/ → Reference dashboard built with @byteion/react
apps/academy/         → Learning resources workspace

Packages

Package	Location	Purpose
@byteion/tokens	packages/tokens	Design token primitives — colors, spacing, radii, shadows, typography, motion, z-index as JS modules. Single source of truth for every visual value.
@byteion/core	packages/core	50+ HTML component primitives, Tailwind v3 preset + v4 entry, CSS variables, component schemas, accessibility docs, CDN bundle.
@byteion/js	packages/js	Optional vanilla JS behavior runtime for interactive components — modal, dropdown, tooltip, tabs, accordion, drawer, toast, popover. Driven by `data-bi-*` attributes.
@byteion/react	packages/react	Typed React component wrappers with `cva()` variant composition. Exports both server-safe and client entry points.
@byteion/vue	packages/vue	Vue 3 component wrappers with `v-model` support and composables. Built on the same design foundation as the other packages.

Apps

Apps consume workspace packages to validate the design system in real contexts and to provide documentation and demos.

docs

This documentation site. Built as static HTML with Vite. Component pages are generated from core schemas and snippets. Content pages are hand-authored or generated from templates.

Packages vs apps

This distinction is important for contributing correctly:

Packages are the source of truth. Every component, token, behavior module, and framework wrapper lives in a package. Changes made in packages affect every consumer.
Apps consume packages. They validate that the design system works in realistic scenarios but should never be the place where design-system fixes are applied.
Rule: If a dashboard or demo needs a new component variant, add it to the package first, then consume it in the app. Do not fix design-system issues only inside apps — the fix would not reach other consumers.

Where to edit what

What you want to change	Where to edit
Design tokens (colors, spacing, shadows, etc.)	packages/tokens/ + packages/core/theme/variables.css
Component HTML markup	packages/core/src/components/<component>/
Component metadata and API contracts	packages/core/src/components/<component>/schema.json
Vanilla JS behavior (modal, dropdown, etc.)	packages/js/src/
React component wrappers	packages/react/src/
Vue 3 component wrappers	packages/vue/src/
Tailwind preset configuration	packages/core/tailwind.preset.cjs
Theme CSS variables and brand themes	packages/core/theme/
Documentation site content	apps/docs/
Generated component doc pages	apps/docs/scripts/generate-component-pages.mjs (via schemas + snippets)

Component anatomy

Every component in packages/core/src/components/ follows the same structure. Here is the button/ directory as an example:

button/
  index.html         → Default component markup (basic, single instance)
  variants.html     → All visual variants — sizes, tones, states, groups
  schema.json       → Component metadata: variants, sizes, tones, states, a11y requirements, CSS variables, API contract
  component.config.json → Config flags (interactive, requiresJS, complexity, accessibility level)
  snippets/           → Usage example snippets consumed by the docs generator
  README.md        → Developer notes (optional, not used by the docs generator)

This structure is consistent across all 50+ components. The schema.json and variants.html files drive documentation generation and automated validation.

Audit and generation scripts

The monorepo includes a suite of scripts to validate consistency, generate documentation, and catch regressions:

Command	What it does
npm run audit:package:core	Audit the core package — validate exported entries, file structure, and dependencies
npm run validate --workspace @byteion/core	Full core validation — tokens, schemas, components, a11y, contrast, semantic neutrals
npm run audit --workspace @byteion/docs	Audit documentation site — check links, SEO metadata, anchor validity
npm run docs:generate	Regenerate component documentation pages from schemas and snippets
npm run check:links	Check for broken links across the entire project (via scripts/check-links.js)
npm run validate:packages	Run validation across all packages (core, js, react, vue)
npm run smoke	Pack all packages and verify imports resolve correctly

Developer tips

• Packages are the source of truth. Never modify component HTML in an app — modify it in the package, then consume the updated package. • Apps validate packages. If a component works in a demo but not in a fresh project, the package export is broken. • Run npm run docs:generate after modifying component schemas or snippets to regenerate the documentation site. • Run npm run docs to start the docs dev server at localhost:5172. • Validate before committing. Run npm run validate:packages to catch token, schema, a11y, and contrast issues early.

Introduction — How the system works end-to-end
Quick Start — Get a project running in minutes
Installation — Three install paths (Tailwind v4, v3, CDN)
Design Tokens — Colors, spacing, shadows, and more
Component Architecture — Browse all 50+ components
React Adapter — Using Byteion in React projects
Vue Adapter — Using Byteion in Vue 3 projects

Unlock Premium Patterns

Get access to copy-paste ready Pro blocks, SaaS templates, and advanced component patterns.

Explore Pro Components