@agenticindiedev/ui 0.2.4 → 0.3.1

package/README.md

@@ -8,6 +8,77 @@ A modern React component library built with TypeScript, Tailwind CSS v4, Radix U
 
 ```bash
 bun add @agenticindiedev/ui
+# or
+npm install @agenticindiedev/ui
+# or
+yarn add @agenticindiedev/ui
+```
+
+## Quick Start
+
+Get started in 3 simple steps:
+
+### 1. Add Tailwind Preset
+
+Add the preset to your `tailwind.config.ts`:
+
+```ts
+import type { Config } from 'tailwindcss';
+
+export default {
+  presets: [require('@agenticindiedev/ui/tailwind.preset')],
+  // Your other Tailwind config...
+} satisfies Config;
+```
+
+### 2. Import Theme CSS
+
+Choose a theme and import it (this replaces the need for `styles.css`):
+
+```tsx
+// Light theme (off-white) - includes Tailwind and theme variables
+import '@agenticindiedev/ui/themes/light.scss';
+
+// OR Dark theme (gray) - includes Tailwind and theme variables
+import '@agenticindiedev/ui/themes/dark.scss';
+
+// Note: Import only ONE theme file, not both styles.css and a theme file
+```
+
+### 3. Use Components
+
+```tsx
+import { Button, Card, CardHeader, CardContent } from '@agenticindiedev/ui';
+
+function App() {
+  return (
+    <Card>
+      <CardHeader>Welcome</CardHeader>
+      <CardContent>
+        <Button variant="primary">Click me</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+That's it! Your components are ready to use and look great out of the box.
+
+### Theme Switching
+
+You can switch themes programmatically:
+
+```tsx
+import { setTheme, getTheme, initTheme } from '@agenticindiedev/ui';
+
+// Initialize theme on app load
+initTheme();
+
+// Switch themes
+setTheme('dark'); // or 'light'
+
+// Get current theme
+const currentTheme = getTheme();
 ```
 
 ## Setup
@@ -70,30 +141,205 @@ function App() {
 
 ## Customization
 
-All components accept a `className` prop that merges seamlessly with existing styles, allowing you to customize components easily:
+The library provides multiple ways to customize components to match your design system. All components accept a `className` prop that merges seamlessly with existing styles.
+
+### Method 1: CSS Variables (Global Theming)
+
+The easiest way to customize colors globally is by overriding CSS variables. This affects all components using those color tokens.
+
+**Example: Customize Button Primary Color**
+
+```css
+/* In your global CSS file (e.g., globals.css, app.css) */
+:root {
+  /* Change primary color to green */
+  --primary: 142 76% 36%;
+  --primary-foreground: 0 0% 100%;
+
+  /* Or use any color you want */
+  --primary: 262 83% 58%; /* Purple */
+  --primary: 0 72% 51%; /* Red */
+  --primary: 217 91% 60%; /* Blue */
+}
+```
+
+All buttons with `variant="primary"` will now use your custom color:
+
+```tsx
+<Button variant="primary">My Custom Green Button</Button>
+```
+
+**Available CSS Variables:**
+
+```css
+:root {
+  /* Background & Text */
+  --background: 0 0% 100%;
+  --foreground: 222.2 47.4% 11.2%;
+
+  /* Primary Colors */
+  --primary: 199.1 89.1% 48.2%;
+  --primary-foreground: 210 40% 98%;
+
+  /* Secondary Colors */
+  --secondary: 210 40% 96.1%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+
+  /* Accent Colors */
+  --accent: 210 40% 96.1%;
+  --accent-foreground: 222.2 47.4% 11.2%;
+
+  /* Destructive (Error) Colors */
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 210 40% 98%;
+
+  /* Muted Colors */
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+
+  /* Borders & Inputs */
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 199.1 89.1% 48.2%;
+
+  /* Card Colors */
+  --card: 0 0% 100%;
+  --card-foreground: 222.2 47.4% 11.2%;
+
+  /* Popover Colors */
+  --popover: 0 0% 100%;
+  --popover-foreground: 222.2 47.4% 11.2%;
+
+  /* Border Radius */
+  --radius: 0.5rem;
+}
+```
+
+### Method 2: Component-Specific Customization (className)
+
+For one-off customizations, use the `className` prop to override styles:
 
 ```tsx
 <Button
   variant="primary"
-  className="bg-gradient-to-r from-purple-500 to-pink-500 shadow-lg hover:scale-105"
+  className="bg-purple-500 hover:bg-purple-600 text-white"
 >
-  Custom Styled Button
+  Custom Purple Button
+</Button>
+
+<Button
+  variant="outline"
+  className="border-2 border-pink-500 text-pink-600 hover:bg-pink-50"
+>
+  Custom Pink Outline Button
 </Button>
 ```
 
-### Theming
+### Method 3: Create Custom Theme File
 
-The package uses CSS variables for theming. You can customize colors by overriding CSS variables:
+For a complete custom theme, create your own CSS file:
 
 ```css
+/* my-custom-theme.css */
+@import 'tailwindcss';
+
 :root {
-  --primary: 199.1 89.1% 48.2%;
-  --primary-foreground: 210 40% 98%;
+  --primary: 142 76% 36%; /* Your brand green */
+  --primary-foreground: 0 0% 100%;
+  --secondary: 210 20% 96%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+  /* ... define all your colors */
+  --radius: 0.75rem; /* Custom border radius */
+}
+
+@keyframes accordion-down {
+  from {
+    height: 0;
+  }
+  to {
+    height: var(--radix-accordion-content-height);
+  }
+}
+
+@keyframes accordion-up {
+  from {
+    height: var(--radix-accordion-content-height);
+  }
+  to {
+    height: 0;
+  }
+}
+```
+
+Then import it instead of the default theme:
+
+```tsx
+import './my-custom-theme.css';
+```
+
+### Method 4: Tailwind Config Override
+
+You can also extend colors in your `tailwind.config.ts`:
+
+```ts
+import type { Config } from 'tailwindcss';
+
+export default {
+  presets: [require('@agenticindiedev/ui/tailwind.preset')],
+  theme: {
+    extend: {
+      colors: {
+        // Override or extend colors
+        primary: {
+          DEFAULT: '#10b981', // Your custom green
+          foreground: '#ffffff',
+        },
+      },
+    },
+  },
+} satisfies Config;
+```
+
+### Dark Mode Customization
+
+Dark mode is supported via the `dark` class on your HTML element. Customize dark mode colors:
+
+```css
+.dark {
+  --primary: 142 76% 50%; /* Lighter green for dark mode */
+  --background: 222.2 47.4% 11.2%;
+  --foreground: 210 40% 98%;
   /* ... */
 }
 ```
 
-Dark mode is supported via the `dark` class on your HTML element.
+### Examples: Button Color Customization
+
+**Change all primary buttons to green:**
+
+```css
+:root {
+  --primary: 142 76% 36%;
+  --primary-foreground: 0 0% 100%;
+}
+```
+
+**Change a single button:**
+
+```tsx
+<Button className="bg-green-500 hover:bg-green-600">Green Button</Button>
+```
+
+**Create a custom variant:**
+
+```tsx
+<Button
+  variant="outline"
+  className="border-green-500 text-green-600 hover:bg-green-50"
+>
+  Green Outline
+</Button>
+```
 
 ## Components
 
@@ -259,24 +505,6 @@ src/
 └── index.ts              # Public exports
 ```
 
-## Migration from DaisyUI
-
-If you were using DaisyUI, note that this package has migrated to shadcn/ui patterns with Radix UI primitives. The API remains similar, but components now use Radix UI for better accessibility and TypeScript support.
-
-### Breaking Changes
-
-- DaisyUI classes are no longer available
-- Components now use CSS variables for theming instead of DaisyUI themes
-- Some component APIs have been updated to match shadcn/ui patterns
-
-### Benefits
-
-- ✅ Better accessibility (Radix UI primitives)
-- ✅ Full TypeScript support
-- ✅ More customization options
-- ✅ Better performance
-- ✅ Active maintenance and updates
-
 ## Storybook
 
 This project uses [Storybook](https://storybook.js.org/) for component development and documentation. All components have corresponding `.stories.tsx` files that demonstrate their usage, variants, and interactive examples.