@yuva-devlab/ui 1.4.4 → 2.1.0

package/README.md

@@ -3,20 +3,33 @@
 [![npm version](https://img.shields.io/npm/v/@yuva-devlab/ui.svg)](https://www.npmjs.com/package/@yuva-devlab/ui)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![React 19](https://img.shields.io/badge/React-19.x-61dafb.svg)](https://react.dev)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x%20%7C%206.x-3178c6.svg)](https://www.typescriptlang.org)
+[![TypeScript 6](https://img.shields.io/badge/TypeScript-6.x-3178c6.svg)](https://www.typescriptlang.org)
+[![W3C Cascade Layers](https://img.shields.io/badge/CSS-W3C%20Cascade%20Layers-22c55e.svg)](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
 
-> Production-ready, fully-typed React component library engineered for the DevLab ecosystem. Built on accessible Radix UI primitives, powered by OKLCH CSS design tokens (`@yuva-devlab/tokens`), and fully compatible with Tailwind CSS 4.
+> Production-ready, fully-typed React component library engineered for the DevLab ecosystem. Built on accessible Radix UI primitives, powered by OKLCH CSS design tokens (`@yuva-devlab/tokens`), and modular W3C Cascade Layers (`@layer dl-*`).
+
+---
+
+## What's New in v2.0.0
+
+- **Pure Platform CSS Architecture**: Completely eliminated Tailwind CSS runtime and utility dependencies from components. Component styling is strictly governed by W3C Cascade Layers (`@layer dl-base, dl-tokens, dl-components, dl-utilities`), eliminating CSS specificity conflicts and removing build-step plugin overhead.
+- **First-Class Typography Primitives**: Added `<Heading>` and `<Text>` primitives with decoupled semantic HTML tags (`as="h1"`..`as="h6"`, `span`, `div`) and visual scales (`size="display" | "h1".."h6"` and `variant="body-lg" | "body" | "body-sm" | "caption" | "code" | "metric"`).
+- **64+ Accessible UI Primitives**: Expanded catalog with Radix UI accessibility compliance and multi-brand responsiveness.
+- **Upgraded Design Tokens Peer**: Upgraded to `@yuva-devlab/tokens@^2.0.0` with isolated brand extensions and native VS Code autocomplete.
 
 ---
 
 ## Features
 
 - 🎨 **Multi-Brand Theme Architecture** - Seamless brand isolation across OrchestrAI, VitalAI, FinAI, Logs, and Portal.
-- ⚡ **Zero-Runtime Overhead** - Driven by standard CSS custom properties and modern OKLCH color spaces.
+- 📐 **Dynamic Theme-Driven Sizing** - Automatic adaptation across brand densities (compact telemetry logs, precision finance tables, athletic kinetic scaling).
+- ⚡ **Pure Platform CSS** - Scoped W3C Cascade Layers (`@layer dl-components, dl-layout, dl-utilities`) and semantic design tokens.
+- 🔤 **Typography Primitives** - First-class `<Heading>` and `<Text>` primitives with semantic decoupling.
+- 📐 **Layout & Composition Primitives** - First-class `<Box>`, `<Flex>`, `<Stack>`, `<Grid>`, and `<Container>` primitives.
 - ♿ **Accessible by Default** - Built on Radix UI primitives with complete WAI-ARIA and keyboard navigation compliance.
-- 🧩 **56+ Core UI Components** - Buttons, Calendars, DatePickers, Drawers, Sheets, Sidebars, Menus, Modals, and more.
-- 🔒 **End-to-End Type Safety** - First-class TypeScript definitions with full polymorphic `asChild` composition support.
-- 📦 **Tree-Shakeable ESM & CJS** - Optimized builds producing clean dual artifacts.
+- 🧩 **64+ Core UI & Layout Primitives** - Buttons, Calendars, DatePickers, Drawers, Sheets, Sidebars, Menus, Modals, EmptyStates, Layouts, and more.
+- 🔒 **End-to-End Type Safety** - First-class TypeScript definitions with full polymorphic `asChild` and `as` composition support.
+- 📦 **Tree-Shakeable ESM & CJS** - Highly optimized builds producing clean dual artifacts.
 
 ---
 
@@ -47,38 +60,56 @@ pnpm add react@^19.0.0 react-dom@^19.0.0 sonner@^2.0.0
 
 ### 1. Configure Styles
 
-In your application's root stylesheet (e.g. `globals.css` or `app.css`), import the token preset, desired brand theme, and component styles:
+In your application's root stylesheet (e.g. `globals.css` or `app.css`), establish the W3C Cascade Layer order and import your desired tokens and styles:
 
 ```css
-@import "tailwindcss";
-@import "@yuva-devlab/tokens/preset.css";
-@import "@yuva-devlab/tokens/themes/orchestrai.css";
-@import "@yuva-devlab/ui/components.css";
+/* 1. Establish W3C Cascade Layer hierarchy */
+@layer dl-base, dl-tokens, dl-components, dl-layout, dl-utilities, dl-app;
+
+/* 2. Import design tokens & brand theme */
+@import "@yuva-devlab/tokens/styles.css";
+@import "@yuva-devlab/tokens/themes/finai.css";
+
+/* 3. Import UI components and layout styles */
+@import "@yuva-devlab/ui/styles.css";
 ```
 
-> **Tip:** You can import any theme preset from `@yuva-devlab/tokens/themes/*` (`orchestrai`, `vitalai`, `finai`, `logs`, `portal`).
+> **Tip:** You can import any theme preset from `@yuva-devlab/tokens/themes/*` (`finai`, `vitalai`, `logs`, `orchestrai`, `portal`).
 
-### 2. Render Components
+### 2. Render Components & Typography Primitives
 
 ```tsx
-import { Button, Card, DatePicker, Badge } from "@yuva-devlab/ui";
+import {
+  Heading,
+  Text,
+  Button,
+  Card,
+  Badge,
+  Stack,
+  Flex,
+} from "@yuva-devlab/ui";
 import { Sparkles } from "lucide-react";
 
 export default function DashboardCard() {
   return (
-    <Card className="p-6 max-w-md shadow-md">
-      <div className="flex items-center justify-between mb-4">
-        <h2 className="text-xl font-bold">DevLab Project</h2>
-        <Badge variant="default">Production</Badge>
-      </div>
-
-      <div className="space-y-4">
-        <DatePicker />
-        <Button variant="primary" className="w-full">
-          <Sparkles className="w-4 h-4 mr-2" />
-          Deploy Pipeline
+    <Card>
+      <Stack gap={4}>
+        <Flex justify="between" align="center">
+          {/* Decoupled semantic level and visual scale */}
+          <Heading as="h2" size="h3">
+            DevLab Portfolio
+          </Heading>
+          <Badge variant="default">Active</Badge>
+        </Flex>
+
+        <Text variant="caption">Last updated 5m ago</Text>
+        <Text variant="metric">$1,248,390.50</Text>
+
+        <Button variant="primary">
+          <Sparkles />
+          Execute Transaction
         </Button>
-      </div>
+      </Stack>
     </Card>
   );
 }
@@ -86,13 +117,52 @@ export default function DashboardCard() {
 
 ---
 
+## Typography Primitives
+
+### Heading Component
+
+The `<Heading>` primitive decouples semantic HTML structure (`as`) from visual appearance (`size`):
+
+```tsx
+import { Heading } from "@yuva-devlab/ui";
+
+// Semantic H1 rendered with compact H3 visual appearance
+<Heading as="h1" size="h3">Compact Header</Heading>
+
+// Display heading for landing pages
+<Heading as="h1" size="display">DevLab Cloud</Heading>
+```
+
+| Prop    | Type                                                                                    | Default      | Description                                              |
+| :------ | :-------------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------- |
+| `as`    | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"span"` \| `"div"`         | `"h2"`       | The semantic HTML element rendered to the DOM.           |
+| `size`  | `"display"` \| `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"`                 | Matches `as` | The visual typographic scale applied via Cascade Layers. |
+| `color` | `"default"` \| `"muted"` \| `"primary"` \| `"accent"` \| `"destructive"` \| `"success"` | `"default"`  | Semantic text color token.                               |
+
+### Text Component
+
+The `<Text>` primitive handles body text, captions, inline code, and tabular metric numerals:
+
+```tsx
+import { Text } from "@yuva-devlab/ui";
+
+<Text variant="body-lg">Large intro body copy</Text>
+<Text variant="body">Standard UI body text</Text>
+<Text variant="body-sm">Small helper description</Text>
+<Text variant="caption">Footnotes and timestamps</Text>
+<Text variant="code">const token = useToken();</Text>
+<Text variant="metric">3,492 req/s</Text>
+```
+
+---
+
 ## Multi-Brand Theming
 
 DevLab UI supports multi-brand switching at runtime using `data-brand` and `data-theme` HTML attributes:
 
 ```html
-<!-- Switch to VitalAI Athletic Theme with Dark Mode -->
-<html data-brand="vitalai" class="dark">
+<!-- Switch to FinAI Spacious Theme with Dark Mode -->
+<html data-brand="finai" class="dark">
   ...
 </html>
 ```
@@ -101,19 +171,33 @@ DevLab UI supports multi-brand switching at runtime using `data-brand` and `data
 
 | Brand Key    | Theme Name        | Primary Aesthetic         | Token Import                                |
 | :----------- | :---------------- | :------------------------ | :------------------------------------------ |
-| `orchestrai` | **OrchestrAI**    | Midnight Neon Violet      | `@yuva-devlab/tokens/themes/orchestrai.css` |
-| `vitalai`    | **VitalAI**       | Athletic Volt Kinetic     | `@yuva-devlab/tokens/themes/vitalai.css`    |
 | `finai`      | **FinAI**         | High-Finance Emerald      | `@yuva-devlab/tokens/themes/finai.css`      |
+| `vitalai`    | **VitalAI**       | Athletic Volt Kinetic     | `@yuva-devlab/tokens/themes/vitalai.css`    |
 | `logs`       | **DevLab Logs**   | High-Density Matrix Amber | `@yuva-devlab/tokens/themes/logs.css`       |
+| `orchestrai` | **OrchestrAI**    | Midnight Neon Violet      | `@yuva-devlab/tokens/themes/orchestrai.css` |
 | `portal`     | **DevLab Portal** | Enterprise Modern Indigo  | `@yuva-devlab/tokens/themes/portal.css`     |
 
 ---
 
-## Component Catalog (56 Components)
+## Component Catalog (64 Components)
+
+### Typography Primitives
+
+- **Heading** - Semantic heading with decoupled visual scale (`display`, `h1`..`h6`).
+- **Text** - Multi-variant typography primitive (`body-lg`, `body`, `body-sm`, `caption`, `code`, `metric`).
+
+### Layout & Composition Primitives
+
+- **Box** - Fundamental container with padding, border, radius, shadow, and surface backgrounds.
+- **Flex** - 1D flexbox container (`direction`, `justify`, `align`, `wrap`, `gap`, `inline`).
+- **Stack** - Vertical or horizontal layout flow with token-governed spacing.
+- **Grid** - Responsive 2D grid (`cols`, `gap`, minItemWidth auto-fit).
+- **Container** - Responsive centered layout container with max-width boundaries (`sm` to `2xl`).
+- **AspectRatio**, **Panel**, **Resizable**, **ScrollArea**, **Separator**
 
-### General & Layout
+### General & Display
 
-- **Button**, **CopyButton**, **Card**, **MetricCard**, **SecretRevealCard**, **Badge**, **StatusBadge**, **StatusChip**, **Separator**, **Skeleton**, **LoadingState**, **AspectRatio**, **ScrollArea**, **Resizable**
+- **Button**, **CopyButton**, **Card**, **MetricCard**, **SecretRevealCard**, **Badge**, **StatusBadge**, **StatusChip**, **Skeleton**, **LoadingState**, **EmptyState**
 
 ### Form & Data Entry
 

package/dist/common.css

@@ -106,46 +106,6 @@
   }
 }
 
-@keyframes dl-spin {
-  from {
-    transform: rotate(0deg);
-  }
-  to {
-    transform: rotate(360deg);
-  }
-}
-
-/* ── Sonner Toast Semantic Feedback ──────────────────────────────────────── */
-[data-sonner-toaster] [data-sonner-toast] {
-  border-radius: var(--radius-md, 0.375rem);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="success"] {
-  border-color: color-mix(in oklch, var(--success) 35%, transparent);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="success"] [data-icon] {
-  color: var(--success);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="error"],
-[data-sonner-toaster] [data-sonner-toast][data-type="destructive"] {
-  border-color: color-mix(in oklch, var(--destructive) 35%, transparent);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="error"] [data-icon],
-[data-sonner-toaster] [data-sonner-toast][data-type="destructive"] [data-icon] {
-  color: var(--destructive);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="warning"] {
-  border-color: color-mix(in oklch, var(--warning) 35%, transparent);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="warning"] [data-icon] {
-  color: var(--warning);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="info"] {
-  border-color: color-mix(in oklch, var(--info) 35%, transparent);
-}
-[data-sonner-toaster] [data-sonner-toast][data-type="info"] [data-icon] {
-  color: var(--info);
-}
-
 /* ── Shared Glass & Surface Utilities ────────────────────────────────────── */
 .dl-glass {
   background-color: var(

package/dist/components/accordion/accordion.mdx

@@ -0,0 +1,18 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as AccordionStories from "./accordion.stories";
+
+<Meta of={AccordionStories} />
+
+<Title />
+
+# Accordion
+
+Vertically stacked set of interactive headings that each reveal a section of content.
+
+## Default
+
+<Canvas of={AccordionStories.Default} />
+
+## Component Properties
+
+<Controls />

package/dist/components/alert/alert.css

@@ -1,9 +1,9 @@
 .dl-alert {
   position: relative;
   width: 100%;
-  border-radius: var(--radius-lg, 0.5rem);
+  border-radius: var(--radius, 0.5rem);
   border: 1px solid var(--border);
-  padding: 0.875rem 1rem;
+  padding: var(--space-4, 0.875rem) var(--space-5, 1rem);
   font-size: 0.875rem;
   display: grid;
   grid-template-columns: 1fr;

package/dist/components/alert-dialog/alert-dialog.mdx

@@ -0,0 +1,18 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as AlertDialogStories from "./alert-dialog.stories";
+
+<Meta of={AlertDialogStories} />
+
+<Title />
+
+# Alert Dialog
+
+Modal dialog that interrupts the user with important content and expects a confirmation or cancellation action.
+
+## Default
+
+<Canvas of={AlertDialogStories.Default} />
+
+## Component Properties
+
+<Controls />

package/dist/components/aspect-ratio/aspect-ratio.mdx

@@ -0,0 +1,22 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as AspectRatioStories from "./aspect-ratio.stories";
+
+<Meta of={AspectRatioStories} />
+
+<Title />
+
+# Aspect Ratio
+
+Displays content within a desired ratio, preventing layout shifts during asset loading.
+
+## Default (16:9)
+
+<Canvas of={AspectRatioStories.Default} />
+
+## Square (1:1)
+
+<Canvas of={AspectRatioStories.Square} />
+
+## Component Properties
+
+<Controls />

package/dist/components/badge/badge.css

@@ -39,38 +39,42 @@
   border-color: var(--border);
 }
 
-.dl-status-badge {
+.dl-badge-wrapper {
+  position: relative;
+  display: inline-flex;
+  vertical-align: middle;
+  flex-shrink: 0;
+}
+
+.dl-badge-count {
+  position: absolute;
+  top: 0;
+  right: 0;
+  transform: translate(50%, -50%);
+  transform-origin: 100% 0%;
+  z-index: 10;
   display: inline-flex;
   align-items: center;
-  gap: 0.375rem;
+  justify-content: center;
+  min-width: 1.25rem;
+  height: 1.25rem;
+  padding: 0 0.375rem;
   border-radius: 9999px;
-  padding: 0.25rem 0.625rem;
-  font-size: 0.75rem;
-  font-weight: 500;
+  background-color: var(--destructive);
+  color: var(--destructive-foreground);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  line-height: 1;
+  white-space: nowrap;
+  box-shadow: 0 0 0 2px var(--background);
 }
-.dl-status-badge__dot {
+
+.dl-badge-dot {
+  min-width: 0.5rem;
   width: 0.5rem;
   height: 0.5rem;
+  padding: 0;
   border-radius: 9999px;
-  flex-shrink: 0;
-}
-.dl-status-badge--success {
-  background-color: color-mix(in oklch, var(--success) 15%, transparent);
-  color: var(--success);
-}
-.dl-status-badge--destructive {
-  background-color: color-mix(in oklch, var(--destructive) 15%, transparent);
-  color: var(--destructive);
-}
-.dl-status-badge--warning {
-  background-color: color-mix(in oklch, var(--warning) 15%, transparent);
-  color: var(--warning);
-}
-.dl-status-badge--info {
-  background-color: color-mix(in oklch, var(--info) 15%, transparent);
-  color: var(--info);
-}
-.dl-status-badge--muted {
-  background-color: var(--muted);
-  color: var(--muted-foreground);
+  background-color: var(--destructive);
+  box-shadow: 0 0 0 2px var(--background);
 }

package/dist/components/badge/badge.mdx

@@ -7,18 +7,20 @@ import * as BadgeStories from "./badge.stories";
 
 # Badge
 
-Displays metadata, statuses, count indicators, or short labels with semantic color tokens.
+Versatile badge primitive supporting both standalone status tags and floating notification counters (`count`, `overflowCount`, `dot`) over icons, avatars, and buttons.
 
 ## Default
 
 <Canvas of={BadgeStories.Default} />
 
-## Variants
-
-Available in `default`, `secondary`, `outline`, `destructive`, `success`, `warning`, and `info`.
+## All Semantic Variants
 
 <Canvas of={BadgeStories.AllVariants} />
 
+## Notification Counter & Status Dot
+
+<Canvas of={BadgeStories.NotificationCounts} />
+
 ## Component Properties
 
 <Controls />

package/dist/components/breadcrumb/breadcrumb.mdx

@@ -0,0 +1,18 @@
+import { Meta, Title, Description, Canvas, Controls } from "@storybook/blocks";
+import * as BreadcrumbStories from "./breadcrumb.stories";
+
+<Meta of={BreadcrumbStories} />
+
+<Title />
+
+# Breadcrumb
+
+Hierarchical navigation trail indicating the current page location within a navigational hierarchy.
+
+## Default
+
+<Canvas of={BreadcrumbStories.Default} />
+
+## Component Properties
+
+<Controls />

package/dist/components/calendar/calendar-nav.css

@@ -0,0 +1,111 @@
+.dl-calendar .rdp-month_caption,
+.dl-calendar .dl-calendar__month-caption {
+  position: relative;
+  display: flex;
+  height: var(--cell-size, 2rem);
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+  padding: 0 var(--cell-size, 2rem);
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--foreground);
+  box-sizing: border-box;
+}
+
+.dl-calendar .rdp-caption_label,
+.dl-calendar .dl-calendar__caption-label {
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--foreground);
+  line-height: 1;
+  user-select: none;
+}
+
+.dl-calendar .dl-calendar__caption-label--interactive {
+  display: flex;
+  height: var(--control-height-sm, 2rem);
+  align-items: center;
+  gap: 0.25rem;
+  border-radius: var(--radius-md, 0.375rem);
+  padding-inline: 0.5rem 0.25rem;
+}
+
+.dl-calendar .dl-calendar__dropdowns {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.dl-calendar .dl-calendar__dropdown-root {
+  position: relative;
+  border-radius: var(--radius-md, 0.375rem);
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow-xs, 0 1px 2px 0 rgb(0 0 0 / 0.05));
+}
+
+.dl-calendar .dl-calendar__dropdown {
+  position: absolute;
+  inset: 0;
+  opacity: 0;
+  background: var(--popover);
+  cursor: pointer;
+}
+
+.dl-calendar .rdp-nav,
+.dl-calendar .dl-calendar__nav {
+  position: absolute;
+  top: 0;
+  inset-inline: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  height: var(--cell-size, 2rem);
+  pointer-events: none;
+}
+
+.dl-calendar .rdp-button_previous,
+.dl-calendar .rdp-button_next,
+.dl-calendar .dl-calendar__nav-button {
+  pointer-events: auto;
+  width: var(--cell-size, 2rem) !important;
+  height: var(--cell-size, 2rem) !important;
+  min-width: var(--cell-size, 2rem) !important;
+  padding: 0 !important;
+  display: inline-flex !important;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-md, 0.375rem) !important;
+  border: 1px solid var(--border);
+  background: var(--background);
+  color: var(--muted-foreground);
+  cursor: pointer;
+  user-select: none;
+  transition: all 0.15s ease;
+}
+
+.dl-calendar .rdp-button_previous:hover,
+.dl-calendar .rdp-button_next:hover,
+.dl-calendar .dl-calendar__nav-button:hover {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+
+.dl-calendar .rdp-button_previous[aria-disabled="true"],
+.dl-calendar .rdp-button_next[aria-disabled="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+.dl-calendar .rdp-button_previous svg,
+.dl-calendar .rdp-button_next svg,
+.dl-calendar .dl-calendar__chevron {
+  width: 1rem;
+  height: 1rem;
+  flex-shrink: 0;
+}