Tutorial

Guía completa para crear aplicaciones web con el sistema de diseño del Gobierno de Aragón. Este tutorial está optimizado para ser utilizado por asistentes de IA y desarrolladores que necesiten información técnica precisa sobre DESY. Ver versión markdown para uso con asistentes de IA.

Tabla de contenidos

1. Preguntas iniciales: ¿Qué voy a construir?

Antes de comenzar un proyecto con DESY, debes hacerte estas preguntas clave que guiarán las herramientas y pasos a seguir:

¿Sitio web/Portal o Webapp?

Sitio web o Portal

Un sitio web o portal es principalmente una comunicación unidireccional desde el gobierno hacia las personas usuarias (ciudadanos/as, funcionarios/as, otros).

Características principales:

Muestra información (comunicación de dentro hacia afuera):
- Páginas en estructura jerárquica
- Posts filtrables y ordenables por categorías/etiquetas
- Artículos, noticias, eventos
- Colecciones de items filtrables (fichas de lugares, objetos, etc.)
Buscador para encontrar contenido
URLs amigables para SEO e indexación en buscadores
Apenas recoge información de usuarios (quizás algún formulario sencillo)
Puede tener parte privada tipo intranet o CMS
Puede usar gestores CMS como Liferay, WordPress o sitios estáticos
Usa cabecera avanzada (header-advanced)

Librería recomendada: desy-html

Webapp (Aplicación Web)

Una webapp es un producto digital completo que muestra y recoge información de las personas usuarias.

Características principales:

Información compleja:
- Tablas, cards, elementos interactivos
- Datos sobre personas, documentos, items del dominio
Navegación no lineal: "estados" en lugar de "páginas"
URLs con routing para navegación, pero no siempre indexables
Múltiples formas de búsqueda: filtros en tablas, items, etc.
Acciones CRUD: Create, Read, Update, Delete
Gestión de usuarios y permisos
Autenticación centralizada (DIGA o MFE en Gobierno de Aragón)
APIs/endpoints para manipular contenido
Backend + Frontend separados
Frontend con frameworks: Angular, React, Vue, etc.
Usa cabecera estándar (header)

Librerías recomendadas:

desy-angular (Angular)
desy-ionic (apps móviles híbridas)
desy-react (React)
O construir a partir de desy-html con JavaScript personalizado

Tabla comparativa

Aspecto	Sitio web/Portal	Webapp
Objetivo principal	Informar, comunicar	Interactuar, gestionar datos
Cabecera	Cabecera avanzada (3 bandas)	Cabecera estándar (compacta)
Navegación	Jerárquica, lineal	Por estados, no lineal
Autenticación	Opcional (zona privada)	Obligatoria (gestión usuarios)
SEO	Crítico	Secundario
Librería DESY	desy-html	desy-angular, desy-ionic
Tecnologías	Vite, Tailwind CSS, Nunjucks	Angular 19, esbuild, TypeScript

2. Diseño en Figma

DESY proporciona una librería completa de componentes en Figma para diseñar mockups antes de desarrollar.

Librería principal de DESY

URL: DESY en Figma Community
Contenido: Estilos, componentes, plantillas para sitios web y webapps
Acceso: Cuenta gratuita de Figma

Librería desy-ionic para apps móviles

URL: desy-ionic en Figma
Uso: Diseños para apps iOS/Android con interacción táctil

Flujo de trabajo con Figma

Abrir la librería DESY en Figma
Duplicar la librería a tu cuenta
Crear una página nueva
Usar plantillas como base (móvil y escritorio)
Personalizar con componentes de la librería usando variantes
Aplicar estilos DESY (tipografía, colores, espaciado)
Diseñar Mobile First: comenzar en móvil, luego escritorio
Compartir mockups con el equipo para desarrollo

Más información: Guía para diseñadores

3. Instalación de un proyecto

Usando un asistente de programación con IA

La forma más rápida de comenzar con DESY es usar un asistente de IA configurado con el DESY MCP Server.

DESY MCP Server

URL del servidor: https://desy-mcp.replit.app/mcp
Instrucciones de instalación: https://desy-mcp.replit.app/
Documentación para IA: https://desy.aragon.es/llms.txt

Instalación del MCP Server

Seguir las instrucciones en https://desy-mcp.replit.app/
Configurar tu cliente (GitHub Copilot, Claude Desktop, etc.)
Una vez instalado, el asistente podrá:
- Buscar en la documentación de DESY
- Obtener código de componentes en HTML, Nunjucks o Angular
- Descargar proyectos starter automáticamente
- Generar código conforme a las buenas prácticas de DESY

Prompt ejemplo para IA con MCP Server

Crea un nuevo proyecto con desy-html-starter.
Busca en la documentación DESY usando el MCP server.
Descarga el repositorio desy-html-starter de Bitbucket.
Configura el proyecto para Node.js >= 20.19.2.
Instala las dependencias y muestra cómo ejecutar el servidor de desarrollo.

Instalación manual

Prerrequisitos

Para desy-html:

Node.js: >=20.19.2 <23.0.0
npm: >=10.0.0

Para desy-angular:

Node.js: ^22.0.0
npm: ^10.0.0

Gestión de versiones de Node con NVM

Se recomienda usar Node Version Manager (NVM) para gestionar diferentes versiones de Node.js:

En macOS/Linux:

# Instalar Homebrew (si no lo tienes)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instalar NVM con Homebrew
brew install nvm

# Configurar .zshrc o .bashrc
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"

# Instalar Node.js
nvm install 20.19.2
nvm use 20.19.2

# Verificar versión
node --version

En Windows:

# Descargar NVM para Windows
# URL: https://github.com/coreybutler/nvm-windows/releases

# Después de instalar:
nvm install 20.19.2
nvm use 20.19.2
node --version

Instalación de desy-html-starter

# Clonar el repositorio
git clone https://bitbucket.org/sdaragon/desy-html-starter.git mi-proyecto
cd mi-proyecto

# Instalar dependencias
npm install

# Iniciar servidor de desarrollo (Vite)
npm run dev

# Construir para producción
npm run build

# Previsualizar build de producción
npm run preview

Repositorio: https://bitbucket.org/sdaragon/desy-html-starter

Plantillas de ejemplo: Ver plantillas desy-html

Instalación de desy-angular-starter

# Clonar el repositorio
git clone https://bitbucket.org/sdaragon/desy-angular-starter.git mi-proyecto-angular
cd mi-proyecto-angular

# Renombrar todas las ocurrencias de 'desy-angular-starter' por tu nombre de proyecto
# Archivos a actualizar: angular.json, karma.conf.js, package.json, index.html

# Instalar dependencias
npm install

# En caso de warnings, usar:
npm install --legacy-peer-deps

# Iniciar servidor de desarrollo
npm run dev

# Construir para producción
npm run build-prod

# Ejecutar tests e2e (Playwright)
npm run playwright:install
npm run e2e

Repositorio: https://bitbucket.org/sdaragon/desy-angular-starter

Plantillas de ejemplo: Ver plantillas desy-angular

Demo de componentes: https://desy.aragon.es/desy-angular

Estructura de proyectos

desy-html-starter:

desy-html-starter/
├── public/
│   └── images/              # Imágenes del proyecto
├── src/
│   ├── css/
│   │   ├── styles.css       # Hoja de estilos principal
│   │   └── custom.css       # Estilos personalizados
│   ├── js/
│   │   └── index.js         # JavaScript (inicialización)
│   └── templates/
│       ├── pages/           # Páginas Nunjucks (.njk)
│       └── components/      # Componentes reutilizables
├── vite.config.js           # Configuración de Vite
└── package.json

desy-angular-starter:

desy-angular-starter/
├── src/
│   ├── app/
│   │   ├── core/            # Servicios core
│   │   ├── shared/          # Componentes compartidos
│   │   └── features/        # Módulos de características
│   ├── assets/              # Recursos estáticos
│   └── environments/        # Configuraciones de entorno
├── angular.json             # Configuración de Angular
├── tailwind.config.js       # Configuración de Tailwind CSS
└── package.json

4. Selección de librería

desy-html

Cuándo usar: Sitios web, portales, maquetas HTML, proyectos ligeros

Tecnologías:

Vite 7.1.6: Build tool rápido con HMR (Hot Module Replacement)
Tailwind CSS v4: Framework CSS utility-first
Nunjucks: Motor de plantillas para generar HTML
Sharp: Optimización de imágenes

Versión actual: 15.0.3

Package.json de desy-html-starter:

{
  "name": "desy-html-starter",
  "version": "11.0.3",
  "engines": {
    "node": ">=20.19.2 <23.0.0",
    "npm": ">=10.0.0"
  },
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "desy-html": "^15.0.3",
    "vite": "^7.1.6",
    "tailwindcss": "^4.1.17",
    "nunjucks": "^3.2.4"
  }
}

Características:

Componentes HTML+CSS+JS accesibles (WCAG 2.1 AA)
Patrones ARIA implementados
Playground en Tailwind Play: https://play.tailwindcss.com/xwNket4Bho

Más información: Documentación desy-html

desy-angular

Cuándo usar: Webapps complejas, aplicaciones con gestión de estado, proyectos empresariales

Tecnologías:

Angular 19: Framework frontend robusto
esbuild: Bundler ultrarrápido (integrado en Angular CLI)
TypeScript: Lenguaje tipado
RxJS: Programación reactiva

Versión actual: 17.2.0 (basada en desy-html 14.0.0)

Package.json de desy-angular-starter:

{
  "name": "desy-angular-starter",
  "version": "14.2.0",
  "scripts": {
    "dev": "ng serve",
    "build": "ng build",
    "build-prod": "ng build --configuration=production"
  },
  "dependencies": {
    "@angular/core": "^19.2.10",
    "desy-angular": "17.2.0",
    "desy-html": "14.0.0"
  }
}

Versiones disponibles:

Latest (v17.2.0): Angular 19, nuevas funcionalidades periódicas
LTS (v13.0.2): Angular 16, solo corrección de bugs críticos

Características:

Componentes Angular con inputs/outputs tipados
Integración completa con Angular Router
Gestión de notificaciones accesibles
Spinners con lectores de pantalla

Más información: Documentación desy-angular

desy-ionic

Cuándo usar: Apps móviles nativas (iOS/Android), apps híbridas, interfaz táctil

Tecnologías:

Ionic Framework: Componentes nativos multiplataforma
Angular: Como base del framework
Capacitor: Para compilar a iOS/Android

Características:

Componentes adaptados para interacción táctil
Patrones de navegación móvil
Gestos nativos
Publicable en App Store y Google Play

Recursos:

Repositorio: https://bitbucket.org/sdaragon/desy-ionic
Storybook: https://desy.aragon.es/desy-ionic
Figma: desy-ionic en Figma

Más información: Documentación desy-ionic

5. Elección de plantillas

DESY proporciona plantillas prediseñadas para las páginas más comunes. Las plantillas son el punto de partida para construir tu aplicación.

Plantillas para webapps

Sin sesión iniciada

Uso: Landing de aplicación, antes de autenticación
Cabecera: Estándar con logo extendido
Ejemplo: Ver plantilla

Con sesión iniciada

Uso: Después de autenticación
Cabecera: Estándar con logo reducido, menú usuario
Elementos: Zonas de notificaciones, spinners, navegación
Ejemplo: Ver plantilla

Edición de contenido

Uso: Formularios, CRUD
Elementos: Campos de entrada, validaciones, acciones
Ejemplo: Ver plantilla

Plantillas para portales

Portal web

Uso: Sitios de contenido público
Cabecera: Avanzada (3 bandas)
Elementos: Megamenú, buscador, navegación compleja
Ejemplo: Ver plantilla

Correo electrónico

Uso: Comunicaciones por email
Formato: HTML compatible con clientes de correo
Ejemplo: Ver plantilla

Catálogo completo: Ver todas las plantillas

Consideraciones técnicas en webapps

Notificaciones accesibles

Las plantillas tienen zonas de notificaciones predefinidas
Implementan atributos ARIA para lectores de pantalla
Tipos: éxito, error, advertencia, información
Ver: Componente notificaciones

Spinners de carga

Posición correcta según plantilla
Accesibles con aria-live y role="status"
Texto alternativo para lectores de pantalla
Ver: Componente spinner

Routing en SPAs (Angular)

Cambio de URL en barra de navegación
Scroll automático al inicio de página/sección
Gestión de breadcrumbs
Ejemplo en desy-angular-starter: revisar app-routing.module.ts

6. Uso de patrones

Los patrones son agrupaciones de componentes que resuelven necesidades comunes. Antes de crear algo desde cero, busca si existe un patrón.

Categorías de patrones

Cómo pedimos información

Cómo mostramos información

Ayudar a navegar y encontrar

Páginas y flujos completos

Catálogo completo: Ver todos los patrones

Cómo usar un patrón

Identifica tu necesidad (ej: "necesito pedir el nombre y NIF")
Busca en el catálogo de patrones
Abre el patrón correspondiente
Copia el código (HTML o Angular según tu librería)
Personaliza según tus necesidades

Ejemplo - Datos de identidad en HTML (Nunjucks):

{% from "components/input-text/_macro.input-text.njk" import componentInputText %}

<div class="grid lg:grid-cols-2 gap-base">
  <div>
    {{ componentInputText({
      "label": "Nombre y apellidos",
      "id": "nombre-completo",
      "name": "nombreCompleto",
      "required": true
    }) }}
  </div>
  <div>
    {{ componentInputText({
      "label": "NIF o NIE",
      "id": "nif-nie",
      "name": "nifNie",
      "required": true,
      "pattern": "[0-9]{8}[A-Za-z]|[XYZ][0-9]{7}[A-Za-z]"
    }) }}
  </div>
</div>

7. Composición con componentes

Si no existe un patrón para tu necesidad, construye usando componentes individuales.

Categorías de componentes

Componentes principales: Botones, Detalles, Modal
Formularios: Inputs, Textareas, Selects, Checkboxes, Radios, Datepicker, File upload
Navegación: Menús, Breadcrumbs, Paginación, Barra de búsqueda
Mostrar y ocultar: Acordeón, Tabs, Dropdown, Tooltip, Toggle
Datos: Tablas, Cards, Píldoras, Items, Listados
Avisos: Notificaciones, Modales, Resumen de errores
Información visual: Cabeceras, Footer, Iconos, Imágenes, Spinners

Catálogo completo: Ver todos los componentes

Cada componente incluye:

Descripción: Cuándo y cómo usarlo
Variantes: Diferentes estilos disponibles
Código HTML: Implementación con Nunjucks
Código Angular: Implementación con componentes Angular
Accesibilidad: Requisitos WCAG 2.1 AA
Ejemplos visuales: Screenshots en móvil y escritorio

Ejemplo - Botón primario

HTML (Nunjucks):

{% from "components/button/_macro.button.njk" import componentButton %}

{{ componentButton({
  "text": "Enviar formulario",
  "classes": "c-button c-button--primary",
  "type": "submit"
}) }}

Angular (TypeScript):

<desy-button
  [text]="'Enviar formulario'"
  [type]="'submit'"
  [variant]="'primary'">
</desy-button>

Resultado HTML:

<button type="submit" class="c-button c-button--primary">
  Enviar formulario
</button>

8. Flujo de trabajo completo

Para un sitio web/portal con desy-html

Diseño:
- Duplicar librería DESY en Figma
- Usar plantilla "Portal web"
- Diseñar páginas con componentes DESY
- Compartir mockups con equipo
Instalación:
- Instalar Node.js >=20.19.2 con NVM
- Clonar desy-html-starter
- Ejecutar npm install
- Ejecutar npm run dev
Desarrollo:
- Buscar plantilla "Portal web" en src/templates/pages/
- Usar patrones de portales
- Componer con componentes DESY
- Personalizar estilos en src/css/custom.css
Construcción:
- Ejecutar npm run build
- Archivos en /dist listos para producción
- Integrar en CMS (Liferay, WordPress, etc.)

Para una webapp con desy-angular

Diseño:
- Duplicar librería DESY en Figma
- Usar plantillas "Sin sesión" y "Con sesión iniciada"
- Diseñar flujos de usuario
- Compartir mockups
Instalación:
- Instalar Node.js ^22.0.0 con NVM
- Clonar desy-angular-starter
- Renombrar proyecto en archivos de configuración
- Ejecutar npm install
- Ejecutar npm run dev
Desarrollo:
- Usar plantillas en src/app/
- Implementar routing en app-routing.module.ts
- Usar patrones de aplicaciones
- Importar componentes de desy-angular
- Gestionar notificaciones y spinners
Construcción:
- Ejecutar npm run build-prod
- Archivos en /dist con esbuild optimizado
- Desplegar en servidor (Azure, AWS, etc.)

Para una app móvil con desy-ionic

Diseño:
- Duplicar librerías DESY y desy-ionic en Figma
- Seguir guías de diseño táctil
- Diseñar para iOS y Android
Instalación:
- Clonar desy-ionic
- Instalar Ionic CLI
- Ejecutar npm install
- Ejecutar ionic serve
Desarrollo:
- Usar componentes Ionic adaptados
- Implementar gestos nativos
- Probar en emuladores iOS/Android
Compilación nativa:
- Configurar Capacitor
- Compilar para iOS/Android
- Publicar en stores

9. Lógica de selección inteligente para asistentes de IA

Esta sección documenta los árboles de decisión para que asistentes de IA puedan seleccionar automáticamente el tipo de proyecto, plantilla o patrón adecuado según las necesidades del usuario.

9.1 Árbol de decisión para selección de proyecto

Pregunta inicial: "¿Qué vas a construir?"

Respuesta	Librería	Starter	Node.js	Cuándo usarlo
Sitio web/Portal público	desy-html	desy-html-starter	>=20.19.2 <23.0.0	Comunicación unidireccional, SEO crítico, cabecera avanzada
Webapp con autenticación	desy-angular	desy-angular-starter	^22.0.0	CRUD, gestión de usuarios, routing, estados no lineales
App móvil híbrida	desy-ionic	desy-ionic	^18.0.0	iOS/Android, gestos táctiles, stores

Criterios clave:

¿Comunicación unidireccional? → desy-html (portal)
¿Gestión de datos CRUD? → desy-angular (webapp)
¿App móvil nativa? → desy-ionic
¿SEO crítico? → desy-html
¿Auth centralizada obligatoria? → desy-angular

9.2 Árbol de decisión para selección de plantilla

Pregunta 1: "¿Cuál es el contexto de esta página?"

Contexto	Auth requerida	Acción principal	Plantilla	Archivo Nunjucks
Portal institucional	No (público)	Ver información	Portal web	_template.with-header-advanced.njk
Portal institucional	Sí (zona privada)	Ver información	Portal privado	_template.with-header-advanced.njk
Aplicación web	No	Landing page	Sin sesión iniciada	_template.logged-out.njk
Aplicación web	Sí	Ver información	Con sesión iniciada - Base	_template.logged-in.njk
Aplicación web	Sí	Ver información	Con sesión iniciada - Selector app	_template.logged-selector.njk
Aplicación web	Sí	Ver información	Con sesión iniciada - Menú lateral	_template.logged-selector-sidebar.njk
Aplicación web	Sí	Ver información	Con sesión iniciada - Cabecera fija	_template.logged-in-fixed.njk
Aplicación web	Sí	Ver información	Con sesión iniciada - Subcabecera	_template.logged-in-subheader.njk
Aplicación web	Sí	Editar/Crear	Edición - Base	_template.edition.njk
Aplicación web	Sí	Editar/Crear	Edición - Cabecera fija	_template.edition-fixed.njk
Aplicación web	Sí	Editar/Crear	Edición - Sidebar	_template.edition-sidebar.njk
Correo electrónico	No	Comunicar	Email	_template.email.njk

Sub-preguntas para refine:

¿Necesitas cambiar entre aplicaciones? → Incluir selector de apps en cabecera
¿Necesitas navegación lateral (índice)? → Usar variante con sidebar (25% ancho)
¿Cabecera fija al hacer scroll? → Usar variante fixed o headroom
¿Navegación lateral mientras editas? → Edición sidebar sticky

9.3 Árbol de decisión para selección de patrones

Pregunta inicial: "¿Qué necesitas hacer?"

9.3.1 Pedir información (formularios)

Sub-pregunta: "¿Qué datos necesitas?"

Datos	Patrón	Componentes clave
Nombre + NIF/NIE	datos-identidad	2x Input text, Fieldset
Email + Teléfono	datos-contacto	2x Input text
Calle + Provincia + Municipio	domicilio-postal	3x Input, 1x Select
Consentimiento legal	aceptar-politicas	Checkbox, Modal
Preferencias cookies	configurar-cookies	Toggle, Switch

9.3.2 Mostrar información

Sub-pregunta: "¿Cómo quieres mostrarlo?"

Formato	Patrón	Componentes clave
Tabla con acciones	acciones-tabla	Tabla, Botones
Lista de items	listados	Cards, Items
Solo botones	grupo-acciones	Lista botones
Title navegador	title-pagina	Meta tags
Encabezados	titulos-encabezados	Tipografía H1-H6

9.3.3 Navegar y encontrar

Sub-pregunta: "¿Qué navegación necesitas?"

Necesidad	Patrón	Componentes clave
Entre pasos de formulario	avanzar-retroceder + barra-progreso	2-3 Botones, Progress bar
Búsqueda	buscar	Input + Botón buscar
Filtrado	filtrar	Selects, Checkboxes
Navegación portal	megamenu	Menú horizontal
Volver atrás	volver-atras	Link + Icono

9.3.4 Resolver dudas (ayuda)

Sub-pregunta: "¿Qué ayuda necesitas?"

Necesidad	Patrón	Componentes clave
FAQ	preguntas-frecuentes	Acordeón
Ayuda in-context	asistencia-contextual	Tooltip, Glosario
Contacto	soporte	Links, Teléfonos

9.3.5 Flujos completos

Sub-pregunta: "¿Qué flujo necesitas?"

Flujo	Patrón	Plantilla base
Autenticación Cl@ve	acceso-mfe	Sin sesión + Spinner
Form multietapa	formulario-pasos	Edición + Progreso
Dashboard app	pagina-aplicaciones	Con sesión iniciada
Portal público	pagina-portales	Portal web

9.4 Reglas de composición automática

Los patrones pueden combinarse entre sí según las necesidades del usuario:

Patrón principal	Se combina con	Resultado
datos-identidad	avanzar-retroceder, barra-progreso	Paso 1 de formulario multietapa
datos-contacto	avanzar-retroceder, barra-progreso	Paso 2 de formulario multietapa
domicilio-postal	avanzar-retroceder, barra-progreso	Paso 3 de formulario multietapa
formulario-pasos	datos-identidad, datos-contacto, domicilio-postal	Formulario 3 pasos completo
acceso-mfe	spinner, selector-organismo	Flujo auth completo
buscar	input-text, button	Barra búsqueda completa
filtrar	select, checkbox, table	Filtros con resultados
pagina-aplicaciones	cards, tabla, acciones-tabla	Dashboard con acciones
pagina-portales	megamenu, buscar, pagination	Portal completo

9.5 Flujo completo: Autenticación + Formulario por pasos

Este es el patrón más común para aplicaciones del Gobierno de Aragón:

Paso 1: Acceso (MFE)

Pantalla: Selector método auth (Clave, Certificado, Cl@ve)
Spinner de carga durante autenticación
Selector de organismo (si tiene múltiples)
Template: _template.logged-out.njk + Spinner

Paso 2-4: Formulario por pasos (3 pasos)

Barra de progreso: [Paso 1 de 3]
Paso 1: Datos identidad (nombre + NIF/NIE)
Paso 2: Datos contacto (email + teléfono)
Paso 3: Domicilio postal (calle + municipio)
Botones: Volver, Siguiente, Saltar (opcional), Enviar
Template: _template.edition.njk + barra-progreso

Patrones necesarios:

acceso-mfe
barra-progreso
avanzar-retroceder
datos-identidad
datos-contacto
domicilio-postal

9. La skill DESY para asistentes de IA

La skill DESY es una configuración especial para asistentes de programación con IA (como Claude Code, GitHub Copilot, etc.) que permite crear proyectos, páginas y componentes siguiendo la metodología DESY del Gobierno de Aragón de forma automática.

¿Qué es una skill?

Una skill es un conjunto de instrucciones y contexto que se proporciona a un asistente de IA para que entienda cómo realizar tareas específicas siguiendo unas determinadas directrices. La skill DESY incluye:

Reglas para seleccionar el starter correcto (desy-html, desy-angular, desy-ionic)
Lógica para elegir plantillas según el contexto
Catálogo de patrones y cómo combinarlos
Acceso al MCP Server para obtener código de componentes
Normativa de accesibilidad WCAG 2.2 AA

¿Cómo usarla?

Opción 1: Con Claude Code (recomendado)

La skill ya está configurada en .claude/skills/desy-create/SKILL.md. Solo tienes que invocar la skill con el comando:

/desy-create

Y describir lo que necesitas crear. El asistente seguirá la metodología DESY automáticamente.

Opción 2: Con otros asistentes

Puedes copiar el contenido de la skill en las instrucciones del asistente o usar el archivo directamente:

Archivo de la skill: desy-create-skill.md
Documentación técnica para IA: llms.txt

Flujo de trabajo con la skill

Describe tu proyecto: "Quiero crear una aplicación web para gestionar solicitudes"
La skill te hará preguntas para clarificar:
- ¿Es un portal o una webapp?
- ¿Necesita autenticación?
- ¿Qué tipo de información necesitas mostrar/recoger?
Según tus respuestas, la skill selecciona:
- El starter adecuado
- La plantilla base
- Los patrones necesarios
- Los componentes específicos
Genera código conforme a las buenas prácticas DESY

Categorías de la skill

Selección de proyecto: Elige entre desy-html, desy-angular o desy-ionic
Selección de plantilla: 11 variantes según el contexto (con/sin sesión, portal, email...)
Selección de patrones: 21 patrones organizados en 5 categorías
Composición automática: Reglas para combinar patrones
Flujos completos: Auth + Formulario por pasos, Portales, etc.

Archivo de referencia: Ver skill completa (desy-create-skill.md)

9.6 Resumen para LLMs

Categoría	Items	Para qué sirve
Proyectos	3 starters	desy-html, desy-angular, desy-ionic
Plantillas	11 variantes	5 bases × variantes según contexto
Patrones	21 patrones	5 categorías según necesidad
Componentes	~50+	Accesibles vía MCP Server
Flujos comunes	3 principales	Auth → Form → Dashboard

9.7 Uso del MCP Server para obtener código

Para obtener código de componentes, plantillas o patrones mediante el DESY MCP Server:

// Obtener código de plantillas
await mcp.get_component_code_nunjucks('template-logged-in');
await mcp.get_component_code_html('template-edition');

// Obtener código de patrones
await mcp.get_component_code_html('patrones-datos-identidad');
await mcp.get_component_code_nunjucks('patrones-avanzar-retroceder');

// Obtener componentes individuales
await mcp.get_component_code_html('input-text');
await mcp.get_component_code_html('button');
await mcp.get_component_props('formularios');

// Listar categorías disponibles
await mcp.list_categories();

// Buscar componentes
await mcp.search_components('buscar filtro');
await mcp.search_components('tabla datos');

9.8 Prompt ejemplo para IA con la lógica integrada

Crea una página para una aplicación web del Gobierno de Aragón.

Contexto:
- Tipo: Webapp con autenticación
- Usuario: Ya logueado (sesión iniciada)
- Acción: Ver información en formato tabla con acciones
- Necesita: Filtrado por columnas y paginación

Usa la lógica de selección de DESY:
1. Proyecto: desy-angular-starter (webapp con auth)
2. Plantilla: "Con sesión iniciada - Base" (_template.logged-in.njk)
3. Patrón: "acciones-tabla" para mostrar datos con acciones
4. Patrón: "filtrar" para opciones de filtrado
5. Componentes: table, pagination, button, input-text

Genera el código Nunjucks para la página.

10. Desarrollo con desy-html-starter

Esta sección indica cómo desarrollar proyectos de maquetación, prototipos MVP o proyectos completos usando desy-html-starter. Este starter es ideal para validar ideas, crear maquetas funcionales y, posteriormente, evolucionar hacia desy-angular si se necesita funcionalidad JavaScript avanzada (llamadas a APIs, gestión de estado, etc.).

10.1 Cuándo usar desy-html-starter

Caso de uso	Descripción
Maquetación	Crear prototipos visuales rápidos de páginas, portales o aplicaciones
MVP funcional	Validar conceptos con stakeholders antes de desarrollar en Angular
Sitio web estático	Proyectos que no requieren backend complejo ni autenticación
Base para migración	Maqueta que luego se puede convertir a proyecto desy-angular

10.2 Flujo de trabajo recomendado

Paso 1: Diseño conceptual previo

Antes de programar, diseña a nivel conceptual lo que vas a construir
Identifica las secciones principales de cada página
Decide qué información va en cada zona

Paso 2: Maquetación en Nunjucks

Usa Nunjucks como lenguaje de plantillas base
Aprovecha la estructura de includes y layouts de DESY

Paso 3: Reutilización de código DESY

Busca en la documentación de DESY antes de escribir código nuevo
Usa el MCP Server o llms.txt para encontrar plantillas, patrones y componentes
Prioriza código existente que se ajuste a tus necesidades

Paso 4: Construcción progresiva

Crea las páginas una a una
Duplica plantillas existentes y personaliza sobre ellas
Evita escribir HTML desde cero cuando hay alternativas en DESY

10.3 Proceso de creación de páginas

Caso A: Tienes una imagen de referencia

1. Analiza la imagen

Identifica las secciones principales de cada página
Localiza: cabecera (header), pie (footer) y zona de contenido

2. Identifica el tipo de cabecera

Cabecera avanzada (header-advanced): para portales públicos con megamenú
Cabecera estándar (header): para aplicaciones web
Otro tipo: consulta la documentación de Cabeceras o usa el MCP Server

3. Identifica el tipo de pie

Consulta qué tipo de pies existen en DESY
Verifica si incluye logotipos institucionales
Usa el MCP Server para encontrar el ejemplo más parecido

4. Analiza la retícula y columnas

DESY recomienda no usar ancho completo para textos/formularios
Usa grid con columnas (típicamente 70% contenido + 30% sidebar o variantes)
Consulta la sección Retícula para detalles de breakpoints

5. Identifica la plantilla usada

Con la información anterior, determina qué plantilla de DESY se parece más
Usa el MCP Server para buscar ejemplos de esa plantilla

Caso B: No tienes imagen de referencia

1. Lista los elementos necesarios

Haz una lista de todos los elementos que necesita la página
Incluye: cabecera, pie, zonas de contenido, navegación, formularios, etc.

2. Selecciona componentes DESY

Compara tu lista con las plantillas, patrones y componentes disponibles
Elige los que mejor encajen con tus necesidades

3. Busca código por elemento

Usa el MCP Server o llms.txt para cada elemento
Usa el mapeo ES ↔ EN de componentes para buscar correctamente
Copia código de ejemplo y personalízalo

10.4 Búsqueda y reutilización de código

Fuentes de código DESY:

MCP Server: get_component_code_nunjucks(), search_components(), list_categories()
llms.txt: documentación en markdown de todas las páginas
Web DESY: https://desy.aragon.es

Prioridad al reutilizar código:

Busca plantillas base que se parezcan
Busca patrones que resuelvan tu necesidad
Busca componentes individuales
Solo entonces, escribe HTML propio siguiendo estilos DESY

Flujo de búsqueda típico:

// 1. Listar categorías disponibles
await mcp.list_categories();

// 2. Buscar por palabra clave
await mcp.search_components('cabecera header avanzado');

// 3. Obtener código Nunjucks del componente
await mcp.get_component_code_nunjucks('Cabecera avanzada');

11. Mapeo de nombres de componentes: Español ↔ Inglés

Esta sección muestra la correspondencia entre los nombres de componentes en español (usados en la documentación y MCP Server) y sus nombres técnicos en inglés. Úsala para buscar componentes cuando trabajes con el MCP Server o consultes código en inglés.

11.1 Componentes principales

Español	Inglés	Notas
Botones	Button, Button loader	Button loader incluye indicador de carga
Detalles	Details	Elemento desplegable simple
Modal	Modal, Dialog	Dialog es el componente base

11.2 Formularios

Español	Inglés	Notas
Árbol	Tree	Estructura jerárquica navegable
Área de texto	Textarea, Character count	Character count es el contador de caracteres
Bloques de datos	Date input	Input para fechas con calendario
Botón de radio	Radios	Selección única
Calendario	Datepicker	Selector de fechas completo
Carga de archivos	File upload	Input para subir archivos
Casilla de verificación	Checkboxes	Selección múltiple
Entrada de texto	Input, Fieldset, Input group, Label	Fieldset agrupa campos; Input group agrupa inputs relacionados
Selector	Select, Listbox	Dropdown de selección

11.3 Navegación

Español	Inglés	Notas
Barra de búsqueda	Searchbar	Campo de búsqueda con botón
Listado de enlaces	Links list	Lista de enlaces relacionados
Menú de navegación	Menu navigation	Navegación principal del sitio
Menú horizontal	Menu horizontal	Menú en fila
Menú vertical	Menu vertical	Menú en columna
Migas de pan	Breadcrumbs	Ruta de navegación
Paginación	Pagination	Navegación entre páginas

11.4 Mostrar y ocultar

Español	Inglés	Notas
Acordeón	Accordion	Secciones plegables
Acordeón histórico	Accordion history	Versión con histórico de cambios
Desplegable	Dropdown	Menú contextual
Pestañas	Tabs	Navegación por pestañas
Interruptor	Toggle	Interruptor binario on/off
Globo de ayuda	Tooltip, Hint	Hint es la pista visual; Tooltip es el globo informativo

11.5 Datos

Español	Inglés	Notas
Tabla	Table, Table advanced, Treegrid	Table advanced incluye funcionalidades adicionales
Card	Card	Tarjeta de contenido
Item	Item	Elemento de lista
Píldoras	Pill	Etiquetas/etiquetas de estado
Item de estado	Status, Status item	Indicador visual de estado

11.6 Avisos

Español	Inglés	Notas
Notificaciones	Notification, Alert	Mensajes informativos
Modal	Modal, Dialog	Ventana emergente
Resumen de errores	Error summary, Error message	Error summary lista errores; Error message muestra uno

11.7 Información visual

Español	Inglés	Notas
Cabeceras	Header, Header mini, Header advanced, Skip link	Distintos tipos de cabecera
Iconos	(sin equivalente directo)	Usa los iconos SVG de DESY
Imágenes	Media object	Imagen con texto adyacente
Spinner	Spinner, Status	Status es un indicador estático
Pie de página	Footer	Footer del sitio
Contraible	Collapsible	Elemento contraible
Barra de menús	Menubar	Menú de navegación tipo aplicación
Navegación vertical	Nav	Navegación lateral

Cómo empezar Índice de páginas

Tutorial

Tabla de contenidos

1. Preguntas iniciales: ¿Qué voy a construir?

¿Sitio web/Portal o Webapp?

Sitio web o Portal

Webapp (Aplicación Web)

Tabla comparativa

2. Diseño en Figma

Librería principal de DESY

Librería desy-ionic para apps móviles

Flujo de trabajo con Figma

3. Instalación de un proyecto

Usando un asistente de programación con IA

DESY MCP Server

Instalación del MCP Server

Prompt ejemplo para IA con MCP Server

Instalación manual

Prerrequisitos

Gestión de versiones de Node con NVM

Instalación de desy-html-starter

Instalación de desy-angular-starter

Estructura de proyectos

4. Selección de librería

desy-html

desy-angular

desy-ionic

5. Elección de plantillas

Plantillas para webapps

Sin sesión iniciada

Con sesión iniciada

Edición de contenido

Plantillas para portales

Portal web

Correo electrónico

Consideraciones técnicas en webapps

Notificaciones accesibles

Spinners de carga

Routing en SPAs (Angular)

6. Uso de patrones

Categorías de patrones

Cómo pedimos información

Cómo mostramos información

Ayudar a navegar y encontrar

Páginas y flujos completos

Cómo usar un patrón

7. Composición con componentes

Categorías de componentes

Cada componente incluye:

Ejemplo - Botón primario

8. Flujo de trabajo completo

Para un sitio web/portal con desy-html

Para una webapp con desy-angular

Para una app móvil con desy-ionic

9. Lógica de selección inteligente para asistentes de IA

9.1 Árbol de decisión para selección de proyecto

9.2 Árbol de decisión para selección de plantilla

9.3 Árbol de decisión para selección de patrones

9.3.1 Pedir información (formularios)

9.3.2 Mostrar información

9.3.3 Navegar y encontrar

9.3.4 Resolver dudas (ayuda)

9.3.5 Flujos completos

9.4 Reglas de composición automática

9.5 Flujo completo: Autenticación + Formulario por pasos

Paso 1: Acceso (MFE)

Paso 2-4: Formulario por pasos (3 pasos)

Patrones necesarios:

9. La skill DESY para asistentes de IA

¿Qué es una skill?

¿Cómo usarla?

Flujo de trabajo con la skill

Categorías de la skill

9.6 Resumen para LLMs

9.7 Uso del MCP Server para obtener código

9.8 Prompt ejemplo para IA con la lógica integrada

10. Desarrollo con desy-html-starter

10.1 Cuándo usar desy-html-starter

10.2 Flujo de trabajo recomendado

Paso 1: Diseño conceptual previo