@alkimi.org/ui-kit 0.1.13 → 0.1.14

package/README.github.md

@@ -10,95 +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: {
-    fontSize: {
-      xs: ["0.75rem", "1rem"],
-      sm: ["12px", "1.25rem"],
-      base: ["14px", "1.5rem"],
-      lg: ["1.125rem", "1.75rem"],
-      xl: ["1.25rem", "1.75rem"],
-      "2xl": ["1.5rem", "2rem"],
-      "3xl": ["1.875rem", "2.25rem"],
-      "4xl": ["2.25rem", "2.5rem"],
-      "5xl": ["3rem", "1"],
-      "6xl": ["3.75rem", "1"],
-      "7xl": ["4.5rem", "1"],
-      "8xl": ["6rem", "1"],
-      "9xl": ["8rem", "1"],
-    },
-    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: {
-        DEFAULT: "var(--radius)",
-        lg: "calc(var(--radius) + 2px)",
-        md: "var(--radius)",
-        sm: "calc(var(--radius) - 2px)",
-        xl: "calc(var(--radius) + 4px)",
-        "2xl": "calc(var(--radius) + 6px)",
-        "3xl": "3.75rem",
-      },
-    },
-  },
-  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`):
 
@@ -106,40 +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 {
-    /* Dark Mode Theme (Default) */
-    --background: 240 10% 4%;
-    --foreground: 144 100% 97%;
-    --card: 0 0% 3.5%;
-    --card-foreground: 140 100% 97.1%;
-    --popover: 0 0% 3.5%;
-    --popover-foreground: 140 100% 97.1%;
-    --primary: 140 100% 97.1%;
-    --primary-foreground: 240 6% 10%;
-    --secondary: 240 4% 16%;
-    --secondary-foreground: 140 100% 97.1%;
-    --muted: 240 4% 16%;
-    --muted-foreground: 144 4.3% 54.9%;
-    --accent: 0 0% 15.3%;
-    --accent-foreground: 140 100% 97.1%;
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 140 100% 97.1%;
-    --border: 240 3.7% 27.6%;
-    --input: 240 3.7% 27.6%;
-    --ring: 140 100% 97.1%;
-    --radius: 0.625rem;
+    /* Define ALL color variables used by the library */
+    --background: 0 0% 100%;
+    --foreground: 0 0% 0%;
+    --card: 0 0% 100%;
+    --card-foreground: 0 0% 0%;
+    --popover: 0 0% 100%;
+    --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;
   }
 
   body {
-    font-size: 14px;
+    @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:

package/README.md

@@ -10,95 +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: {
-    fontSize: {
-      xs: ['0.75rem', '1rem'],
-      sm: ['12px', '1.25rem'],
-      base: ['14px', '1.5rem'],
-      lg: ['1.125rem', '1.75rem'],
-      xl: ['1.25rem', '1.75rem'],
-      '2xl': ['1.5rem', '2rem'],
-      '3xl': ['1.875rem', '2.25rem'],
-      '4xl': ['2.25rem', '2.5rem'],
-      '5xl': ['3rem', '1'],
-      '6xl': ['3.75rem', '1'],
-      '7xl': ['4.5rem', '1'],
-      '8xl': ['6rem', '1'],
-      '9xl': ['8rem', '1'],
-    },
-    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: {
-        DEFAULT: "var(--radius)",
-        lg: "calc(var(--radius) + 2px)",
-        md: "var(--radius)",
-        sm: "calc(var(--radius) - 2px)",
-        xl: "calc(var(--radius) + 4px)",
-        "2xl": "calc(var(--radius) + 6px)",
-        "3xl": "3.75rem",
-      },
-    },
-  },
-  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`):
 
@@ -106,40 +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 {
-    /* Dark Mode Theme (Default) */
-    --background: 240 10% 4%;
-    --foreground: 144 100% 97%;
-    --card: 0 0% 3.5%;
-    --card-foreground: 140 100% 97.1%;
-    --popover: 0 0% 3.5%;
-    --popover-foreground: 140 100% 97.1%;
-    --primary: 140 100% 97.1%;
-    --primary-foreground: 240 6% 10%;
-    --secondary: 240 4% 16%;
-    --secondary-foreground: 140 100% 97.1%;
-    --muted: 240 4% 16%;
-    --muted-foreground: 144 4.3% 54.9%;
-    --accent: 0 0% 15.3%;
-    --accent-foreground: 140 100% 97.1%;
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 140 100% 97.1%;
-    --border: 240 3.7% 27.6%;
-    --input: 240 3.7% 27.6%;
-    --ring: 140 100% 97.1%;
-    --radius: 0.625rem;
+    /* Define ALL color variables used by the library */
+    --background: 0 0% 100%;
+    --foreground: 0 0% 0%;
+    --card: 0 0% 100%;
+    --card-foreground: 0 0% 0%;
+    --popover: 0 0% 100%;
+    --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;
   }
 
   body {
-    font-size: 14px;
+    @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