@j3m-quantum/ui

J3M Quantum UI - A React component library with J3M design tokens.

Requirements

• React >= 18
• Tailwind CSS v4 (required - not compatible with v3)
• tw-animate-css >= 1.0.0

Features

• J3M Design Tokens - Orange primary, neutral grays, pill-shaped buttons
• Dark Mode - Full dark theme support via .dark class
• Glass Mode - Frosted glass effects via .theme-glass class
• 60+ Components - Complete UI component library with J3M styling
• All-in-One - Everything bundled, just install and use
• Smooth Animations - Powered by tw-animate-css

Installation

npm install @j3m-quantum/ui tw-animate-css

That's it! All dependencies (Radix UI, lucide-react, etc.) are bundled with the package.

Quick Start

1. Setup Vite + Tailwind

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install
npm add -D tailwindcss @tailwindcss/vite

2. Configure Vite

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

3. Import Styles (IMPORTANT ORDER)

/* src/index.css */
@import "tailwindcss";
@import "tw-animate-css";              /* Required for animations */
@import "@j3m-quantum/ui/styles";      /* J3M theme and tokens */

Order matters! Import tw-animate-css before @j3m-quantum/ui/styles to ensure animations work correctly on Dialog, Sheet, Select, Popover, and other overlay components.

4. Use Components

import { Button, Card, Input, Dialog, DialogTrigger, DialogContent } from '@j3m-quantum/ui'

function App() {
  return (
    <div className="j3m-app-bg min-h-screen p-8">
      <Card className="glass-context">
        <Input placeholder="Enter email" />
        <Dialog>
          <DialogTrigger asChild>
            <Button>Open Dialog</Button>
          </DialogTrigger>
          <DialogContent>
            <p>This dialog has smooth animations!</p>
          </DialogContent>
        </Dialog>
      </Card>
    </div>
  )
}

Theme Modes

The design system supports four theme modes. Use the .j3m-app-bg utility class for proper backgrounds:

Light Mode (Default)

<div className="j3m-app-bg">
  {/* Light themed content */}
</div>

Dark Mode

<div className="dark j3m-app-bg">
  {/* Dark themed content */}
</div>

Glass Mode (Light)

Frosted glass on colorful gradient or image background:

<div className="theme-glass j3m-app-bg">
  {/* Light glass themed content */}
</div>

Glass Mode (Dark)

Dark frosted glass on deep gradient - sophisticated industrial aesthetic:

<div className="dark theme-glass j3m-app-bg">
  {/* Dark glass themed content */}
</div>

Custom Background Images

In glass mode, you can set a custom background image:

:root {
  --j3m-bg-image: url('/your-background.jpg');
}

Glass Context

When using glass mode, cards containing interactive components (inputs, buttons, selects) need the glass-context class for proper styling:

// Correct - inputs and buttons styled properly in glass mode
<Card className="glass-context">
  <CardHeader>
    <CardTitle>Contact Form</CardTitle>
  </CardHeader>
  <CardContent>
    <Input placeholder="Name" />
    <Button>Submit</Button>
  </CardContent>
</Card>

Note: Portal components (Dialog, Sheet, Popover, Select dropdown) automatically adapt to the current theme mode - no glass-context needed.

Design Tokens

Color System: 12-Step Scale

Colors use HEX format for simplicity and compatibility:

| Scale | Steps | Purpose | |-------|-------|---------| | --j3m-orange-1 to --j3m-orange-12 | 12 | Primary/accent colors | | --j3m-gray-1 to --j3m-gray-12 | 12 | Neutral colors |

Scale Step Usage

| Step | Purpose | Example | |------|---------|---------| | 1-2 | Backgrounds | Page bg, subtle areas | | 3-5 | Interactive | Button bg, hover states | | 6-8 | Borders | Input borders, dividers | | 9-10 | Solid colors | Primary buttons | | 11-12 | Text | Body text, headings |

Semantic Tokens

| Token | Description | |-------|-------------| | --primary | Brand accent (#F58446) | | --background | Page background | | --foreground | Main text | | --muted | Subtle backgrounds | | --border | Default borders | | --ring | Focus rings | | --radius | Global border radius (12px) |

Background & Surface Tokens

A hierarchical system that adapts to all four theme modes automatically:

| Token | Purpose | |-------|---------| | --j3m-bg-app | Root app canvas | | --j3m-bg-page | Content area | | --j3m-bg-surface | Cards, sections | | --j3m-bg-surface-hover | Hovered cards | | --j3m-bg-surface-active | Active/pressed cards | | --j3m-bg-elevated | Raised elements | | --j3m-bg-overlay | Popovers, tooltips | | --j3m-bg-muted | Subtle backgrounds | | --j3m-bg-subtle | Very subtle backgrounds | | --j3m-bg-element | Interactive elements | | --j3m-bg-input | Input backgrounds | | --j3m-bg-sidebar | Sidebar background |

These tokens automatically resolve to the correct values in each theme mode:

• Light/Dark solid: Solid gray colors
• Glass Light: Frosted white glass fills
• Glass Dark: Dark frosted glass with blue tint

Dark Glass Primitives

For advanced dark glass customization:

| Token | Description | |-------|-------------| | --j3m-glass-dark-surface | Main dark glass surface | | --j3m-glass-dark-elevated | Elevated dark glass | | --j3m-glass-dark-overlay | Dark glass overlays | | --j3m-glass-dark-border | Subtle white border | | --j3m-glass-dark-element | Interactive element highlight |

Included Dependencies

All of these are bundled and ready to use:

• All Radix UI primitives
• lucide-react (icons)
• cmdk (Command palette)
• vaul (Drawer)
• sonner (Toast notifications)
• recharts (Charts)
• react-day-picker + date-fns (Calendar)
• embla-carousel-react (Carousel)
• react-resizable-panels (Resizable)
• react-hook-form (Form handling)

Exports

// Everything from one package!
import { 
  Button, Card, Dialog, Input,
  SidebarProvider, Sidebar, SidebarContent,
  NavMain, NavUser, SiteHeader,
  EventCalendar, ThemeSwitch
} from '@j3m-quantum/ui'

// Styles (CSS)
import '@j3m-quantum/ui/styles'

Components

Inputs

Button, ButtonGroup, Input, InputGroup, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, Form, Field, Label, CopyButton

Display

Card, Table, Badge, Avatar, UserAvatarsDropdown, Separator, Skeleton, Accordion, Tabs, Calendar, EventCalendar, Carousel, Chart, AspectRatio, Empty, Item, Kbd

Feedback

Alert, AlertDialog, Progress, Tooltip, Sonner (Toast), Spinner

Navigation

Breadcrumb, Pagination, Command, SearchTrigger, DropdownMenu, Menubar, NavigationMenu, ContextMenu

Overlay

Dialog, Drawer, Sheet, Popover, HoverCard

Layout

ScrollArea, Collapsible, Resizable, Sidebar, SidebarProvider, SidebarInset, Section

Utilities

ThemeSwitch, ToolbarCanvas, PlayerCanvas

Blocks

Pre-built, composable sidebar components for enterprise applications.

Sidebar with Header

A collapsible sidebar with sticky header, based on shadcn's sidebar-16.

import { 
  SidebarProvider, 
  SidebarInset, 
  SidebarTrigger,
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SiteHeader,
  NavMain,
  NavUser,
} from '@j3m-quantum/ui'
import { HomeIcon, SettingsIcon } from 'lucide-react'

const navItems = [
  {
    title: "Dashboard",
    url: "/dashboard",
    icon: HomeIcon,
    isActive: true,
    items: [
      { title: "Overview", url: "/dashboard" },
      { title: "Analytics", url: "/dashboard/analytics" },
    ],
  },
]

export default function Dashboard() {
  return (
    <div style={{ "--header-height": "3.5rem" }}>
      <SidebarProvider>
        <SiteHeader 
          trigger={<SidebarTrigger />}
          breadcrumbs={[{ label: "Dashboard" }]} 
        />
        <div className="flex flex-1">
          <Sidebar>
            <SidebarContent>
              <NavMain items={navItems} />
            </SidebarContent>
            <SidebarFooter>
              <NavUser user={{ name: "User", email: "[email protected]", avatar: "" }} />
            </SidebarFooter>
          </Sidebar>
          <SidebarInset>
            <main className="p-4">
              {/* Your content */}
            </main>
          </SidebarInset>
        </div>
      </SidebarProvider>
    </div>
  )
}

Block Components

| Component | Description | |-----------|-------------| | SiteHeader | Sticky header with breadcrumbs and trigger slot | | NavMain | Collapsible navigation groups with sub-items | | NavProjects | Projects section with dropdown actions | | NavSecondary | Secondary links (Support, Feedback) | | NavUser | User avatar with dropdown menu | | SearchForm | Search input component |

Custom Navigation

import { NavMain, type NavItem } from '@j3m-quantum/ui'
import { HomeIcon, SettingsIcon } from 'lucide-react'

const navItems: NavItem[] = [
  {
    title: "Dashboard",
    url: "/dashboard",
    icon: HomeIcon,
    isActive: true,
    items: [
      { title: "Overview", url: "/dashboard" },
      { title: "Analytics", url: "/dashboard/analytics" },
    ],
  },
  {
    title: "Settings",
    url: "/settings",
    icon: SettingsIcon,
    items: [
      { title: "Profile", url: "/settings/profile" },
      { title: "Team", url: "/settings/team" },
    ],
  },
]

<NavMain items={navItems} />

Customization

Override CSS variables after the import:

@import "tailwindcss";
@import "tw-animate-css";
@import "@j3m-quantum/ui/styles";

/* Custom overrides */
:root {
  --primary: #3B82F6;  /* Blue accent instead of orange */
  --radius: 8px;
}

Troubleshooting

Animations not working (Dialog, Sheet, Select, etc.)

Make sure you've:

1. Installed tw-animate-css: npm install tw-animate-css
2. Imported it before the J3M styles:

   @import "tw-animate-css";
   @import "@j3m-quantum/ui/styles";

"Invalid hook call" error

If using local file links during development, add dedupe to your Vite config:

export default defineConfig({
  resolve: {
    dedupe: ["react", "react-dom"],
  },
})

Components look wrong in glass mode

Make sure to add glass-context class to Cards containing interactive components:

<Card className="glass-context">
  <Input />
  <Button>Submit</Button>
</Card>

Cursor Rules (AI Assistant)

If your team uses Cursor or AI coding assistants, we provide ready-to-use rules to ensure consistent usage of the design system.

See cursor-rules-for-consumers.md for:

• Rules to copy into your project's .cursor/rules file
• Quick setup guide for new projects
• Complete component list

This helps AI assistants understand how to use @j3m-quantum/ui correctly and avoid common mistakes.

Version Strategy

We follow semantic versioning (semver):

| Version Change | When to Use | Example | |----------------|-------------|---------| | Patch (0.8.1 → 0.8.2) | Bug fixes, small styling tweaks | Fix button hover color | | Minor (0.8.x → 0.9.0) | New components, new features (backward compatible) | Add new PlayerCanvas component | | Major (0.x.x → 1.0.0) | Breaking changes, API changes, removed components | Rename component props |

Updating

To get the latest version:

npm update @j3m-quantum/ui
# or
npm install @j3m-quantum/ui@latest

Third-Party Licenses

• Event Calendar: Based on big-calendar by Leonardo Ramos, MIT License

License

MIT