@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):

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

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

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 (
    <ThemeProvider theme={theme}>
      <MeetingHeader
        title="Weekly Sales Meeting"
        date={new Date().toISOString()}
  participants={[{ name: 'John Doe', role: 'Sales Manager' }]}
        onReload={() => console.log('reload')}
      />
    </ThemeProvider>
  );
}

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:

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:

import { MUIButton } from '@getsupervisor/design-system/atoms';

o bien rutas profundas si se habilita export granular (evita incluir todo el bundle):

// 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:

<type>(<scope>): <summary>

[body]

[BREAKING CHANGE: <descr>]

Tipos sugeridos: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

Ejemplos:

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): https://design-system.getsupervisor.ai

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: [email protected]