@alkimi.org/ui-kit 0.1.14 → 0.1.16

package/README.md

@@ -10,15 +10,28 @@ npm install @alkimi.org/ui-kit
 
 ## Setup
 
-### 1. Install Tailwind CSS v4
+You have **two setup options** depending on your needs:
 
-If you haven't already, install Tailwind CSS v4 and its dependencies in your project:
+- **Option A (Recommended)**: Import pre-compiled library styles - simpler setup, works immediately
+- **Option B (Advanced)**: Manual styling with full control - requires more configuration
+
+Choose the option that best fits your project requirements.
+
+---
+
+### Option A: Import Library Styles (Recommended)
+
+**Best for**: Most projects. Simple setup with minimal configuration.
+
+**What you get**: Pre-compiled utility classes (`rounded-lg`, `bg-primary`, etc.) + CSS variables + fonts
+
+#### 1. Install Tailwind CSS v4
 
 ```bash
 npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
 ```
 
-### 2. Configure PostCSS
+#### 2. Configure PostCSS
 
 Create or update your `postcss.config.js`:
 
@@ -31,124 +44,158 @@ module.exports = {
 }
 ```
 
-### 3. Configure Tailwind
+#### 3. Import Library Styles
 
-Create a `tailwind.config.js` to specify your content paths:
+In your root layout file (e.g., `app/layout.tsx` for Next.js App Router):
 
-```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  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}",
-  ],
-}
+```tsx
+import "@alkimi.org/ui-kit/styles.css"
+import "./globals.css" // Your custom CSS
 ```
 
-**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.).
+**Important**: Import the library styles **before** your custom CSS so you can override variables if needed.
 
-### 4. Import Tailwind in Your CSS
+#### 4. Configure Your CSS
 
-Create or update your main CSS file (e.g., `app.css` or `globals.css`):
+Create your `globals.css`:
 
 ```css
 @import "tailwindcss";
+
+/* Optional: Override library CSS variables */
+:root {
+  /* Example: Custom primary color */
+  --primary: oklch(0.992 0.019 155.826);
+  --primary-foreground: oklch(0.205 0 0);
+
+  /* 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)
+  */
+}
 ```
 
-### 5. Import Styles
+**That's it!** The library components will work immediately because:
 
-Import the library's CSS in your main application file (e.g., `App.tsx` or `index.tsx`):
+- `styles.css` contains pre-compiled utility classes
+- All CSS variables are defined
+- Fonts are included
+- **No `@source` directive needed** (utilities are already compiled into the CSS)
 
-```tsx
-import "@alkimi.org/ui-kit/styles.css"
-```
+#### When to Use Option A
 
-## Customizing Colors
+- You want the quickest setup
+- You're happy with the library's default styling approach
+- You want to customize colors via CSS variables
+- You don't need complete control over Tailwind configuration
 
-The library uses CSS variables for colors, making it easy to customize. You have two approaches:
+---
 
-### Option A: Override CSS Variables (Recommended)
+### Option B: Manual Styling (Advanced)
 
-Add custom color values to your CSS file **after** importing the library styles:
+**Best for**: Advanced users who want complete control over CSS generation and Tailwind configuration.
 
-```css
-/* In your app.css or globals.css */
-@import "tailwindcss";
-@import "@alkimi.org/ui-kit/styles.css";
+**What you do**: Define all CSS variables yourself and use `@source` to dynamically generate utility classes.
 
-/* 👇 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)
-    */
-  }
+#### 1. Install Tailwind CSS v4
+
+```bash
+npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
+```
+
+#### 2. Configure PostCSS
+
+Create or update your `postcss.config.js`:
+
+```js
+module.exports = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+    autoprefixer: {},
+  },
 }
 ```
 
-### Option B: Don't Import Library CSS (Manual Setup)
+#### 3. Do NOT Import Library Styles
+
+In your root layout file (e.g., `app/layout.tsx`):
 
-If you want complete control, skip importing the library CSS and define all variables yourself:
+```tsx
+// ❌ Do NOT import library styles in Option B
+// import "@alkimi.org/ui-kit/styles.css"
+
+import "./globals.css" // Only import your custom CSS
+```
+
+#### 4. Configure Your CSS with @source
+
+Create your `globals.css`:
 
 ```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;
-  }
+/* REQUIRED: Tell Tailwind v4 to scan library components */
+@source "../node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}";
+
+/* REQUIRED: Define ALL CSS variables the library needs */
+:root {
+  --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);
+  --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;
+  --font-family: "Helvetica Now Display", "Helvetica", sans-serif;
+}
 
-  body {
-    @apply bg-background text-foreground;
-  }
+body {
+  @apply bg-background text-foreground;
 }
 ```
 
-**Note**: When using Option B, don't import `@alkimi.org/ui-kit/styles.css` in your code.
+**Key points**:
+
+- The `@source` directive tells Tailwind v4 to scan the library's component files
+- Tailwind will dynamically generate utility classes for any classes used in those components
+- You must define all CSS variables the library expects
+- VS Code may show a warning for `@source` - you can safely ignore it (it's a valid Tailwind v4 directive)
+
+#### When to Use Option B
+
+- You want complete control over CSS generation
+- You're customizing Tailwind's configuration extensively
+- You want to manage all CSS variables manually
+- You're comfortable with more advanced Tailwind v4 configuration
+
+---
 
 ## 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)
@@ -158,18 +205,53 @@ The library uses **rem-based sizing** with a base font size of **1rem (16px)**.
 ### 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 (
@@ -187,6 +269,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