# 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 la herramienta `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 (desde Penpot)

### Paleta de Colores
| Token | Hex | Uso |
|---|---|---|
| Blanco | `#FFFFFF` | Fondos, texto sobre oscuro |
| Azul Navy | `#1B2A4A` | Brand principal, headers, texto oscuro |
| Ámbar | `#D4880F` | Brand secundario, acentos |
| Dorado Institucional | `#EABF2D` | Brand primario, CTAs, highlights |
| Gris Oscuro | `#2D2D3F` | Texto body, bordes |
| Gris Medio | `#6B6B7B` | Texto secundario, placeholders |
| Gris Claro | `#F5F5F7` | Fondos de sección, cards |
| Negro Profundo | `#1A1A2E` | Texto principal, headers |
| 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
| 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, buttons |
| Montserrat Body | Montserrat | 14px | Normal | Body text |
| Montserrat Regular | Montserrat | 14px | Normal | Body text |
| Noeteric Bold | Noeteric-Bold | 14px | Bold | Logo, branding |

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

## Componentes a Implementar

### 1. Buttons (7 variantes)
- `Button/Primary` — Dorado bg, Azul Navy text, rounded
- `Button/Outline Gold` — Dorado border, transparent bg
- `Button/Outline Dark Default` — Gris Oscuro border
- `Button/Outline Dark Hover` — Hover state
- `Button/Outline Light BG` — Light bg variant
- `Button/Ghost Default` — Transparent, text only
- `Button/Ghost Hover` — Hover state
- `Button/Circular` — Circle shape, icon
- `Button/Icon Delete` — Red icon button
- `Button/Icon Edit` — Edit icon button

### 2. Forms
- `Input/Text` — Default state (border Gris Medio)
- `Input/Text Focus` — Focus state (border Dorado)
- `Input/Search` — Con icono de búsqueda
- `Select/Dropdown` — Custom select component
- `Toggle Track` — Toggle switch
- `Button/File Upload` — File upload button

### 3. Navigation
- `Breadcrumb` — Navegación jerárquica
- `Tabs` — Tab navigation
- `Navbar/Admin` — Admin panel navbar
- `Navbar/Admin Mobile` — Mobile collapsed
- `Navbar/Admin Mobile Overlay` — Mobile overlay
- `Navbar/Pública` — Public site navbar

### 4. Data Display
- `Table/Encuestados` — Tabla de encuestados con status
- `Table/Climas` — Tabla de climas organizacionales
- `Table/Semáforo` — Tabla con indicadores de color
- `Pagination` — Paginación
- `Card/Editor Section` — Card para editor
- `Card/Servicio` — Card de servicio (marketing)
- `Card/Login BG` — Card con fondo login
- `Badge/Status Check` — Badge de estado
- `Badge/Order Number` — Badge numérico
- `Chip/Removable` — Chip con botón de eliminar
- `ListItem/Factor` — List item para factores

### 5. Feedback
- `Alert/Danger` — Error alert
- `Alert/Info` — Info alert
- `Alert/Success` — Success alert
- `Modal/Content` — Modal container
- `Loader` — Loading spinner

### 6. Charts
- `Chart/Bar Comparative` — Gráfica de barras comparativa
- `Chart/Bar Single` — Gráfica de barra simple
- `Chart/Donut` — Gráfica donut

### 7. Layout
- `Footer` — Pie de página

## Arquitectura de la Library

```
create-react-component-library/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── index.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   ├── Button.test.tsx
│   │   │   ├── Button.cy.tsx
│   │   │   └── style.scss
│   │   ├── 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
│       └── ...
├── .storybook/
│   ├── main.js
│   └── preview.js
├── package.json
├── tsconfig.json
└── README.md
```

### Tokens de diseño (src/tokens/)
- `colors.ts` — Exportar todos los colores como constantes TypeScript
- `typography.ts` — Exportar todas las tipografías como objetos con fontFamily, fontSize, fontWeight, lineHeight
- Estos tokens se reutilizan en cada componente SCSS y TSX

### Cada componente sigue el patrón:
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: Configuración del proyecto
1. Clonar/crear `create-react-component-library` como base
2. Configurar `package.json` con nombre `@blconsultores/design-system`
3. Configurar Storybook con soporte SCSS
4. Configurar Jest + Testing Library + Cypress Component Testing
5. Configurar tsconfig para la library

### Fase 2: Crear tokens de diseño
1. `src/tokens/colors.ts` — Todas las variables de color del design system
2. `src/tokens/typography.ts` — Todas las tipografías con sus propiedades
3. `src/tokens/index.ts` — Barrel export

### Fase 3: Implementar componentes (por categoría)
1. **Buttons** — 7+ variantes con estados hover/active/disabled
2. **Forms** — Input, Select, Toggle, File Upload
3. **Navigation** — Breadcrumb, Tabs, Navbar (Admin + Pública)
4. **Data Display** — Table, Card, Badge, Chip, ListItem, Pagination
5. **Feedback** — Alert, Modal, Loader
6. **Charts** — Bar Comparative, Bar Single, Donut
7. **Layout** — Footer

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

### Fase 5: Testing
1. Unit tests para cada componente
2. Component tests con Cypress
3. Visual regression (opcional)

### Fase 6: Integración
1. Publicar como package npm local (`npm link`)
2. Instalar en `blconsultores_app` como dependencia
3. Migrar componentes existentes del proyecto para usar la library

## 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
- [ ] 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'`