196 lines
6.9 KiB
Markdown
196 lines
6.9 KiB
Markdown
# 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'`
|