Usar DESIGN.md
Indica al agente que consulte DESIGN.md junto con AGENTS.md y las fichas de los componentes que va a utilizar. Puedes copiarlo o descargarlo desde la cabecera.
Mantener el sistema
Al cambiar una primitiva global actualiza su ficha, demo y reglas afectadas en el mismo cambio. Añade componentes nuevos al inventario, incluso si son locales. Ejecuta docs:design-system:check, type:check y build de Platform.
Responsabilidades
DESIGN.md describe el lenguaje visual y enlaza las fuentes. AGENTS.md conserva las instrucciones operativas, permisos y validaciones; los contratos especializados mantienen su detalle.
DESIGN.md
# Veetcuna Design System
Referencia visual de Veetcuna para diseño, desarrollo y agentes de IA.
Portal: https://platform.veetcuna.com/docs/design-system
## Identidad y fuentes de verdad
Veetcuna utiliza una sola identidad visual en CRM, Finance, CMS, HR, Events,
Zuyo y superficies públicas. CRM es la referencia visual actual. El prefijo
histórico `Crm` de una primitiva visual no limita su uso al módulo CRM.
Los tokens y componentes implementan el sistema; este documento resume las
reglas aprobadas. Si el código difiere de una regla, registra la diferencia y
consulta la referencia especializada antes de reproducirla. No conviertas un
estilo legacy en un nuevo estándar.
- Tokens: `apps/platform/src/app/globals.css`.
- Tipografías: `apps/platform/src/app/fonts.ts`.
- Escalas y breakpoints: `packages/config-tailwind/tailwind.config.ts`.
- Inventario: `apps/platform/src/shared/COMPONENT_INVENTORY.md`.
- Contrato visual detallado: `.agents/skills/use-global-look-and-feel/SKILL.md`.
- Modales: `.agents/skills/use-global-look-and-feel/references/modal-standard.md`.
## Motivación y estilo
Buscamos un espacio de trabajo tangible, sereno y coherente. Nuestra interpretación
del neoesqueuomorfismo utiliza profundidad suave: superficies elevadas agrupan
contenido, regiones inset alojan controles y acentos contenidos señalan acciones.
La luz y la sombra sugieren materialidad; la jerarquía debe seguir siendo legible
sin ellas. Conserva contraste, foco, etiquetas y densidad adecuados al trabajo.
El neumorfismo inspira la continuidad entre fondo y controles. Las transparencias
pueden aportar contexto a overlays y cabeceras; el vidrio y los reflejos de las
referencias no implican convertir tablas o formularios en superficies translúcidas.
Motivación y estilo:
https://platform.veetcuna.com/docs/design-system/motivacion-y-estilo
## Color y superficies
Usa roles semánticos, sin copiar valores hexadecimales a cada pantalla.
| Rol | Token |
| --- | --- |
| Fondo de trabajo | `--vee-workspace` |
| Tarjeta elevada | `--vee-surface-raised` |
| Región hundida | `--vee-surface-inset` |
| Control | `--vee-surface-control` |
| Overlay y panel flotante | `--vee-surface-overlay`, `--vee-surface-floating` |
| Bordes | `--vee-border`, `--vee-border-subtle`, `--vee-border-floating` |
| Texto | `--vee-text-primary`, `--vee-text-secondary`, `--vee-text-muted` |
| Foco | `--vee-focus` |
| Carga | `--vee-skeleton`, `--vee-skeleton-strong` |
El tema global controla claro y oscuro. Usa las mismas primitivas en ambos.
Los acentos distinguen estados y contexto; no deben crear sistemas visuales
independientes por módulo. El CTA principal es una píldora celeste suave.
## Tipografía y densidad
Inter es la familia de interfaz por defecto. Lexend Deca está disponible en la
configuración; no la conviertas en una segunda jerarquía global sin referencia.
Usa `font-semibold` como peso máximo: no `font-bold`, `font-extrabold` ni
`font-black`. Código e identificadores técnicos usan monoespaciada.
Conserva la densidad de CRM: títulos claros, etiquetas compactas, separación
consistente y texto secundario con contraste suficiente. Reutiliza tamaños,
alturas, radios y espaciado de las primitivas antes de añadir valores locales.
## Componentes preferidos
| Necesidad | Componente e importación |
| --- | --- |
| Acciones | `CrmActionButton`, `CrmActionLink`, `CrmActionAnchor`, `CrmActionDownload` desde `@modules/crm/components/action-button` |
| Superficies | `CrmInsetSurface`, `CrmRaisedSurface`, `getCrmPlasticSurfaceStyle` desde `@modules/crm/components/inset-surface` |
| Campos | `CrmCompactInput`, `CrmCompactTextarea`, `CrmFieldShell`, `CrmChipSelectField` desde `@modules/crm/components/form-ui` |
| Tablas | `CrmEditableTable` (default) desde `@modules/crm/components/editable-table` |
| Selección booleana | `CrmCheckboxButton` desde `@modules/crm/components/checkbox-button` |
| Secciones | `CrmInsetTabSwitcher` desde `@modules/crm/components/inset-tab-switcher` |
| Personas | `UserAvatar` (default) desde `@shared/components/user-avatar` |
| Modales | `PlatformFormModal`, `PlatformModalBody` desde `@shared/components/platform-form-modal` |
| Ayuda de campos | `CrmInfoPopover` desde `@modules/crm/components/info-popover` |
| Explicación breve | `PlatformTooltip` desde `@shared/components/platform-tooltip` |
Para asignar responsables usa `AdvisorMenu`, no un selector genérico. Revisa el
inventario para cargas de archivos, fechas, asociaciones y patrones de negocio.
Usa RizzUI/template cuando no exista una primitiva más específica.
## Composición y elevación
Usa `--vee-shadow-raised`, `--vee-shadow-floating`, `--vee-shadow-inset` y
`--vee-shadow-plastic` mediante las primitivas compartidas. No copies recetas
de sombras. Las tarjetas agrupan contenido; las superficies inset agrupan
controles. La elevación flotante corresponde a contenido superpuesto.
Las tablas reciben las acciones por `headerActions`. Los formularios mantienen
el estado en su propietario común más cercano. Los modales usan el shell global,
con cabecera y acciones fuera del cuerpo desplazable. Respeta `isBusy` y
`dismissible={false}`; no añadas rutas de cierre a un onboarding obligatorio.
## Estados, acciones y accesibilidad
Documenta y conserva estados normal, foco, hover, seleccionado, deshabilitado,
carga y error cuando correspondan. No uses solamente color para explicar estados.
Proporciona etiquetas accesibles y foco visible; verifica navegación por teclado.
Usa enlaces para navegación segura y botones para acciones. Los enlaces de acción
visibles terminan con `PiArrowSquareOutBold`. Exportar, descargar o mutar no debe
activarse mediante prefetch. Usa `CrmActionDownload` para descargas nativas.
`UserAvatar` preserva fotos y proporciona fallback ilustrado: pasa un ID estable
como `seed`. No recrees avatares con iniciales como sustituto global.
Los uploads ocultan el input nativo detrás de un control accesible y muestran
formatos, límites y nombres seleccionados. La validación visual no sustituye la
validación de archivos del servidor en flujos reales.
## Responsive y movimiento
Usa los breakpoints del Tailwind compartido. Evita anchos rígidos que desborden;
las columnas se apilan y las tablas usan su presentación responsive existente.
Conserva acciones alcanzables y scroll del cuerpo en modales. Comprueba al menos
390, 768 y 1440 px y ambos temas.
Las transiciones explican cambios de estado. Respeta `prefers-reduced-motion`;
reutiliza animaciones compartidas en vez de crear efectos decorativos por módulo.
## Reglas de contribución
Busca primero en shared, core y primitivas globales históricas de CRM. Promueve o
adapta cuando corresponda; evita duplicados y archivos grandes. Registra cada
componente nuevo en el inventario, incluso si su alcance es local.
Una primitiva global nueva o modificada actualiza su ficha y ejemplo del portal
en el mismo cambio. Actualiza este documento cuando cambie una regla global.
Las demos usan datos ficticios, estado local y nunca ejecutan operaciones reales.
Los componentes de negocio sin demo se identifican como Solo referencia.
`AGENTS.md` mantiene las reglas de trabajo, validación, permisos y despliegue.
Este documento no autoriza Chrome, commits, despliegues ni cambios de datos.