npm package: @firstplug/design-system
Description: First Plug Design System - Componentes React con Tailwind CSS y Shadcn UI
Author: First Plug
Latest version: 0.1.0

# 🎨 First Plug Design System

> Sistema de diseño unificado para los proyectos de First Plug, construido con React, TypeScript, Tailwind CSS y Shadcn UI.

[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-19-61dafb)](https://react.dev/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.4-38bdf8)](https://tailwindcss.com/)
[![Vite](https://img.shields.io/badge/Vite-7-646cff)](https://vitejs.dev/)

---

## ✨ Características

- 🎯 **TypeScript First**: Tipos completos y autocomplete
- 🎨 **Colores First Plug**: Todos los colores de marca incluidos
- 🧩 **Shadcn UI**: Componentes personalizables con `shadcn@latest add`
- ⚡ **Vite**: Build rápido y optimizado
- 📚 **Storybook**: Documentación visual interactiva
- 🌲 **Tree-shakeable**: Solo importas lo que usas
- 📦 **Múltiples formatos**: ESM, CommonJS, y Types

---

## 🚀 Inicio Rápido

### Para Desarrollo

```bash
# 1. Build el design system
cd /Users/nahuel-rodriguez/work/firstplug/firstplug-design-system
npm run build
npm link

# 2. Vincular en el proyecto Client
cd /Users/nahuel-rodriguez/work/firstplug/First-Plug-Platform-Client
npm link @firstplug/design-system
```

### Para Producción

```bash
npm install @firstplug/design-system
```

**📖 Documentación completa:** Lee [`QUICK-START.md`](./QUICK-START.md) para instrucciones detalladas.

---

## 📦 Uso Básico

### 1. Importar estilos

```typescript
// En src/app/layout.tsx
import '@firstplug/design-system/styles.css';
```

### 2. Usar componentes

```typescript
import { Button, Card, CardHeader, CardTitle, CardContent } from '@firstplug/design-system';

export default function MyPage() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Mi Componente</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="success">Guardar</Button>
      </CardContent>
    </Card>
  );
}
```

### 3. TypeScript Autocomplete ✨

```typescript
<Button 
  variant="success"  // ✅ Autocomplete funciona
  size="lg"          // ✅ Autocomplete funciona
  onClick={...}      // ✅ Tipos correctos
/>
```

---

## 🧩 Componentes Disponibles

| Componente | Descripción | Variantes |
|------------|-------------|-----------|
| **Button** | Botón interactivo | default, destructive, outline, ghost, link, success, purple |
| **Input** | Campo de entrada | - |
| **Card** | Contenedor con secciones | Header, Title, Description, Content, Footer |
| **Badge** | Etiqueta/Tag | default, secondary, destructive, outline, success, purple |
| **Label** | Etiqueta de formulario | - |

**Ver todos en Storybook:** `npm run storybook`

---

## 🎨 Colores First Plug

Todos los colores están disponibles en Tailwind:

```typescript
// Principales
className="bg-blue text-white"
className="bg-purple text-white"
className="bg-green text-white"

// Estados
className="bg-success text-white"
className="bg-error text-white"

// Neutrales
className="bg-light-grey text-dark-grey"
className="border-border"

// Teams
className="bg-team1"  // team1 a team25
```

---

## 🔧 Desarrollo

### Comandos Principales

```bash
# Desarrollo
npm run dev              # Vite dev server
npm run storybook        # Storybook en localhost:6006

# Build
npm run build            # Build completo
npm run verify           # Verificar build

# Agregar componentes de Shadcn
npx shadcn@latest add dialog
npx shadcn@latest add select
npx shadcn@latest add table
```

### Agregar un Componente

1. **Usar Shadcn CLI:**
   ```bash
   npx shadcn@latest add [component-name]
   ```

2. **Exportar en `src/components/ui/index.ts`:**
   ```typescript
   export * from "./nuevo-componente";
   ```

3. **Crear Story:**
   ```typescript
   // src/components/ui/nuevo-componente.stories.tsx
   ```

4. **Rebuild:**
   ```bash
   npm run build
   ```

**Guía completa:** [`SHADCN-SETUP.md`](./SHADCN-SETUP.md)

---

## 📚 Documentación

| Archivo | Descripción |
|---------|-------------|
| [`QUICK-START.md`](./QUICK-START.md) | **Empieza aquí** - Guía de inicio rápido |
| [`INTEGRATION-CLIENT.md`](./INTEGRATION-CLIENT.md) | Cómo integrar con First-Plug-Platform-Client |
| [`SHADCN-SETUP.md`](./SHADCN-SETUP.md) | Agregar componentes de Shadcn |
| [`TAILWIND-CONFIG.md`](./TAILWIND-CONFIG.md) | Configuración completa de Tailwind CSS y tokens de diseño |
| [`USAGE.md`](./USAGE.md) | Guía de uso detallada |
| [`RESUMEN.md`](./RESUMEN.md) | Resumen de configuración |

---

## 📁 Estructura del Proyecto

```
firstplug-design-system/
├── src/
│   ├── components/ui/        # Componentes exportables
│   ├── lib/                  # Utilidades (cn, etc)
│   ├── styles/              # Estilos globales
│   └── index.ts             # Export principal
├── dist/                    # Build output
│   ├── index.mjs           # ESM
│   ├── index.cjs           # CommonJS
│   ├── index.d.ts          # TypeScript types ⭐
│   └── styles.css          # CSS compilado
├── .storybook/             # Configuración Storybook
└── docs/                   # Documentación
```

---

## 🔗 Integración con Client

### Configurar Tailwind en el Client

```javascript
// tailwind.config.js en First-Plug-Platform-Client
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@firstplug/design-system/dist/**/*.{js,mjs}", // ⭐ Agregar esta línea
  ],
  // ... resto de config
};
```

**Guía completa:** [`INTEGRATION-CLIENT.md`](./INTEGRATION-CLIENT.md)

---

## ✅ Verificación

Después del build, verifica que todo esté correcto:

```bash
npm run verify
```

Esto confirma:
- ✅ Archivos de build existen (mjs, cjs, d.ts, css)
- ✅ Tipos TypeScript exportados correctamente
- ✅ Componentes disponibles
- ✅ Paquete listo para uso

---

## 🎯 Próximos Componentes Recomendados

```bash
# Alta prioridad
npx shadcn@latest add dialog
npx shadcn@latest add select
npx shadcn@latest add dropdown-menu
npx shadcn@latest add table
npx shadcn@latest add form
npx shadcn@latest add toast

# Media prioridad
npx shadcn@latest add tabs
npx shadcn@latest add checkbox
npx shadcn@latest add switch
npx shadcn@latest add textarea
```

---

## 📊 Build Output

Después de `npm run build`:

```
dist/
├── index.mjs          # 78.91 KB (ESM)
├── index.cjs          # 30.64 KB (CommonJS)
├── index.d.ts         # 2.60 KB (TypeScript types)
└── styles.css         # 10.62 KB (Tailwind compilado)
```

---

## 🛠️ Tech Stack

- **Framework**: React 19
- **Lenguaje**: TypeScript 5.9
- **Estilos**: Tailwind CSS 3.4
- **Componentes**: Shadcn UI
- **Build**: Vite 7
- **Tipos**: vite-plugin-dts
- **Docs**: Storybook 9
- **Testing**: Vitest

---

## 📝 Ejemplo Completo

```typescript
import { 
  Button, 
  Input, 
  Card, 
  CardHeader, 
  CardTitle, 
  CardContent,
  Badge,
  Label 
} from '@firstplug/design-system';

export default function UserForm() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <div className="flex items-center justify-between">
          <CardTitle>Nuevo Usuario</CardTitle>
          <Badge variant="success">Activo</Badge>
        </div>
      </CardHeader>
      <CardContent className="space-y-4">
        <div>
          <Label htmlFor="name">Nombre</Label>
          <Input id="name" placeholder="Nombre completo" />
        </div>
        
        <div>
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" placeholder="email@ejemplo.com" />
        </div>
        
        <div className="flex gap-2 justify-end">
          <Button variant="outline">Cancelar</Button>
          <Button variant="success">Guardar</Button>
        </div>
      </CardContent>
    </Card>
  );
}
```

---

## 🤝 Contribuir

1. Desarrolla componentes en Storybook
2. Crea tests con Vitest
3. Documenta con stories
4. Build y verifica: `npm run build && npm run verify`
5. Actualiza versión: `npm version patch|minor|major`

---

## 📄 Licencia

Privado - First Plug

---

## 🆘 Soporte

- 📖 **Documentación**: Lee los archivos `.md` en este repo
- 🎨 **Storybook**: `npm run storybook` para ver componentes
- 🐛 **Issues**: Reporta problemas en el repositorio
- 💬 **Equipo**: Consulta con el equipo de First Plug

---

**¿Listo para empezar?** 🚀

👉 Lee [`QUICK-START.md`](./QUICK-START.md)