Alkimi UI Kit

A React component library built with shadcn/ui and Tailwind CSS.

Installation

npm install @alkimi.org/ui-kit

Setup

You have two setup options depending on your needs:

• 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

npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer

2. Configure PostCSS

Create or update your postcss.config.js:

module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
    autoprefixer: {},
  },
}

3. Import Library Styles

In your root layout file (e.g., app/layout.tsx for Next.js App Router):

import "@alkimi.org/ui-kit/styles.css"
import "./globals.css" // Your custom CSS

Important: Import the library styles before your custom CSS so you can override variables if needed.

4. Configure Your CSS

Create your globals.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)
  */
}

That's it! The library components will work immediately because:

• 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)

When to Use Option A

• 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

Option B: Manual Styling (Advanced)

Best for: Advanced users who want complete control over CSS generation and Tailwind configuration.

What you do: Define all CSS variables yourself and use @source to dynamically generate utility classes.

1. Install Tailwind CSS v4

npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer

2. Configure PostCSS

Create or update your postcss.config.js:

module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
    autoprefixer: {},
  },
}

3. Do NOT Import Library Styles

In your root layout file (e.g., app/layout.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:

@import "tailwindcss";

/* 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;
}

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)
• 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:

/* 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:

/* 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

You can import components in two ways:

Option 1: Import from Main Package

Import all components from the main package entry point:

import { Button, Tabs } from "@alkimi.org/ui-kit"

function App() {
  return (
    <div>
      <Button>Click me</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="destructive">Delete</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="link">Link</Button>
      <Button size="sm">Small</Button>
      <Button size="lg">Large</Button>
    </div>
  )
}

Option 2: Import Individual Components (Optimized Bundle Size)

For better code splitting and smaller production bundles, import components individually:

// 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