@j3m-quantum/ui 0.9.1 → 1.3.0

package/README.md

@@ -84,44 +84,122 @@ function App() {
 
 ## Theme Modes
 
-### Dark Mode
+The design system supports four theme modes. Use the `.j3m-app-bg` utility class for proper backgrounds:
+
+### Light Mode (Default)
+
+```tsx
+<div className="j3m-app-bg">
+  {/* Light themed content */}
+</div>
+```
 
-Add the `dark` class to your root element:
+### Dark Mode
 
 ```tsx
-<div className="dark">
+<div className="dark j3m-app-bg">
   {/* Dark themed content */}
 </div>
 ```
 
-### Glass Mode
+### Glass Mode (Light)
 
-Add `theme-glass` class for frosted glass effects:
+Frosted glass on colorful gradient background:
 
 ```tsx
-<div className="theme-glass">
-  {/* Glass themed content */}
+<div className="theme-glass j3m-app-bg">
+  {/* Light glass themed content */}
 </div>
 ```
 
-Combine with dark mode:
+### Glass Mode (Dark)
+
+Dark frosted glass on deep gradient - sophisticated industrial aesthetic:
 
 ```tsx
-<div className="dark theme-glass">
+<div className="dark theme-glass j3m-app-bg">
   {/* Dark glass themed content */}
 </div>
 ```
 
+### Mesh Variant
+
+For a more complex gradient background, add the `.mesh` class:
+
+```tsx
+<div className="theme-glass j3m-app-bg mesh">
+  {/* Glass with mesh gradient */}
+</div>
+```
+
 ## Design Tokens
 
-| Token | Light | Dark |
-|-------|-------|------|
-| `--primary` | #F58446 | #F58446 |
-| `--background` | #FFFFFF | #333333 |
-| `--foreground` | #333333 | #FFFFFF |
-| `--muted` | #E8E8E8 | #4A4A4A |
-| `--destructive` | #FB3748 | #D00416 |
-| `--radius` | 12px | 12px |
+### 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
 
@@ -141,13 +219,123 @@ All of these are bundled and ready to use:
 ## Exports
 
 ```typescript
-// Components
-import { Button, Card, Dialog, ... } from '@j3m-quantum/ui'
+// Everything from one package!
+import { 
+  Button, Card, Dialog,
+  SidebarProvider, Sidebar, SidebarContent,
+  NavMain, NavUser, SiteHeader 
+} from '@j3m-quantum/ui'
 
 // Styles (CSS)
 import '@j3m-quantum/ui/styles'
 ```
 
+## Blocks
+
+Pre-built, composable sidebar components for enterprise applications.
+
+### Sidebar with Header
+
+A collapsible sidebar with sticky header, based on shadcn's sidebar-16.
+
+```tsx
+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: "user@example.com", 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
+
+```tsx
+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:
@@ -159,7 +347,7 @@ Override CSS variables after the import:
 
 /* Custom overrides */
 :root {
-  --primary: #your-color;
+  --primary: #3B82F6;  /* Blue accent instead of orange */
   --radius: 8px;
 }
 ```
@@ -216,6 +404,10 @@ npm update @j3m-quantum/ui
 npm install @j3m-quantum/ui@latest
 ```
 
+## Third-Party Licenses
+
+- **Event Calendar**: Based on [big-calendar](https://github.com/lramos33/big-calendar) by Leonardo Ramos, MIT License
+
 ## License
 
 MIT