@numaris-microfront/ui-kit

Librería de componentes de UI de la plataforma Numaris. Si estás construyendo un widget para esta plataforma y necesitás componentes visuales — tablas, botones, formularios, modales — instalá este paquete en vez de traer tu propia librería: así tu widget hace match visual con el Shell y con el resto de los widgets, sin coordinarte manualmente con nadie sobre qué usar.

Qué es, en una frase

Un wrapper de antd v6 — reexporta el paquete completo — más un sistema de tokens de marca (colores, tipografía) y el proveedor que los aplica al tema de antd, y un componente propio (diálogo de confirmación).

Instalación

npm install @numaris-microfront/ui-kit antd

react y react-dom (^19.2.0) son peer dependencies — tu proyecto ya los tiene. antd es una dependencia directa del paquete (se instala igual, junto con @ant-design/icons, al instalar @numaris-microfront/ui-kit).

Importá también la hoja de estilos una vez, en el punto de entrada de tu widget:

import '@numaris-microfront/ui-kit/styles.css';

Trae ajustes a antd que su sistema de tokens no expone (ver más abajo). Sin ella, tu widget sigue funcionando pero se ve levemente distinto al resto de la plataforma.

Uso: los componentes son los de antd

import { Button, Table, Form, Input, ConfigProvider } from '@numaris-microfront/ui-kit';

function MyWidget() {
  return (
    <Form onFinish={(values) => console.log(values)}>
      <Form.Item name="name" label="Nombre">
        <Input />
      </Form.Item>
      <Button type="primary" htmlType="submit">
        Guardar
      </Button>
    </Form>
  );
}

Es el mismo import que tendrías con antd directo — mismos componentes, misma API, misma documentación (la de ant.design). Lo único que cambia es de dónde sale el import, para que todo el que construye un widget para esta plataforma use la misma versión de antd.

Aplicar la marca de la organización: NumarisThemeProvider

Si tu widget corre dentro del Shell (host de Module Federation), no montes este provider vos: el Shell ya lo monta una sola vez, arriba de todo, y tu widget hereda el tema a través de las CSS variables que ese provider escribe en el documento (ver la sección siguiente, "Por qué dos mecanismos"). Montarlo también en tu widget pisaría el tema del Shell.

Si tu widget corre standalone (fuera del Shell, para desarrollo o demo aislada), montalo vos en la raíz:

import { NumarisThemeProvider } from '@numaris-microfront/ui-kit';

function StandaloneRoot() {
  return (
    <NumarisThemeProvider>
      <MyWidget />
    </NumarisThemeProvider>
  );
}

Acepta un brand opcional (Partial<BrandTokens>) para forzar una marca distinta a la default — útil para probar cómo se ve tu widget con otros colores sin depender del Shell real.

Leer la marca activa dentro de un widget remoto: useBrandTheme

Este es el hook que sí usás dentro de un widget montado por el Shell, para que sus componentes de antd (los que vengan de este mismo paquete) respeten el tema de la organización activa:

import { ConfigProvider } from '@numaris-microfront/ui-kit';
import { useBrandTheme } from '@numaris-microfront/ui-kit';

function MyWidgetRoot() {
  const theme = useBrandTheme('my-widget-theme'); // el string identifica a TU widget, ver abajo
  return (
    <ConfigProvider theme={theme}>
      <MyWidget />
    </ConfigProvider>
  );
}

El argumento de useBrandTheme es obligatorio-en-la-práctica si tu plataforma monta varios widgets con antd en la misma página (aunque el tipo lo declare opcional): identifica a tu copia de antd frente a las demás. Sin un valor propio, o repitiendo el de otro widget, las variables CSS de tema de una copia pisan a las de otra en el documento — el síntoma es que al guardar un cambio de tema, algunos colores de tu widget cambian y otros no, sin ningún error en consola. Usá algo único a tu widget, por ejemplo '<tu-widget-id>-theme'.

Por qué dos mecanismos (NumarisThemeProvider y useBrandTheme) y no uno solo

El contexto de React (ConfigProvider) no cruza la frontera entre bundles separados (Module Federation, iframes, cualquier arquitectura donde el host y el widget cargan su propia copia de React y de antd). Si el Shell solo montara ConfigProvider, cada widget remoto renderizaría con el azul por defecto de antd, sin ningún error.

Lo que sí cruza esa frontera son las CSS variables, porque viven en el documento HTML, no en el árbol de React. Por eso NumarisThemeProvider (el que monta el host) hace dos cosas: monta el ConfigProvider para lo que está en su propio árbol, y además escribe las CSS variables de marca en :root. Cada widget remoto, con useBrandTheme, lee esas variables del documento y reconstruye su propio tema de antd a partir de ellas — sin necesitar contexto de React compartido.

Si tu integración no usa Module Federation (por ejemplo, tu app es un monolito de React sin remotos separados), no necesitás useBrandTheme: un solo NumarisThemeProvider en la raíz alcanza, porque ahí sí hay un único árbol de React.

Los tokens de marca (BrandTokens)

interface BrandTokens {
  colorPrimary: string;         // botones primarios, links, foco
  colorPrimaryContrast: string; // texto sobre colorPrimary
  colorSecondary: string;       // acento de apoyo (no tiene equivalente directo en antd)
  colorSuccess: string;
  colorWarning: string;
  colorError: string;
  colorInfo: string;
  colorTextBase: string;        // base de la que antd deriva la escala de grises del texto
  fontFamily: string;           // un stack CSS completo, no solo el nombre de la familia
  borderRadius: number;
  borderRadiusLG: number;
}

numarisBrand exporta los valores por defecto de la plataforma. resolveBrandTokens(partial) combina esos defaults con lo que quieras sobreescribir. brandCssVariables(tokens) convierte el catálogo a un mapa de CSS variables (--numaris-brand-*) — es lo que usa internamente NumarisThemeProvider, y también sirve si necesitás leer un color de marca desde CSS plano fuera de un componente de antd.

BRAND_FONTS es la lista cerrada de tipografías entre las que se puede elegir (Source Sans 3, Inter, IBM Plex Sans, cada una con su propio stack de fallback) y DEFAULT_FONT es cuál se usa si no se personaliza nada.

El componente propio: useConfirmationDialog

El único componente que este paquete expone más allá del wrapper de antd — el diálogo de "¿estás seguro?":

import { App, Button } from '@numaris-microfront/ui-kit';
import { useConfirmationDialog } from '@numaris-microfront/ui-kit';

function DeleteButton({ onDelete }: { onDelete: () => void }) {
  const confirm = useConfirmationDialog('danger'); // 'danger' | 'info' | 'warning'

  return (
    <Button
      danger
      onClick={() =>
        confirm({
          title: '¿Eliminar este elemento?',
          content: 'Esta acción no se puede deshacer.',
          confirmLabel: 'Eliminar',
          cancelLabel: 'Cancelar',
          onConfirm: onDelete,
        })
      }
    >
      Eliminar
    </Button>
  );
}

Requiere que exista un <App> de antd en algún ancestro — NumarisThemeProvider ya lo monta, así que si tu widget vive bajo ese provider (directo o indirectamente vía el Shell) esto ya está resuelto. Si lo usás fuera de ese árbol, envolvé tu componente en <App> vos mismo. Sin <App>, el diálogo igual aparece pero ignora el tema de marca — sin error ni warning en consola.

La hoja de estilos (ui-kit/styles.css)

Existe para lo que el sistema de tokens de antd no alcanza a expresar. Es lo único que este paquete emite además de JavaScript/TypeScript. Importala una vez por aplicación (o una vez por widget, si tu widget puede correr standalone) — importarla varias veces no duplica nada visible, son las mismas reglas CSS.

Qué NO es este paquete

• No es un design system con componentes propios de dominio. No vas a encontrar un <UserTable> ni un <DeviceForm> acá — eso vive en tu widget. Lo que este paquete expone es presentación genérica (los ~300 componentes de antd) más tokens de marca.
• No tiene estado de negocio. Ningún componente de acá sabe qué es un usuario, un dispositivo o una organización más allá de sus colores.