@alkimi.org/ui-kit 0.1.12 → 0.1.14

package/README.github.md

@@ -10,76 +10,59 @@ npm install @alkimi.org/ui-kit
 
 ## Setup
 
-### 1. Install Tailwind CSS
+### 1. Install Tailwind CSS v4
 
-If you haven't already, install Tailwind CSS in your project:
+If you haven't already, install Tailwind CSS v4 and its dependencies in your project:
 
 ```bash
-npm install -D tailwindcss postcss autoprefixer
-npx tailwindcss init -p
+npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
 ```
 
-### 2. Configure Tailwind
+### 2. Configure PostCSS
 
-Update your `tailwind.config.js` to include the library's content:
+Create or update your `postcss.config.js`:
+
+```js
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+    autoprefixer: {},
+  },
+}
+```
+
+### 3. Configure Tailwind
+
+Create a `tailwind.config.js` to specify your content paths:
 
 ```js
 /** @type {import('tailwindcss').Config} */
 module.exports = {
-  darkMode: ["class"],
   content: [
+    // 👇 Scans YOUR project files for Tailwind classes
     "./src/**/*.{js,jsx,ts,tsx}",
+    "./app/**/*.{js,jsx,ts,tsx}", // If using Next.js App Router
+    "./pages/**/*.{js,jsx,ts,tsx}", // If using Next.js Pages Router
+    "./components/**/*.{js,jsx,ts,tsx}",
+
+    // 👇 Scans the UI Kit's components for their Tailwind classes
+    //    (Required for library components to be styled correctly)
     "./node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}",
   ],
-  theme: {
-    extend: {
-      colors: {
-        border: "hsl(var(--border))",
-        input: "hsl(var(--input))",
-        ring: "hsl(var(--ring))",
-        background: "hsl(var(--background))",
-        foreground: "hsl(var(--foreground))",
-        primary: {
-          DEFAULT: "hsl(var(--primary))",
-          foreground: "hsl(var(--primary-foreground))",
-        },
-        secondary: {
-          DEFAULT: "hsl(var(--secondary))",
-          foreground: "hsl(var(--secondary-foreground))",
-        },
-        destructive: {
-          DEFAULT: "hsl(var(--destructive))",
-          foreground: "hsl(var(--destructive-foreground))",
-        },
-        muted: {
-          DEFAULT: "hsl(var(--muted))",
-          foreground: "hsl(var(--muted-foreground))",
-        },
-        accent: {
-          DEFAULT: "hsl(var(--accent))",
-          foreground: "hsl(var(--accent-foreground))",
-        },
-        popover: {
-          DEFAULT: "hsl(var(--popover))",
-          foreground: "hsl(var(--popover-foreground))",
-        },
-        card: {
-          DEFAULT: "hsl(var(--card))",
-          foreground: "hsl(var(--card-foreground))",
-        },
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)",
-      },
-    },
-  },
-  plugins: [require("tailwindcss-animate")],
 }
 ```
 
-### 3. Import Styles
+**Important**: The second path (`node_modules/@alkimi.org/ui-kit/dist/...`) is **required** for the library components to display correctly. It tells Tailwind to scan the library's compiled files and generate CSS for the utility classes used inside the components (like `bg-primary`, `rounded-3xl`, etc.).
+
+### 4. Import Tailwind in Your CSS
+
+Create or update your main CSS file (e.g., `app.css` or `globals.css`):
+
+```css
+@import "tailwindcss";
+```
+
+### 5. Import Styles
 
 Import the library's CSS in your main application file (e.g., `App.tsx` or `index.tsx`):
 
@@ -87,57 +70,98 @@ Import the library's CSS in your main application file (e.g., `App.tsx` or `inde
 import "@alkimi.org/ui-kit/styles.css"
 ```
 
-Or if you prefer, add the CSS variables to your own CSS file:
+## Customizing Colors
+
+The library uses CSS variables for colors, making it easy to customize. You have two approaches:
+
+### Option A: Override CSS Variables (Recommended)
+
+Add custom color values to your CSS file **after** importing the library styles:
 
 ```css
+/* In your app.css or globals.css */
+@import "tailwindcss";
+@import "@alkimi.org/ui-kit/styles.css";
+
+/* 👇 Override the library's default colors */
 @layer base {
   :root {
+    /* Your custom colors (HSL format: Hue Saturation% Lightness%) */
+    --primary: 220 100% 50%; /* Custom blue primary color */
+    --primary-foreground: 0 0% 100%; /* White text on primary */
+    --secondary: 280 60% 60%; /* Custom purple secondary */
+    --background: 0 0% 100%; /* White background */
+    --foreground: 0 0% 0%; /* Black text */
+
+    /* You can override any of these variables:
+       --muted, --muted-foreground
+       --accent, --accent-foreground
+       --destructive, --destructive-foreground
+       --border, --input, --ring
+       --radius (border radius)
+    */
+  }
+}
+```
+
+### Option B: Don't Import Library CSS (Manual Setup)
+
+If you want complete control, skip importing the library CSS and define all variables yourself:
+
+```css
+/* In your app.css or globals.css */
+@import "tailwindcss";
+
+@layer base {
+  :root {
+    /* Define ALL color variables used by the library */
     --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
+    --foreground: 0 0% 0%;
     --card: 0 0% 100%;
-    --card-foreground: 222.2 84% 4.9%;
+    --card-foreground: 0 0% 0%;
     --popover: 0 0% 100%;
-    --popover-foreground: 222.2 84% 4.9%;
-    --primary: 222.2 47.4% 11.2%;
-    --primary-foreground: 210 40% 98%;
-    --secondary: 210 40% 96.1%;
-    --secondary-foreground: 222.2 47.4% 11.2%;
-    --muted: 210 40% 96.1%;
-    --muted-foreground: 215.4 16.3% 46.9%;
-    --accent: 210 40% 96.1%;
-    --accent-foreground: 222.2 47.4% 11.2%;
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 210 40% 98%;
-    --border: 214.3 31.8% 91.4%;
-    --input: 214.3 31.8% 91.4%;
-    --ring: 222.2 84% 4.9%;
+    --popover-foreground: 0 0% 0%;
+    --primary: 220 100% 50%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 280 60% 60%;
+    --secondary-foreground: 0 0% 100%;
+    --muted: 0 0% 96%;
+    --muted-foreground: 0 0% 45%;
+    --accent: 0 0% 96%;
+    --accent-foreground: 0 0% 0%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --border: 0 0% 90%;
+    --input: 0 0% 90%;
+    --ring: 220 100% 50%;
     --radius: 0.5rem;
   }
 
-  .dark {
-    --background: 222.2 84% 4.9%;
-    --foreground: 210 40% 98%;
-    --card: 222.2 84% 4.9%;
-    --card-foreground: 210 40% 98%;
-    --popover: 222.2 84% 4.9%;
-    --popover-foreground: 210 40% 98%;
-    --primary: 210 40% 98%;
-    --primary-foreground: 222.2 47.4% 11.2%;
-    --secondary: 217.2 32.6% 17.5%;
-    --secondary-foreground: 210 40% 98%;
-    --muted: 217.2 32.6% 17.5%;
-    --muted-foreground: 215 20.2% 65.1%;
-    --accent: 217.2 32.6% 17.5%;
-    --accent-foreground: 210 40% 98%;
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 210 40% 98%;
-    --border: 217.2 32.6% 17.5%;
-    --input: 217.2 32.6% 17.5%;
-    --ring: 212.7 26.8% 83.9%;
+  body {
+    @apply bg-background text-foreground;
   }
 }
 ```
 
+**Note**: When using Option B, don't import `@alkimi.org/ui-kit/styles.css` in your code.
+
+## Typography & Sizing
+
+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.
+
 ## Usage
 
 You can import components in two ways:
@@ -210,37 +234,6 @@ function App() {
 }
 ```
 
-### Card Component
-
-```tsx
-import {
-  Card,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent,
-  CardFooter,
-} from "@alkimi.org/ui-kit/card"
-import { Button } from "@alkimi.org/ui-kit/button"
-
-function App() {
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>Card Title</CardTitle>
-        <CardDescription>Card Description</CardDescription>
-      </CardHeader>
-      <CardContent>
-        <p>Card Content</p>
-      </CardContent>
-      <CardFooter>
-        <Button>Action</Button>
-      </CardFooter>
-    </Card>
-  )
-}
-```
-
 ## Adding More Components
 
 To add more shadcn/ui components to this library:

package/README.md

@@ -10,76 +10,59 @@ npm install @alkimi.org/ui-kit
 
 ## Setup
 
-### 1. Install Tailwind CSS
+### 1. Install Tailwind CSS v4
 
-If you haven't already, install Tailwind CSS in your project:
+If you haven't already, install Tailwind CSS v4 and its dependencies in your project:
 
 ```bash
-npm install -D tailwindcss postcss autoprefixer
-npx tailwindcss init -p
+npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
 ```
 
-### 2. Configure Tailwind
+### 2. Configure PostCSS
 
-Update your `tailwind.config.js` to include the library's content:
+Create or update your `postcss.config.js`:
+
+```js
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+    autoprefixer: {},
+  },
+}
+```
+
+### 3. Configure Tailwind
+
+Create a `tailwind.config.js` to specify your content paths:
 
 ```js
 /** @type {import('tailwindcss').Config} */
 module.exports = {
-  darkMode: ["class"],
   content: [
+    // Scans YOUR project files for Tailwind classes
     "./src/**/*.{js,jsx,ts,tsx}",
+    "./app/**/*.{js,jsx,ts,tsx}", // If using Next.js App Router
+    "./pages/**/*.{js,jsx,ts,tsx}", // If using Next.js Pages Router
+    "./components/**/*.{js,jsx,ts,tsx}",
+
+    // Scans the UI Kit's components for their Tailwind classes
+    //    (Required for library components to be styled correctly)
     "./node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}",
   ],
-  theme: {
-    extend: {
-      colors: {
-        border: "hsl(var(--border))",
-        input: "hsl(var(--input))",
-        ring: "hsl(var(--ring))",
-        background: "hsl(var(--background))",
-        foreground: "hsl(var(--foreground))",
-        primary: {
-          DEFAULT: "hsl(var(--primary))",
-          foreground: "hsl(var(--primary-foreground))",
-        },
-        secondary: {
-          DEFAULT: "hsl(var(--secondary))",
-          foreground: "hsl(var(--secondary-foreground))",
-        },
-        destructive: {
-          DEFAULT: "hsl(var(--destructive))",
-          foreground: "hsl(var(--destructive-foreground))",
-        },
-        muted: {
-          DEFAULT: "hsl(var(--muted))",
-          foreground: "hsl(var(--muted-foreground))",
-        },
-        accent: {
-          DEFAULT: "hsl(var(--accent))",
-          foreground: "hsl(var(--accent-foreground))",
-        },
-        popover: {
-          DEFAULT: "hsl(var(--popover))",
-          foreground: "hsl(var(--popover-foreground))",
-        },
-        card: {
-          DEFAULT: "hsl(var(--card))",
-          foreground: "hsl(var(--card-foreground))",
-        },
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)",
-      },
-    },
-  },
-  plugins: [require("tailwindcss-animate")],
 }
 ```
 
-### 3. Import Styles
+**Important**: The second path (`node_modules/@alkimi.org/ui-kit/dist/...`) is **required** for the library components to display correctly. It tells Tailwind to scan the library's compiled files and generate CSS for the utility classes used inside the components (like `bg-primary`, `rounded-3xl`, etc.).
+
+### 4. Import Tailwind in Your CSS
+
+Create or update your main CSS file (e.g., `app.css` or `globals.css`):
+
+```css
+@import "tailwindcss";
+```
+
+### 5. Import Styles
 
 Import the library's CSS in your main application file (e.g., `App.tsx` or `index.tsx`):
 
@@ -87,57 +70,100 @@ Import the library's CSS in your main application file (e.g., `App.tsx` or `inde
 import "@alkimi.org/ui-kit/styles.css"
 ```
 
-Or if you prefer, add the CSS variables to your own CSS file:
+## Customizing Colors
+
+The library uses CSS variables for colors, making it easy to customize. You have two approaches:
+
+### Option A: Override CSS Variables (Recommended)
+
+Add custom color values to your CSS file **after** importing the library styles:
 
 ```css
+/* In your app.css or globals.css */
+@import "tailwindcss";
+@import "@alkimi.org/ui-kit/styles.css";
+
+/* 👇 Override the library's default colors */
+@layer base {
+  :root {
+    /* Your custom colors (HSL format: Hue Saturation% Lightness%) */
+    --primary: 220 100% 50%;        /* Custom blue primary color */
+    --primary-foreground: 0 0% 100%; /* White text on primary */
+    --secondary: 280 60% 60%;        /* Custom purple secondary */
+    --background: 0 0% 100%;         /* White background */
+    --foreground: 0 0% 0%;           /* Black text */
+
+    /* You can override any of these variables:
+       --card, --card-foreground
+       --popover, --popover-foreground
+       --muted, --muted-foreground
+       --accent, --accent-foreground
+       --destructive, --destructive-foreground
+       --border, --input, --ring
+       --radius (border radius)
+    */
+  }
+}
+```
+
+### Option B: Don't Import Library CSS (Manual Setup)
+
+If you want complete control, skip importing the library CSS and define all variables yourself:
+
+```css
+/* In your app.css or globals.css */
+@import "tailwindcss";
+
 @layer base {
   :root {
+    /* Define ALL color variables used by the library */
     --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
+    --foreground: 0 0% 0%;
     --card: 0 0% 100%;
-    --card-foreground: 222.2 84% 4.9%;
+    --card-foreground: 0 0% 0%;
     --popover: 0 0% 100%;
-    --popover-foreground: 222.2 84% 4.9%;
-    --primary: 222.2 47.4% 11.2%;
-    --primary-foreground: 210 40% 98%;
-    --secondary: 210 40% 96.1%;
-    --secondary-foreground: 222.2 47.4% 11.2%;
-    --muted: 210 40% 96.1%;
-    --muted-foreground: 215.4 16.3% 46.9%;
-    --accent: 210 40% 96.1%;
-    --accent-foreground: 222.2 47.4% 11.2%;
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 210 40% 98%;
-    --border: 214.3 31.8% 91.4%;
-    --input: 214.3 31.8% 91.4%;
-    --ring: 222.2 84% 4.9%;
+    --popover-foreground: 0 0% 0%;
+    --primary: 220 100% 50%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 280 60% 60%;
+    --secondary-foreground: 0 0% 100%;
+    --muted: 0 0% 96%;
+    --muted-foreground: 0 0% 45%;
+    --accent: 0 0% 96%;
+    --accent-foreground: 0 0% 0%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --border: 0 0% 90%;
+    --input: 0 0% 90%;
+    --ring: 220 100% 50%;
     --radius: 0.5rem;
   }
 
-  .dark {
-    --background: 222.2 84% 4.9%;
-    --foreground: 210 40% 98%;
-    --card: 222.2 84% 4.9%;
-    --card-foreground: 210 40% 98%;
-    --popover: 222.2 84% 4.9%;
-    --popover-foreground: 210 40% 98%;
-    --primary: 210 40% 98%;
-    --primary-foreground: 222.2 47.4% 11.2%;
-    --secondary: 217.2 32.6% 17.5%;
-    --secondary-foreground: 210 40% 98%;
-    --muted: 217.2 32.6% 17.5%;
-    --muted-foreground: 215 20.2% 65.1%;
-    --accent: 217.2 32.6% 17.5%;
-    --accent-foreground: 210 40% 98%;
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 210 40% 98%;
-    --border: 217.2 32.6% 17.5%;
-    --input: 217.2 32.6% 17.5%;
-    --ring: 212.7 26.8% 83.9%;
+  body {
+    @apply bg-background text-foreground;
   }
 }
 ```
 
+**Note**: When using Option B, don't import `@alkimi.org/ui-kit/styles.css` in your code.
+
+## Typography & Sizing
+
+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.
+
 ## Usage
 
 ### Button Component