@metadiv-studio/card

A modern, flexible card component library built with React, TypeScript, and Tailwind CSS. This package provides a comprehensive set of card components that are fully customizable, accessible, and designed for modern web applications.

🚀 Quick Start

Installation

npm i @metadiv-studio/card

Basic Usage

import Card from '@metadiv-studio/card';

function App() {
  return (
    <Card
      title="Welcome"
      description="This is a simple card component"
    />
  );
}

📦 Package Description

The @metadiv-studio/card package provides a collection of React card components that are:

• Fully TypeScript: Built with TypeScript for excellent developer experience
• Tailwind CSS Ready: Includes pre-built styles that work seamlessly with Tailwind CSS
• Customizable: Easy to customize with className props and Tailwind utilities
• Accessible: Built with accessibility best practices
• Responsive: Mobile-first design that works on all screen sizes
• Dark Mode Support: Built-in dark mode support with CSS custom properties

🎯 Components

Main Components

• Card - The main card component with flexible content structure
• CardHeader - Header section for the card
• CardTitle - Title element for the card
• CardDescription - Description text below the title
• CardContent - Main content area of the card
• CardFooter - Footer section with actions or additional info

💻 Usage Examples

1. Basic Card

import Card from '@metadiv-studio/card';

<Card
  title="Simple Card"
  description="This is a basic card with just a title and description."
/>

2. Card with Header

import Card from '@metadiv-studio/card';
import { Star } from 'lucide-react';

<Card
  header={<div className="flex items-center gap-2">
    <Star className="h-5 w-5 text-yellow-500" /> 
    Featured
  </div>}
  title="Premium Feature"
  description="This card has a custom header with an icon and badge."
/>

3. Card with Custom Content

import Card from '@metadiv-studio/card';

<Card
  title="User Profile"
  description="Detailed user information"
>
  <div className="space-y-3">
    <div className="flex items-center gap-3">
      <div className="w-12 h-12 bg-gradient-to-br from-blue-500 to-purple-600 rounded-full flex items-center justify-center text-white font-semibold">
        JD
      </div>
      <div>
        <p className="font-medium">John Doe</p>
        <p className="text-sm text-gray-500">Software Engineer</p>
      </div>
    </div>
  </div>
</Card>

4. Card with Footer Actions

import Card from '@metadiv-studio/card';
import { Button } from '@metadiv-studio/button';

<Card
  title="Action Card"
  description="This card has a footer with action buttons."
  footer={
    <div className="flex gap-2">
      <Button variant="outline" size="sm">Cancel</Button>
      <Button variant="default" size="sm">Confirm</Button>
    </div>
  }
/>

5. Interactive Card

import Card from '@metadiv-studio/card';
import { ArrowRight } from 'lucide-react';

<Card
  title="Clickable Card"
  description="This card is interactive and can be clicked."
  className="cursor-pointer hover:shadow-lg transition-shadow duration-200 border-2 hover:border-blue-300"
>
  <div className="flex items-center justify-between">
    <span className="text-sm text-gray-600">Click to view details</span>
    <ArrowRight className="h-4 w-4 text-gray-400" />
  </div>
</Card>

6. Stats Card

import Card from '@metadiv-studio/card';
import { TrendingUp } from 'lucide-react';

<Card
  header={<div className="flex items-center gap-2">
    <TrendingUp className="h-5 w-5 text-green-500" /> 
    Analytics
  </div>}
  title="Monthly Revenue"
  description="Your business performance this month"
>
  <div className="text-center py-4">
    <div className="text-3xl font-bold text-green-600">$24,500</div>
    <div className="text-sm text-green-600 flex items-center justify-center gap-1">
      <TrendingUp className="h-4 w-4" />
      +12.5% from last month
    </div>
  </div>
</Card>

7. Grid Layout

import Card from '@metadiv-studio/card';

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <Card
    title="Quick Action 1"
    description="Fast access to common tasks"
    className="hover:shadow-md transition-shadow"
  />
  <Card
    title="Quick Action 2"
    description="Another quick action item"
    className="hover:shadow-md transition-shadow"
  />
  <Card
    title="Quick Action 3"
    description="Third quick action option"
    className="hover:shadow-md transition-shadow"
  />
</div>

🎨 Customization

Props

The main Card component accepts the following props:

interface CardProps {
  className?: string;           // Custom CSS classes
  header?: React.ReactNode;     // Custom header content
  title?: React.ReactNode;      // Card title
  description?: React.ReactNode; // Card description
  footer?: React.ReactNode;     // Custom footer content
  children?: React.ReactNode;   // Main card content
}

Styling with Tailwind CSS

// Custom colors and borders
<Card className="border-blue-200 bg-blue-50 hover:bg-blue-100" />

// Custom shadows and animations
<Card className="shadow-xl hover:shadow-2xl transition-all duration-300" />

// Custom sizing
<Card className="max-w-sm min-h-[200px]" />

// Custom spacing
<Card className="p-8 m-4" />

🌙 Dark Mode Support

The card components automatically support dark mode when using Tailwind CSS dark mode classes. The components use CSS custom properties that automatically adapt to light/dark themes.

📱 Responsive Design

All card components are built with a mobile-first approach and include responsive utilities:

• Responsive padding and margins
• Flexible grid layouts
• Mobile-optimized touch targets
• Adaptive typography scales

🔧 Dependencies

This package has the following peer dependencies:

• React: ^18.0.0
• React DOM: ^18.0.0

And includes:

• Tailwind CSS: For styling and utilities
• @metadiv-studio/button: For button components in examples

🚀 Development

To run the development environment and see all examples:

npm run dev

This will start a Next.js development server where you can:

• View all card examples
• Test different props and configurations
• See dark/light mode switching
• Test responsive behavior

📦 Building

To build the package for production:

npm run build

This generates the dist/ folder with compiled JavaScript and TypeScript declarations.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This package is licensed under the UNLICENSED license.

Built with ❤️ by the Metadiv Studio team