Paradox UI

A modern, DaisyUI-inspired React component library built as a Tailwind CSS plugin. Paradox UI provides semantic, high-level component class names that are abstractions of Tailwind's low-level utility classes, improving developer speed, code readability, and maintainability while retaining the full customization power of Tailwind.

✨ Features

- 🎨 DaisyUI-Inspired: Semantic component class names like btn, card
- 🧩 Compound Components: Flexible component composition patterns
- 🎯 TypeScript First: Full TypeScript support with strict typing
- 🌓 Theme System: Dynamic theming with CSS custom properties
- ♿ Accessible: Built with accessibility best practices
- 📱 Responsive: Mobile-first design approach
- 🎭 Storybook: Comprehensive component documentation
- 🧪 Tested: Full test coverage with Jest and React Testing Library
- 📦 Tree-Shakable: Optimized bundle size with selective imports
- 🔧 Developer Friendly: Excellent DX with hot reload and IntelliSense

🚀 Installation

``bash
npm install paradox-ui


or

yarn add paradox-ui

or

pnpm add paradox-ui
`

$3

Paradox UI requires the following peer dependencies:

`bash
npm install react react-dom tailwindcss


or

yarn add react react-dom tailwindcss

or

pnpm add react react-dom tailwindcss
`

⚙️ Setup

$3

Make sure you have Tailwind CSS configured in your project. If you don't, create a tailwind.config.js:

`javascript
module.exports = {
content: [
'./src/*/.{js,ts,jsx,tsx}',
'./node_modules/paradox-ui/dist/*/.{js,ts,jsx,tsx}',
],
theme: {
extend: {},
},
plugins: [],
};
`

$3

Import the Paradox UI styles in your main CSS file:

`css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
`

$3

Wrap your application with the ThemeProvider:

`tsx
import React from 'react';
import { ThemeProvider } from 'paradox-ui';

function App() {
return (

{/ Your app content /}

);
}
`

📚 Usage

$3

`tsx
import { Button } from 'paradox-ui';

function Example() {
return (



);
}
`

$3

`tsx
import { Card, CardTitle, CardBody, CardActions, CardMedia } from 'paradox-ui';

function Example() {
return (

Card Title

This is the card body content. You can put any content here.


Action 1
Action 2


);
}

// Card with image
function CardWithImage() {
return (

Beautiful Image

Cards can have images at the top, bottom, left, or right.


View Details


);
}
`

$3

Paradox UI works great with icon libraries like Heroicons, Lucide React, or custom SVG icons:

`tsx
import { Button } from 'paradox-ui';
import { PlusIcon, TrashIcon } from '@heroicons/react/24/outline';

function IconExample() {
return (



);
}
`

🎨 Theming

$3

Paradox UI comes with built-in light and dark themes:

`tsx
import { ThemeProvider, useTheme } from 'paradox-ui';

function App() {
return (
defaultTheme="light"
persistTheme={true} // Save theme preference to localStorage
>

{/ Your app content /}

);
}

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

return (



);
}
`

$3

Create your own themes by extending the base theme:

`tsx
import { ThemeProvider, createThemeVariant } from 'paradox-ui';
import { lightTheme } from 'paradox-ui/themes';

const corporateTheme = createThemeVariant(
lightTheme,
'corporate',
'Corporate',
(theme) => ({
colors: {
...theme.colors,
primary: {
...theme.colors.primary,
500: '#1e40af', // Custom primary color
},
},
})
);

function App() {
return (
defaultTheme="corporate"
themes={[lightTheme, corporateTheme]}
>
{/ Your app content /}

);
}
`

🔧 Component API Reference

$3

`tsx
interface ButtonProps extends React.ButtonHTMLAttributes {
variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'link' | 'info' | 'success' | 'warning' | 'error';
size?: 'sm' | 'md' | 'lg';
loading?: boolean;
disabledWhileLoading?: boolean;
fullWidth?: boolean;
shape?: 'default' | 'square' | 'circle';
icon?: React.ReactNode;
iconPosition?: 'left' | 'right';
loadingIndicator?: React.ReactNode;
as?: React.ElementType;
}
`

$3

`tsx
interface CardProps extends React.HTMLAttributes {
variant?: 'default' | 'bordered' | 'compact' | 'side';
shadow?: boolean;
responsive?: boolean;
backgroundColor?: 'base-100' | 'base-200' | 'neutral';
imageSrc?: string;
imageAlt?: string;
imagePosition?: 'top' | 'bottom' | 'left' | 'right';
}
`

#### Card Sub-components

- CardTitle: Card title with configurable heading level
- CardBody: Main content area
- CardActions: Action buttons area
- CardMedia: Image or custom media content
- CardFooter: Footer section

📦 Bundle Size

Paradox UI is optimized for minimal bundle impact:

- Full Library: ~45KB gzipped
- Individual Components: ~8-15KB gzipped each
- Tree-shakable: Only import what you use

$3

You can import individual components to reduce bundle size further:

`tsx
// Import all components (larger bundle)
import { Button, Card } from 'paradox-ui';

// Import individual components (smaller bundle)
import Button from 'paradox-ui/Button';
import Card from 'paradox-ui/Card';
`

🧪 Development

$3

`bash


Clone the repository

git clone https://github.com/yourusername/paradox-ui.git
cd paradox-ui

Install dependencies

npm install

Start development server

npm run dev

Start Storybook

npm run storybook

Run tests

npm test

Run tests with coverage

npm run test:coverage

Build library

npm run build
`

$3

`
paradox-ui/
├── src/
│ ├── components/ # React components
│ │ ├── Button/
│ │ └── Card/
│ ├── providers/ # React context providers
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ ├── hooks/ # Custom React hooks
│ ├── styles/ # CSS and styling
│ └── index.ts # Main entry point
├── .storybook/ # Storybook configuration
├── stories/ # Storybook stories
├── dist/ # Built library
└── package.json
`

$3

1. Create component directory in src/components/
2. Implement component with TypeScript
3. Create Storybook stories
4. Write comprehensive tests
5. Update exports in src/index.ts

Example:

`tsx
// src/components/Alert/Alert.tsx
import React from 'react';
import { cn } from '../../utils/cn';

interface AlertProps extends React.HTMLAttributes {
variant?: 'info' | 'success' | 'warning' | 'error';
children: React.ReactNode;
}

export const Alert = ({ variant = 'info', className, children, ...props }: AlertProps) => {
const variantClasses = {
info: 'alert-info',
success: 'alert-success',
warning: 'alert-warning',
error: 'alert-error',
};

return (
className={cn('alert', variantClasses[variant], className)}
role="alert"
{...props}
>
{children}