@cmedinavera/design-system

v1.0.6

Published

2 months ago

Enterprise UI Component Library for Acme Corporation, built with Angular 21, PrimeNG 21, and Tailwind CSS v4.

0High
0Medium
0Low

cmedinavera

angular primeng tailwind design-system uikit components acme

🎨 @cmedinavera/design-system

@cmedinavera/design-system es la biblioteca oficial de componentes UI empresariales de Acme Corporation. Diseñada bajo estándares de excelencia visual, accesibilidad y máxima flexibilidad responsiva, integrando de forma nativa Angular 21, PrimeNG 21 y Tailwind CSS v4.

✨ Características Principales

🧩 Arquitectura Standalone: Todos los componentes son completamente modulares e independientes para minimizar el bundle final.
🌓 Modo Oscuro Integrado: Transición automática y armónica entre temas mediante variables de colores semánticos (text-surface-700, bg-surface-0, etc.).
📱 Rejilla y Flujo Responsivo: Componentes estructurales avanzados como <acme-stack> que adaptan su layout automáticamente a pantallas móviles.
♿ Accesibilidad de Nivel WAI-ARIA: Inyección de directivas ARIA nativas, asociación semántica de campos de formulario e interactividad fluida con teclado.
🚀 CVA Compilado: Todos los componentes interactivos de formulario implementan ControlValueAccessor de Angular para una vinculación impecable y reactiva.

🌈 Sistema Cromático (Paleta de Colores)

Nuestra paleta de colores aprovecha la arquitectura HSL dinámica de Tailwind CSS v4 y PrimeNG 21, lo que garantiza transiciones de Modo Claro a Modo Oscuro fluidas y consistentes.

1. Colores Semánticos de Severidad (Estados)

Cada severidad está enlazada automáticamente a un conjunto de tokens CSS que controlan el color de fondo, el borde y el texto según el estado de la UI:

2. Escala de Grises y Superficies (Surfaces)

Para garantizar la consistencia en los fondos y bordes de las tarjetas y modales, utilizamos la escala semántica surface que se adapta de forma armónica al tema actual:

  💡 Modo Claro (Fondo Brillante):
  [Surface 0] ------------> [Surface 100] ------------> [Surface 200] ------------> [Surface 950]
  #FFFFFF (Fondo)           #F1F5F9 (Separadores)       #E2E8F0 (Bordes)           #0F172A (Texto)

  🌙 Modo Oscuro (Fondo Profundo):
  [Surface 950] ----------> [Surface 900] ------------> [Surface 800] ------------> [Surface 50]
  #090D16 (Fondo)           #0F172A (Separadores)       #1E293B (Bordes)           #F8FAFC (Texto)

Clases Semánticas Recomendadas:

Fondo de la aplicación: bg-surface-0 dark:bg-surface-950
Tarjetas y Paneles: bg-surface-0 dark:bg-surface-900 border border-surface-200 dark:border-surface-800
Textos Principales: text-surface-900 dark:text-surface-50
Labels y Textos Secundarios: text-surface-700 dark:text-surface-300
Subtextos y Ayudas: text-surface-500 dark:text-surface-400

📦 Instalación

Instala el paquete y sus dependencias requeridas ejecutando en tu terminal:

npm install @cmedinavera/design-system primeng primeicons

⚙️ Configuración Global

1. Importación de Estilos y Temas

En el archivo de estilos globales de tu aplicación (e.g., styles.scss), importa las librerías necesarias de PrimeNG y configura la tipografía corporativa Lato:

@import "primeicons/primeicons.css";

@theme {
  --font-family-sans: "Lato", "Inter", sans-serif;
}

/* Configuración de transiciones de color globales y soporte Dark Mode */
html {
  transition: background-color 0.2s ease, border-color 0.2s ease;
  scroll-behavior: smooth;
}

2. Importación de Componentes en Angular

Dado que la biblioteca es totalmente Standalone, puedes importar selectivamente los componentes individuales en tus controladores Angular:

import { Component } from '@angular/core';
import { 
  StackComponent, 
  InputComponent, 
  LabelComponent, 
  ButtonComponent 
} from '@cmedinavera/design-system';

@Component({
  selector: 'app-mi-formulario',
  standalone: true,
  imports: [StackComponent, InputComponent, LabelComponent, ButtonComponent],
  templateUrl: './mi-formulario.html'
})
export class MiFormularioComponent {
  // ...
}

🛠️ Ejemplos Prácticos y Casos de Uso Comunes

Ejemplo 1: Tarjeta Contenedora Responsiva con Soporte para Modo Oscuro

Una tarjeta corporativa que adapta su tipografía, fondos y bordes automáticamente cuando cambia el tema:

<div class="card p-6 rounded-2xl bg-surface-0 dark:bg-surface-900 border border-surface-200 dark:border-surface-800 shadow-sm flex flex-col gap-4">
  <acme-stack direction="row" align="center" gap="1rem" [responsive]="false">
    <acme-avatar image="assets/usuario.png" size="large" shape="circle"></acme-avatar>
    <acme-stack direction="column" gap="0.25rem" [responsive]="false" class="flex-1">
      <h3 class="text-lg font-bold text-surface-900 dark:text-surface-50 m-0">Carlos Medina Vera</h3>
      <span class="text-xs text-surface-500 dark:text-surface-400">[email protected]</span>
    </acme-stack>
    <acme-tag severity="success" value="Administrador"></acme-tag>
  </acme-stack>
  
  <acme-divider></acme-divider>
  
  <p class="text-sm text-surface-700 dark:text-surface-300 leading-relaxed m-0">
    Bienvenido al panel del Sistema de Diseño del HospitalHIS. Utiliza las variables y atómicos corporativos para asegurar consistencia visual en todos tus microfrontends.
  </p>
</div>

Ejemplo 2: Formulario Complejo y Altamente Accesible

Layout de formulario reactivo en cuadrícula responsiva, utilizando textos de ayuda asociados por accesibilidad:

<div class="p-8 bg-surface-0 dark:bg-surface-950 rounded-xl border border-surface-200 dark:border-surface-800 flex flex-col gap-6">
  <div class="text-xl font-bold text-surface-900 dark:text-surface-50">Registro de Paciente</div>
  
  <acme-stack direction="column" gap="1.5rem" [responsive]="false">
    <!-- Fila 1: Nombre y Apellido -->
    <acme-stack direction="row" gap="1.5rem" [responsive]="true">
      <div class="flex-1 flex flex-col gap-2">
        <acme-label for="nombre-input" [required]="true">Nombre(s)</acme-label>
        <acme-input id="nombre-input" [floatLabel]="false" placeholder="Ej. Carlos"></acme-input>
      </div>
      <div class="flex-1 flex flex-col gap-2">
        <acme-label for="apellido-input" [required]="true">Apellido(s)</acme-label>
        <acme-input id="apellido-input" [floatLabel]="false" placeholder="Ej. Medina"></acme-input>
      </div>
    </acme-stack>
    
    <!-- Fila 2: Documento e Interruptor -->
    <acme-stack direction="row" gap="1.5rem" [responsive]="true">
      <div class="flex-1 flex flex-col gap-2">
        <acme-label for="rut-input">Cédula o Identificación</acme-label>
        <acme-input id="rut-input" [floatLabel]="false" placeholder="12345678-9" helpText="Ingrese el documento sin puntos."></acme-input>
      </div>
      <acme-stack direction="row" align="center" gap="1rem" [responsive]="false" class="flex-1 justify-between pt-6">
        <span class="text-sm font-medium text-surface-700 dark:text-surface-300">¿Requiere Asistencia Médica?</span>
        <acme-toggle-switch [(ngModel)]="requiereAsistencia"></acme-toggle-switch>
      </acme-stack>
    </acme-stack>
    
    <!-- Botones de Acción -->
    <acme-stack direction="row" gap="1rem" class="justify-end w-full pt-4" [responsive]="true">
      <acme-button label="Cancelar" severity="secondary" variant="text" class="w-full md:w-auto"></acme-button>
      <acme-button label="Guardar Paciente" icon="pi pi-check" severity="primary" class="w-full md:w-auto"></acme-button>
    </acme-stack>
  </acme-stack>
</div>

Ejemplo 3: Tabla de Datos Avanzada (`acme-table`)

Componente de visualización modular y paginado con soporte para plantillas personalizadas:

<acme-table [value]="productos" [paginator]="true" [rows]="5" styleClass="p-datatable-striped">
  <ng-template #header>
    <tr>
      <th>Código</th>
      <th>Nombre</th>
      <th>Categoría</th>
      <th>Precio</th>
    </tr>
  </ng-template>
  <ng-template #body let-product>
    <tr>
      <td>{{ product.code }}</td>
      <td>{{ product.name }}</td>
      <td>{{ product.category }}</td>
      <td>{{ product.price | currency }}</td>
    </tr>
  </ng-template>
</acme-table>

Ejemplo 4: Componentes de Superposición y Overlays (`acme-dialog`, `acme-popover`, `acmeTooltip`)

Muestra cómo integrar modales con footer personalizado, popovers reactivos cargados con tablas y la directiva de tooltips sobre botones o inputs de texto:

<!-- Botones para disparar overlays -->
<acme-stack direction="row" gap="1rem" [responsive]="true">
  <acme-button label="Abrir Diálogo de Confirmación" (onClick)="dialogVisible = true" acmeTooltip="Haga clic para abrir la ventana modal"></acme-button>
  <acme-button label="Ver Detalles Rápidos" severity="secondary" (onClick)="pop.toggle($event)" acmeTooltip="Haga clic para ver detalles contextuales"></acme-button>
</acme-stack>

<!-- 1. Diálogo Modal Premium -->
<acme-dialog header="Confirmar Registro de Paciente" [(visible)]="dialogVisible" [modal]="true" [style]="{ width: '450px' }">
  <p class="text-sm text-surface-700 dark:text-surface-300 leading-relaxed m-0">
    ¿Está seguro de que desea guardar los datos ingresados en el expediente de este paciente? Esta acción registrará la fecha y hora actual en la bitácora.
  </p>
  <ng-template #footer>
    <acme-button label="Cancelar" severity="secondary" [text]="true" (onClick)="dialogVisible = false"></acme-button>
    <acme-button label="Confirmar Registro" severity="success" (onClick)="dialogVisible = false"></acme-button>
  </ng-template>
</acme-dialog>

<!-- 2. Popover Ligero Contextual -->
<acme-popover #pop [style]="{ width: '280px' }">
  <div class="p-4 flex flex-col gap-2">
    <h4 class="font-bold text-surface-900 dark:text-surface-50 m-0">Información del Sistema</h4>
    <p class="text-xs text-surface-600 dark:text-surface-400 m-0">
      El estado actual de la red de microfrontends es <strong>Operativo (100%)</strong>. No se registran retrasos en el API gateway.
    </p>
  </div>
</acme-popover>

🧭 Catálogo Completo de Componentes (71 Componentes)

Todos los componentes son de arquitectura Standalone (se importan de forma individual y bajo demanda). Están clasificados en las siguientes 7 categorías estructurales:

1. Layout & Estructura (11 Componentes)

Diseñados para estructurar y segmentar el flujo visual de tus interfaces:

<acme-stack>: Flexbox inteligente que gestiona la dirección (fila/columna), espaciado (gap) y alineación, con soporte para reordenamiento responsivo en dispositivos móviles.
<acme-panel>: Panel tipo tarjeta colapsable ideal para secciones independientes de información.
<acme-accordion>: Acordeón para colapsar y expandir secciones de datos de forma compacta.
<acme-tabs>: Sistema de navegación por pestañas superiores.
<acme-fieldset>: Recuadro delimitador con título (leyenda) integrado en el borde superior, con soporte opcional de colapso.
<acme-toolbar>: Barra de herramientas dividida en secciones para proyectar botones y controles (start, center, end).
<acme-divider>: Separador visual responsivo que puede ser vertical u horizontal con contenido centrado.
<acme-card>: Contenedor principal de tarjetas con bordes redondeados y transiciones premium.
<acme-card-header>: Cabecera estructurada para albergar títulos, iconos o acciones de tarjetas.
<acme-card-body>: Cuerpo central para el contenido principal de la tarjeta.
<acme-card-footer>: Pie de página autoalineable diseñado para metadatos o contadores de tarjetas.

2. Atómicos & Formularios (19 Componentes)

Controles interactivos de formularios que implementan ControlValueAccessor (CVA) para un enlace de datos reactivo y bidireccional impecable:

<acme-input>: Entrada de texto estándar con soporte para placeholders, iconos, etiquetas y textos de ayuda accesibles.
<acme-input-number>: Entrada dedicada a números con formato de moneda, porcentajes o decimales específicos.
<acme-textarea>: Campo de comentarios de múltiples líneas ajustable.
<acme-label>: Etiqueta para asociar controles interactivos con indicador visual de obligatoriedad ([required]="true").
<acme-checkbox>: Casilla de confirmación y selección múltiple.
<acme-radio>: Selector exclusivo de opciones circulares.
<acme-select>: Menú desplegable para selección individual de datos (Combobox).
<acme-multiselect>: Menú desplegable para selección múltiple de datos.
<acme-datepicker>: Calendario corporativo responsivo para selección de fechas sencillas o rangos de fecha.
<acme-calendar>: Selector de fechas y horas avanzado, con soporte para vistas inline, selección de rangos, horas y selección múltiple.
<acme-autocomplete>: Entrada de texto predictiva con filtrado interactivo en tiempo real.
<acme-toggle-switch>: Interruptor de estado binario deslizante (tipo switch de iOS/Material).
<acme-toggle-button>: Botón plano que retiene estados activos/inactivos de manera visual.
<acme-select-button>: Grupo de botones planos alineados donde solo uno puede estar seleccionado.
<acme-rating>: Calificador en escala de estrellas.
<acme-slider>: Barra de selección de rangos numéricos continuos.
<acme-colorpicker>: Selector y mezclador interactivo de color.
<acme-knob>: Dial giratorio de control numérico circular.
<acme-fileupload>: Cargador de archivos con soporte para arrastrar y soltar (drag and drop), validación de tamaños y formatos, y visualización de progreso.

3. Botones & Acciones (3 Componentes)

Componentes diseñados para disparar eventos y controlar flujos:

<acme-button>: Botón plano corporativo con severidades semánticas (primary, success, danger, etc.), soporte de carga ([loading]="true") y estilos de borde.
<acme-button-group>: Contenedor para alinear y fusionar bordes de múltiples botones en un solo bloque visual.
<acme-split-button>: Botón combinado con una acción directa a la izquierda y un disparador de menú dropdown a la derecha.

4. Grillas & Visualización de Datos (11 Componentes)

Componentes de alto rendimiento diseñados para renderizar y estructurar conjuntos complejos de información:

<acme-table>: Tabla de datos empresariales con paginador responsivo, plantillas flexibles (#header, #body) y estilos de filas alternas.
<acme-dataview>: Visualizador dinámico que transforma listas de objetos en cuadrículas de tarjetas responsivas.
<acme-list-item>: Elemento de visualización reutilizable tipo tarjeta o fila para productos, adaptado para listas o grillas con soporte completo para modo claro/oscuro y stock.
<acme-tree>: Visualizador modular para explorar estructuras de datos en forma de árbol colapsable.
<acme-treetable>: Tabla combinada con jerarquías de árbol que permite colapsar subfilas y subcarpetas en tiempo real.
<acme-picklist>: Lista de transferencia dinámica bidireccional para mover elementos entre columnas de origen y destino con controles y drag & drop.
<acme-orderlist>: Lista interactiva para ordenar y priorizar colecciones de elementos con botones de desplazamiento integrados.
<acme-chart>: Visualizador y estructurador de gráficos estadísticos (barras, líneas, tarta, rosca, radar, área polar) de alto rendimiento basado en Chart.js.
<acme-timeline>: Línea de tiempo responsiva para visualizar flujos clínicos u hojas de ruta secuenciales en orden cronológico.
<acme-crud>: Plantilla/componente completo de CRUD (Crear, Leer, Actualizar, Borrar) para administración de catálogos y datos.
<acme-dashboard>: Dashboard completo responsivo que integra estadísticas, gráficos, tabla de ventas recientes y notificaciones.

5. Visuales, Estados & Feedback (13 Componentes)

Elementos informativos rápidos y componentes para mejorar la experiencia de usuario en carga:

<acme-avatar>: Caja circular u cuadrada para renderizar imágenes, iconos o iniciales del perfil del usuario.
<acme-avatar-group>: Contenedor para apilar múltiples avatares superpuestos en fila (ideal para equipos colaborativos).
<acme-badge>: Pequeñas insignias numéricas de estado de color asociadas a severidades.
<acme-overlay-badge>: Insignia especial diseñada para superponerse automáticamente en la esquina de iconos o avatares (muy útil para notificaciones sin leer).
<acme-tag>: Píldoras estáticas de estado de severidad (success para Completado, danger para Cancelado, etc.).
<acme-chip>: Etiquetas tipo tag interactivas y compactas, ideales para filtros aplicados con soporte opcional de eliminación (removable="true").
<acme-progressbar>: Barra de progreso porcentual estática, animada o de carga indeterminada.
<acme-skeleton>: Cajas animadas de color gris que simulan la estructura del contenido mientras se cargan los datos reales (Skeleton Screen Loader).
<acme-toast>: Contenedor de notificaciones emergentes (Toast) con estilos premium para severidades de éxito, información, advertencias, error, secundario y contraste.
<acme-message>: Barra de mensaje estática en línea con el flujo de la UI, con soporte premium para severidades.
<acme-carousel>: Carrusel corporativo premium y responsivo para deslizar e interactuar con listas de tarjetas u objetos.
<acme-galleria>: Galería interactiva avanzada para visualizar álbumes de fotos o imágenes con miniaturas y controles táctiles.
<acme-image>: Visualizador dinámico de imágenes individuales con soporte de carga diferida y modo de zoom flotante (Preview).

6. Navegación & Menús (8 Componentes)

Diseñados para guiar y estructurar el flujo de navegación de los usuarios a través del sistema:

<acme-menubar>: Barra de navegación superior responsiva y horizontal con soporte para submenús e iconos.
<acme-breadcrumb>: Hilo de Ariadna responsivo para indicar la ubicación jerárquica actual en flujos clínicos.
<acme-menu>: Menú estándar vertical de enlaces o acciones, con soporte para renderizarse en línea o como ventana flotante (popup).
<acme-tieredmenu>: Menú de niveles anidados con submenús laterales que se despliegan de forma interactiva.
<acme-contextmenu>: Menú contextual emergente de alta fidelidad que se activa mediante clic derecho sobre un objetivo definido.
<acme-megamenu>: Menú gigante de navegación organizado en una cuadrícula estructurada de múltiples columnas.
<acme-panelmenu>: Menú acordeón colapsable vertical, idóneo para barras laterales de control y navegación principal.
<acme-stepper>: Indicador y controlador lineal de pasos interactivos (wizard), ideal para guiar procesos secuenciales estructurados.

7. Componentes de Superposición / Overlays (6 Componentes)

Diseñados para desplegar paneles flotantes, notificaciones integradas y ventanas emergentes enriquecidas:

<acme-dialog>: Ventana de diálogo modal o no-modal con cabecera, pie de página flexible y redimensionado responsivo.
<acme-drawer>: Panel colapsable deslizante (cajón) desde cualquier extremo del viewport (izquierda, derecha, arriba, abajo o pantalla completa).
<acme-popover>: Contenedor emergente ligero de posicionamiento contextual absoluto activado al hacer clic.
<acme-confirm-popup>: Diálogo flotante simplificado para confirmaciones rápidas en línea (ConfirmPopup).
<acme-confirm-dialog>: Diálogo modal simplificado para confirmaciones críticas integradas (ConfirmDialog).
acmeTooltip: Directiva premium (Tooltip) que inyecta descripciones flotantes dinámicas en el costado deseado del host.

🚀 Scripts de Desarrollo

Si estás contribuyendo al desarrollo del design system:

Compilar la Librería:
```
npm run build:lib
```
Ejecutar Storybook en Entorno Local:
```
npm run storybook
```
Compilar Storybook Estático:
```
npm run build-storybook
```
Aplicar Formato Estándar (Prettier):
```
npm run format
```

📄 Licencia

Este proyecto está bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.