@work-rjkashyap/unified-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Unified UI Changelog
+
+All notable changes to the Unified UI design system will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-02-27
+
+### Added
+
+#### Design Tokens
+
+- Color palettes: `slate`, `gray`, `zinc`, `neutral`, `red`, `green`, `blue`, `amber`, `teal`, `brand`, `pure`
+- Semantic color mappings for light and dark themes (`semanticLight`, `semanticDark`)
+- Spacing scale (0–96 + custom values)
+- Typography tokens: `fontFamily` (display, sans, serif, mono, inherit), `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, typography variant presets
+- Radius scale (`none` through `full`)
+- Shadow scale with light and dark variants
+- Z-index scale (`hide`, `base`, `dropdown`, `sticky`, `overlay`, `modal`, `popover`, `toast`, `max`)
+- Motion tokens: `duration`, `easing`, `spring`, `stagger` (with CSS and seconds variants)
+
+#### Theme System
+
+- CSS variable contract using `--ds-` prefix for all tokens
+- `DSThemeProvider` component with light/dark/system mode support
+- `useDSTheme()` hook for programmatic theme access
+- `buildLightThemeVars()` / `buildDarkThemeVars()` / `buildThemeCSS()` utilities
+- `cssVar()` helper for type-safe CSS variable references
+
+#### Typography System
+
+- Multi-font architecture with four font families:
+  - **Outfit** (`--font-outfit`) — primary sans-serif UI typeface
+  - **Inter** (`--font-inter`) — display / headings
+  - **Lora** (`--font-lora`) — serif / editorial
+  - **JetBrains Mono** (`--font-jetbrains`) — monospace / code
+- `font` prop on `Typography` component for runtime font switching
+- Graceful fallback to system font stacks when web fonts are unavailable
+
+#### Tailwind CSS v4 Integration
+
+- `design-system.css` with full `@theme` block mapping all tokens to Tailwind utilities
+- `ds-*` prefixed utilities for colors, radius, shadows, transitions, fonts
+- Font CSS custom properties (`--font-outfit`, `--font-inter`, `--font-lora`, `--font-jetbrains`)
+
+#### Primitive Components
+
+- **Typography** — polymorphic text component with `variant`, `font`, `color`, `align`, `truncate` props
+- **Heading** — semantic heading (h1–h6) with automatic size mapping
+- **Subheading** — secondary heading variant
+- **Body** — paragraph text with size variants
+- **Caption** — small supporting text
+- **Label** — form label with required indicator support
+- **Overline** — uppercase label text
+- **InlineCode** — inline code formatting
+- **Container** — responsive max-width wrapper (`sm` through `2xl`)
+- **Stack** — flexbox layout with `direction`, `gap`, `align`, `justify`
+- **Grid** — CSS grid layout with responsive column configuration
+- **Divider** — horizontal/vertical separator with label support
+
+#### Composite Components (22 total)
+
+- **Button** — primary, secondary, outline, ghost, danger, link variants; sm/md/lg sizes; icon-only mode; loading state
+- **Input** — text input with prefix/suffix slots, error state, disabled state
+- **Textarea** — auto-resize support, character count, error state
+- **Select** — Radix-based with groups, labels, separators; searchable variant
+- **Checkbox** — with `CheckboxGroup` for managing groups; indeterminate state
+- **Radio** — `RadioGroup` + `RadioGroupItem` + `RadioCard` variant
+- **Switch** — toggle with label positioning (start/end), sizes
+- **Card** — composable `Card` / `CardHeader` / `CardBody` / `CardFooter`; elevated, outline, ghost variants
+- **Badge** — default, secondary, outline, success, warning, danger variants; sm/md/lg sizes
+- **Avatar** — image with fallback initials, status indicator, `AvatarGroup` stacking
+- **Tooltip** — Radix-based with configurable side, align, delay
+- **Popover** — Radix-based with arrow, close button, controlled/uncontrolled
+- **DropdownMenu** — full Radix menu with items, checkbox items, radio items, sub-menus, shortcuts
+- **Dialog** — modal with sm/md/lg/xl/full sizes; composable header/body/footer; scroll locking
+- **Sheet** — slide-out drawer from top/right/bottom/left; sm/md/lg/xl sizes
+- **Tabs** — underline, segment, pills variants; horizontal/vertical orientation
+- **Accordion** — single/multiple mode; default/bordered/ghost variants; sm/md/lg sizes
+- **Toast** — portal-based with stacking, auto-dismiss, pause-on-hover, progress bar, `useToast()` hook
+- **Alert** — info, success, warning, error variants with icon, title, description
+- **Skeleton** — base `Skeleton` + `SkeletonText`, `SkeletonCircle`, `SkeletonRect` presets; pulse animation
+- **Table** — semantic table with striped rows, hover highlight, sticky header, responsive wrapper; compact/default/relaxed density
+- **Pagination** — page numbers with ellipsis, prev/next, compact variant, controlled/uncontrolled
+- **Breadcrumb** — composable sub-components + `BreadcrumbNav` shorthand; truncation with ellipsis
+
+#### Motion System
+
+- Fade presets: `fadeIn`, `fadeInFast`, `fadeInSlow`
+- Slide presets: `slideUp`, `slideUpSm`, `slideUpLg`, `slideUpSpring`, `slideDown`, `slideDownSm`, `slideLeft`, `slideRight`, `slideInFromLeft`, `slideInFromRight`, `slideInFromBottom`
+- Scale presets: `scaleIn`, `scaleInLg`, `scaleInSpring`
+- Blur presets: `blurIn`, `blurInSubtle`
+- Overlay/modal: `overlayBackdrop`, `modalContent`, `modalContentSpring`
+- Toast: `toastSlideIn`, `toastSlideUp`
+- Expand/collapse: `expandHeight`, `expandHeightSlow`
+- Micro-interactions: `press`, `tapScale`, `hoverScale`, `hoverLift`, `pop`, `popSubtle`
+- Loading: `pulse`, `spin`
+- Stagger containers: `staggerContainer`, `staggerContainerFast`, `staggerContainerSlow`
+- `motionProps()` spread helper for clean JSX usage
+- `reduceMotion` / `withReducedMotion()` utilities for `prefers-reduced-motion` support
+
+#### Utilities
+
+- `cn()` — class name merger (clsx + tailwind-merge)
+- `mergeSlots()` — slot-based class merging for composite components
+- `composeRefs()` — compose multiple React refs into one
+- `dsAttr()` / `dsDataAttrs()` — data attribute generators for component identification
+- `dsStateAttr()` — conditional data attribute for component states
+- `dsVar()` / `dsColorVar()` — CSS custom property reference helpers
+- `typedKeys()` — type-safe `Object.keys`
+- `noop` — no-operation function
+- Polymorphic component types: `AsProp`, `PolymorphicProps`, `PolymorphicPropsWithRef`, `PolymorphicRef`, `PolymorphicComponent`
+- Slot types: `SlotClasses`, `SlotConfig`, `SlotDefinition`, `SlotRenderFn`, `Slots`
+- Component types: `ComponentSize`, `ComponentIntent`, `ChildrenProps`, `OptionalChildrenProps`
+
+#### Package & Build
+
+- `tsup` build pipeline producing ESM (`.mjs`) and CJS (`.cjs`) with TypeScript declarations (`.d.ts` / `.d.cts`)
+- 7 entry points: `index`, `tokens`, `theme`, `primitives`, `components`, `motion`, `utils`
+- Selective `"use client"` directive — applied only to client entry points (not tokens/utils)
+- Radix UI packages externalized as optional peer dependencies
+- Tree-shakeable with code splitting enabled
+- `design-system.css` exported as `unified-ui/css` for Tailwind `@theme` integration
+- `@unified-ui/*` TypeScript path aliases (zero relative cross-directory imports)
+- Consumer documentation: `INSTALL.md` with setup guide, font loading, theme provider, import patterns, troubleshooting
+
+#### Infrastructure
+
+- `UNIFIED_UI_VERSION` exported constant for runtime version checking
+- `.npmignore` for clean package distribution
+- `sideEffects` field for optimal tree-shaking
+- Conditional `exports` map with full `import`/`require`/`types` resolution
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- Documentation site overhaul (Phase 6) — MDX pages with interactive component previews
+- Motion & accessibility hardening (Phase 7) — focus ring standardization, WCAG AA contrast audit, `prefers-reduced-motion` audit
+- Migration guide (Phase 9) — mapping from legacy `fd-*` tokens to `ds-*` tokens, component replacement strategy
+- CI/CD pipeline for automated publishing on git tags
+- `UnifiedUIProvider` component for optional auto CSS injection
+
+---
+
+_Design system: Unified UI v0.1.0_
+_Maintainer: Rajeshwar Kashyap_

package/README.md

@@ -0,0 +1,365 @@
+# @work-rjkashyap/unified-ui
+
+> A scalable, token-driven React design system built with Tailwind CSS v4, Radix UI, and Framer Motion.
+
+[![npm version](https://img.shields.io/npm/v/@work-rjkashyap/unified-ui)](https://www.npmjs.com/package/@work-rjkashyap/unified-ui)
+[![license](https://img.shields.io/npm/l/@work-rjkashyap/unified-ui)](./LICENSE)
+
+---
+
+## Features
+
+- **Token-driven** — Every color, spacing, radius, shadow, and motion value flows from a single source of truth
+- **22+ components** — Battle-tested composites built on Radix UI primitives
+- **Tailwind CSS v4** — First-class integration via `@theme` and `ds-*` utility classes
+- **Framer Motion** — Consistent animation presets with `prefers-reduced-motion` support
+- **Accessible** — WCAG AA contrast, keyboard navigation, ARIA attributes, and focus management
+- **Tree-shakeable** — 7 independent entry points with ESM/CJS dual output and code splitting
+- **Type-safe** — Full TypeScript coverage with exported types for every prop, variant, and token
+
+---
+
+## Installation
+
+```bash
+npm install @work-rjkashyap/unified-ui
+```
+
+### Peer Dependencies
+
+| Package        | Version   | Required |
+| -------------- | --------- | -------- |
+| `react`        | ≥ 19.0.0  | Yes      |
+| `react-dom`    | ≥ 19.0.0  | Yes      |
+| `tailwindcss`  | ≥ 4.0.0   | Optional |
+
+Radix UI primitives and Framer Motion are optional — install only the ones you use:
+
+```bash
+# If using motion presets
+npm install framer-motion
+
+# If using Radix-based components (Dialog, Select, Tabs, etc.)
+npm install @radix-ui/react-dialog @radix-ui/react-select @radix-ui/react-tabs
+# ... and any other @radix-ui/* packages for the components you need
+```
+
+---
+
+## Quick Start
+
+### 1. Import the CSS
+
+Add the stylesheet to your global CSS file **before** any component usage. This registers all `--ds-*` CSS custom properties and Tailwind `@theme` utilities.
+
+```css
+/* src/app/globals.css */
+@import "tailwindcss";
+@import "@work-rjkashyap/unified-ui/styles.css";
+```
+
+### 2. Load Fonts (Recommended)
+
+Unified UI references four font families via CSS variables. Load them in your root layout:
+
+```tsx
+// src/app/layout.tsx
+import { Outfit, Inter, Lora, JetBrains_Mono } from "next/font/google";
+
+const outfit = Outfit({ subsets: ["latin"], variable: "--font-outfit" });
+const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });
+const lora = Lora({ subsets: ["latin"], variable: "--font-lora" });
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ["latin"],
+  variable: "--font-jetbrains",
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html
+      lang="en"
+      className={`${outfit.variable} ${inter.variable} ${lora.variable} ${jetbrainsMono.variable} ${outfit.className}`}
+    >
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+If you don't load these fonts, the system gracefully falls back to system font stacks.
+
+### 3. Wrap with Theme Provider (Optional)
+
+If you need programmatic light/dark/system theme toggling:
+
+```tsx
+import { DSThemeProvider } from "@work-rjkashyap/unified-ui";
+
+export default function Providers({ children }) {
+  return <DSThemeProvider>{children}</DSThemeProvider>;
+}
+```
+
+If you already use `next-themes` or another provider that toggles the `.dark` class on `<html>`, the CSS variables respond automatically — no `DSThemeProvider` needed.
+
+### 4. Use Components
+
+```tsx
+import { Button, Heading, Body, Stack } from "@work-rjkashyap/unified-ui";
+
+export function Hero() {
+  return (
+    <Stack direction="column" gap={4}>
+      <Heading level={1}>Welcome to Unified UI</Heading>
+      <Body>A token-driven design system for React applications.</Body>
+      <Button variant="primary" size="md">
+        Get Started
+      </Button>
+    </Stack>
+  );
+}
+```
+
+---
+
+## Import Patterns
+
+### Barrel import (most common)
+
+```tsx
+import { Button, Typography, fadeIn, cn } from "@work-rjkashyap/unified-ui";
+```
+
+### Layer-specific imports (better tree-shaking in large apps)
+
+```tsx
+import { spacing, radius } from "@work-rjkashyap/unified-ui/tokens";
+import { DSThemeProvider } from "@work-rjkashyap/unified-ui/theme";
+import { Typography, Heading } from "@work-rjkashyap/unified-ui/primitives";
+import { Button, Dialog } from "@work-rjkashyap/unified-ui/components";
+import { slideUp, motionProps } from "@work-rjkashyap/unified-ui/motion";
+import { cn, mergeSlots } from "@work-rjkashyap/unified-ui/utils";
+```
+
+---
+
+## Architecture
+
+The design system is organized into strict layers. Each layer only depends on the layers below it — never sideways or upward.
+
+```
+┌─────────────────────────────────────────────────┐
+│  Layer 6: Utilities         src/utils/           │
+│  Layer 5: Motion System     src/motion/          │
+│  Layer 4: Components        src/components/      │
+│  Layer 3: Primitives        src/primitives/      │
+│  Layer 2: Theme System      src/theme/           │
+│  Layer 1: Design Tokens     src/tokens/          │
+└─────────────────────────────────────────────────┘
+```
+
+### Layer 1 — Design Tokens (`tokens/`)
+
+Raw design values: colors, spacing, typography, radius, shadows, z-index, and motion timing. The **single source of truth** for all visual properties.
+
+| File            | Contents                                                      |
+| --------------- | ------------------------------------------------------------- |
+| `colors.ts`     | Color palettes + semantic maps for light/dark                 |
+| `spacing.ts`    | 4px-grid spacing scale                                        |
+| `typography.ts` | Font families, sizes, weights, line heights, letter spacing   |
+| `radius.ts`     | Border radius scale                                           |
+| `shadows.ts`    | Box shadow elevation scale (light + dark)                     |
+| `z-index.ts`    | Z-index layering scale                                        |
+| `motion.ts`     | Duration, easing, spring, and stagger tokens                  |
+
+### Layer 2 — Theme System (`theme/`)
+
+Bridges tokens to runtime via CSS custom properties and React context.
+
+| File           | Contents                                                        |
+| -------------- | --------------------------------------------------------------- |
+| `contract.ts`  | Maps token keys → CSS variable names (`--ds-*`), `cssVar` helper |
+| `provider.tsx` | `DSThemeProvider` + `useDSTheme` hook                           |
+
+### Layer 3 — Primitives (`primitives/`)
+
+Foundational UI building blocks:
+
+- **Typography** — `Typography`, `Heading`, `Body`, `Caption`, `Label`, `Overline`, `InlineCode`
+- **Layout** — `Container`, `Stack`, `Grid`
+- **Structural** — `Divider`
+
+### Layer 4 — Components (`components/`)
+
+22 production-ready composite components:
+
+| Component      | Component       | Component      |
+| -------------- | --------------- | -------------- |
+| Accordion      | Dialog          | Select         |
+| Alert          | DropdownMenu    | Sheet          |
+| Avatar         | Input           | Skeleton       |
+| Badge          | Pagination      | Switch         |
+| Breadcrumb     | Popover         | Table          |
+| Button         | Radio           | Tabs           |
+| Card           | Checkbox        | Textarea       |
+|                |                 | Toast / Tooltip|
+
+### Layer 5 — Motion (`motion/`)
+
+Framer Motion animation presets: `fadeIn`, `slideUp`, `scaleIn`, `modalContent`, `toastSlideIn`, stagger containers, micro-interactions, and reduced-motion utilities.
+
+### Layer 6 — Utilities (`utils/`)
+
+- `cn()` — class merging (clsx + tailwind-merge)
+- `mergeSlots()` — slot-based class composition
+- `composeRefs()` — combine multiple refs
+- `dsAttr()` / `dsStateAttr()` — data attribute generators
+- `dsVar()` / `dsColorVar()` — CSS variable reference helpers
+- Focus ring utilities
+- WCAG contrast checking utilities
+- Polymorphic component types
+
+---
+
+## CSS Variable Prefix
+
+All CSS custom properties use the `--ds-` prefix:
+
+```
+--ds-color-primary
+--ds-radius-md
+--ds-shadow-lg
+--ds-duration-normal
+--ds-easing-standard
+--ds-font-sans
+```
+
+### Tailwind Utility Classes
+
+After importing the CSS, use `ds-*` prefixed Tailwind utilities anywhere:
+
+```html
+<!-- Colors (supports opacity modifier) -->
+<div class="bg-ds-primary text-ds-primary-foreground">Primary</div>
+<div class="bg-ds-muted/50">Semi-transparent muted</div>
+
+<!-- Radius, shadows, transitions -->
+<div class="rounded-ds-md shadow-ds-lg">Elevated card</div>
+<button class="duration-ds-fast ease-ds-standard">Animated</button>
+
+<!-- Fonts -->
+<p class="font-ds-serif">Editorial text</p>
+<code class="font-ds-mono">console.log("hello")</code>
+```
+
+### Data Attributes
+
+Components emit `data-ds` attributes for CSS scoping and testing:
+
+```html
+<button data-ds data-ds-component="button" data-ds-variant="primary" data-ds-size="md">
+  Click me
+</button>
+```
+
+---
+
+## Entry Points
+
+The package provides 7 independently importable entry points for optimal tree-shaking:
+
+| Entry Point   | Import Path                     | Contains                           |
+| ------------- | ------------------------------- | ---------------------------------- |
+| Root          | `@work-rjkashyap/unified-ui`             | Everything (barrel)                |
+| Tokens        | `@work-rjkashyap/unified-ui/tokens`      | Design tokens (pure JS, no React)  |
+| Theme         | `@work-rjkashyap/unified-ui/theme`       | Theme provider, contract, hooks    |
+| Primitives    | `@work-rjkashyap/unified-ui/primitives`  | Typography, Layout, Divider        |
+| Components    | `@work-rjkashyap/unified-ui/components`  | All 22 composite components        |
+| Motion        | `@work-rjkashyap/unified-ui/motion`      | Animation presets and utilities     |
+| Utils         | `@work-rjkashyap/unified-ui/utils`       | cn, mergeSlots, contrast, etc.     |
+| CSS           | `@work-rjkashyap/unified-ui/styles.css`  | Tailwind @theme + CSS variables    |
+
+---
+
+## Build
+
+The package is built with [tsup](https://tsup.egoist.dev/), producing:
+
+- **ESM** (`.mjs`) and **CJS** (`.cjs`) formats
+- **TypeScript declarations** (`.d.ts` / `.d.cts`)
+- Code splitting enabled for optimal bundle size
+- Selective `"use client"` directive on client entry points (tokens/utils remain server-safe)
+
+```bash
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Type check
+npm run typecheck
+
+# Clean dist/
+npm run clean
+```
+
+---
+
+## Key Rules
+
+1. **Never hardcode design values.** All colors, spacing, radii, shadows, and motion values must come from tokens.
+2. **Always use `cn()` for class merging.** Never concatenate class strings manually.
+3. **Components must emit `data-ds` attributes** for scoping and testability.
+4. **Respect the layer hierarchy.** Tokens → Theme → Primitives → Components. No upward imports.
+5. **All components must support `ref` forwarding** via `React.forwardRef`.
+6. **Accessibility is mandatory.** Focus rings, ARIA attributes, keyboard navigation, and `prefers-reduced-motion` support.
+
+---
+
+## Adding a New Component
+
+1. Create `src/components/<name>.tsx`
+2. Use CVA for variant composition (if the component has variants)
+3. Use `cn()` for all class merging
+4. Forward refs with `React.forwardRef`
+5. Add `data-ds`, `data-ds-component`, and relevant `data-ds-*` state attributes
+6. Export from `src/components/index.ts`
+7. Re-export from `src/index.ts`
+
+---
+
+## Version
+
+Check the installed version programmatically:
+
+```tsx
+import { UNIFIED_UI_VERSION } from "@work-rjkashyap/unified-ui";
+console.log(UNIFIED_UI_VERSION); // "0.1.0"
+```
+
+---
+
+## Troubleshooting
+
+### `bg-ds-primary` and other Tailwind utilities aren't working
+
+Make sure you import the CSS **after** `@import "tailwindcss"` in your global stylesheet. The `@theme` block must be processed by Tailwind.
+
+### Fonts aren't loading
+
+Verify that the CSS variables (`--font-outfit`, `--font-inter`, etc.) are applied to the `<html>` element. Inspect with DevTools → Computed Styles.
+
+### Dark mode isn't switching
+
+Unified UI uses the `.dark` class on `<html>` for dark mode. Ensure your theme provider toggles this class.
+
+### Bundle size is larger than expected
+
+Use layer-specific imports (`@work-rjkashyap/unified-ui/components`) instead of the barrel import to improve tree-shaking.
+
+---
+
+## License
+
+MIT © [Rajeshwar Kashyap](https://github.com/work-rjkashyap)

package/dist/chunk-2JFREULQ.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// src/tokens/spacing.ts
+var spacing = {
+  0: "0px",
+  px: "1px",
+  0.5: "2px",
+  1: "4px",
+  1.5: "6px",
+  2: "8px",
+  2.5: "10px",
+  3: "12px",
+  3.5: "14px",
+  4: "16px",
+  5: "20px",
+  6: "24px",
+  7: "28px",
+  8: "32px",
+  9: "36px",
+  10: "40px",
+  11: "44px",
+  12: "48px",
+  14: "56px",
+  16: "64px",
+  20: "80px",
+  24: "96px"
+};
+
+exports.spacing = spacing;