# Cómo empezar - Tutorial. DESY. Sistema de diseño del Gobierno de Aragón.

## Cómo empezar Índice de páginas

Cómo empezar

# 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](como-empezar-tutorial.html.md).

## 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](desarrollo-desy-html.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](desarrollo-desy-angular.html) (Angular)
-   [desy-ionic](desarrollo-desy-ionic.html) (apps móviles híbridas)
-   desy-react (React)
-   O construir a partir de [desy-html](desarrollo-desy-html.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](https://www.figma.com/community/file/1167029569064210460)
-   **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](https://www.figma.com/community/file/1383376074462615538/desy-ionic)
-   **Uso:** Diseños para apps iOS/Android con interacción táctil

### Flujo de trabajo con Figma

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

**Más información:** [Guía para diseñadores](como-empezar-disenador.html)

* * *

## 3\. Instalación de un proyecto

### Instalación manual

#### Prerrequisitos

Consulta los requisitos exactos en el archivo `package.json` de cada starter:

-   **Para desy-html:** Consulta `package.json` en [desy-html-starter](https://bitbucket.org/sdaragon/desy-html-starter)
-   **Para desy-angular:** Consulta `package.json` en [desy-angular-starter](https://bitbucket.org/sdaragon/desy-angular-starter)

#### 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:**

```bash
# 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 (versión del proyecto)
nvm install
nvm use

# Verificar versión
node --version
```

**En Windows:**

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

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

#### Instalación de desy-html-starter

```bash
# 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](https://bitbucket.org/sdaragon/desy-html-starter)

**Plantillas de ejemplo:** [Ver plantillas desy-html](https://desy.aragon.es/pages/desy-html-starter/)

#### Instalación de desy-angular-starter

```bash
# 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](https://bitbucket.org/sdaragon/desy-angular-starter)

**Plantillas de ejemplo:** [Ver plantillas desy-angular](https://desy.aragon.es/pages/desy-angular-starter/)

**Demo de componentes:** [https://desy.aragon.es/desy-angular](https://desy.aragon.es/desy-angular)

#### Estructura de proyectos

**desy-html-starter:**

```text
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:**

```text
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:** Build tool rápido con HMR (Hot Module Replacement)
-   **Tailwind CSS:** Framework CSS utility-first
-   **Nunjucks:** Motor de plantillas para generar HTML
-   **Sharp:** Optimización de imágenes

La versión actual está definida en el archivo `package.json` del starter.

**Características:**

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

**Más información:** [Documentación desy-html](desarrollo-desy-html.html)

### desy-angular

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

**Tecnologías:**

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

La versión actual está definida en el archivo `package.json` del starter.

**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](desarrollo-desy-angular.html)

### 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](https://bitbucket.org/sdaragon/desy-ionic)
-   **Storybook:** [https://desy.aragon.es/desy-ionic](https://desy.aragon.es/desy-ionic)
-   **Figma:** [desy-ionic en Figma](https://www.figma.com/community/file/1383376074462615538/desy-ionic)

**Más información:** [Documentación desy-ionic](desarrollo-desy-ionic.html)

* * *

## 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](plantillas-sin-sesion-iniciada-p1.html)

#### 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](plantillas-con-sesion-iniciada.html)

#### Edición de contenido

-   **Uso:** Formularios, CRUD
-   **Elementos:** Campos de entrada, validaciones, acciones
-   **Ejemplo:** [Ver plantilla](plantillas-edicion.html)

### Plantillas para portales

#### Portal web

-   **Uso:** Sitios de contenido público
-   **Cabecera:** Avanzada (3 bandas)
-   **Elementos:** Megamenú, buscador, navegación compleja
-   **Ejemplo:** [Ver plantilla](plantillas-portal-p1.html)

#### Correo electrónico

-   **Uso:** Comunicaciones por email
-   **Formato:** HTML compatible con clientes de correo
-   **Ejemplo:** [Ver plantilla](plantillas-correo-p1.html)

**Catálogo completo:** [Ver todas las plantillas](plantillas.html)

### 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](componente-notificaciones.html)

#### 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](componente-spinner-codigo.html)

#### 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

-   [Aceptar políticas de privacidad](patrones-aceptar-politicas.html)
-   [Configurar cookies](patrones-configurar-cookies.html)
-   [Datos de identidad](patrones-datos-identidad.html) (Nombre, NIF/NIE)
-   [Datos de contacto](patrones-datos-contacto.html) (Email, teléfono)
-   [Domicilio postal](patrones-domicilio-postal.html)

#### Cómo mostramos información

-   [Acciones de tabla](patrones-acciones-tabla.html)
-   [Grupo de acciones](patrones-grupo-acciones.html)
-   [Listados](patrones-listados.html)
-   [Title de página](patrones-title.html)
-   [Títulos y encabezados](patrones-titulos-encabezados.html)

#### Ayudar a navegar y encontrar

-   [Avanzar y retroceder](patrones-avanzar-retroceder.html)
-   [Barra de progreso](patrones-barra-progreso.html)
-   [Buscar](patrones-buscar.html)
-   [Filtrar](patrones-filtrar.html)
-   [Megamenú en portales](patrones-megamenu.html)
-   [Volver atrás](patrones-volver-atras.html)

#### Páginas y flujos completos

-   [Acceso por MFE](patrones-pagina-acceso.html)
-   [Formulario por pasos](patrones-pagina-formulario.html)
-   [Páginas de aplicaciones](patrones-pagina-aplicaciones.html)
-   [Páginas de portales](patrones-pagina-portales.html)

**Catálogo completo:** [Ver todos los patrones](patrones.html)

### Cómo usar un patrón

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

**Ejemplo - Datos de identidad en HTML (Nunjucks):**

```html
{% 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](componente-principales.html): Botones, Detalles, Modal
-   [Formularios](componente-formularios.html): Inputs, Textareas, Selects, Checkboxes, Radios, Datepicker, File upload
-   [Navegación](componente-navegacion.html): Menús, Breadcrumbs, Paginación, Barra de búsqueda
-   [Mostrar y ocultar](componente-mostrar-ocultar.html): Acordeón, Tabs, Dropdown, Tooltip, Toggle
-   [Datos](componente-datos.html): Tablas, Cards, Píldoras, Items, Listados
-   [Avisos](componente-avisos.html): Notificaciones, Modales, Resumen de errores
-   [Información visual](componente-info-visual.html): Cabeceras, Footer, Iconos, Imágenes, Spinners

**Catálogo completo:** [Ver todos los componentes](componentes.html)

### 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):**

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

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

**Angular (TypeScript):**

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

**Resultado HTML:**

```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

1.  **Diseño:**
    -   Duplicar librería DESY en Figma
    -   Usar plantilla "Portal web"
    -   Diseñar páginas con componentes DESY
    -   Compartir mockups con equipo
2.  **Instalación:**
    -   Instalar Node.js (consultar package.json)
    -   Clonar desy-html-starter
    -   Ejecutar `npm install`
    -   Ejecutar `npm run dev`
3.  **Desarrollo:**
    -   Buscar plantilla "Portal web" en `src/templates/pages/`
    -   Usar patrones de portales
    -   Componer con componentes DESY
    -   Personalizar estilos en `src/css/custom.css`
4.  **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

1.  **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
2.  **Instalación:**
    -   Instalar Node.js (consultar package.json)
    -   Clonar desy-angular-starter
    -   Renombrar proyecto en archivos de configuración
    -   Ejecutar `npm install`
    -   Ejecutar `npm run dev`
3.  **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
4.  **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

1.  **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
2.  **Instalación:**
    -   Clonar desy-ionic
    -   Instalar Ionic CLI
    -   Ejecutar `npm install`
    -   Ejecutar `ionic serve`
3.  **Desarrollo:**
    -   Usar componentes Ionic adaptados
    -   Implementar gestos nativos
    -   Probar en emuladores iOS/Android
4.  **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

consultar package.json

Comunicación unidireccional, SEO crítico, cabecera avanzada

Webapp con autenticación

desy-angular

desy-angular-starter

consultar package.json

CRUD, gestión de usuarios, routing, estados no lineales

App móvil híbrida

desy-ionic

desy-ionic

consultar package.json

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 **OpenCode** (recomendado), 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
-   Normativa de accesibilidad WCAG 2.2 AA

#### ¿Cómo usarla?

**Opción 1: Con OpenCode (recomendado)**

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

```text
/desy-create
```

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

**Opción 2: Con otros asistentes** (Claude Code, GitHub Copilot, etc.)

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](desy-create-skill.md)
-   Documentación técnica para IA: [llms.txt](llms.txt)

#### Flujo de trabajo con la skill

1.  Describe tu proyecto: "Quiero crear una aplicación web para gestionar solicitudes"
2.  La skill te hará preguntas para clarificar:
    -   ¿Es un portal o una webapp?
    -   ¿Necesita autenticación?
    -   ¿Qué tipo de información necesitas mostrar/recoger?
3.  Según tus respuestas, la skill selecciona:
    -   El starter adecuado
    -   La plantilla base
    -   Los patrones necesarios
    -   Los componentes específicos
4.  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)](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+

Ver documentación

Flujos comunes

3 principales

Auth → Form → Dashboard

### 9.7 Prompt ejemplo para IA con la lógica integrada

```text
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 `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](componente-cabeceras.html)

##### 3\. Identifica el tipo de pie

-   Consulta qué tipo de pies existen en DESY
-   Verifica si incluye logotipos institucionales

##### 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](#reticula) para detalles de breakpoints

##### 5\. Identifica la plantilla usada

-   Con la información anterior, determina qué plantilla de DESY se parece más

#### 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 `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:

-   **llms.txt**: documentación en markdown de todas las páginas
-   **Web DESY**: [https://desy.aragon.es](https://desy.aragon.es)

#### Prioridad al reutilizar código:

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

* * *

## 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 sus nombres técnicos en inglés. Úsala para buscar componentes cuando 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

* * *

## 12\. Personalización de marca (Branding)

DESY incluye un sistema de personalización de marca que permite adaptar el design system a diferentes organizaciones. Por defecto, los valores están configurados para el Gobierno de Aragón, pero puedes personalizarlos para tu entidad.

### 12.1 ¿Qué es el branding en DESY?

El sistema de branding de desy-html permite personalizar:

-   Nombre y datos de contacto de la organización
-   Logos institucionales (versiones compact, mini, expanded)
-   Logos de fondos europeos
-   Tipografía del sitio
-   Contenido del pie de página
-   Imágenes de fondo de cabecera
-   Favicon

### 12.2 Configuración básica

La configuración de branding se encuentra en el directorio `branding/` del proyecto:

-   **Por defecto:** `branding/branding.config.js` (Gobierno de Aragón)
-   **Personalizado:** `branding/branding.config.{tu-organizacion}.js`

Para activar una configuración personalizada, usa la variable de entorno `BRANDING_CONFIG`:

```bash
# Activar configuración personalizada
  BRANDING_CONFIG=tu-organizacion npm run dev

  # En Windows (PowerShell)
  $env:BRANDING_CONFIG="tu-organizacion"; npm run dev
```

### 12.3 Elementos personalizables

Categoría

Propiedades

Descripción

**Organización**

name, website, contact

Nombre, web, dirección, teléfono

**Logos**

organization, eu

compact, mini, expanded + logos UE

**Tipografía**

fontFamily, fontUrl

Fuentes Google Fonts o autoalojadas

**Footer**

license, euFundsUrl

Licencia CC BY 4.0, URL fondos europeos

**Imágenes**

headerBackground, headerBackgroundLg

Fondos de cabecera (móvil y escritorio)

**Favicon**

svg, ico, appleTouch

Iconos para el navegador

### 12.4 Ejemplo: Crear una configuración personalizada

Copia el archivo de ejemplo `branding/branding.config.yourorganization.js` y personalízalo:

```javascript
export default {
  organization: {
    name: 'Tu Organización',
    website: 'https://www.tuorganizacion.es/',
    contact: {
      address: 'Calle Principal, 1',
      city: '28001 - Madrid',
      phone: '900 123 456',
      phoneLink: '+34900123456',
    },
  },
  logos: {
    organization: {
      compact: '/branding/logos/tu-logo-compact.svg',
      mini: '/branding/logos/tu-logo-mini.svg',
      expanded: '/branding/logos/tu-logo-expanded.svg',
      alt: 'Tu Organización',
    },
  },
  typography: {
    fontFamily: {
      sans: '"Tu Fuente", ui-sans-serif, system-ui, sans-serif',
      heading: '"Tu Fuente", ui-sans-serif, system-ui, sans-serif',
    },
    fontUrl: 'https://fonts.googleapis.com/css2?family=Tu+Fuente:wght@400;600;700&display=swap',
  },
  // ... resto de configuración
};
```

**Más información:** Consulta el archivo `branding/branding.config.js` en `node_modules/desy-html/branding/` para ver todos los valores disponibles.

* * *

## Recursos adicionales

### Documentación principal

-   [DESY - Inicio](index.html)
-   [Catálogo de componentes](componentes.html)
-   [Catálogo de patrones](patrones.html)
-   [Plantillas web](plantillas.html)
-   [Guía de estilos](estilos.html)
-   [Accesibilidad WCAG 2.1 AA](como-empezar-accesibilidad.html)

### Librerías

-   [desy-html](desarrollo-desy-html.html) - Documentación completa
-   [desy-angular](desarrollo-desy-angular.html) - Documentación completa
-   [desy-ionic](desarrollo-desy-ionic.html) - Documentación completa
-   [Tabla de versiones](desarrollo-versiones.html)

### Herramientas

-   [llms.txt](https://desy.aragon.es/llms.txt) - Documentación para LLMs
-   [Playground Tailwind](https://play.tailwindcss.com/xwNket4Bho) - Pruebas rápidas

### Repositorios

-   [desy-html-starter](https://bitbucket.org/sdaragon/desy-html-starter)
-   [desy-angular-starter](https://bitbucket.org/sdaragon/desy-angular-starter)
-   [desy-ionic](https://bitbucket.org/sdaragon/desy-ionic)

### Figma

-   [DESY en Figma Community](https://www.figma.com/community/file/1167029569064210460)
-   [desy-ionic en Figma](https://www.figma.com/community/file/1383376074462615538/desy-ionic)

### Soporte

-   [Cómo obtener ayuda](acerca-de-soporte.html)
-   [Novedades y actualizaciones](acerca-de-novedades.html)