@mivabyte/ui

The production-grade React 19 UI component system and semantic design tokens for high-craft applications, dashboards, and marketing surfaces.

Quick Start • Component Catalog • Design System • Accessibility • Storybook • Documentation

---

Highlights

• 📦 Zero Copy-Paste Required: Shipped as a fully compiled, tree-shakeable npm package (@mivabyte/ui) with dual ESM and CommonJS exports and bundled TypeScript declarations.
• 🎨 Midnight, Cyan & Azure Visual System: A cohesive, distinctive color language engineered with semantic HSL channels. Features rich deep navy dark surfaces, energetic cyan highlights, and crisp azure daylight actions.
• ⚡ 66 Production-Ready Component Primitives: Built on battle-tested Radix UI and @shadcn/react foundations, from buttons and responsive dialogs to TanStack data tables and Recharts visualizations.
• 🎯 Precise Subpath Imports: Fine-grained subpath exports (@mivabyte/ui/button, @mivabyte/ui/card, @mivabyte/ui/dialog) guarantee minimal bundle footprints and prevent barrel file bloat.
• ♿ WCAG 2.1 AA Compliance Built-In: Fully tested with Axe Core across all components. Keyboard traps, accessible dialog lifecycles, ARIA roles, and high-contrast focus outlines work out of the box.
• 📏 Adaptive Density Scaling: Seamlessly switch between spacious touch-friendly comfortable mode and information-dense compact desktop mode via data-density.
• 🔤 Self-Hosted Typography: The Onest variable font is self-hosted and compiled directly into @mivabyte/ui/styles.css with zero external Google Fonts network dependencies.
• 🚀 Native React 19 & Next.js App Router: Zero runtime CSS-in-JS overhead; fully compatible with React Server Components (RSC), Next.js 15+, Vite, and modern bundlers.

---

Installation

Install @mivabyte/ui and its peer dependencies into your project:

# npm
npm install @mivabyte/ui

# pnpm
pnpm add @mivabyte/ui

# yarn
yarn add @mivabyte/ui

# bun
bun add @mivabyte/ui

Peer Dependency Requirement: @mivabyte/ui requires react >= 19.0.0 and react-dom >= 19.0.0.

---

Quick start

1. Import Global Styles

Import @mivabyte/ui/styles.css once at your application root (e.g. app/layout.tsx, src/main.tsx, or _app.tsx). It bundles Tailwind CSS utilities, self-hosted Onest variable fonts, and core design tokens:

// app/layout.tsx (Next.js App Router) or src/main.tsx (Vite)
import "@mivabyte/ui/styles.css"

2. Compose Your Application

import * as React from "react"
import { Button } from "@mivabyte/ui/button"
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@mivabyte/ui/card"
import { Field, FieldDescription, FieldLabel } from "@mivabyte/ui/field"
import { Input } from "@mivabyte/ui/input"
import { Toaster } from "@mivabyte/ui/toast"

export function ProjectSetup() {
  const [name, setName] = React.useState("")

  return (
    <div className="flex min-h-screen items-center justify-center p-6 bg-background text-foreground">
      <Card className="w-full max-w-md">
        <CardHeader>
          <CardTitle>Create Project</CardTitle>
          <CardDescription>
            Configure your workspace deployment settings.
          </CardDescription>
        </CardHeader>
        <CardContent className="space-y-4">
          <Field>
            <FieldLabel htmlFor="project-name">Project name</FieldLabel>
            <Input
              id="project-name"
              placeholder="e.g. Apollo Telemetry"
              value={name}
              onChange={(e) => setName(e.target.value)}
              required
            />
            <FieldDescription>
              Unique identifier used in API routing and logs.
            </FieldDescription>
          </Field>

          <Button className="w-full" size="default">
            Deploy workspace
          </Button>
        </CardContent>
      </Card>
      <Toaster />
    </div>
  )
}

---

Import Architecture

@mivabyte/ui provides dual export paths to support both granular bundle optimization and rapid prototyping.

Subpath Imports (Recommended)

Subpath imports bypass root barrel files, ensuring optimal tree-shaking, fast bundler startup, and minimal production bundle sizes:

import { Button } from "@mivabyte/ui/button"
import { Card, CardContent, CardHeader } from "@mivabyte/ui/card"
import { DataTable } from "@mivabyte/ui/data-table"
import { Dialog, DialogContent, DialogTrigger } from "@mivabyte/ui/dialog"
import {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
} from "@mivabyte/ui/field"
import { Input } from "@mivabyte/ui/input"
import { ChartContainer, ChartTooltip } from "@mivabyte/ui/chart"
import { Sidebar, SidebarTrigger } from "@mivabyte/ui/sidebar"

Root Barrel Import

For rapid prototyping or small script bundles, all components and utilities are also accessible from the package root:

import { Badge, Button, Card, Dialog, Input, Tabs, Tooltip } from "@mivabyte/ui"

Authoritative Export Catalog: For the complete machine-verified subpath and module inventory, consult docs/generated/exports.md.

---

Component Catalog

@mivabyte/ui contains 66 component modules, grouped into logical architectural families:

Category	Primitives & Modules
Actions & Triggers	Button, ButtonGroup, Toggle, ToggleGroup
Forms & User Input	Input, InputGroup, InputOTP, Textarea, Checkbox, RadioGroup, Select, NativeSelect, Switch, Slider, DatePicker, Calendar, Field, Combobox, Questionnaire
Overlays & Dialogs	Dialog, AlertDialog, Sheet, Drawer, Popover, Tooltip, HoverCard, ContextMenu, DropdownMenu, Command
Navigation	NavigationMenu, Breadcrumb, Pagination, Tabs, Menubar, Sidebar, Direction
Layout & Structure	Container, Card, Separator, Resizable, ScrollArea, AspectRatio, Collapsible, Accordion
Data Display & Content	DataTable, Table, Badge, Avatar, Skeleton, Empty, Item, Bubble, Attachment, Marker, Message, MessageScroller, Carousel, Kbd, KbdGroup
Typography	Heading, Text, Eyebrow, Label
Feedback & Status	Alert, Progress, Spinner, Toast (Toaster, toast)
Data Visualization	Chart (ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent)

For comprehensive API signatures, props interfaces, and code examples for every component, refer to docs/components.md.

---

Design System and Tokens

The Mivabyte design system balances technical precision with warm human typography and deliberate visual depth. Read DESIGN.md for the complete design contract.

The Midnight, Cyan & Azure Palette

• Light Mode (:root / .light): A clean, cool canvas (--background: 202 68% 97%) anchored by an Azure action tone (--primary: 198 92% 31%), providing high clarity without harsh starkness.
• Dark Mode (.dark): A rich Midnight navy canvas (--background: 218 63% 6%) illuminated by vibrant Cyan accents (--primary: 188 86% 53% and --accent: 194 57% 17%).

To enable dark mode, toggle the .dark class on the <html> or <body> element:

<html class="dark">
  <!-- Themed automatically -->
</html>

Surface Elevation Hierarchy

Elevation in Mivabyte UI is communicated via structured tonal layers rather than exaggerated shadows:

Canvas (--background)
  └── Section Layer (--section)
        └── Card / Surface Layer (--surface)
              └── Floating / Elevated Layer (--surface-elevated, --popover)
                    └── Interactive Highlight (--surface-interactive)

Density Control

Mivabyte UI supports contextual interface density via the data-density attribute:

• data-density="comfortable" (Default): 44px control height, spacious touch padding, fluid reading rhythms.
• data-density="compact": 32px control height on desktop, tight information hierarchy designed for data grids and dense operator consoles.

{
  /* Dense workspace region */
}
;<div data-density="compact" className="space-y-2">
  <Input placeholder="Filter records..." />
  <Button size="compact">Search</Button>
</div>

Touch Target Safety: When viewed on touch devices or coarse pointers, Mivabyte UI automatically retains accessible 44px minimum target areas even in compact density mode.

Typography System

The visual role of text is strictly separated from the underlying semantic HTML element:

import { Heading, Text, Eyebrow } from "@mivabyte/ui/typography"

;<section className="space-y-3">
  <Eyebrow>Platform Architecture</Eyebrow>
  <Heading variant="display" render={<h1 />}>
    Engineered for mission-critical velocity.
  </Heading>
  <Text variant="lead">
    High-craft components with zero-compromise accessibility.
  </Text>
</section>

• Heading Variants: display, statement, page, section, title, card, signal.
• Text Variants: lead, body, muted, code.

---

Forms & Validation

Form composition uses semantic helper primitives that manage labels, helper descriptions, and error announcements while leaving DOM identifiers and binding under consumer control:

import {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
} from "@mivabyte/ui/field"
import { Input } from "@mivabyte/ui/input"

;<Field>
  <FieldLabel htmlFor="email">Work Email</FieldLabel>
  <Input
    id="email"
    type="email"
    aria-describedby="email-desc"
    placeholder="alex@mivabyte.com"
  />
  <FieldDescription id="email-desc">
    We will never share your email with third parties.
  </FieldDescription>
  {/* <FieldError>Invalid email address</FieldError> */}
</Field>

Compatible with react-hook-form, zod, Formik, or standard HTML form submissions.

---

Accessibility & Motion

• A11y Standards: Strict WCAG 2.1 Level AA compliance across all components, validated with automated Axe Core integration tests.
• Keyboard Navigation: Native keyboard orchestration across all complex families (Arrow navigation in Menubars, Dropdowns, and Tabs; Escape key dismissal for Overlays; Tab cycling with focus trapping in Dialogs and Sheets).
• Reduced Motion: All animations and transitions automatically respect user preferences via @media (prefers-reduced-motion: reduce). Essential loading indicators (such as Skeleton and Spinner) retain visible state without animated pulsation.
• High-Contrast & Forced Colors: Tested and hardened against Windows High Contrast mode and browser forced-colors environments. Focus rings use double-offset styling for clear visibility over any surface.

---

Interactive Storybook

Storybook provides an interactive sandbox for inspecting all 66 components, their token foundations, and complete full-page compositions (marketing websites and administrative dashboards).

# Start local Storybook development server
npm run storybook

CI strictly verifies that every registered component in config/components.mjs has a corresponding Storybook story with zero orphan primitives.

---

Development & Testing

Mivabyte UI maintains an exhaustive verification suite with zero tolerance for broken types, missing exports, bundle regressions, or accessibility failures.

Local Verification

# Clean dependency installation (avoids executing arbitrary lifecycle scripts)
npm ci --ignore-scripts

# Run the complete verification suite
npm run verify

The canonical npm run verify command runs:

1. lint: ESLint rules across all source, story, test, and script files.
2. format:check: Prettier code style validation.
3. audit:source: Security audit forbidding unsafe code generation patterns.
4. registry:check: Validates consistency between component catalog, source, and exports.
5. storybook:check: Verifies 100% story coverage across all components.
6. typecheck: TypeScript check with strict compiler configurations.
7. build: Builds ESM and CJS bundles (tsup), compiles CSS (tailwindcss), and emits declaration files.
8. bundle:check: Enforces strict bundle budgets on all distribution targets.
9. test:contracts: Verifies package export contracts and upstream baseline guarantees.
10. pack:check: Builds a dry-run tarball and validates packed package contents.
11. package:lint: Runs publint (package export health) and attw (Are The Types Wrong).
12. api:check: Validates public surface against Microsoft API Extractor contract report.
13. test:coverage: Executes Vitest unit tests with v8 code coverage reporting.

End-to-End & Design Testing

# Run Playwright E2E browser tests across Chromium, Firefox, WebKit
npm run test:e2e

# Run Playwright design, accessibility, and composition tests
npm run test:design

---

Releases & Governance

• Changeset-Driven: All releases are declared using Changesets. Every user-facing feature or fix includes a changeset markdown file.
• Calendar Versioning (CalVer): Releases follow the format YY.M.D-patch (e.g. 26.9.10-1).
• Cryptographic Provenance: Published directly through GitHub Actions with OpenID Connect (OIDC) token exchange, npm provenance attestations, and zero static token storage.
• Registry Release Probe: Post-publish CI job pulls the newly released package from npm and executes integration smoke tests in clean Vite and Next.js consumer fixtures.

See docs/maintainers/releases.md for maintainer publishing procedures.

---

Documentation Directory

Document	Purpose
DESIGN.md	Canonical design contract, color philosophy, typography, and motion specifications
docs/components.md	Complete component catalog, API signatures, and usage patterns
docs/generated/exports.md	Machine-generated authoritative package export and subpath map
docs/upstream/component-parity.md	Parity tracking against upstream shadcn/ui primitives
docs/accessibility/keyboard-interactions.md	Keyboard interaction and focus management specification
docs/maintainers/releases.md	Release workflow and publishing procedures
docs/migration/shadcn-compatible-release.md	Migration guide from legacy versions to the pure Radix/shadcn distribution

---

License

MIT © Mivabyte