@getsupervisor/design-system

> Biblioteca de componentes UI para las aplicaciones de Supervisor AI. Basada en React + Material UI, organizada con Atomic Design y versionada automáticamente con semantic-release.

Badges (se actualizan tras primer release):
!License !TypeScript

Tabla de contenidos

- @getsupervisor/design-system
- Tabla de contenidos
- Visión
- Características
- Instalación
- Primer uso rápido
- Arquitectura Atomic
- Theming y personalización
- Optimización de imports / tree-shaking
- Scripts de desarrollo
- Versionado \& Releases
- Convención de commits
- Documentación detallada
- Contribuir
- Troubleshooting
- Seguridad de tokens
- Roadmap corto
- Licencia

Visión

Ofrecer un núcleo UI consistente, accesible y escalable que acelere la construcción de interfaces de analítica y colaboración de Supervisor AI, reduciendo duplicidad y asegurando calidad visual/funcional.

Características

- Atomic Design (atoms → molecules → organisms → templates → pages)
- Integración MUI: extendemos componentes y tokens del tema
- Theming centralizado: capa para overrides y design tokens propios
- Componentes especializados: métricas de reuniones, transcripciones, sentiment, etc.
- Accesibilidad: foco en roles ARIA, contraste y navegación por teclado
- TypeScript First: tipado estricto y generación de declaraciones
- Storybook: catálogo vivo + documentación interactiva
- Versionado semántico automático: semantic-release + Conventional Commits
- Rendimiento: tree-shaking y imports granulares

Instalación

``bash
npm install @getsupervisor/design-system


o


yarn add @getsupervisor/design-system
`
Requiere peer deps: react, react-dom, @mui/material, @emotion/react, @emotion/styled, etc. (ver package.json para versiones). Si falta algo, npm/yarn avisará.

Primer uso rápido

`tsx
import React from 'react';
import { ThemeProvider, createTheme } from '@mui/material/styles';
import { MeetingHeader } from '@getsupervisor/design-system';
import BaseTheme from '@getsupervisor/design-system/base-theme';

const theme = createTheme(BaseTheme); // puedes extenderlo

export function Example() {
return (

title="Weekly Sales Meeting"
date={new Date().toISOString()}
participants={[{ name: 'John Doe', role: 'Sales Manager' }]}
onReload={() => console.log('reload')}
/>

);
}
`

Arquitectura Atomic

- Atoms: wrappers directos o estilizados de MUI (MUIButton, MUITypography, etc.)
- Molecules: combinaciones sencillas (TitleWithIcon, MetadataInsightItem)
- Organisms: bloques funcionales complejos (SentimentSummary, EvaluationItem)
- Templates / Pages: composición de organisms para vistas completas (MeetingPage)

Beneficios: reutilización, trazabilidad de estilos, escalabilidad.

Theming y personalización

Puntos de extensión:

1. base-theme.tsx: tokens base (paleta, tipografía, spacing).
2. theme-creator.ts: helper para generar temas derivados.

Ejemplo override de color primario:

`ts
import { createTheme } from '@mui/material/styles';
import BaseTheme from '@getsupervisor/design-system/base-theme';
const theme = createTheme({
...BaseTheme,
palette: {
...BaseTheme.palette,
primary: { main: '#0052CC' }
}
});
`

Optimización de imports / tree-shaking

Preferir importación específica:

`ts
import { MUIButton } from '@getsupervisor/design-system/atoms';
`
o bien rutas profundas si se habilita export granular (evita incluir todo el bundle):

`ts
// NO recomendado para consumidores externos porque rompe compatibilidad semántica:
// import MUIButton from '@getsupervisor/design-system/src/atoms/MUIButton';
// Mantén importaciones públicas; el tree-shaking vendrá de exportaciones granulares.
`

Scripts de desarrollo

| Script | Descripción |
|--------|-------------|
| yarn storybook | Dev server de Storybook |
| yarn build-storybook | Build estático de Storybook |
| yarn build | Compila bundle + tipos TS |
| yarn test | Ejecuta suite Jest |
| yarn test:coverage | Cobertura de pruebas |
| yarn release | Ejecuta semantic-release (normalmente vía CI) |

Versionado & Releases

Automático en rama main usando semantic-release:

1. Analiza commits (commit-analyzer)
2. Genera notas (release-notes-generator)
3. Actualiza CHANGELOG.md y package.json (@semantic-release/git)
4. Publica a npm (@semantic-release/npm)
5. Crea release en GitHub (@semantic-release/github)

Tipos de incremento:

- fix: → patch
- feat: → minor
- feat! / fix! / BREAKING CHANGE: → major

Otros tipos (chore:, docs:, refactor:) no generan versión salvo que incluyan BREAKING.

Nota: si migras el repositorio y en Git faltan los tags históricos que sí existen en npm, crea manualmente el tag correspondiente a la última versión publicada (por ejemplo git tag -a v1.x.y -m "sync" && git push origin v1.x.y) antes de que corra semantic-release; así evitas que intente recalcular desde v1.0.0.

Convención de commits

Formato básico:

`text
():

[body]

[BREAKING CHANGE: ]
`
Tipos sugeridos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

Ejemplos:

`text
feat(meeting-header): add reload action
fix(date-utils): handle timezone offset in formatDateString
chore(release): 1.2.0 [skip ci]
`

Documentación detallada


La documentación extendida está en docs/:

- Atoms
- Molecules
- Organisms
- Templates
- Pages
- Hooks
- Tipos
- Utils
- Theming
- Contribución

Storybook (catálogo visual):

Contribuir

1. Crea rama desde main: feat/nueva-funcionalidad.
2. Implementa componente siguiendo atomic design.
3. Añade Storybook story + tests básicos.
4. Corre yarn build && yarn test.
5. Commit con convención; abre PR (cumplirá protección de rama).

PR Checklist rápido:

- ¿Storybook doc incluida?
- ¿Tests (happy path + edge)?
- ¿Tipado exportado?
- ¿No se introducen breaking sin aviso?

Troubleshooting

| Problema | Causa común | Solución |
|----------|-------------|----------|
| 401 npm whoami en CI | Token mal copiado / scope / secret incorrecto | Regenerar Automation token y actualizar secret |
| GH006 Protected branch | semantic-release no puede pushear | Permitir bypass de GitHub Actions o flujo con PR intermedio |
| “There are no relevant changes” | Commits sin feat/fix/perf | Usa tipos correctos o añade BREAKING CHANGE |
| Tipos TS faltantes | build:types` falló | Revisa exports y dependencias peer |

Seguridad de tokens

- Nunca pegues el token npm en issues o chats públicos.
- Usa tokens Automation (bypass 2FA) restringidos a lo mínimo.
- Revoca inmediatamente tokens expuestos.

Roadmap corto

- Mejora de documentación theming avanzado
- Tests visuales (Chromatic / Loki)
- Lint checks automáticos y story lint
- Playground de tokens dinámico

Licencia

Proyecto proprietary / interno. Uso exclusivamente dentro de Supervisor AI. No redistribuir sin autorización.

---
¿Dudas o sugerencias? Contacto interno: lizbeth@getsupervisor.ai