npm package: @homlista-devs/ui
Description: <div align="center">
Latest version: 2.0.2

<div align="center">

# 🏡 HomLista Design System

**A world-class, production-ready design system for modern React applications**

[![npm version](https://img.shields.io/npm/v/@homlista-devs/ui.svg)](https://www.npmjs.com/package/@homlista-devs/ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
[![Tests](https://img.shields.io/badge/tests-43%20passing-success)](https://github.com/team-homlista/ui)
[![Coverage](https://img.shields.io/badge/coverage-80%25+-success)](https://github.com/team-homlista/ui)
[![Bundle Size](https://img.shields.io/badge/gzip-25.5kB-success)](https://github.com/team-homlista/ui)

[Documentation](https://team-homlista.github.io/ui) • [Storybook](https://team-homlista.github.io/ui/storybook) • [NPM](https://www.npmjs.com/package/@homlista-devs/ui) • [GitHub](https://github.com/team-homlista/ui)

</div>

---

## ✨ Features

<table>
<tr>
<td width="50%">

### 🎨 **Theming**
- 4 built-in themes (light, dark, corporate, minimal)
- CSS custom properties for easy customization
- Dynamic theme switching
- Full Tailwind CSS v4 integration

### 🧩 **Architecture**
- Feature-Sliced Design principles
- Clean, maintainable codebase
- Effector for state management
- Tree-shakeable exports

</td>
<td width="50%">

### ♿ **Accessibility**
- WCAG 2.1 AA compliant
- Keyboard navigation support
- Screen reader compatible
- Focus management

### 🚀 **Developer Experience**
- Full TypeScript support
- Comprehensive Storybook docs
- 43 automated tests
- ESM + CJS support

</td>
</tr>
</table>

## Installation

```bash
npm install @homlista-devs/ui
# or
yarn add @homlista-devs/ui
# or
pnpm add @homlista-devs/ui
```

## Quick Start

### 1. Import the CSS

First, import the design system styles in your application entry point:

```tsx
// In your main.tsx or App.tsx
import '@homlista-devs/ui/styles.css';
```

For Tailwind v4 consumers, also add a source path so app-side Tailwind generates utilities used by DS components:

```css
@import "@homlista-devs/ui/styles.css";
@import "tailwindcss";
@source "../../node_modules/@homlista-devs/ui/dist";
```

### 2. Use Components

```tsx
import { Button, ThemeProvider } from '@homlista-devs/ui';

function App() {
  return (
    <ThemeProvider>
      <Button variant="default">Hello World</Button>
    </ThemeProvider>
  );
}
```

### CSS Entrypoints

- `@homlista-devs/ui/styles.css`: Minimal default bundle (tokens + base + DS component classes)
- `@homlista-devs/ui/base.css`: Alias of minimal bundle
- `@homlista-devs/ui/tokens.css`: Tokens and theme variables only
- `@homlista-devs/ui/precompiled.css`: Legacy full precompiled Tailwind bundle (deprecated)

Migration guide: `docs/CSS_PACKAGING_MIGRATION.md`.

**Note**: The `ThemeProvider` is optional. If you don't need dynamic theme switching, you can use components directly.

## Theme Customization

### Using CSS Custom Properties (Recommended)

Your design system uses CSS custom properties for theming. Simply override the CSS variables in your application:

```css
/* Light theme (default) */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  /* ... other variables */
}

/* Dark theme */
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --primary: 217.2 91.2% 59.8%;
  /* ... other variables */
}
```

### Dynamic Theme Switching

```tsx
// Toggle dark mode
const toggleTheme = () => {
  document.documentElement.classList.toggle('dark');
};
```

## Components

### Button

```tsx
import { Button } from '@homlista:ui/design-system';

<Button variant="primary" size="md">
  Click me
</Button>
```

#### Button Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button |
| `children` | `ReactNode` | - | Button content |
| `disabled` | `boolean` | `false` | Whether the button is disabled |

### PropertyCard

```tsx
import { PropertyCard } from '@homlista-devs/ui';

const property = {
  id: '1',
  title: 'Casa de lujo en Cancún',
  price: { amount: 8500000, currency: 'MXN' },
  location: { city: 'Cancún', state: 'Quintana Roo' },
  coordinates: { lat: 21.1619, lng: -86.8515 },
  images: ['/path/to/image1.jpg', '/path/to/image2.jpg'],
  transactionTypes: [{ type: 'Venta', variant: 'primary' }],
  features: { bedrooms: 4, bathrooms: 3, parking: 2, area: 280 },
  amenities: ['alberca', 'jardín', 'terraza'],
  href: '/properties/1',
};

<PropertyCard
  property={property}
  onLike={(id, liked) => console.log(`Property ${id} ${liked ? 'liked' : 'unliked'}`)}
  onImageClick={(index, id) => console.log(`Image ${index} clicked for ${id}`)}
/>
```

#### PropertyCard Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `property` | `PropertyCardData` | - | Property data object |
| `className` | `string` | - | Additional CSS classes |
| `onLike` | `(propertyId: string, isLiked: boolean) => void` | - | Like button click handler |
| `onImageClick` | `(imageIndex: number, propertyId: string) => void` | - | Image click handler |
| `showLikeButton` | `boolean` | `true` | Whether to show the like button |
| `showNavigation` | `boolean` | `true` | Whether to show image navigation |
| `imageAspectRatio` | `'4/3' \| '16/9' \| '1/1'` | `'4/3'` | Aspect ratio of property images |

#### PropertyCardData Type

```typescript
interface PropertyCardData {
  id: string;
  title: string;
  price: PropertyPrice;
  location: PropertyLocation;
  coordinates: PropertyCoordinates;
  images: string[];
  transactionTypes: PropertyTransactionType[];
  features: PropertyFeatures;
  amenities: string[];
  href?: string;
}
```

## Development

### Setup

```bash
npm install
```

### Development Server

```bash
npm run dev
```

### Storybook

```bash
npm run storybook
```

### Building the Library

```bash
npm run build:lib
```

### Testing

```bash
npm test
```

## Architecture

This design system follows the **Feature-Sliced Design** architecture:

```
src/
├── features/          # Feature modules
│   ├── button/        # Button feature
│   ├── card/          # Card components
│   ├── modal/         # Modal components
│   ├── text/          # Text components
│   ├── theme/         # Theme management (optional)
│   └── property-card/ # Property-specific components
├── shared/            # Shared code
│   ├── lib/           # Shared utilities (cn, design-system.ts)
│   ├── types/         # TypeScript types
│   └── config/        # Configuration & tokens
├── entities/          # Business entities
├── widgets/           # Composite components
├── pages/             # Page components
└── lib/               # Application libraries
```

## Design Tokens

The design system uses CSS custom properties for theming. All components automatically adapt to theme changes through these variables:

```css
/* Available CSS Custom Properties */
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 221.2 83.2% 53.3%;
--secondary: 210 40% 96%;
--success: 142.1 70.6% 45.3%;
--warning: 38 92% 50.2%;
--error: 0 84.2% 60.2%;
--info: 199.2 89.1% 50.2%;
--border: 214.3 31.8% 91.4%;
--radius: 0.5rem;
/* ... and many more */
```

### Token Categories

- **Colors**: Brand, semantic, and neutral color palettes
- **Typography**: Font families, sizes, weights, and spacing
- **Spacing**: Consistent spacing scale (0.25rem increments)
- **Shadows**: Elevation system for depth
- **Border Radius**: Consistent corner rounding
- **Breakpoints**: Responsive design breakpoints

## Contributing

1. Follow the existing code style and architecture patterns
2. Add Storybook stories for new components
3. Write tests for new functionality
4. Update documentation as needed
5. Ensure TypeScript types are properly exported

## License

MIT
# Release Test