@alkimi.org/ui-kit 0.1.13 → 0.1.15

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,36 +70,131 @@ 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 {
-    /* 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;
+    /* 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: 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
+
+### 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;
   }
 }
 ```
@@ -150,25 +209,32 @@ You can import components in two ways:
 import { Button, Card } from "@alkimi.org/ui-kit"
 ```
 
-### Option 2: Import Individual Components (Tree-Shakeable)
+### Option 2: Import Individual Components (Optimized Bundle Size)
 
-For better tree-shaking and smaller bundle sizes, import components individually:
+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 Card components
-import { Card, CardHeader, CardTitle } from "@alkimi.org/ui-kit/card"
+// 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.
+
 ### Available Component Paths
 
 - `@alkimi.org/ui-kit/button` - Button component
-- `@alkimi.org/ui-kit/card` - Card components
+- `@alkimi.org/ui-kit/tabs` - Tabs components (with animated sliding indicator)
 - `@alkimi.org/ui-kit/text-decoder` - TextDecoder component
 - `@alkimi.org/ui-kit/glitch-link` - GlitchLink component (requires Next.js)
 - `@alkimi.org/ui-kit/pixel-load` - PixelLoad component (requires Next.js)

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,46 +70,145 @@ 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
+
+### 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;
   }
 }
 ```
 
 ## Usage
 
-### Button Component
+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 } from "@alkimi.org/ui-kit"
+import { Button, Tabs } from "@alkimi.org/ui-kit"
 
 function App() {
   return (
@@ -163,6 +226,28 @@ function App() {
 }
 ```
 
+### 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