@alkimi.org/ui-kit 0.2.29 → 0.2.31

package/README.github.md

@@ -64,19 +64,50 @@ Create your `globals.css`:
 
 /* Optional: Override library CSS variables */
 :root {
-  /* Example: Custom primary color */
+  /* 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);
 
-  /* You can override any of these variables:
-     --secondary, --secondary-foreground
-     --background, --foreground
-     --muted, --muted-foreground
-     --accent, --accent-foreground
-     --destructive, --destructive-foreground
-     --border, --input, --ring
-     --radius (border radius)
-  */
+  --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);
 }
 ```
 
@@ -144,20 +175,20 @@ Create your `globals.css`:
 
 /* 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);
-  --card: oklch(0.992 0.019 155.826);
-  --card-foreground: oklch(0.205 0 0);
-  --popover: oklch(0.992 0.019 155.826);
-  --popover-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;
@@ -165,6 +196,34 @@ Create your `globals.css`:
   --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 {
@@ -188,6 +247,56 @@ body {
 
 ---
 
+## 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
@@ -267,9 +376,7 @@ function App() {
         <SidebarHeader showTrigger>
           <h2>My App</h2>
         </SidebarHeader>
-        <SidebarContent>
-          {/* Your sidebar content */}
-        </SidebarContent>
+        <SidebarContent>{/* Your sidebar content */}</SidebarContent>
       </Sidebar>
       <SidebarInset>
         <header>
@@ -290,6 +397,7 @@ function App() {
 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
@@ -299,6 +407,7 @@ Wraps your entire layout and provides sidebar context.
 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"`)
@@ -311,6 +420,7 @@ The main sidebar container.
 Header section of the sidebar.
 
 **Props:**
+
 - `showTrigger?: boolean` - Show toggle button in header (default: `false`)
 
 ##### SidebarContent
@@ -342,8 +452,7 @@ import {
   SidebarGroupLabel,
   SidebarGroupContent,
 } from "@alkimi.org/ui-kit"
-
-<SidebarGroup>
+;<SidebarGroup>
   <SidebarGroupLabel>Navigation</SidebarGroupLabel>
   <SidebarGroupContent>
     <SidebarMenu>
@@ -359,6 +468,7 @@ import {
 ```
 
 **Available Components:**
+
 - `SidebarGroup` - Groups related menu items
 - `SidebarGroupLabel` - Label for a group
 - `SidebarGroupContent` - Container for group items
@@ -406,6 +516,7 @@ function MyComponent() {
 ```
 
 **Returns:**
+
 - `state: "expanded" | "collapsed"` - Current sidebar state
 - `isOpen: boolean` - Whether sidebar is fully open
 - `setOpen: (open: boolean) => void` - Set desktop sidebar state
@@ -487,11 +598,7 @@ import { useScreenSize } from "@alkimi.org/ui-kit"
 function MyComponent() {
   const { isMobile, isLg } = useScreenSize()
 
-  return (
-    <div>
-      {isMobile ? <MobileView /> : <DesktopView />}
-    </div>
-  )
+  return <div>{isMobile ? <MobileView /> : <DesktopView />}</div>
 }
 ```
 
@@ -549,9 +656,7 @@ The library uses these Tailwind breakpoints:
 Use Tailwind's responsive prefixes in your components:
 
 ```tsx
-<div className="text-sm md:text-base lg:text-lg">
-  Responsive text size
-</div>
+<div className="text-sm md:text-base lg:text-lg">Responsive text size</div>
 ```
 
 ### Migrating useSidebar Hook

package/README.md

@@ -64,19 +64,50 @@ Create your `globals.css`:
 
 /* Optional: Override library CSS variables */
 :root {
-  /* Example: Custom primary color */
+  /* 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;
 
-  /* You can override any of these variables:
-     --secondary, --secondary-foreground
-     --background, --foreground
-     --muted, --muted-foreground
-     --accent, --accent-foreground
-     --destructive, --destructive-foreground
-     --border, --input, --ring
-     --radius (border radius)
-  */
+  /* 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);
 }
 ```
 
@@ -144,20 +175,20 @@ Create your `globals.css`:
 
 /* 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);
-  --card: oklch(0.992 0.019 155.826);
-  --card-foreground: oklch(0.205 0 0);
-  --popover: oklch(0.992 0.019 155.826);
-  --popover-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;
@@ -165,6 +196,34 @@ Create your `globals.css`:
   --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 {
@@ -188,6 +247,56 @@ body {
 
 ---
 
+## 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
@@ -267,9 +376,7 @@ function App() {
         <SidebarHeader showTrigger>
           <h2>My App</h2>
         </SidebarHeader>
-        <SidebarContent>
-          {/* Your sidebar content */}
-        </SidebarContent>
+        <SidebarContent>{/* Your sidebar content */}</SidebarContent>
       </Sidebar>
       <SidebarInset>
         <header>
@@ -290,6 +397,7 @@ function App() {
 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
@@ -299,6 +407,7 @@ Wraps your entire layout and provides sidebar context.
 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"`)
@@ -311,6 +420,7 @@ The main sidebar container.
 Header section of the sidebar.
 
 **Props:**
+
 - `showTrigger?: boolean` - Show toggle button in header (default: `false`)
 
 ##### SidebarContent
@@ -343,7 +453,7 @@ import {
   SidebarGroupContent,
 } from "@alkimi.org/ui-kit"
 
-<SidebarGroup>
+;<SidebarGroup>
   <SidebarGroupLabel>Navigation</SidebarGroupLabel>
   <SidebarGroupContent>
     <SidebarMenu>
@@ -359,6 +469,7 @@ import {
 ```
 
 **Available Components:**
+
 - `SidebarGroup` - Groups related menu items
 - `SidebarGroupLabel` - Label for a group
 - `SidebarGroupContent` - Container for group items
@@ -406,6 +517,7 @@ function MyComponent() {
 ```
 
 **Returns:**
+
 - `state: "expanded" | "collapsed"` - Current sidebar state
 - `open: boolean` - Whether sidebar is open (desktop)
 - `setOpen: (open: boolean) => void` - Set sidebar state