AZ UI Library

A modern React component library built with Radix UI and Tailwind CSS, designed for building beautiful and accessible user interfaces.

Features

• 🎨 Built with Radix UI - Unstyled, accessible components as foundation
• 🎯 Tailwind CSS - Utility-first CSS framework for rapid styling
• 📚 Storybook - Interactive component documentation and testing
• 🔧 TypeScript - Full type safety and excellent developer experience
• ⚡ Vite - Fast build tool and development server
• 🧪 Vitest - Fast unit testing with browser support
• 📦 Tree-shakable - Import only what you need

Installation

npm install az-ui-lib
# or
yarn add az-ui-lib
# or
pnpm add az-ui-lib

Peer Dependencies

Make sure you have React 19+ installed:

npm install react react-dom

Usage

Basic Setup

First, import the CSS in your main application file:

// In your main App.tsx or index.tsx
import 'az-ui-lib/styles.css';

Using Components

import {
  Button,
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from 'az-ui-lib';

function App() {
  return (
    <Card className="w-[350px]">
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
        <CardDescription>
          This is a card component from AZ UI Library
        </CardDescription>
      </CardHeader>
      <CardContent>
        <p>Card content goes here</p>
      </CardContent>
      <CardFooter>
        <Button variant="outline">Cancel</Button>
        <Button>Confirm</Button>
      </CardFooter>
    </Card>
  );
}

Using Providers

Import providers from the dedicated /providers entry point:

import { ThemeProvider, useTheme } from 'az-ui-lib/providers';
import { Button } from 'az-ui-lib';

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <Button
      variant="outline"
      onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}
    >
      Toggle theme (current: {theme})
    </Button>
  );
}

function App() {
  return (
    <ThemeProvider defaultTheme="light" storageKey="my-app-theme">
      <div className="min-h-screen bg-background text-foreground">
        <ThemeToggle />
        {/* Your other components */}
      </div>
    </ThemeProvider>
  );
}

With Tailwind CSS (Recommended)

If you're using Tailwind CSS in your project, you can leverage the full design system:

import { Button } from 'az-ui-lib';

function MyComponent() {
  return (
    <div className="p-4 bg-background">
      <Button className="mb-4" variant="default" size="lg">
        Large Button
      </Button>
      <Button variant="outline" size="sm">
        Small Outline Button
      </Button>
    </div>
  );
}

Available Components

Components

• Button - Customizable button component with multiple variants (default, secondary, outline, destructive, ghost, link)
• Card - Flexible card container with Header, Content, Footer, Title, and Description sub-components

Providers

• ThemeProvider - Manages light/dark/system theme switching with localStorage persistence
  • useTheme() hook for accessing and updating the current theme
  • Automatic system theme detection
  • Customizable storage key and CSS attribute

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd az-ui-lib

# Install dependencies
npm install

# Start development server
npm run dev

# Start Storybook
npm run storybook

Scripts

• npm run dev - Start Vite development server
• npm run build - Build the application
• npm run build:lib - Build the library for production
• npm run storybook - Start Storybook development server
• npm run build-storybook - Build Storybook for production
• npm run test - Run tests
• npm run lint - Run ESLint

Building Components

This library follows a structured approach to component development:

1. Base on Radix UI - Use Radix UI primitives for accessibility
2. Style with Tailwind - Use utility classes and component variants
3. Export properly - Add exports to src/index.ts
4. Document with Storybook - Create stories for each component
5. Test thoroughly - Write tests for component behavior

Example Component Structure

import * as React from 'react';
import { Slot } from '@radix-ui/react-slot';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '~/lib/utils';

const componentVariants = cva(
  // base styles
  'base classes',
  {
    variants: {
      variant: {
        default: 'default styles',
        // other variants
      },
    },
    defaultVariants: {
      variant: 'default',
    },
  }
);

export interface ComponentProps
  extends
    React.HTMLAttributes<HTMLElement>,
    VariantProps<typeof componentVariants> {
  asChild?: boolean;
}

const Component = React.forwardRef<HTMLElement, ComponentProps>(
  ({ className, variant, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : 'div';
    return (
      <Comp
        className={cn(componentVariants({ variant, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Component.displayName = 'Component';

export { Component, componentVariants };

Publishing to NPM

This library is configured for easy publishing to NPM. Before publishing:

Prerequisites

1. Create an NPM account: Sign up at npmjs.com
2. Login to NPM: Run npm login in your terminal
3. Update package details: Edit package.json to update:
   • name - Choose a unique package name
   • author - Add your name and email
   • repository - Add your GitHub repository URL
   • homepage - Add your project homepage

Publishing Steps

1. Build the library:

   npm run build:lib

2. Test the package locally (optional):

   npm pack
   # This creates a .tgz file you can test with npm install ./package-name.tgz

3. Publish to NPM:

   # For patch version (0.1.0 → 0.1.1)
   npm run release
   
   # For minor version (0.1.0 → 0.2.0)
   npm run release:minor
   
   # For major version (0.1.0 → 1.0.0)
   npm run release:major
   
   # Or manually
   npm run build:lib
   npm version patch  # or minor/major
   npm publish

Package Contents

The published package includes:

• ✅ Compiled JavaScript (ES modules and CommonJS)
• ✅ TypeScript declarations (.d.ts files)
• ✅ README.md and LICENSE
• ❌ Source code (excluded for smaller package size)
• ❌ Development files (tests, stories, configs)

Usage After Publishing

Once published, users can install your library:

npm install your-package-name

And use it in their projects:

import { Button, Card } from 'your-package-name';

// Note: Users need to import Tailwind CSS separately
// or set up their own styling system

License

MIT © [Your Name] ], languageOptions: { parserOptions: { project: ['./tsconfig.node.json', './tsconfig.app.json'], tsconfigRootDir: import.meta.dirname, }, // other options... }, }, ])

You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:

```js
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])

VS Code + Tailwind IntelliSense (important)

If you use Tailwind CSS IntelliSense (v2/v4) in VS Code and you're working in a monorepo or with TypeScript path aliases, you must ensure your TypeScript config exposes the correct root directories so the extension can resolve files and the Tailwind config correctly.

Add rootDirs under compilerOptions in your tsconfig.json (or the config used by your editor) to point to your source folders. Example:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["src/*"]
    },
    "rootDirs": ["./src"]
  }
}

Why this matters

• The Tailwind IntelliSense language server resolves imports and scans your project to determine which classes are used. When the editor cannot resolve your source layout (for example, because of path aliases or non-standard folder layouts), IntelliSense can miss class names used in component helpers like cva, cn, or cx.
• Adding rootDirs helps the language server locate your files reliably so class extraction and suggestions work consistently.

After updating tsconfig.json, reload VS Code (Developer: Reload Window) and restart the Tailwind language server (Tailwind CSS: Restart Language Server) to pick up the change.

VS Code workspace settings (important)

In addition to tsconfig.json, some VS Code settings help the Tailwind CSS IntelliSense extension detect classes inside helpers like cva, cn, or cx and work correctly with TypeScript path aliases. Create or update .vscode/settings.json in your project root with these recommended keys:

{
  "tailwindCSS.includeLanguages": {
    "typescript": "html",
    "typescriptreact": "html",
  },
  "tailwindCSS.classFunctions": [
    "cva",
    "cx",
    "cn",
    "twMerge",
    "className",
    "classNames",
  ],
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(\\s*\\[([^\\]]*)\\]", "[\\\"'`]([^\\\"'`]*)[\\\"'`]"],
    ["cva\\(([^)]*)\\)", "[\\\"'`]([^\\\"'`]*)[\\\"'`]"],
    ["cx\\(([^)]*)\\)", "[\\\"'`]([^\\\"'`]*)[\\\"'`]"],
    ["cn\\(([^)]*)\\)", "[\\\"'`]([^\\\"'`]*)[\\\"'`]"],
  ],
  "tailwindCSS.suggestions": true,
  "tailwindCSS.validate": true,
}

Notes:

• includeLanguages maps TypeScript files to HTML parsing so the extension can extract classes from JSX.
• classFunctions tells the extension which helpers to inspect for classes.
• experimental.classRegex adds custom regex patterns so the extension can find class strings inside arrays and helper calls (common with cva). Adjust these patterns if you use different helper names or structures.
• After changing .vscode/settings.json, reload VS Code and run Tailwind CSS: Restart Language Server.