# Integración con producto: demos, composición y versión **Audiencia:** equipos que consumen el Design System fuera de este repositorio (otra app, otro stack). **Objetivo:** alinear la implementación con lo que veis en la guía **sin** discutir si manda Figma, un HTML inventado o el demo interactivo. --- ## 1. Fuente de verdad (qué manda) | Qué | Dónde | |-----|--------| | **Composición y aspecto** de la pantalla “contenedor de plantillas” | Ruta pública de la guía: **`/demo-contenedor-plantillas`**. | | **Código que la renderiza** (orden de piezas, props) | `app/demo-contenedor-plantillas/page.tsx` + `app/sections/_demos/DemoFormularioMaquetaCuerpo.tsx` (y componentes del DS que importa). | | **Reglas CSS** del marco lienzo, shell de demo, pestañas, etc. | Partials bajo `styles/partials/`, en particular **`10-contenedores.css`** y la navegación de herramientas; el bundle publicado es **`mkclinico-ui.css` / `mkclinico-ui.min.css`**. | **Criterio de equipo:** si hay discrepancia entre un mock estático y el demo en la guía, **prevalece el demo en la ruta** anterior para composición y clases, salvo acuerdo explícito en un brief. Los demos no son archivos HTML sueltos: son **páginas Next.js (React)** + clases del DS. Replicar en otro stack significa respetar **misma jerarquía y mismas clases** documentadas, no importar el código de la guía tal cual. --- ## 2. Contrato de versión (CSS ↔ guía) 1. **Fecha en el CSS generado** Tras `npm run build:css`, la cabecera de `mkclinico-ui.css` y el comentario de `mkclinico-ui.min.css` incluyen **`Versión: YYYY-MM-DD`** (día de generación). Esa fecha es la referencia rápida de “qué build” tenéis. 2. **Cambios relevantes** **[`CHANGELOG.md`](../CHANGELOG.md)** (raíz del repo) describe lo que afecta a consumidores: clases, tokens, demos, contexto para IA. 3. **Alineación con vuestro proyecto** Recomendación: en el **README o ADR** de la app, anotar al menos: - URL o ruta del **`mkclinico-ui.min.css`** que usáis (CDN o copia), y - **fecha de la cabecera** del CSS en el momento de la integración, **o** el **commit/tag** de este repositorio si clonáis o copiáis artefactos desde el monorepo. 4. **Desarrollo vs producción** Coherente con el uso típico: en **producción** enlazad el **`.min.css`**; en **desarrollo** podéis usar el **no minificado** para depurar, siempre **mismo origen lógico** (mismo despliegue o mismo commit) para no mezclar fechas. **CDN documentado (referencia):** `https://cdnmk3.masterkey.cl/assets/css/mkclinico-ui.min.css` — detalle en [`versionado-css-y-cdn.md`](./versionado-css-y-cdn.md). --- ## 3. `guia-*` frente a `demo-pantalla-*` y contenedores de producto Muchas clases con prefijo **`guia-`** (p. ej. `guia-tab-item-demo-row`, `guia-card-paciente-demo-ancho`, `guia-navegacion-navbar-demo-frame`) existen para **vistas previas dentro de los artículos** de la guía: anchos fijos, marcos de demostración, o scroll en columnas de documentación. **No están pensadas como API estable para pantallas reales** del producto. | Prefijo / familia | Uso típico en la guía | Uso en producto | |-------------------|----------------------|-----------------| | **`guia-*`** (demos de artículo) | Ajustar el layout del **recuadro** del componente en la guía. | **Evitar** en pantallas reales, salvo que se acuerde con el DS un caso concreto. | | **`demo-pantalla-*`**, **`demo-constructor-*`** | Shell y maquetas de rutas **`/demo-*`**. | Tratar como **composición de referencia**; al portar, encapsulad en vuestro layout o sustituid por abstracción equivalente. | | **`contenedor-lienzo-plantillas*`, `layout-pantalla-*`, `area-principal`, `panel-principal`**, piezas de **TabItem**, **SidebarNav**, etc. | Parte del lenguaje visual compartido con la guía. | **Sí** como base, según el contexto del DS (documentado en `mkclinico-ai-context.md` y secciones de la guía). | Para **fila de pestañas a pantalla completa** (parecido al **builder**), las demos **`/demo-contenedor-plantillas`** y similares usan clases bajo el **shell de maqueta** (p. ej. `demo-pantalla-tabs-*`, `demo-pantalla-maqueta-grid-pre-panel*`), no la variante `guia-tab-item-demo-row` del artículo *Navegación → Tab Item* (ese bloque `guia-*` sirve para leer el componente en la guía, no como copia 1:1 del lienzo de plantillas). **En la guía (Tab Item, paridad con producto):** ancla interna `#tab-item-paridad-producto` (bloque bajo *Pestañas formato 1* que enlaza al demo y a este documento). **Fila de pestañas + Formato/acciones en** `/demo-contenedor-plantillas` **(referencia, orden de cajas):** implementación en `DemoFormularioMaquetaCuerpo` (modo lienzo, sin F2) — clases de envoltorio frecuentes en la pre-panel y tabs: | Región (aprox.) | Clases CSS (referencia) | |-----------------|-------------------------| | Rejilla sobre el panel (card, tabs, celdas) | `demo-pantalla-maqueta-grid-pre-panel` | | Card / cabecera paciente (demo) | `demo-pantalla-maqueta-card-cell` | | Fila con pestañas (celda) | `demo-pantalla-maqueta-tabs-cell` (y en modo lienzo: `...--lienzo` cuando aplica) | | Scroll horizontal de tabs + CTA + | `demo-pantalla-tabs-outer` → `demo-pantalla-tabs-scroll-y-agregar` → `tab-row-scroll` + `demo-pantalla-tab-row-scroll` | | Formato/⋮ junto a la pista de tabs | `demo-pantalla-tabs-formato-y-opciones` (con variantes de fila de radios según el demo) | | Panel blanco bajo el conector | `demo-pantalla-maqueta-panel-cell` (y cadenas de `contenedor-lienzo-plantillas*`, rail `demo-pantalla-sidebar-rail`, etc., según subpestañas) | Los nombres exactos pueden ajustarse con variantes; la **fuente** sigue siendo el TSX y el demo en el navegador, no una tabla fija. Componente de cada pestaña: clases del **`TabItem`** (`.tab-item`, `.tab-item--activo`, etc.). **Paridad cromática (tabs, scroll, conector activo, sombras):** respetar la estructura documentada para **`.tab-item` / `.tab-row-scroll`** y los contenedores de la sección *Navegación → Tab Item* y el comentario de estructura en el contexto IA. Si añadís menú contextual, arrastre o borrado, envolved los controles para **no** romper el contenedor de scroll que evita recortar sombras (ver trampa de **overflow** en `mkclinico-ai-context.md` / § Tab Item). --- ## 4. Composición “publicada” hoy El **mismo** archivo **`mkclinico-ui.min.css`** del CDN incluye tokens, componentes y reglas de contenedores y demos (no hay un paquete CSS distinto solo para el demo). Lo que este documento fija es el **compromiso semántico**: la referencia viva de composición del contenedor de plantillas es la ruta **`/demo-contenedor-plantillas`** y las clases asociadas en los partials citados, no un mock externo. Si en el futuro el DS expusiera un subconjunto bajo otra URL, se anunciará en el CHANGELOG. --- ## 5. Resumen accionable 1. Fijar **`/demo-contenedor-plantillas`** + **versión (fecha o commit)** del CSS como criterio de alineación. 2. **No** basar el layout de producto solo en clases **`guia-*`** de artículos; usar el demo de **pantalla completa** y contenedores documentados. 3. Revisar **`CHANGELOG.md`** al **actualizar** el CSS en vuestra app. 4. **Tab / builder:** mantener la estructura de fila de pestañas y overflow que documenta el DS para no romper bordes y sombras. Documentación relacionada: [`versionado-css-y-cdn.md`](./versionado-css-y-cdn.md), [`uso-ds-sin-cdn.md`](./uso-ds-sin-cdn.md), `mkclinico-ai-context-lite.md` (sección *Demos de la guía*).