# Plan: Crear el Design System de BL Consultores como Component Library React

## Context

BL Consultores tiene un design system completo definido en Penpot (páginas Foundations, Components, Screens) con colores, tipografía, botones, formularios, navegación, tablas, gráficos, alertas y modales. El objetivo es exportar estos diseños desde Penpot y crear una librería de componentes React reutilizable usando `create-react-component-library` (aleleba/create-react-component-library), que ya soporta Storybook, testing y publicación npm.

La librería se integrará en `blconsultores_app` como dependencia local o npm para estandarizar toda la UI del proyecto.

## Fundamentos del Design System (extraídos de Penpot)

### Paleta de Colores (12 tokens)
| Token | Hex | Grupo |
|---|---|---|
| Blanco | `#FFFFFF` | Neutro |
| Dorado Institucional | `#EABF2D` | Brand primario |
| Ámbar | `#D4880F` | Brand secundario |
| Azul Navy | `#1B2A4A` | Brand / texto oscuro |
| Negro Profundo | `#1A1A2E` | Texto principal |
| Gris Oscuro | `#2D2D3F` | Texto / bordes |
| Gris Medio | `#6B6B7B` | Texto secundario |
| Gris Claro | `#F5F5F7` | Fondos de sección |
| Encuesta - Totalmente de Acuerdo | `#2CDEA3` | Semántica encuesta |
| Encuesta - De Acuerdo | `#F5E53E` | Semántica encuesta |
| Encuesta - En Desacuerdo | `#FAC132` | Semántica encuesta |
| Encuesta - Totalmente en Desacuerdo | `#DE3626` | Semántica encuesta |

### Tipografía (11 tokens)
| Token | Font | Size | Weight | Uso |
|---|---|---|---|---|
| Heading 50 | Montserrat | 50px | Bold | Hero titles |
| Heading 25 | Montserrat | 25px | Bold | Page titles |
| Heading 18 | Montserrat | 18px | Bold | Section headers |
| Subheading 22 | Montserrat | 22px | Normal | Subheaders |
| Montserrat Heading | Montserrat | 14px | Bold | Card titles |
| Montserrat Subheading | Montserrat | 14px | Bold | Subtitles |
| Montserrat SemiBold | Montserrat | 14px | Semibold | Labels |
| Montserrat Body | Montserrat | 14px | Normal | Body text |
| Montserrat Regular | Montserrat | 14px | Normal | Body text |
| Noeteric Bold | Noeteric-Bold | 14px | Bold | Logo/branding |
| Montserrat Bold | Montserrat | 14px | Bold | Emphasis |

### Tipografías del Library
- `Montserrat` (Regular, SemiBold, Bold)
- `Noeteric-Bold`

### Componentes definidos en Penpot (22 boards)

**Buttons (8 variantes):**
- Primary (Dorado bg, Azul Navy text)
- Outline Gold (Dorado border)
- Outline Dark Default / Hover
- Outline Light BG
- Ghost Default / Hover
- Circular (icon button)
- Icon Delete (rojo)
- Icon Edit

**Forms (5):**
- Input/Text (default + focus states)
- Input/Search
- Select/Dropdown
- Toggle Track
- Button/File Upload

**Navigation (6):**
- Breadcrumb
- Tabs
- Navbar/Admin
- Navbar/Admin Mobile (collapsed + overlay)
- Navbar/Pública

**Data Display (11):**
- Table/Encuestados, Table/Climas, Table/Semáforo
- Pagination
- Card/Editor Section, Card/Servicio, Card/Login BG
- Badge/Status Check, Badge/Order Number
- Chip/Removable
- ListItem/Factor

**Feedback (4):**
- Alert (Danger, Info, Success)
- Modal/Content
- Loader

**Charts (3):**
- Bar Comparative, Bar Single, Donut

**Layout (1):**
- Footer

## Arquitectura de la Library

```
create-react-component-library/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── index.tsx          # Componente React con props tipadas
│   │   │   ├── Button.stories.tsx # Storybook stories (variantes, estados)
│   │   │   ├── Button.test.tsx    # Unit tests (Jest)
│   │   │   ├── Button.cy.tsx      # Component tests (Cypress)
│   │   │   └── style.scss         # Estilos SCSS usando tokens
│   │   ├── Input/
│   │   ├── Select/
│   │   ├── Toggle/
│   │   ├── Navbar/
│   │   ├── Breadcrumb/
│   │   ├── Tabs/
│   │   ├── Table/
│   │   ├── Card/
│   │   ├── Alert/
│   │   ├── Modal/
│   │   ├── Badge/
│   │   ├── Chip/
│   │   ├── ListItem/
│   │   ├── Pagination/
│   │   ├── Loader/
│   │   ├── Footer/
│   │   ├── Chart/
│   │   └── index.tsx              # Barrel export
│   ├── tokens/
│   │   ├── colors.ts              # Design tokens (colores)
│   │   ├── typography.ts          # Design tokens (tipografía)
│   │   └── index.ts
│   └── stories/
│       └── Introduction.mdx       # Guía de uso
├── .storybook/
│   ├── main.js
│   └── preview.js
├── package.json
├── tsconfig.json
└── README.md
```

Cada componente sigue el patrón de `create-react-component-library`:
1. `index.tsx` — Componente React con props tipadas
2. `*.stories.tsx` — Storybook stories (variantes, estados)
3. `*.test.tsx` — Tests unitarios Jest
4. `*.cy.tsx` — Tests de componentes Cypress
5. `style.scss` — Estilos SCSS que usan los tokens

## Pasos de Implementación

### Fase 1: Configurar tokens de diseño
1. `src/tokens/colors.ts` — Todas las variables de color como constantes TypeScript + CSS variables
2. `src/tokens/typography.ts` — Todas las tipografías como objetos con fontFamily, fontSize, fontWeight, lineHeight
3. `src/tokens/index.ts` — Barrel export

### Fase 2: Implementar componentes por categoría (orden de prioridad)
1. **Buttons** (8 variantes) — Base de toda la UI interactiva
2. **Forms** (5 componentes) — Inputs, selects, toggles
3. **Navigation** (6 componentes) — Breadcrumbs, tabs, navbars
4. **Data Display** (11 componentes) — Tablas, cards, badges, chips
5. **Feedback** (4 componentes) — Alerts, modals, loader
6. **Charts** (3 componentes) — Gráficas con Chart.js
7. **Layout** (1 componente) — Footer

### Fase 3: Export barrel y documentación
1. `src/components/index.ts` — Exportar todos los componentes
2. Storybook Introduction page con guía de uso y ejemplos
3. README con instrucciones de instalación y uso

### Fase 4: Testing
1. Unit tests para cada componente (Jest + Testing Library)
2. Component tests con Cypress
3. Storybook visual regression (opcional)

## Integración con blconsultores_app

### package.json de blconsultores_app:
```json
{
  "dependencies": {
    "@blconsultores/design-system": "file:../create-react-component-library"
  }
}
```

### Uso en componentes existentes:
```tsx
// Antes (Bootstrap inline)
<div className="btn btn-primary" style={{...}}>

// Después (Design System)
import { Button } from '@blconsultores/design-system'
<Button variant="primary" size="md">Click</Button>
```

## Verificación
- [ ] Storybook abre y muestra todos los componentes
- [ ] Todos los colores y tipografías coinciden con Penpot (verificar hex codes)
- [ ] Tests unitarios pasan (Jest)
- [ ] Tests de componentes pasan (Cypress)
- [ ] `npm link` funciona y los componentes se importan en blconsultores_app
- [ ] Export barrel funciona: `import { Button, Input, Table } from '@blconsultores/design-system'`