npm package: @qtalo/qt-ui-library
Description: Type-safe React component library built with React 19, TypeScript, Vite, and TailwindCSS 4. This library provides reusable UI primitives, components, patterns, and design tokens for building consistent user interfaces.
Author: QTalo
Latest version: 0.1.20

# QT UI Library

A modern, type-safe React component library built with React 19, TypeScript, Vite, and TailwindCSS 4. This library provides reusable UI primitives, components, patterns, and design tokens for building consistent user interfaces.

## Project Overview

The QT UI Library is a component library that organizes UI elements into three main categories: primitives (low-level building blocks), components (composed elements), and patterns (higher-level combinations). It uses TailwindCSS 4 for styling and Ladle for component development and documentation.

## Project Structure (High-Level)

```
src/
  primitives/    # Low-level, reusable UI building blocks
  components/    # Composed elements built from primitives
  patterns/      # Higher-level combinations for common use cases
  icons/         # SVG icon components
  tokens/        # Design tokens (colors, spacing, etc.)
  utils/         # Shared utility functions
  types/         # Shared TypeScript types and interfaces used across the UI library
```

- **Primitives**: Basic building blocks with minimal dependencies (e.g., Button, Input, Checkbox)
- **Components**: Composed elements that combine primitives (e.g., Card, Accordion, Badge)
- **Patterns**: Higher-level UI patterns that solve specific use cases (e.g., FilterBar, ActionMenu, StatusBadge)
- **Icons**: Reusable SVG icon components organized by category
- **Tokens**: Design system values that serve as the single source of truth
- **Utils**: Shared utilities like classname merging and helper functions
- **Types**: Shared TypeScript types and interfaces that define global UI contracts such as density, size scales, orientation, theming, and reusable behavioral patterns. This folder contains system-level types, not component-specific props.


## Creating UI Elements

### Primitives

Primitives are low-level, headless UI building blocks with minimal styling and dependencies. They provide core functionality and accessibility features.

**When to create a primitive:**

- You need a basic, reusable UI element (button, input, checkbox)
- The element should be highly flexible and composable
- It serves as a foundation for other components

**Where they live:** `src/primitives/`

### Components

Components are composed elements built from primitives. They provide more structure and styling out of the box.

**When to create a component:**

- You need a composed UI element that combines multiple primitives
- The element has a specific structure and visual design
- It's a common UI pattern that benefits from a consistent API

**Where they live:** `src/components/`

### Patterns

Patterns are higher-level combinations of components and primitives that solve specific use cases or workflows.

**When to create a pattern:**

- You need a complete UI solution for a specific use case
- The pattern combines multiple components in a meaningful way
- It represents a reusable workflow or interaction pattern

**Where they live:** `src/patterns/`

## Stories

This library uses [Ladle](https://ladle.dev) for component development and documentation. Stories allow you to develop and test components in isolation.

**Naming convention:** Story files use the `.story.tsx` extension and live alongside their component files.

**Example story:**

```tsx
// src/primitives/button.story.tsx
import type { Story } from "@ladle/react";
import { Button } from "./button";

export default {
  title: "Primitives/Button",
};

export const Overview: Story = () => (
  <Button>Click me</Button>
);
```

Run `npm run dev` to start the Ladle development server and view all stories.

## Installation & Usage

### Installation

This package is published publicly on npmjs.org.

```bash
npm install @qtalo/qt-ui-library
```

### Peer Dependencies

This library requires the following peer dependencies:

```bash
npm install react@^19.2.3 react-dom@^19.2.3 clsx@^2.1.1 tailwind-merge@^3.4.0 tailwind-variants@^3.2.2 tailwindcss@^4.1.18
```

### Usage

Import components, primitives, patterns, icons, and tokens from the main entry point:

```tsx
import { Button, Card, StatusBadge, Logo } from "@qtalo/qt-ui-library";
```

**Styles are automatically included!** This library uses `vite-plugin-lib-inject-css` to automatically inject styles when you import components. No manual CSS import is needed.

### Tailwind CSS v4 Configuration

This library is built with **Tailwind CSS v4** and uses the modern `@theme` directive for design tokens. The styles are automatically injected into your application when you import components.

**For Next.js projects**, ensure you have Tailwind CSS v4 installed and configured:

```bash
npm install -D tailwindcss@^4.1.18 @tailwindcss/postcss@^4.1.18
```

**In your `app/globals.css`:**

**Option 1: Auto-injection (Recommended)**
Styles are automatically injected when you import components. You only need to import Tailwind CSS:

```css
@import "tailwindcss";

@theme {
  /* Your custom design tokens (optional) */
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.1 0 0);
}
```

**Option 2: Manual import**
If auto-injection doesn't work or you prefer manual control, you can import the library's CSS explicitly:

```css
@import "tailwindcss";
@import "@qtalo/qt-ui-library/styles.css";

@theme {
  /* Your custom design tokens (optional) */
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.1 0 0);
}
```

**Note:** The library exports `./styles.css` which points to the **source CSS file** (not compiled). This allows your Tailwind to process it and generate utilities for ALL colors. Always import `tailwindcss` first, as it's required for Tailwind CSS v4 to work properly.

### Using All Color Utilities

**✨ Automatic - No Manual Work Required!**

In Tailwind CSS 4, **all colors defined in `@theme` automatically generate utilities** for all utility types. You don't need to maintain any safelist or manually add colors - just add them to `@theme` and they're immediately available!

**How it works:**

1. **Import the library CSS** in your main CSS file (this imports the SOURCE CSS, not compiled):

```css
@import "tailwindcss";
@import "@qtalo/qt-ui-library/styles.css";
```

2. **Tailwind will process the library's `@theme`** and automatically generate utilities for ALL colors.

3. **That's it!** All colors from `@theme` are now available as utilities in your app.

**Every color works with ALL Tailwind utility types automatically:**

- `bg-{color}` - Background colors
- `text-{color}` - Text colors  
- `border-{color}` - Border colors
- `ring-{color}` - Ring colors
- `outline-{color}` - Outline colors
- `divide-{color}` - Divide colors
- `accent-{color}` - Accent colors
- `caret-{color}` - Caret colors
- `fill-{color}` - Fill colors
- `stroke-{color}` - Stroke colors

**Example usage:**

```tsx
// All these work automatically for ANY color in @theme
<div className="bg-surface-dark text-white border-primary-deep ring-primary-500">
  All utility types work with all colors
</div>

<input className="accent-primary-500 caret-primary-500" />
<svg className="fill-success-base stroke-error-base" />

// Add a new color to @theme? It's immediately available!
// --color-brand-new: #ff0000; → bg-brand-new, text-brand-new, etc. all work!
```

**What colors are available?**

Every color defined in the library's `@theme` block is automatically available, including:
- Surface colors (`surface-dark`, `surface-darker`, etc.)
- Primary colors (all variants)
- Tertiary colors (all variants)
- Success and error colors
- All neutral colors (50-900 with all variants)
- White and black variants
- **Any new colors you add to `@theme`** - they work automatically!

**Note:** When using `vite-plugin-lib-inject-css`, styles are automatically injected. For full utility access, import the CSS explicitly as shown above. The base styles (html background, text colors) are always included automatically.

**In your `next.config.js`:**

```javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@qtalo/qt-ui-library'],
};

module.exports = nextConfig;
```

### Next.js Usage

This library is built with React Server Components in mind. All components that use React hooks or accept event handlers are marked as Client Components.

**⚠️ Important:** When using this library in a Next.js app, you **MUST** mark your component as a Client Component if you're passing event handlers (like `onClick`, `onChange`, etc.):

```tsx
"use client";  // ← REQUIRED when passing event handlers

import { Button } from "@qtalo/qt-ui-library";

export function MyComponent() {
  return (
    <Button onClick={() => console.log("clicked")}>
      Click me
    </Button>
  );
}
```

**Why?** Next.js cannot serialize functions from Server Components to Client Components. Even though library components are Client Components, the component that imports and uses them must also be a Client Component when passing event handlers.

**If you see this error:**
```
Event handlers cannot be passed to Client Component props.
```

**Solution:** Add `"use client"` at the top of the file that's using the library component with event handlers.

### Usage with Other Frameworks

**Vite + React:**

```tsx
// main.tsx or App.tsx
import { Button } from "@qtalo/qt-ui-library";

function App() {
  return <Button>Click me</Button>;
}
```

Styles are automatically included - no additional setup needed!

**Create React App:**

This library works with CRA, but requires Tailwind CSS v4 to be configured in your project.

## Design Tokens

This library uses Tailwind CSS v4's `@theme` directive for design tokens. You can access these tokens in your consuming application:

```css
@theme {
  /* Library tokens are automatically available */
  --color-brand-primary: oklch(0.5 0.2 250);
  --color-brand-secondary: oklch(0.6 0.15 180);
}
```

You can override these tokens in your own application's CSS by redefining them in your `@theme` block.

## Release & Publishing Workflow

Versioning is handled via npm's `version` command, which automatically updates `package.json`, creates a commit, and creates a git tag.

### Supported Commands

```bash
npm version patch --message "Update version to %s"
npm version minor --message "Update version to %s"
npm version major --message "Update version to %s"
```

**When to use each version type:**

- **patch**  
  Use for small changes such as bug fixes, minor UI tweaks, or internal refactors that do not affect the public API.  

  _Example:_  
  - Fix a padding issue in `Button`
  - Improve internal styles of `StatusBadge`
  - Refactor code without changing component props  
  `0.1.0 → 0.1.1`

- **minor**  
  Use when adding new components, patterns, or features in a backward-compatible way. Existing usage should continue to work without changes.  

  _Example:_  
  - Add a new `FilterBar` pattern
  - Introduce a new optional prop to an existing component
  - Add new icons or tokens  
  `0.1.1 → 0.2.0`

- **major**  
  Use when introducing breaking changes, such as API changes, removed components, or significant behavior updates that require changes in consuming applications.  

  _Example:_  
  - Rename or remove component props
  - Change component behavior in a non-compatible way
  - Remove or restructure patterns  
  `0.2.0 → 1.0.0`

The `npm version` command automatically:

- Updates the version in `package.json`
- Creates a commit with your message
- Creates a git tag matching the version

### Release Flow

1. **Commit your changes:**

   ```bash
   git add .
   git commit -m "Your changes"
   ```

2. **Bump the version:**

   ```bash
   npm version patch --message "Update version to %s"
   # or minor/major as needed
   ```

3. **Push commits and tags:**

   ```bash
   git push --follow-tags
   ```

4. **Create a GitHub Release:**
   - Go to GitHub → Releases
   - Click "Create a new release"
   - Select the tag that was just created
   - Add release notes
   - Click "Publish release"

5. **Publishing happens automatically:**
   - When you publish the GitHub Release, the GitHub Actions workflow triggers
   - The workflow builds the package and publishes it to **npmjs.org**
   - Publishing only occurs when a GitHub Release is published

**Note:** The GitHub Actions workflow verifies that the tag version matches the `package.json` version before publishing.

## Troubleshooting

### Styles not appearing

1. Ensure `transpilePackages: ['@qtalo/qt-ui-library']` is in your `next.config.js`
2. Verify Tailwind CSS v4 is installed: `npm list tailwindcss`
3. Clear cache: `rm -rf .next node_modules/.cache`
4. Rebuild: `npm run dev`

### Type errors

Ensure you have the correct peer dependencies installed with compatible versions.

### Components not rendering

Check that you're using React 19+. This library requires React 19.2.3 or higher.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on contributing to this library.

## License

MIT