@alkimi.org/ui-kit 0.9.10 → 0.10.0

package/README.github.md

@@ -1,589 +1,589 @@
-# Alkimi UI Kit
-
-A React component library built with [shadcn/ui](https://ui.shadcn.com/) and [Tailwind CSS](https://tailwindcss.com/).
-
-## Installation
-
-```bash
-npm install @alkimi.org/ui-kit
-```
-
-## Setup
-
-You have **two setup options** depending on your needs:
-
-- **Option A (Recommended)**: Import pre-compiled library styles - simpler setup, works immediately
-- **Option B (Advanced)**: Manual styling with full control - requires more configuration
-
-Choose the option that best fits your project requirements.
-
----
-
-### Option A: Import Library Styles (Recommended)
-
-**Best for**: Most projects. Simple setup with minimal configuration.
-
-**What you get**: Pre-compiled utility classes (`rounded-lg`, `bg-primary`, etc.) + CSS variables + fonts
-
-#### 1. Install Tailwind CSS v4
-
-```bash
-npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
-```
-
-#### 2. Configure PostCSS
-
-Create or update your `postcss.config.js`:
-
-```js
-module.exports = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-    autoprefixer: {},
-  },
-}
-```
-
-#### 3. Import Library Styles
-
-In your root layout file (e.g., `app/layout.tsx` for Next.js App Router):
-
-```tsx
-import "@alkimi.org/ui-kit/styles.css"
-import "./globals.css" // Your custom CSS
-```
-
-**Important**: Import the library styles **before** your custom CSS so you can override variables if needed.
-
-#### 4. Configure Your CSS
-
-Create your `globals.css`:
-
-```css
-@import "tailwindcss";
-
-/* Optional: Override library CSS variables */
-:root {
-  /* Base color variables */
-  --background: oklch(0.992 0.019 155.826);
-  --foreground: oklch(0.205 0 0);
-  --primary: oklch(0.992 0.019 155.826);
-  --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.992 0.019 155.826);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.608 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.992 0.019 155.826);
-  --destructive: oklch(0.576 0.214 25.467);
-  --destructive-foreground: oklch(0.992 0.019 155.826);
-  --border: #3f3f46;
-  --input: #3f3f46;
-  --ring: oklch(0.992 0.019 155.826);
-  --radius: 0.625rem;
-
-  /* Component-specific variables (optional - default to base variables) */
-  /* Override these to customize individual components independently */
-  --sidebar: var(--background);
-  --sidebar-foreground: var(--primary-accent);
-  --sidebar-accent: var(--base-accent);
-  --sidebar-accent-foreground: var(--base-accent-foreground);
-  --sidebar-border: var(--border);
-  --sidebar-ring: var(--ring);
-
-  --card: var(--background);
-  --card-foreground: var(--primary-accent);
-
-  --popover: var(--background);
-  --popover-foreground: var(--primary-accent);
-
-  --dialog: var(--background);
-  --dialog-foreground: var(--foreground);
-
-  --sheet: var(--background);
-  --sheet-foreground: var(--foreground);
-
-  --tooltip: var(--background);
-  --tooltip-foreground: var(--primary-accent);
-
-  --dropdown-menu: var(--background);
-  --dropdown-menu-foreground: var(--primary-accent);
-}
-```
-
-**That's it!** The library components will work immediately because:
-
-- `styles.css` contains pre-compiled utility classes
-- All CSS variables are defined
-- Fonts are included
-- **No `@source` directive needed** (utilities are already compiled into the CSS)
-
-#### When to Use Option A
-
-- You want the quickest setup
-- You're happy with the library's default styling approach
-- You want to customize colors via CSS variables
-- You don't need complete control over Tailwind configuration
-
----
-
-### Option B: Manual Styling (Advanced)
-
-**Best for**: Advanced users who want complete control over CSS generation and Tailwind configuration.
-
-**What you do**: Define all CSS variables yourself and use `@source` to dynamically generate utility classes.
-
-#### 1. Install Tailwind CSS v4
-
-```bash
-npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
-```
-
-#### 2. Configure PostCSS
-
-Create or update your `postcss.config.js`:
-
-```js
-module.exports = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-    autoprefixer: {},
-  },
-}
-```
-
-#### 3. Do NOT Import Library Styles
-
-In your root layout file (e.g., `app/layout.tsx`):
-
-```tsx
-// ❌ Do NOT import library styles in Option B
-// import "@alkimi.org/ui-kit/styles.css"
-
-import "./globals.css" // Only import your custom CSS
-```
-
-#### 4. Configure Your CSS with @source
-
-Create your `globals.css`:
-
-```css
-@import "tailwindcss";
-
-/* REQUIRED: Tell Tailwind v4 to scan library components */
-@source "../node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}";
-
-/* REQUIRED: Define ALL CSS variables the library needs */
-:root {
-  /* Base color variables */
-  --background: oklch(0.992 0.019 155.826);
-  --foreground: oklch(0.205 0 0);
-  --primary: oklch(0.992 0.019 155.826);
-  --primary-foreground: oklch(0.205 0 0);
-  --primary-accent: oklch(0.992 0.019 155.826);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.992 0.019 155.826);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.608 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.992 0.019 155.826);
-  --base-accent: oklch(0.269 0 0);
-  --base-accent-foreground: oklch(0.992 0.019 155.826);
-  --destructive: oklch(0.576 0.214 25.467);
-  --destructive-foreground: oklch(0.992 0.019 155.826);
-  --border: #3f3f46;
-  --input: #3f3f46;
-  --ring: oklch(0.992 0.019 155.826);
-  --radius: 0.625rem;
-  --font-family: "Helvetica Now Display", "Helvetica", sans-serif;
-
-  /* Component-specific variables (default to base variables, can be overridden) */
-  --sidebar: var(--background);
-  --sidebar-foreground: var(--primary-accent);
-  --sidebar-primary: var(--primary-accent);
-  --sidebar-primary-foreground: var(--primary-foreground);
-  --sidebar-accent: var(--base-accent);
-  --sidebar-accent-foreground: var(--base-accent-foreground);
-  --sidebar-border: var(--border);
-  --sidebar-ring: var(--ring);
-
-  --card: var(--background);
-  --card-foreground: var(--primary-accent);
-
-  --popover: var(--background);
-  --popover-foreground: var(--primary-accent);
-
-  --dialog: var(--background);
-  --dialog-foreground: var(--foreground);
-
-  --sheet: var(--background);
-  --sheet-foreground: var(--foreground);
-
-  --tooltip: var(--background);
-  --tooltip-foreground: var(--primary-accent);
-
-  --dropdown-menu: var(--background);
-  --dropdown-menu-foreground: var(--primary-accent);
-}
-
-body {
-  @apply bg-background text-foreground;
-}
-```
-
-**Key points**:
-
-- The `@source` directive tells Tailwind v4 to scan the library's component files
-- Tailwind will dynamically generate utility classes for any classes used in those components
-- You must define all CSS variables the library expects
-- VS Code may show a warning for `@source` - you can safely ignore it (it's a valid Tailwind v4 directive)
-
-#### When to Use Option B
-
-- You want complete control over CSS generation
-- You're customizing Tailwind's configuration extensively
-- You want to manage all CSS variables manually
-- You're comfortable with more advanced Tailwind v4 configuration
-
----
-
-## Customizing Component Colors
-
-The library supports **component-specific color customization**. By default, all components use base color variables, but you can override individual component colors independently.
-
-### How It Works
-
-Component-specific variables (like `--sidebar`, `--card`, `--popover`, etc.) default to base variables but can be overridden:
-
-```css
-:root {
-  /* Base colors */
-  --background: oklch(0.992 0.019 155.826);
-  --primary-accent: oklch(0.992 0.019 155.826);
-
-  /* Override just the sidebar color */
-  --sidebar: oklch(0.2 0.05 200); /* Custom sidebar background */
-  --sidebar-foreground: oklch(0.9 0.02 150); /* Custom sidebar text */
-
-  /* Override card independently */
-  --card: oklch(0.95 0.02 150);
-  --card-foreground: oklch(0.1 0.05 200);
-
-  /* All other components still use --background */
-}
-```
-
-### Available Component Variables
-
-- **Sidebar**: `--sidebar`, `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
-- **Card**: `--card`, `--card-foreground`
-- **Popover**: `--popover`, `--popover-foreground`
-- **Dialog**: `--dialog`, `--dialog-foreground`
-- **Sheet**: `--sheet`, `--sheet-foreground`
-- **Tooltip**: `--tooltip`, `--tooltip-foreground`
-- **Dropdown Menu**: `--dropdown-menu`, `--dropdown-menu-foreground`
-
-### Example: Custom Sidebar Theme
-
-```css
-:root {
-  /* Custom sidebar with different colors */
-  --sidebar: oklch(0.15 0.05 250); /* Dark blue sidebar */
-  --sidebar-foreground: oklch(0.95 0.02 150); /* Light text */
-  --sidebar-accent: oklch(0.25 0.08 250); /* Hover state */
-  --sidebar-accent-foreground: oklch(0.98 0.01 150);
-}
-```
-
----
-
-## Typography & Sizing
-
-### Default Font
-
-The library uses **Helvetica Now Display** as the default font family. This font is included in the library and will be automatically loaded when you import the styles.
-
-### Font Sizes
-
-The library uses **rem-based sizing** with a base font size of **1rem (16px)**. All font sizes use rem units for better accessibility and scalability:
-
-- **Base text**: 1rem (16px)
-- **Small text**: 0.875rem (14px) - Used in small buttons, captions, etc.
-- **Large text**: 1.125rem (18px) and above
-
-### Button Sizes
-
-Buttons have the following font sizes by default:
-
-- **Small** (`size="sm"`): 0.875rem (14px)
-- **Default**: 1rem (16px)
-- **Large** (`size="lg"`): 1rem (16px)
-
-You can override these sizes using Tailwind's text utility classes (e.g., `className="text-lg"`) on any component.
-
-## Customizing Font
-
-You can override the default font family by setting the `--font-family` CSS variable in your own CSS file:
-
-```css
-/* In your app.css or globals.css */
-@import "tailwindcss";
-@import "@alkimi.org/ui-kit/styles.css";
-
-@layer base {
-  :root {
-    /* Override the library's default font */
-    --font-family: "Your Custom Font", "Helvetica", sans-serif;
-  }
-}
-```
-
-Make sure to include your custom font using `@font-face` or a web font service like Google Fonts:
-
-```css
-/* Example: Using Google Fonts */
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
-
-@layer base {
-  :root {
-    --font-family: "Inter", system-ui, sans-serif;
-  }
-}
-```
-
-## Available Components
-
-### Sidebar
-
-A collapsible sidebar component with responsive design and keyboard shortcuts. The sidebar supports multiple variants, collapsible modes, and includes all necessary sub-components for building navigation interfaces.
-
-#### Basic Usage
-
-```tsx
-import {
-  Sidebar,
-  SidebarContent,
-  SidebarHeader,
-  SidebarProvider,
-  SidebarInset,
-  SidebarTrigger,
-} from "@alkimi.org/ui-kit"
-
-function App() {
-  return (
-    <SidebarProvider>
-      <Sidebar collapsible="icon">
-        <SidebarHeader showTrigger>
-          <h2>My App</h2>
-        </SidebarHeader>
-        <SidebarContent>{/* Your sidebar content */}</SidebarContent>
-      </Sidebar>
-      <SidebarInset>
-        <header>
-          <SidebarTrigger />
-          <h1>Main Content Area</h1>
-        </header>
-        {/* Your main content */}
-      </SidebarInset>
-    </SidebarProvider>
-  )
-}
-```
-
-#### Components
-
-##### SidebarProvider
-
-Wraps your entire layout and provides sidebar context.
-
-**Props:**
-
-- `defaultOpen?: boolean` - Initial sidebar state (default: `true`)
-- `open?: boolean` - Controlled sidebar state
-- `onOpenChange?: (open: boolean) => void` - Callback when sidebar state changes
-
-##### Sidebar
-
-The main sidebar container.
-
-**Props:**
-
-- `side?: "left" | "right"` - Sidebar position (default: `"left"`)
-- `variant?: "sidebar" | "floating" | "inset"` - Visual style (default: `"sidebar"`)
-- `collapsible?: "offcanvas" | "icon" | "none"` - Collapse behavior (default: `"offcanvas"`)
-  - `offcanvas` - Sidebar slides completely off-screen
-  - `icon` - Sidebar collapses to icon-only mode
-  - `none` - Sidebar is always visible and non-collapsible
-
-##### SidebarHeader
-
-Header section of the sidebar.
-
-**Props:**
-
-- `showTrigger?: boolean` - Show toggle button in header (default: `false`)
-
-##### SidebarContent
-
-Scrollable content area of the sidebar.
-
-##### SidebarFooter
-
-Footer section of the sidebar.
-
-##### SidebarTrigger
-
-Button to toggle sidebar visibility. Automatically shows appropriate icons for mobile and desktop.
-
-##### SidebarInset
-
-Main content area wrapper that adapts to sidebar state.
-
-##### Navigation Components
-
-Build navigation menus using these components:
-
-```tsx
-import {
-  SidebarMenu,
-  SidebarMenuItem,
-  SidebarMenuButton,
-  SidebarGroup,
-  SidebarGroupLabel,
-  SidebarGroupContent,
-} from "@alkimi.org/ui-kit"
-
-;<SidebarGroup>
-  <SidebarGroupLabel>Navigation</SidebarGroupLabel>
-  <SidebarGroupContent>
-    <SidebarMenu>
-      <SidebarMenuItem>
-        <SidebarMenuButton tooltip="Home">
-          <Home />
-          <span>Home</span>
-        </SidebarMenuButton>
-      </SidebarMenuItem>
-    </SidebarMenu>
-  </SidebarGroupContent>
-</SidebarGroup>
-```
-
-**Available Components:**
-
-- `SidebarGroup` - Groups related menu items
-- `SidebarGroupLabel` - Label for a group
-- `SidebarGroupContent` - Container for group items
-- `SidebarGroupAction` - Action button for a group
-- `SidebarMenu` - Menu list container
-- `SidebarMenuItem` - Individual menu item
-- `SidebarMenuButton` - Interactive menu button with tooltip support
-- `SidebarMenuAction` - Action button for menu items
-- `SidebarMenuBadge` - Badge/count indicator
-- `SidebarMenuSub` - Submenu container
-- `SidebarMenuSubItem` - Submenu item
-- `SidebarMenuSubButton` - Submenu button
-
-##### SidebarMenuButton Props
-
-- `variant?: "default" | "outline"` - Visual style
-- `size?: "default" | "sm" | "lg"` - Button size
-- `isActive?: boolean` - Highlight as active
-- `tooltip?: string | TooltipProps` - Tooltip text or props
-- `asChild?: boolean` - Render as child component (e.g., for links)
-
-##### Utility Components
-
-- `SidebarInput` - Styled input for sidebar (e.g., search)
-- `SidebarSeparator` - Visual separator
-- `SidebarRail` - Clickable rail for toggling sidebar
-- `SidebarMenuSkeleton` - Loading skeleton for menu items
-
-##### useSidebar Hook
-
-Access sidebar state and controls from any component within `SidebarProvider`:
-
-```tsx
-import { useSidebar } from "@alkimi.org/ui-kit"
-
-function MyComponent() {
-  const { state, open, toggleSidebar, isMobile } = useSidebar()
-
-  return (
-    <div>
-      Sidebar is {state} {/* "expanded" or "collapsed" */}
-    </div>
-  )
-}
-```
-
-**Returns:**
-
-- `state: "expanded" | "collapsed"` - Current sidebar state
-- `open: boolean` - Whether sidebar is open (desktop)
-- `setOpen: (open: boolean) => void` - Set sidebar state
-- `openMobile: boolean` - Whether sidebar is open (mobile)
-- `setOpenMobile: (open: boolean) => void` - Set mobile sidebar state
-- `isMobile: boolean` - Whether viewing on mobile
-- `toggleSidebar: () => void` - Toggle sidebar visibility
-
-#### Keyboard Shortcuts
-
-- `Cmd+B` (Mac) or `Ctrl+B` (Windows/Linux) - Toggle sidebar
-
-#### Responsive Behavior
-
-- **Desktop**: Sidebar is fixed and collapsible based on the `collapsible` prop
-- **Mobile**: Sidebar automatically becomes a slide-out sheet overlay
-
-## Usage
-
-You can import components in two ways:
-
-### Option 1: Import from Main Package
-
-Import all components from the main package entry point:
-
-```tsx
-import { Button, Tabs } from "@alkimi.org/ui-kit"
-
-function App() {
-  return (
-    <div>
-      <Button>Click me</Button>
-      <Button variant="secondary">Secondary</Button>
-      <Button variant="destructive">Delete</Button>
-      <Button variant="outline">Outline</Button>
-      <Button variant="ghost">Ghost</Button>
-      <Button variant="link">Link</Button>
-      <Button size="sm">Small</Button>
-      <Button size="lg">Large</Button>
-    </div>
-  )
-}
-```
-
-### Option 2: Import Individual Components (Optimized Bundle Size)
-
-For better code splitting and smaller production bundles, import components individually:
-
-```tsx
-// Import only the Button component
-import { Button } from "@alkimi.org/ui-kit/button"
-
-// Import only the Tabs components
-import {
-  Tabs,
-  TabsList,
-  TabsTrigger,
-  TabsContent,
-} from "@alkimi.org/ui-kit/tabs"
-
-// Import utilities
-import { cn } from "@alkimi.org/ui-kit/utils"
-```
-
-**Note**: Both import methods require installing the full `@alkimi.org/ui-kit` package. The individual imports help optimize your production bundle size (only used components are included), but don't reduce installation size.
-
-## License
-
-MIT
+# Alkimi UI Kit
+
+A React component library built with [shadcn/ui](https://ui.shadcn.com/) and [Tailwind CSS](https://tailwindcss.com/).
+
+## Installation
+
+```bash
+npm install @alkimi.org/ui-kit
+```
+
+## Setup
+
+You have **two setup options** depending on your needs:
+
+- **Option A (Recommended)**: Import pre-compiled library styles - simpler setup, works immediately
+- **Option B (Advanced)**: Manual styling with full control - requires more configuration
+
+Choose the option that best fits your project requirements.
+
+---
+
+### Option A: Import Library Styles (Recommended)
+
+**Best for**: Most projects. Simple setup with minimal configuration.
+
+**What you get**: Pre-compiled utility classes (`rounded-lg`, `bg-primary`, etc.) + CSS variables + fonts
+
+#### 1. Install Tailwind CSS v4
+
+```bash
+npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
+```
+
+#### 2. Configure PostCSS
+
+Create or update your `postcss.config.js`:
+
+```js
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+    autoprefixer: {},
+  },
+}
+```
+
+#### 3. Import Library Styles
+
+In your root layout file (e.g., `app/layout.tsx` for Next.js App Router):
+
+```tsx
+import "@alkimi.org/ui-kit/styles.css"
+import "./globals.css" // Your custom CSS
+```
+
+**Important**: Import the library styles **before** your custom CSS so you can override variables if needed.
+
+#### 4. Configure Your CSS
+
+Create your `globals.css`:
+
+```css
+@import "tailwindcss";
+
+/* Optional: Override library CSS variables */
+:root {
+  /* Base color variables */
+  --background: oklch(0.992 0.019 155.826);
+  --foreground: oklch(0.205 0 0);
+  --primary: oklch(0.992 0.019 155.826);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.992 0.019 155.826);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.608 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.992 0.019 155.826);
+  --destructive: oklch(0.576 0.214 25.467);
+  --destructive-foreground: oklch(0.992 0.019 155.826);
+  --border: #3f3f46;
+  --input: #3f3f46;
+  --ring: oklch(0.992 0.019 155.826);
+  --radius: 0.625rem;
+
+  /* Component-specific variables (optional - default to base variables) */
+  /* Override these to customize individual components independently */
+  --sidebar: var(--background);
+  --sidebar-foreground: var(--primary-accent);
+  --sidebar-accent: var(--base-accent);
+  --sidebar-accent-foreground: var(--base-accent-foreground);
+  --sidebar-border: var(--border);
+  --sidebar-ring: var(--ring);
+
+  --card: var(--background);
+  --card-foreground: var(--primary-accent);
+
+  --popover: var(--background);
+  --popover-foreground: var(--primary-accent);
+
+  --dialog: var(--background);
+  --dialog-foreground: var(--foreground);
+
+  --sheet: var(--background);
+  --sheet-foreground: var(--foreground);
+
+  --tooltip: var(--background);
+  --tooltip-foreground: var(--primary-accent);
+
+  --dropdown-menu: var(--background);
+  --dropdown-menu-foreground: var(--primary-accent);
+}
+```
+
+**That's it!** The library components will work immediately because:
+
+- `styles.css` contains pre-compiled utility classes
+- All CSS variables are defined
+- Fonts are included
+- **No `@source` directive needed** (utilities are already compiled into the CSS)
+
+#### When to Use Option A
+
+- You want the quickest setup
+- You're happy with the library's default styling approach
+- You want to customize colors via CSS variables
+- You don't need complete control over Tailwind configuration
+
+---
+
+### Option B: Manual Styling (Advanced)
+
+**Best for**: Advanced users who want complete control over CSS generation and Tailwind configuration.
+
+**What you do**: Define all CSS variables yourself and use `@source` to dynamically generate utility classes.
+
+#### 1. Install Tailwind CSS v4
+
+```bash
+npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
+```
+
+#### 2. Configure PostCSS
+
+Create or update your `postcss.config.js`:
+
+```js
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+    autoprefixer: {},
+  },
+}
+```
+
+#### 3. Do NOT Import Library Styles
+
+In your root layout file (e.g., `app/layout.tsx`):
+
+```tsx
+// ❌ Do NOT import library styles in Option B
+// import "@alkimi.org/ui-kit/styles.css"
+
+import "./globals.css" // Only import your custom CSS
+```
+
+#### 4. Configure Your CSS with @source
+
+Create your `globals.css`:
+
+```css
+@import "tailwindcss";
+
+/* REQUIRED: Tell Tailwind v4 to scan library components */
+@source "../node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}";
+
+/* REQUIRED: Define ALL CSS variables the library needs */
+:root {
+  /* Base color variables */
+  --background: oklch(0.992 0.019 155.826);
+  --foreground: oklch(0.205 0 0);
+  --primary: oklch(0.992 0.019 155.826);
+  --primary-foreground: oklch(0.205 0 0);
+  --primary-accent: oklch(0.992 0.019 155.826);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.992 0.019 155.826);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.608 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.992 0.019 155.826);
+  --base-accent: oklch(0.269 0 0);
+  --base-accent-foreground: oklch(0.992 0.019 155.826);
+  --destructive: oklch(0.576 0.214 25.467);
+  --destructive-foreground: oklch(0.992 0.019 155.826);
+  --border: #3f3f46;
+  --input: #3f3f46;
+  --ring: oklch(0.992 0.019 155.826);
+  --radius: 0.625rem;
+  --font-family: "Helvetica Now Display", "Helvetica", sans-serif;
+
+  /* Component-specific variables (default to base variables, can be overridden) */
+  --sidebar: var(--background);
+  --sidebar-foreground: var(--primary-accent);
+  --sidebar-primary: var(--primary-accent);
+  --sidebar-primary-foreground: var(--primary-foreground);
+  --sidebar-accent: var(--base-accent);
+  --sidebar-accent-foreground: var(--base-accent-foreground);
+  --sidebar-border: var(--border);
+  --sidebar-ring: var(--ring);
+
+  --card: var(--background);
+  --card-foreground: var(--primary-accent);
+
+  --popover: var(--background);
+  --popover-foreground: var(--primary-accent);
+
+  --dialog: var(--background);
+  --dialog-foreground: var(--foreground);
+
+  --sheet: var(--background);
+  --sheet-foreground: var(--foreground);
+
+  --tooltip: var(--background);
+  --tooltip-foreground: var(--primary-accent);
+
+  --dropdown-menu: var(--background);
+  --dropdown-menu-foreground: var(--primary-accent);
+}
+
+body {
+  @apply bg-background text-foreground;
+}
+```
+
+**Key points**:
+
+- The `@source` directive tells Tailwind v4 to scan the library's component files
+- Tailwind will dynamically generate utility classes for any classes used in those components
+- You must define all CSS variables the library expects
+- VS Code may show a warning for `@source` - you can safely ignore it (it's a valid Tailwind v4 directive)
+
+#### When to Use Option B
+
+- You want complete control over CSS generation
+- You're customizing Tailwind's configuration extensively
+- You want to manage all CSS variables manually
+- You're comfortable with more advanced Tailwind v4 configuration
+
+---
+
+## Customizing Component Colors
+
+The library supports **component-specific color customization**. By default, all components use base color variables, but you can override individual component colors independently.
+
+### How It Works
+
+Component-specific variables (like `--sidebar`, `--card`, `--popover`, etc.) default to base variables but can be overridden:
+
+```css
+:root {
+  /* Base colors */
+  --background: oklch(0.992 0.019 155.826);
+  --primary-accent: oklch(0.992 0.019 155.826);
+
+  /* Override just the sidebar color */
+  --sidebar: oklch(0.2 0.05 200); /* Custom sidebar background */
+  --sidebar-foreground: oklch(0.9 0.02 150); /* Custom sidebar text */
+
+  /* Override card independently */
+  --card: oklch(0.95 0.02 150);
+  --card-foreground: oklch(0.1 0.05 200);
+
+  /* All other components still use --background */
+}
+```
+
+### Available Component Variables
+
+- **Sidebar**: `--sidebar`, `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
+- **Card**: `--card`, `--card-foreground`
+- **Popover**: `--popover`, `--popover-foreground`
+- **Dialog**: `--dialog`, `--dialog-foreground`
+- **Sheet**: `--sheet`, `--sheet-foreground`
+- **Tooltip**: `--tooltip`, `--tooltip-foreground`
+- **Dropdown Menu**: `--dropdown-menu`, `--dropdown-menu-foreground`
+
+### Example: Custom Sidebar Theme
+
+```css
+:root {
+  /* Custom sidebar with different colors */
+  --sidebar: oklch(0.15 0.05 250); /* Dark blue sidebar */
+  --sidebar-foreground: oklch(0.95 0.02 150); /* Light text */
+  --sidebar-accent: oklch(0.25 0.08 250); /* Hover state */
+  --sidebar-accent-foreground: oklch(0.98 0.01 150);
+}
+```
+
+---
+
+## Typography & Sizing
+
+### Default Font
+
+The library uses **Helvetica Now Display** as the default font family. This font is included in the library and will be automatically loaded when you import the styles.
+
+### Font Sizes
+
+The library uses **rem-based sizing** with a base font size of **1rem (16px)**. All font sizes use rem units for better accessibility and scalability:
+
+- **Base text**: 1rem (16px)
+- **Small text**: 0.875rem (14px) - Used in small buttons, captions, etc.
+- **Large text**: 1.125rem (18px) and above
+
+### Button Sizes
+
+Buttons have the following font sizes by default:
+
+- **Small** (`size="sm"`): 0.875rem (14px)
+- **Default**: 1rem (16px)
+- **Large** (`size="lg"`): 1rem (16px)
+
+You can override these sizes using Tailwind's text utility classes (e.g., `className="text-lg"`) on any component.
+
+## Customizing Font
+
+You can override the default font family by setting the `--font-family` CSS variable in your own CSS file:
+
+```css
+/* In your app.css or globals.css */
+@import "tailwindcss";
+@import "@alkimi.org/ui-kit/styles.css";
+
+@layer base {
+  :root {
+    /* Override the library's default font */
+    --font-family: "Your Custom Font", "Helvetica", sans-serif;
+  }
+}
+```
+
+Make sure to include your custom font using `@font-face` or a web font service like Google Fonts:
+
+```css
+/* Example: Using Google Fonts */
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
+
+@layer base {
+  :root {
+    --font-family: "Inter", system-ui, sans-serif;
+  }
+}
+```
+
+## Available Components
+
+### Sidebar
+
+A collapsible sidebar component with responsive design and keyboard shortcuts. The sidebar supports multiple variants, collapsible modes, and includes all necessary sub-components for building navigation interfaces.
+
+#### Basic Usage
+
+```tsx
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarHeader,
+  SidebarProvider,
+  SidebarInset,
+  SidebarTrigger,
+} from "@alkimi.org/ui-kit"
+
+function App() {
+  return (
+    <SidebarProvider>
+      <Sidebar collapsible="icon">
+        <SidebarHeader showTrigger>
+          <h2>My App</h2>
+        </SidebarHeader>
+        <SidebarContent>{/* Your sidebar content */}</SidebarContent>
+      </Sidebar>
+      <SidebarInset>
+        <header>
+          <SidebarTrigger />
+          <h1>Main Content Area</h1>
+        </header>
+        {/* Your main content */}
+      </SidebarInset>
+    </SidebarProvider>
+  )
+}
+```
+
+#### Components
+
+##### SidebarProvider
+
+Wraps your entire layout and provides sidebar context.
+
+**Props:**
+
+- `defaultOpen?: boolean` - Initial sidebar state (default: `true`)
+- `open?: boolean` - Controlled sidebar state
+- `onOpenChange?: (open: boolean) => void` - Callback when sidebar state changes
+
+##### Sidebar
+
+The main sidebar container.
+
+**Props:**
+
+- `side?: "left" | "right"` - Sidebar position (default: `"left"`)
+- `variant?: "sidebar" | "floating" | "inset"` - Visual style (default: `"sidebar"`)
+- `collapsible?: "offcanvas" | "icon" | "none"` - Collapse behavior (default: `"offcanvas"`)
+  - `offcanvas` - Sidebar slides completely off-screen
+  - `icon` - Sidebar collapses to icon-only mode
+  - `none` - Sidebar is always visible and non-collapsible
+
+##### SidebarHeader
+
+Header section of the sidebar.
+
+**Props:**
+
+- `showTrigger?: boolean` - Show toggle button in header (default: `false`)
+
+##### SidebarContent
+
+Scrollable content area of the sidebar.
+
+##### SidebarFooter
+
+Footer section of the sidebar.
+
+##### SidebarTrigger
+
+Button to toggle sidebar visibility. Automatically shows appropriate icons for mobile and desktop.
+
+##### SidebarInset
+
+Main content area wrapper that adapts to sidebar state.
+
+##### Navigation Components
+
+Build navigation menus using these components:
+
+```tsx
+import {
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarGroupContent,
+} from "@alkimi.org/ui-kit"
+
+;<SidebarGroup>
+  <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+  <SidebarGroupContent>
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <SidebarMenuButton tooltip="Home">
+          <Home />
+          <span>Home</span>
+        </SidebarMenuButton>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  </SidebarGroupContent>
+</SidebarGroup>
+```
+
+**Available Components:**
+
+- `SidebarGroup` - Groups related menu items
+- `SidebarGroupLabel` - Label for a group
+- `SidebarGroupContent` - Container for group items
+- `SidebarGroupAction` - Action button for a group
+- `SidebarMenu` - Menu list container
+- `SidebarMenuItem` - Individual menu item
+- `SidebarMenuButton` - Interactive menu button with tooltip support
+- `SidebarMenuAction` - Action button for menu items
+- `SidebarMenuBadge` - Badge/count indicator
+- `SidebarMenuSub` - Submenu container
+- `SidebarMenuSubItem` - Submenu item
+- `SidebarMenuSubButton` - Submenu button
+
+##### SidebarMenuButton Props
+
+- `variant?: "default" | "outline"` - Visual style
+- `size?: "default" | "sm" | "lg"` - Button size
+- `isActive?: boolean` - Highlight as active
+- `tooltip?: string | TooltipProps` - Tooltip text or props
+- `asChild?: boolean` - Render as child component (e.g., for links)
+
+##### Utility Components
+
+- `SidebarInput` - Styled input for sidebar (e.g., search)
+- `SidebarSeparator` - Visual separator
+- `SidebarRail` - Clickable rail for toggling sidebar
+- `SidebarMenuSkeleton` - Loading skeleton for menu items
+
+##### useSidebar Hook
+
+Access sidebar state and controls from any component within `SidebarProvider`:
+
+```tsx
+import { useSidebar } from "@alkimi.org/ui-kit"
+
+function MyComponent() {
+  const { state, open, toggleSidebar, isMobile } = useSidebar()
+
+  return (
+    <div>
+      Sidebar is {state} {/* "expanded" or "collapsed" */}
+    </div>
+  )
+}
+```
+
+**Returns:**
+
+- `state: "expanded" | "collapsed"` - Current sidebar state
+- `open: boolean` - Whether sidebar is open (desktop)
+- `setOpen: (open: boolean) => void` - Set sidebar state
+- `openMobile: boolean` - Whether sidebar is open (mobile)
+- `setOpenMobile: (open: boolean) => void` - Set mobile sidebar state
+- `isMobile: boolean` - Whether viewing on mobile
+- `toggleSidebar: () => void` - Toggle sidebar visibility
+
+#### Keyboard Shortcuts
+
+- `Cmd+B` (Mac) or `Ctrl+B` (Windows/Linux) - Toggle sidebar
+
+#### Responsive Behavior
+
+- **Desktop**: Sidebar is fixed and collapsible based on the `collapsible` prop
+- **Mobile**: Sidebar automatically becomes a slide-out sheet overlay
+
+## Usage
+
+You can import components in two ways:
+
+### Option 1: Import from Main Package
+
+Import all components from the main package entry point:
+
+```tsx
+import { Button, Tabs } from "@alkimi.org/ui-kit"
+
+function App() {
+  return (
+    <div>
+      <Button>Click me</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="destructive">Delete</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="link">Link</Button>
+      <Button size="sm">Small</Button>
+      <Button size="lg">Large</Button>
+    </div>
+  )
+}
+```
+
+### Option 2: Import Individual Components (Optimized Bundle Size)
+
+For better code splitting and smaller production bundles, import components individually:
+
+```tsx
+// Import only the Button component
+import { Button } from "@alkimi.org/ui-kit/button"
+
+// Import only the Tabs components
+import {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from "@alkimi.org/ui-kit/tabs"
+
+// Import utilities
+import { cn } from "@alkimi.org/ui-kit/utils"
+```
+
+**Note**: Both import methods require installing the full `@alkimi.org/ui-kit` package. The individual imports help optimize your production bundle size (only used components are included), but don't reduce installation size.
+
+## License
+
+MIT