@amsintegra/design-system

Sistema de diseño de React para la plataforma B2BMX de AMS Integra. Está construido sobre Ant Design v6 con el tema de marca Metronic (primario #A72432, tipografía Inter, base de 13px) e incluye Storybook para explorar y documentar cada componente.

Cubre todos los componentes de Ant Design v6 como wrappers/re-exports tipados con el tema aplicado, más composites propios que consolidan patrones ya usados en los microfrontends.

📦 Se instala en cada proyecto

Este es un paquete de librería: cada proyecto que lo use tiene que instalarlo por su cuenta. No es algo que se instale una sola vez y quede disponible para todos los proyectos. Cuando arranques un portal o microfrontend nuevo, corré la instalación de abajo dentro de ese proyecto.

Es una dependencia normal de la app (sus componentes se renderizan en runtime), así que va en dependencies, no en devDependencies.

Instalación

1. Instalá el paquete

npm install @amsintegra/design-system

2. Asegurate de tener sus peers

La librería necesita que tu proyecto tenga estas piezas (son peer dependencies, o sea que las comparte con tu app en vez de traer su propia copia):

| Peer | Versión | |------|---------| | react / react-dom | 18, 19 o 20 | | antd | 6 | | @ant-design/icons | 6 | | dayjs | 1.11+ |

• Si tu proyecto ya tiene React y antd 6 (por ejemplo un portal con Next.js): no hacés nada más, la librería usa los que ya tenés.

• Si te falta alguno, instalalos de una:

  npm install antd@^6 @ant-design/icons@^6 dayjs react react-dom

Ojo con antd: tiene que ser la versión 6, igual que @ant-design/icons (icons 6 no funciona con antd 5). Y antd 6 pide React 18 o superior.

Requiere Node.js 18 o superior para desarrollar.

Declarar React y antd como peers (en vez de empaquetarlos dentro de la librería) evita terminar con dos instancias de React/antd en runtime —el clásico Invalid hook call y los contextos de tema duplicados— cuando la librería se consume bajo Module Federation. La librería reutiliza la copia que ya tiene tu app.

Uso

Envuelve la app una sola vez en la raíz con AmsConfigProvider (aplica el tema y el contexto de antd App para message/notification/Modal):

import { AmsConfigProvider, Button, DataTable } from '@amsintegra/design-system';
import esES from 'antd/locale/es_ES';

export function Root({ children }) {
  return (
    <AmsConfigProvider mode="light" locale={esES}>
      {children}
    </AmsConfigProvider>
  );
}

Luego importa componentes con named imports:

import { Button, DataTable, ModalDialog, FilterSelect } from '@amsintegra/design-system';

Modo oscuro:

<AmsConfigProvider mode="dark">…</AmsConfigProvider>

Toasts context-safe (sin el warning de método estático de antd):

import { useAmsMessage } from '@amsintegra/design-system';

function Guardar() {
  const message = useAmsMessage();
  return <Button onClick={() => message.success('Guardado')}>Guardar</Button>;
}

Qué incluye

• Tema: AmsConfigProvider, buildTheme, tokens de Metronic (primitives, semantic, radius, typography, sizing).
• Todos los componentes de antd v6 como re-exports tipados (General, Layout, Navigation, Data Entry, Data Display, Feedback y otros).
• Composites AMS: DataTable, ModalDialog, FilterSelect, FileUploadDragger, PageHeader, DownloadButton, ConfirmModal.
• Hooks: useAmsMessage, useAmsNotification, useControllableState.

El inventario completo con estado por componente está en plan/03-component-inventory.md.

Desarrollo

npm install              # instala dependencias
npm run storybook        # levanta Storybook en http://localhost:6006
npm run test             # corre los tests (Vitest)
npm run typecheck        # tsc --noEmit
npm run build            # build de la librería (ESM + CJS + tipos) con tsup
npm run build-storybook  # Storybook estático (para publicar la doc)

Storybook

Storybook (v10, @storybook/react-vite) es la documentación viva del design system: una story por componente, docs en MDX y un piloto de pantalla real (Pilot/Consulta de Facturas). Incluye los addons de accesibilidad (a11y), themes (light/dark) y docs.

Desarrollo local

npm run storybook

Levanta el servidor en http://localhost:6006 con hot reload.

Build del sitio estático

npm run build-storybook

Genera el sitio en storybook-static/. Esa carpeta es un sitio estático autocontenido que se puede servir con cualquier hosting de estáticos.

Despliegue

Publicá el contenido de storybook-static/ en el hosting que use el equipo:

• Servir localmente para revisar el build:

  npx http-server storybook-static

• Bitbucket Pages / hosting estático: subí el contenido de storybook-static/ como artefacto del pipeline.

• Netlify / Vercel / S3+CloudFront: apuntá el directorio de publicación a storybook-static y el comando de build a npm run build-storybook.

storybook-static/ está en .gitignore — es un artefacto de build, no se commitea. Se regenera en cada despliegue.

Publicación

El paquete se publica en el registry público de npm bajo el scope @amsintegra, con acceso público (publishConfig.access = "public"). prepublishOnly corre typecheck + tests + build automáticamente, así que no se publica un build roto.

npm login                # autenticación en npmjs.com (requiere permiso en el scope @amsintegra)
npm publish              # publica la versión actual de package.json

El scope @amsintegra debe existir en npm y tu cuenta necesita permiso de publicación en él. Una versión publicada es prácticamente inmutable: no se puede re-publicar el mismo número con otro contenido.

Generar un tarball para entregar/instalar sin registry:

npm run pack:tarball     # genera amsintegra-design-system-<version>.tgz
# en el proyecto consumidor:
npm install /ruta/al/amsintegra-design-system-<version>.tgz

Para asistentes de IA

En la raíz del paquete hay un llms.txt: una guía concisa y legible por máquina para que un asistente de IA descubra e interprete cómo usar la librería (imports, reglas de oro, setup) aunque no tenga la skill dedicada. Se incluye dentro del paquete publicado en npm, así que también aparece en node_modules. La referencia completa por componente vive en docs/skills/ams-design-system/SKILL.md.

Changelog

El historial de versiones está en CHANGELOG.md.

Licencia

MIT © AMS Integra

Estado

• ✅ Tema (light + dark, tokens Metronic)
• ✅ Cobertura completa de componentes antd v6 + composites AMS
• ✅ Storybook con story por componente y un piloto (Pilot/Consulta de Facturas)
• ✅ Empaquetado listo para publicar (@amsintegra/design-system)

Detalles y roadmap en plan/.