Proprietary UI component library for Supervisor AI's frontend applications. Built on Material-UI with Atomic Design principles, offering specialized components for AI-driven analytics interfaces. For internal use only.
npm install @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
- @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
- 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
``bash`
npm install @getsupervisor/design-systemo
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á.
`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 (
date={new Date().toISOString()}
participants={[{ name: 'John Doe', role: 'Sales Manager' }]}
onReload={() => console.log('reload')}
/>
);
}
`
- 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.
Puntos de extensión:
1. base-theme.tsx: tokens base (paleta, tipografía, spacing).theme-creator.ts
2. : 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' }
}
});
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.
| 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) |
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: → patchfeat:
- → minorfeat!
- / 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.
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]
:- 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 |- 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.
- Mejora de documentación theming avanzado
- Tests visuales (Chromatic / Loki)
- Lint checks automáticos y story lint
- Playground de tokens dinámico
Proyecto proprietary / interno. Uso exclusivamente dentro de Supervisor AI. No redistribuir sin autorización.
---
¿Dudas o sugerencias? Contacto interno: lizbeth@getsupervisor.ai