dgz-ui

UI Components Library

A modern, accessible, and customizable React component library built with TypeScript, Tailwind CSS, and Shadcn/ui components.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Components
  • Button
  • Badge
  • Avatar
• Development
• License

⚡ Quick Start

import { Button, Badge, Avatar, AvatarImage, AvatarFallback } from "dgz-ui";

function App() {
  return (
    <div className="p-8 space-y-4">
      <Button>Hello World</Button>
      <Badge variant="secondary">New Feature</Badge>
      <Avatar>
        <AvatarImage src="/avatar.jpg" alt="User" />
        <AvatarFallback>UN</AvatarFallback>
      </Avatar>
    </div>
  );
}

🚀 Features

• TypeScript Support - Full type safety with comprehensive TypeScript definitions
• Accessibility First - WCAG compliant components with proper ARIA attributes
• Shadcn/ui Based - Built on proven Shadcn/ui patterns and Radix UI primitives
• Customizable - Easy theming with Tailwind CSS and CSS variables
• Copy & Paste Friendly - Components designed for easy customization and modification

📦 Installation

npm install dgz-ui
# or
yarn add dgz-ui
# or
pnpm add dgz-ui

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

Shadcn/ui Setup

This library is built on top of Shadcn/ui. If you're starting fresh, initialize Shadcn/ui in your project:

npx shadcn-ui@latest init

📚 Components

Button

A versatile button component with multiple variants, sizes, and states.

import { Button } from 'dgz-ui';

// Basic usage
<Button>Click me</Button>

// With variants
<Button variant="secondary">Secondary Button</Button>
<Button variant="tertiary">Tertiary Button</Button>
<Button variant="ghost">Ghost Button</Button>
<Button variant="destructive">Destructive Button</Button>

// With sizes
<Button size="xs">Extra Small</Button>
<Button size="sm">Small Button</Button>
<Button size="lg">Large Button</Button>
<Button size="icon">🎯</Button>

// With states
<Button disabled>Disabled Button</Button>
<Button loading>Loading Button</Button>

Available Props:

• variant: 'default' | 'destructive' | 'secondary' | 'tertiary' | 'ghost'
• size: 'lg' | 'default' | 'sm' | 'xs' | 'icon'
• disabled: boolean
• asChild: boolean - Render as child component
• All standard HTML button attributes

---

Badge

A flexible badge component with multiple types, color variants, sizes, and styling options.

import { Badge } from 'dgz-ui';

// Basic usage
<Badge>New</Badge>

// Different types
<Badge type="status">Online</Badge>
<Badge type="indicator">5</Badge>
<Badge type="icon">⭐</Badge>

// Color variants (filled)
<Badge variant="blue">Info</Badge>
<Badge variant="green">Success</Badge>
<Badge variant="red">Error</Badge>
<Badge variant="orange">Warning</Badge>
<Badge variant="purple">Premium</Badge>

// Outlined variants
<Badge variant="blue-outlined">Info Outlined</Badge>
<Badge variant="green-outlined">Success Outlined</Badge>
<Badge variant="red-outlined">Error Outlined</Badge>

// Different sizes
<Badge size="sm">Small</Badge>
<Badge size="lg">Large</Badge>

// Different border radius
<Badge rounded="default">Default Rounded</Badge>
<Badge rounded="full">Fully Rounded</Badge>

// Combinations
<Badge
  type="status"
  variant="green"
  size="sm"
  rounded="full"
>
  Active
</Badge>

Available Props:

• type: 'default' | 'status' | 'indicator' | 'icon'
• variant: 'default' | 'gray' | 'blue' | 'cyan' | 'green' | 'lime' | 'orange' | 'red' | 'purple' | 'indigo' | 'default-outlined' | 'gray-outlined' | 'blue-outlined' | 'cyan-outlined' | 'green-outlined' | 'lime-outlined' | 'orange-outlined' | 'red-outlined' | 'purple-outlined' | 'indigo-outlined'
• size: 'sm' | 'lg'
• rounded: 'default' | 'full'
• className: string - Additional CSS classes
• All standard HTML span attributes

---

Avatar

A circular avatar component for displaying user profile images with automatic fallback.

import { Avatar, AvatarImage, AvatarFallback } from 'dgz-ui';

// Basic usage
<Avatar>
  <AvatarImage src="/path/to/image.jpg" alt="User name" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

// With sizes
<Avatar size="sm">
  <AvatarImage src="/avatar.jpg" alt="Small avatar" />
  <AvatarFallback>S</AvatarFallback>
</Avatar>

<Avatar size="lg">
  <AvatarImage src="/avatar.jpg" alt="Large avatar" />
  <AvatarFallback>L</AvatarFallback>
</Avatar>

// Custom styling
<Avatar className="border-2 border-blue-500">
  <AvatarImage src="/avatar.jpg" alt="Styled avatar" />
  <AvatarFallback className="bg-blue-100">ST</AvatarFallback>
</Avatar>

Available Props:

Avatar:

• size: 'sm' | 'default' | 'md' | 'lg' | 'xl'
• className: string - Additional CSS classes

AvatarImage:

• src: string - Image source URL
• alt: string - Alternative text for accessibility
• className: string - Additional CSS classes

AvatarFallback:

• className: string - Additional CSS classes
• children: ReactNode - Fallback content (usually initials)

---

🏗️ Development

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Testing

npm run test
# or
yarn test

Building

npm run build
# or
yarn build

🤝 Acknowledgments

• Shadcn/ui - For the excellent component patterns and design system
• Radix UI - For the accessible primitives
• Tailwind CSS - For the utility-first CSS framework

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Issues

If you encounter any issues or have feature requests, please create an issue on GitHub.