@alkimi.org/ui-kit 0.1.15 → 0.1.17

package/README.github.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,119 +44,149 @@ 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:
-       --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
 
-If you want complete control, skip importing the library CSS and define all variables yourself:
+In your root layout file (e.g., `app/layout.tsx`):
+
+```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
 
@@ -181,7 +224,7 @@ You can override the default font family by setting the `--font-family` CSS vari
 @layer base {
   :root {
     /* Override the library's default font */
-    --font-family: 'Your Custom Font', 'Helvetica', sans-serif;
+    --font-family: "Your Custom Font", "Helvetica", sans-serif;
   }
 }
 ```
@@ -190,11 +233,11 @@ Make sure to include your custom font using `@font-face` or a web font service l
 
 ```css
 /* Example: Using Google Fonts */
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+@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;
+    --font-family: "Inter", system-ui, sans-serif;
   }
 }
 ```
@@ -203,64 +246,12 @@ Make sure to include your custom font using `@font-face` or a web font service l
 
 You can import components in two ways:
 
-### Option 1: Import from Main Package (All Components)
-
-```tsx
-import { Button, Card } from "@alkimi.org/ui-kit"
-```
-
-### Option 2: Import Individual Components (Optimized Bundle Size)
+### Option 1: Import from Main Package
 
-For better code splitting and smaller production bundles, import components individually:
+Import all components from the main package entry point:
 
 ```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.
-
-### Available Component Paths
-
-- `@alkimi.org/ui-kit/button` - Button component
-- `@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)
-- `@alkimi.org/ui-kit/utils` - Utility functions
-
-### Next.js Components
-
-Some components require Next.js to be installed:
-
-```bash
-npm install next
-```
-
-Then you can use:
-
-```tsx
-import GlitchLink from "@alkimi.org/ui-kit/glitch-link"
-import { PixelLoad } from "@alkimi.org/ui-kit/pixel-load"
-```
-
-> **Note:** If you're not using Next.js, you can still use all other components. Next.js is marked as an optional peer dependency.
-
-### Button Component
-
-```tsx
-import { Button } from "@alkimi.org/ui-kit/button"
+import { Button, Tabs } from "@alkimi.org/ui-kit"
 
 function App() {
   return (
@@ -278,153 +269,27 @@ function App() {
 }
 ```
 
-## Adding More Components
-
-To add more shadcn/ui components to this library:
-
-1. Use the shadcn CLI to add components:
-
-   ```bash
-   npx shadcn-ui@latest add [component-name]
-   ```
-
-2. Export the new component in [src/index.ts](src/index.ts):
-
-   ```tsx
-   export { ComponentName } from "./components/component-name"
-   ```
-
-3. Create a story file in the `stories/` folder:
-
-   ```tsx
-   // stories/ComponentName.stories.tsx
-   import type { Meta, StoryObj } from "@storybook/react"
-   import { ComponentName } from "../src/components/component-name"
-
-   const meta = {
-     title: "Components/ComponentName",
-     component: ComponentName,
-     parameters: {
-       layout: "centered",
-     },
-     tags: ["autodocs"],
-   } satisfies Meta<typeof ComponentName>
-
-   export default meta
-   type Story = StoryObj<typeof meta>
-
-   export const Default: Story = {
-     args: {
-       // your component props
-     },
-   }
-   ```
-
-4. Test locally with Storybook:
-
-   ```bash
-   npm run storybook
-   ```
-
-5. Commit and push to main:
-
-   ```bash
-   git add .
-   git commit -m "feat: add ComponentName"
-   git push
-   ```
-
-6. Update the Storybook deployment:
-
-   ```bash
-   git checkout storybook
-   git merge main
-   git push
-   ```
-
-   Vercel will automatically rebuild and deploy the updated Storybook.
-
-7. (Optional) Publish to npm:
-   ```bash
-   git checkout main
-   # Update version in package.json
-   npm run build
-   npm publish
-   ```
-
-## Development
-
-### Running the Demo
-
-To see the components in action, run the demo application:
-
-```bash
-cd demo
-npm install
-npm run dev
-```
-
-Then open [http://localhost:3000](http://localhost:3000) in your browser.
-
-The demo showcases all available components with interactive examples, including:
-
-- All button variants and sizes
-- Card layouts and compositions
-- Dark mode toggle
-- Interactive component states
-
-### Build
-
-Build the library for production:
-
-```bash
-npm run build
-```
-
-### Watch Mode
-
-Build the library in watch mode during development:
-
-```bash
-npm run dev
-```
-
-### Type Check
-
-Run TypeScript type checking:
-
-```bash
-npm run type-check
-```
-
-### Storybook
-
-View and develop components in isolation using Storybook:
-
-```bash
-npm run storybook
-```
+### Option 2: Import Individual Components (Optimized Bundle Size)
 
-This will start Storybook on [http://localhost:6006](http://localhost:6006).
+For better code splitting and smaller production bundles, import components individually:
 
-#### Building Storybook for Deployment
+```tsx
+// Import only the Button component
+import { Button } from "@alkimi.org/ui-kit/button"
 
-To build a static version of Storybook for deployment:
+// Import only the Tabs components
+import {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+} from "@alkimi.org/ui-kit/tabs"
 
-```bash
-npm run build-storybook
+// Import utilities
+import { cn } from "@alkimi.org/ui-kit/utils"
 ```
 
-This will generate a static site in the `storybook-static` directory that you can deploy to any static hosting service.
-
-## Publishing to npm
-
-1. Update the version number in [package.json](package.json) (e.g., from `0.1.3` to `0.1.4`)
-2. Build the library: `npm run build`
-3. Login to npm (if not already logged in): `npm login`
-4. Publish: `npm publish`
-
-**Note:** Make sure to bump the version in [package.json](package.json) before publishing any changes to avoid conflicts with existing versions on npm.
+**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