24. Interfaz de usuario: Material, CDK, estilos y animaciones

24.1 Qué vas a poder hacer al terminar

Este capítulo no va de «poner bonita» la aplicación. Va de que la capa visual siga siendo modificable dentro de dos años, con otro equipo y con el triple de pantallas.

• Explicar por qué el CSS se degrada más rápido que el TypeScript y qué propiedades del lenguaje lo provocan, para poder neutralizarlas con arquitectura en lugar de con disciplina.
• Elegir con criterio entre CSS plano con BEM, preprocesadores, utilidades tipo Tailwind y estilos de componente de Angular, sabiendo qué aporta y qué cuesta cada opción en un proyecto con encapsulación emulada.
• Usar flexbox, grid, variables personalizadas, clamp(), contenedores de consulta, :has(), capas en cascada y propiedades lógicas para resolver con CSS nativo lo que hace cinco años exigía una librería entera.
• Diseñar un sistema de tokens de diseño y construir sobre él un modo claro y un modo oscuro que respeten la preferencia del sistema, se puedan cambiar sin recargar, persistan entre sesiones y no parpadeen al arrancar.
• Decidir si Angular Material encaja en tu proyecto, instalarlo, personalizar su tema por los mecanismos oficiales y no con ::ng-deep, e integrarlo con formularios reactivos tipados.
• Construir componentes propios sobre el CDK —overlay, portal, arrastrar y soltar, scroll virtual, puntos de ruptura, gestión del foco, anuncios a lectores de pantalla, portapapeles y campos de texto— en lugar de importar una librería completa para resolver un problema pequeño.
• Integrar Tailwind en Angular entendiendo por qué funciona pese a la encapsulación de estilos, y aplicar el patrón de extraer componentes antes de que las plantillas se vuelvan ilegibles.
• Maquetar en móvil primero con puntos de ruptura justificados, imágenes adaptativas y tipografía fluida.
• Animar sin degradar el rendimiento: saber qué propiedades se pueden animar sin provocar recálculo de diseño, cuándo usar CSS y cuándo la API de animaciones de Angular, y respetar la preferencia de movimiento reducido.
• Diseñar la API pública de un componente de interfaz reutilizable: entradas, salidas, contenido proyectado, tokens de personalización y estados de carga, vacío, error y deshabilitado.
• Implementar esqueletos de carga que mejoren la velocidad percibida sin provocar saltos de diseño, y estados vacíos que sirvan para algo.
• Valorar con honestidad si Storybook merece la pena en tu equipo, y medir el coste real de la capa visual en el paquete final.

24.2 El problema: por qué la capa visual acaba siendo la más difícil de mantener

Hay una asimetría curiosa en casi todos los equipos que conozco. Nadie aceptaría una función de TypeScript de setecientas líneas con variables globales y sin pruebas; sin embargo, casi todos conviven con una hoja de estilos de setecientas líneas, con selectores globales, sin pruebas y sin dueño. La razón no es que los programadores de front-end sean menos rigurosos: es que el CSS tiene propiedades de lenguaje que empujan activamente hacia el desorden, y hay que compensarlas con arquitectura.

24.2.1 Cuatro propiedades del CSS que generan deuda

Conviene nombrarlas con precisión, porque cada una tiene un antídoto distinto.

• Todo es global por defecto. Una regla .card { padding: 16px } escrita en cualquier archivo afecta a todos los elementos con esa clase en toda la aplicación, ahora y en el futuro. En TypeScript, para que un módulo afecte a otro hay que importarlo explícitamente; en CSS basta con que el navegador cargue la hoja. Esto convierte cada nombre de clase en una variable global.
• No hay errores. Si escribes colr: red o apuntas a un selector que ya no existe, el navegador ignora la declaración en silencio. No hay compilador, no hay excepción, no hay prueba que falle. El código muerto se acumula sin dejar rastro, y nadie borra una regla que no sabe si sigue en uso.
• La especificidad es una guerra de escalada. Cuando una regla no se aplica, la solución rápida es añadir un selector más, luego un #id, luego !important. Cada escalada obliga a la siguiente a escalar más. Es una carrera armamentística dentro del propio proyecto.
• El resultado depende del contexto. El mismo componente se ve distinto según el ancho del contenedor padre, la fuente heredada, el overflow de un antepasado o un z-index que crea un contexto de apilamiento tres niveles más arriba. La composición no es local, y por tanto no se puede razonar localmente.

24.2.2 Los síntomas, en orden de aparición

La degradación de la capa visual sigue un guion tan repetido que se puede predecir. En TaskFlow, nuestra aplicación de tareas y proyectos, sucedería así:

24.2.3 Un sistema de diseño es una decisión de ingeniería

Aquí está la tesis del capítulo. Cuando alguien propone «montar un sistema de diseño», la reacción habitual de un equipo bajo presión es tratarlo como una petición estética: colores bonitos, una guía de estilo, algo que hace feliz al departamento de diseño. Es un error de categoría.

Un sistema de diseño es, en términos de ingeniería, un mecanismo de reducción del espacio de estados. Sin él, el color de un texto secundario puede ser cualquiera de los 16,7 millones que admite el formato de 24 bits; el espaciado entre dos elementos puede ser cualquier número de píxeles; el radio de una esquina, cualquier valor. Con él, el color secundario es uno, el espaciado es uno de siete valores de una escala y el radio es uno de cuatro. Has pasado de un espacio infinito a un espacio enumerable, y todo lo que sabemos sobre diseño de software dice que eso es exactamente lo que hace un sistema mantenible.

Las consecuencias prácticas son medibles y no tienen nada de estético:

• Los cambios transversales pasan de días a minutos. «Sube un punto el contraste de los textos secundarios» es una línea si existe un token --tf-text-muted, y una semana de arqueología si hay ciento treinta declaraciones de color repartidas por cuarenta archivos.
• El modo oscuro deja de ser un proyecto. Si los componentes no contienen colores literales sino referencias a tokens, añadir un tema es redefinir un conjunto de variables. Si los contienen, hay que revisar cada componente uno a uno. La sección 24.5 lo desarrolla.
• Las revisiones de código dejan de discutir píxeles. «¿Por qué 14px y no 16px?» es una discusión sin criterio; «esto debería usar el token --tf-space-3» es una regla verificable, y hasta automatizable con un linter.
• La accesibilidad se garantiza una vez. Si el contraste se valida en la paleta de tokens, ningún componente puede violarlo por accidente. Si cada componente elige su color, la validación hay que repetirla en cada pantalla y en cada revisión.

/* Apariencia incrustada: cada valor es una decisión
   irrepetible y no localizable desde ningún otro sitio */
.task-card {
  background: #161b2e;
  border: 1px solid #262c44;
  border-radius: 9px;          /* en project-card son 8px */
  padding: 14px 16px;          /* nadie recuerda por qué 14 */
  color: #e6e9f2;
  box-shadow: 0 4px 14px rgba(0,0,0,.35);
}
.task-card__meta { color: #8892b0; font-size: 12.5px; }
.task-card--urgent { border-color: #ff5c7a; }

/* Intención declarada: los valores viven en el sistema
   de tokens y el componente solo los consume */
.task-card {
  background: var(--tf-surface-2);
  border: 1px solid var(--tf-border);
  border-radius: var(--tf-radius-md);
  padding: var(--tf-space-3) var(--tf-space-4);
  color: var(--tf-text);
  box-shadow: var(--tf-shadow-1);
}
.task-card__meta { color: var(--tf-text-muted); font-size: var(--tf-fs-sm); }
.task-card--urgent { border-color: var(--tf-danger); }

Fíjate en que el bloque correcto no tiene menos líneas ni es más listo. Simplemente ha movido las decisiones a un único lugar donde se pueden cambiar todas a la vez, revisar en conjunto y validar automáticamente. Eso es arquitectura: no escribir menos código, sino colocar cada decisión donde solo haya que tomarla una vez.

24.3 Estrategias de estilado comparadas

No existe la estrategia correcta en abstracto; existe la que encaja con tu equipo, tu framework y el tiempo de vida esperado del proyecto. Lo que sí existe es la obligación de elegir conscientemente en lugar de acumular las cinco a la vez, que es lo que ocurre en la mayoría de las bases de código que audito.

24.3.1 Tabla honesta

24.3.2 Cómo aísla Angular realmente

Merece la pena entender el mecanismo, porque explica casi todos los problemas de estilado que se ven en un proyecto Angular. El compilador tiene tres modos, controlados por encapsulation:

import { Component, ViewEncapsulation } from '@angular/core';

@Component({
  selector: 'tf-task-card',
  templateUrl: './task-card.component.html',
  styleUrl: './task-card.component.css',   // singular desde Angular 17
  encapsulation: ViewEncapsulation.Emulated, // valor por defecto
})
export class TaskCardComponent {}

<!-- Plantilla escrita -->
<div class="task-card">
  <h3 class="title">{{ task.title }}</h3>
  <tf-tag-list [tags]="task.tags" />
</div>

<!-- DOM resultante: el hijo lleva OTRO atributo de contenido -->
<div class="task-card" _ngcontent-tf-c12>
  <h3 class="title" _ngcontent-tf-c12>Revisar el informe</h3>
  <tf-tag-list _ngcontent-tf-c12 _nghost-tf-c34>
    <span class="tag" _ngcontent-tf-c34>urgente</span>  <!-- inalcanzable desde el padre -->
  </tf-tag-list>
</div>

Los dos selectores especiales que Angular sí ofrece son :host, que apunta al elemento anfitrión del propio componente, y :host-context(), que permite reaccionar a una clase presente en cualquier antepasado. El segundo es la forma canónica de que un componente cambie de aspecto según el tema activo sin que nadie le pase una entrada.

:host {
  display: block;                 /* los componentes son inline por defecto */
  container-type: inline-size;    /* ver contenedores de consulta, 24.4.4 */
}

:host([data-urgent='true']) .task-card { border-color: var(--tf-danger); }

/* Reacciona a un antepasado con .theme-dark sin recibir ninguna entrada */
:host-context(.theme-dark) .task-card { box-shadow: var(--tf-shadow-2); }

/* Estado deshabilitado del propio anfitrión */
:host(.is-disabled) { opacity: .55; pointer-events: none; }

24.3.3 Criterios de elección

Si tuviera que reducir la decisión a cuatro preguntas, serían estas:

• ¿Cuánta gente va a tocar estos estilos y con qué rotación? Cuanta más rotación, más conviene un sistema que imponga las restricciones por herramienta (utilidades, tokens con linter) y no por convención.
• ¿Hay diseñadores con un sistema propio, o el diseño se decide sobre la marcha? Con un sistema de diseño externo bien definido, Angular Material puede estorbar más de lo que ayuda, porque tendrás que redefinir casi todo. Sin diseñadores, Material te regala centenares de decisiones razonables y accesibles.
• ¿La aplicación es de producto o de herramienta interna? Una herramienta interna con doscientas pantallas de formularios y tablas es el caso de uso ideal de Material. Una aplicación de producto con identidad visual fuerte suele salir mejor con CSS propio más el CDK.
• ¿Cuánto tiempo va a vivir? A cinco años vista, el CSS nativo y el CDK envejecen mucho mejor que cualquier librería de componentes, porque la superficie de API que consumes es más pequeña y más estable.

24.4 Fundamentos de CSS moderno que sustituyen a librerías enteras

Una parte muy grande de las dependencias que arrastra un proyecto de front-end resuelve problemas que el CSS ya resuelve de forma nativa. Rejillas de doce columnas, sistemas de espaciado, utilidades de posicionamiento, plugins para detectar el ancho del contenedor, envoltorios para tipografía adaptativa: todo eso existía porque el lenguaje no llegaba. Hoy llega. Esta sección repasa las siete capacidades que más peso de dependencias eliminan.

24.4.1 Flexbox y grid: no compiten, se reparten el trabajo

La confusión habitual se disuelve con una frase: flexbox distribuye elementos a lo largo de un eje y grid coloca elementos en un plano de dos dimensiones definido de antemano. Flexbox parte del contenido (los hijos negocian el espacio); grid parte del contenedor (el contenedor declara la retícula y los hijos se colocan en ella).

.task-row {
  display: flex;
  align-items: center;
  gap: var(--tf-space-3);        /* sustituye a los márgenes con :last-child */
  padding-block: var(--tf-space-2);
}

.task-row__title {
  flex: 1 1 auto;                /* crece, se encoge, base automática */
  min-width: 0;                  /* CLAVE: permite que text-overflow funcione */
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.task-row__due,
.task-row__assignee { flex: 0 0 auto; }   /* nunca se encogen */

.task-row__menu { margin-inline-start: auto; }  /* empuja al final del eje */

/* 1. Tablero de columnas fijas, cada una con scroll propio */
.board {
  display: grid;
  grid-template-columns: repeat(3, minmax(280px, 1fr));
  gap: var(--tf-space-4);
  align-items: start;            /* que las columnas no se estiren entre sí */
  overflow-x: auto;              /* en móvil se desplaza horizontalmente */
}

/* 2. Cuadrícula adaptativa SIN media queries: el número de columnas
      lo decide el espacio disponible, no un punto de ruptura inventado */
.project-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(260px, 100%), 1fr));
  gap: var(--tf-space-4);
}

/* 3. Formulario con áreas nombradas: la estructura se lee en el CSS */
.task-form {
  display: grid;
  grid-template-columns: 160px 1fr;
  grid-template-areas:
    'label-title   title'
    'label-project project'
    'label-due     due'
    '.             actions';
  gap: var(--tf-space-3) var(--tf-space-4);
  align-items: center;
}
.task-form__actions { grid-area: actions; justify-self: end; }

La regla minmax(min(260px, 100%), 1fr) merece un comentario, porque es el idioma que evita el error clásico: con minmax(260px, 1fr) a secas, en una pantalla de 240 píxeles la columna sigue midiendo 260 y aparece el temido desplazamiento horizontal. El min(260px, 100%) dice «260 píxeles, salvo que no quepan, en cuyo caso todo el ancho disponible». Con esa sola línea desaparecen dos o tres puntos de ruptura.

24.4.2 Variables personalizadas: el mecanismo, no la sintaxis

Las propiedades personalizadas de CSS no son «las variables de Sass pero en el navegador». Son algo distinto y más potente, y las diferencias importan:

• Se resuelven en tiempo de ejecución. Una variable de Sass desaparece en la compilación; una variable CSS existe en el navegador y se puede leer y modificar desde JavaScript con getComputedStyle y style.setProperty. Esto es lo que hace posible el cambio de tema sin recargar.
• Se heredan por el árbol del DOM. No tienen ámbito de archivo, sino ámbito de elemento: el valor que ve un componente es el que haya declarado su antepasado más cercano. Esta es la propiedad que convierte una variable en un punto de extensión de un componente.
• Atraviesan la encapsulación de Angular. La encapsulación emulada reescribe selectores, no valores heredados. Una variable declarada en el padre llega al hijo, y por eso es la forma correcta de personalizar un componente desde fuera sin ::ng-deep.
• Aceptan valores de reserva. var(--tf-radius-md, 8px) permite publicar un componente que funciona aunque el consumidor no defina ningún token.

:root {                          /* alcance global: toda la aplicación */
  --tf-accent: #5b8cff;
  --tf-space-3: 12px;
}

/* Redefinición local: solo dentro de este subárbol */
.project-panel--danger { --tf-accent: #ff5c7a; }

/* El componente consume la variable sin saber quién la define */
.btn { background: var(--tf-accent, #4361ee); }   /* con valor de reserva */

/* Truco útil: componer variables a partir de otras */
:host {
  --tf-card-padding: var(--tf-space-3);
  padding: var(--tf-card-padding);
}

@property --tf-progress {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 0%;
}

.project-progress {
  background: conic-gradient(var(--tf-accent) var(--tf-progress), var(--tf-surface-3) 0);
  transition: --tf-progress .6s ease;   /* ahora sí interpola */
}

24.4.3 clamp() y tipografía fluida

clamp(mínimo, preferido, máximo) expresa en una línea lo que antes exigía tres consultas de medios. El valor preferido suele mezclar una parte fija y una proporcional al ancho de la ventana, de modo que la tipografía crece de forma continua entre dos límites en lugar de dar saltos.

/* Saltos bruscos y tres reglas que mantener sincronizadas */
h1 { font-size: 22px; }
@media (min-width: 640px)  { h1 { font-size: 28px; } }
@media (min-width: 1024px) { h1 { font-size: 34px; } }

.board { padding: 12px; }
@media (min-width: 640px)  { .board { padding: 20px; } }
@media (min-width: 1024px) { .board { padding: 32px; } }

/* Continuo, con mínimo y máximo garantizados */
h1     { font-size: clamp(1.375rem, 1rem + 1.6vw, 2.125rem); }
.board { padding:  clamp(0.75rem, 0.4rem + 1.4vw, 2rem); }

/* Medida de línea legible sin cálculos: 45-75 caracteres */
.prose { max-width: min(68ch, 100%); }

24.4.4 Contenedores de consulta: el fin del componente que no sabe dónde está

Una consulta de medios pregunta por el ancho de la ventana. Pero un componente rara vez quiere saber eso: quiere saber cuánto espacio tiene él. La tarjeta de tarea de TaskFlow aparece en tres sitios —la lista principal a todo lo ancho, una columna estrecha del tablero y el panel lateral de detalle— y con consultas de medios es imposible que se adapte, porque en los tres casos la ventana mide lo mismo.

/* 1. El anfitrión se declara contenedor consultable */
:host {
  display: block;
  container-type: inline-size;   /* solo se consulta el eje en línea */
  container-name: task-card;     /* opcional pero recomendable */
}

/* 2. Diseño compacto por defecto (móvil primero también aquí) */
.task-card { display: grid; gap: var(--tf-space-2); }
.task-card__assignee,
.task-card__project { display: none; }

/* 3. A partir de 380px DE CONTENEDOR, no de ventana */
@container task-card (min-width: 380px) {
  .task-card { grid-template-columns: 1fr auto; align-items: center; }
  .task-card__assignee { display: flex; }
}

@container task-card (min-width: 560px) {
  .task-card__project { display: inline-flex; }
  .task-card__title { font-size: var(--tf-fs-lg); }
}

24.4.5 :has(), el selector de padre que llevábamos veinte años pidiendo

:has() selecciona un elemento en función de lo que contiene. Su impacto práctico es que muchas clases de estado que hoy calcula el componente y aplica con [class.x] dejan de ser necesarias: el CSS puede deducirlas del propio DOM.

/* El campo se marca en rojo porque contiene un input inválido ya tocado */
.field:has(input.ng-invalid.ng-touched) { --tf-field-border: var(--tf-danger); }

/* La fila cambia de fondo si su casilla está marcada */
.task-row:has(input[type='checkbox']:checked) {
  background: var(--tf-surface-3);
  text-decoration: line-through;
}

/* El panel se compacta cuando NO contiene descripción */
.task-panel:not(:has(.task-panel__description)) { padding-block-end: var(--tf-space-2); }

/* La tarjeta se realza si alguno de sus descendientes tiene el foco visible */
.task-card:has(:focus-visible) { outline: 2px solid var(--tf-accent); outline-offset: 2px; }

Ese último ejemplo sustituye a un patrón completo: antes había que escuchar focusin y focusout en el componente, mantener una propiedad booleana y enlazarla a una clase. Cuatro líneas de TypeScript, un estado más que probar y una posible fuga de listeners, resueltas con un selector.

24.4.6 Capas en cascada: el final de las guerras de especificidad

@layer introduce un nivel de decisión por encima de la especificidad. Cuando dos reglas de capas distintas compiten, gana la de la capa declarada más tarde sin mirar la especificidad. Un selector de un solo nombre de clase en una capa posterior vence a un #id .a .b .c de una capa anterior. Esto cambia por completo la forma de integrar CSS de terceros.

/* El orden se fija aquí; lo que venga después se coloca en su capa
   independientemente del orden de los @import o del bundler */
@layer reset, tokens, vendor, base, componentes, utilidades;

@layer reset {
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; }
}

@layer vendor {
  /* Todo el CSS de una librería de terceros entra aquí y queda
     por debajo de nuestros componentes pase lo que pase */
  @import url('vendor/tabla-legacy.css');
}

@layer componentes {
  /* Una sola clase gana a cualquier selector de la capa vendor */
  .tf-table th { background: var(--tf-surface-2); }
}

@layer utilidades {
  .u-hidden { display: none; }   /* gana siempre, sin !important */
}

24.4.7 Propiedades lógicas

Las propiedades físicas (left, right, margin-left) describen la pantalla; las lógicas (inline-start, inline-end, margin-inline-start) describen el flujo del texto. La diferencia solo se nota cuando llega la primera traducción a árabe o hebreo, y entonces se nota mucho: con propiedades físicas hay que revisar la aplicación entera; con lógicas, basta con dir="rtl".

24.5 Temas y modo oscuro

El modo oscuro es la prueba del algodón de una arquitectura de estilos. Si los tokens están bien, es un archivo de treinta líneas y una tarde. Si no, es un proyecto de dos semanas que además deja la aplicación medio rota. Vamos a construirlo entero para TaskFlow.

24.5.1 Anatomía de un sistema de tokens

El error más común al empezar es tener una sola capa de variables: --azul-claro, --gris-oscuro. Falla en cuanto llega el segundo tema, porque el nombre describe el valor y en modo oscuro el «gris oscuro» tiene que ser claro. La solución es separar tres niveles, cada uno con una responsabilidad distinta:

  ┌──────────────────────────────────────────────────────────────────────────┐
  │  NIVEL 1 · TOKENS PRIMITIVOS         (la paleta cruda; nunca se usan     │
  │                                       directamente en un componente)     │
  │    --tf-blue-500: #5b8cff        --tf-gray-900: #0d1020                  │
  │    --tf-blue-600: #4571e8        --tf-gray-700: #262c44                  │
  │    --tf-red-500:  #ff5c7a        --tf-gray-100: #e6e9f2                  │
  └───────────────────────────────┬──────────────────────────────────────────┘
                                  │  se referencian desde
                                  ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  NIVEL 2 · TOKENS SEMÁNTICOS         (describen FUNCIÓN, no color;       │
  │                                       AQUÍ es donde cambia el tema)      │
  │    --tf-surface-1   --tf-text        --tf-accent      --tf-danger        │
  │    --tf-surface-2   --tf-text-muted  --tf-border      --tf-shadow-1      │
  │                                                                          │
  │    tema claro  →  --tf-surface-1: var(--tf-gray-050)                     │
  │    tema oscuro →  --tf-surface-1: var(--tf-gray-900)                     │
  └───────────────────────────────┬──────────────────────────────────────────┘
                                  │  se referencian desde
                                  ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  NIVEL 3 · TOKENS DE COMPONENTE      (puntos de extensión publicados     │
  │                                       por cada componente)               │
  │    --tf-card-bg: var(--tf-surface-2)     --tf-card-radius: …            │
  │    --tf-btn-bg:  var(--tf-accent)        --tf-btn-height: …             │
  └───────────────────────────────┬──────────────────────────────────────────┘
                                  │  los consume
                                  ▼
              .task-card { background: var(--tf-card-bg); }

  REGLA DE ORO: un componente SOLO consume niveles 2 y 3. Si un componente
  menciona --tf-blue-500, el sistema ya está roto: ese componente no podrá
  cambiar de tema y habrá que editarlo a mano.

Con esta separación, cambiar de tema consiste en redefinir el nivel 2. Ni un solo componente se toca. Y como el nivel 1 es una paleta cerrada, el diseñador puede ajustar la marca entera cambiando seis valores.

24.5.2 Los tokens de TaskFlow

Los tokens no son solo colores. Un sistema completo cubre al menos cinco familias: color, espaciado, tipografía, radios y sombras. Las escalas deben ser cortas —si tienes doce valores de espaciado, no tienes escala, tienes libertad disfrazada— y no lineales, porque la percepción tampoco lo es.

@layer tokens {
  :root {
    /* ---------- NIVEL 1: primitivos ---------- */
    --tf-blue-400: #7ba4ff;  --tf-blue-500: #5b8cff;  --tf-blue-600: #4571e8;
    --tf-red-500:  #ff5c7a;  --tf-green-500: #2ecc8f; --tf-amber-500: #ffb020;
    --tf-gray-000: #ffffff;  --tf-gray-050: #f6f7fb;  --tf-gray-100: #e6e9f2;
    --tf-gray-400: #8892b0;  --tf-gray-700: #262c44;  --tf-gray-800: #161b2e;
    --tf-gray-900: #0d1020;

    /* ---------- Escalas independientes del tema ---------- */
    --tf-space-1: 4px;  --tf-space-2: 8px;  --tf-space-3: 12px;
    --tf-space-4: 16px; --tf-space-5: 24px; --tf-space-6: 32px; --tf-space-7: 48px;

    --tf-fs-xs: .75rem;   --tf-fs-sm: .8125rem; --tf-fs-md: .9375rem;
    --tf-fs-lg: 1.125rem; --tf-fs-xl: clamp(1.375rem, 1rem + 1.6vw, 2.125rem);

    --tf-radius-sm: 6px; --tf-radius-md: 10px; --tf-radius-lg: 16px; --tf-radius-full: 999px;

    --tf-dur-fast: 120ms; --tf-dur-base: 200ms; --tf-dur-slow: 320ms;
    --tf-ease: cubic-bezier(.2, 0, 0, 1);

    /* ---------- NIVEL 2: semánticos (tema claro por defecto) ---------- */
    --tf-surface-1: var(--tf-gray-050);   /* fondo de página */
    --tf-surface-2: var(--tf-gray-000);   /* tarjetas y paneles */
    --tf-surface-3: var(--tf-gray-100);   /* estados hover y zonas hundidas */
    --tf-text:       #12172b;
    --tf-text-muted: #5b6480;
    --tf-border:     #dfe3ee;
    --tf-accent:     var(--tf-blue-600);
    --tf-on-accent:  var(--tf-gray-000);
    --tf-danger:     #d93a5c;
    --tf-success:    #15915f;
    --tf-shadow-1: 0 1px 2px rgba(16, 24, 48, .08), 0 4px 12px rgba(16, 24, 48, .06);
    --tf-shadow-2: 0 8px 30px rgba(16, 24, 48, .14);

    color-scheme: light;   /* barras de scroll y controles nativos claros */
  }

  /* ---------- Tema oscuro: SOLO se redefine el nivel 2 ---------- */
  :root[data-theme='dark'] {
    --tf-surface-1: var(--tf-gray-900);
    --tf-surface-2: var(--tf-gray-800);
    --tf-surface-3: var(--tf-gray-700);
    --tf-text:       var(--tf-gray-100);
    --tf-text-muted: var(--tf-gray-400);
    --tf-border:     #2b3252;
    --tf-accent:     var(--tf-blue-500);
    --tf-on-accent:  #071024;
    --tf-danger:     var(--tf-red-500);
    --tf-success:    var(--tf-green-500);
    --tf-shadow-1: 0 1px 2px rgba(0, 0, 0, .5), 0 6px 18px rgba(0, 0, 0, .35);
    --tf-shadow-2: 0 12px 40px rgba(0, 0, 0, .55);

    color-scheme: dark;
  }
}

24.5.3 Cambiar de tema sin recargar, con señales

El servicio de tema tiene tres responsabilidades: recordar la preferencia del usuario (que puede ser «claro», «oscuro» o «lo que diga el sistema»), calcular el tema efectivo a partir de ella y del sistema operativo, y aplicarlo al documento. Con señales queda muy limpio, porque el tema efectivo es literalmente un valor derivado.

import { DOCUMENT } from '@angular/common';   // en Angular 19+ también se exporta desde @angular/core
import { Injectable, computed, effect, inject, signal } from '@angular/core';

export type ThemePreference = 'light' | 'dark' | 'system';
const STORAGE_KEY = 'tf-theme';

@Injectable({ providedIn: 'root' })
export class ThemeService {
  private readonly doc = inject(DOCUMENT);
  private readonly win = this.doc.defaultView;

  /** Lo que el usuario ha elegido explícitamente. */
  readonly preference = signal<ThemePreference>(this.readStoredPreference());

  /** Lo que dice el sistema operativo en este instante. */
  private readonly systemDark = signal(this.matchSystemDark());

  /** Tema realmente aplicado: valor derivado, nunca duplicado. */
  readonly resolved = computed<'light' | 'dark'>(() => {
    const pref = this.preference();
    if (pref !== 'system') return pref;
    return this.systemDark() ? 'dark' : 'light';
  });

  constructor() {
    // Escucha los cambios del sistema para que 'system' sea realmente reactivo
    const mq = this.win?.matchMedia('(prefers-color-scheme: dark)');
    mq?.addEventListener('change', (e) => this.systemDark.set(e.matches));

    // Un único efecto que sincroniza el DOM con el estado derivado
    effect(() => {
      this.doc.documentElement.dataset['theme'] = this.resolved();
    });
  }

  setPreference(pref: ThemePreference): void {
    this.preference.set(pref);
    try {
      if (pref === 'system') this.win?.localStorage.removeItem(STORAGE_KEY);
      else this.win?.localStorage.setItem(STORAGE_KEY, pref);
    } catch {
      /* modo privado o almacenamiento lleno: el tema sigue funcionando en memoria */
    }
  }

  private readStoredPreference(): ThemePreference {
    try {
      const raw = this.win?.localStorage.getItem(STORAGE_KEY);
      return raw === 'light' || raw === 'dark' ? raw : 'system';
    } catch {
      return 'system';
    }
  }

  private matchSystemDark(): boolean {
    return this.win?.matchMedia('(prefers-color-scheme: dark)').matches ?? false;
  }
}

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { ThemePreference, ThemeService } from '../core/theme.service';

@Component({
  selector: 'tf-theme-switch',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <fieldset class="switch">
      <legend class="switch__legend">Apariencia</legend>
      @for (opt of options; track opt.value) {
        <button
          type="button"
          class="switch__btn"
          [class.is-active]="theme.preference() === opt.value"
          [attr.aria-pressed]="theme.preference() === opt.value"
          (click)="theme.setPreference(opt.value)">
          {{ opt.label }}
        </button>
      }
    </fieldset>
  `,
  styles: `
    .switch { display: inline-flex; gap: var(--tf-space-1); border: 1px solid var(--tf-border);
              border-radius: var(--tf-radius-full); padding: var(--tf-space-1); }
    .switch__btn { border: 0; background: transparent; color: var(--tf-text-muted);
                   border-radius: var(--tf-radius-full); padding: 4px 12px; cursor: pointer; }
    .switch__btn.is-active { background: var(--tf-accent); color: var(--tf-on-accent); }
  `,
})
export class ThemeSwitchComponent {
  protected readonly theme = inject(ThemeService);
  protected readonly options: { value: ThemePreference; label: string }[] = [
    { value: 'light',  label: 'Claro'    },
    { value: 'dark',   label: 'Oscuro'   },
    { value: 'system', label: 'Sistema'  },
  ];
}

<script>
  // Se ejecuta de forma síncrona antes de la primera pintura: sin parpadeo.
  (function () {
    try {
      var stored = localStorage.getItem('tf-theme');
      var dark = stored ? stored === 'dark'
                        : matchMedia('(prefers-color-scheme: dark)').matches;
      document.documentElement.dataset.theme = dark ? 'dark' : 'light';
    } catch (e) { /* sin almacenamiento: se queda el tema claro por defecto */ }
  })();
</script>

24.6 Angular Material: cuándo conviene y cuándo no

Angular Material es la implementación oficial de Material Design mantenida por el equipo de Angular. Es, con diferencia, la librería de componentes más usada del ecosistema, y también la que más frustración genera, casi siempre por el mismo motivo: se adopta esperando «unos componentes bonitos que luego personalizo» y resulta que es un sistema de diseño completo con opiniones fuertes. Personalizarla es posible y está previsto; lo que no funciona es pelearse con ella.

24.6.1 La decisión, sin marketing

24.6.2 Instalación y qué toca realmente

ng add @angular/material

# El esquema oficial hace, aproximadamente, esto:
#  · instala @angular/material y @angular/cdk con la versión que corresponde a tu Angular
#  · añade un tema (prefabricado o generado) a la configuración de estilos de angular.json
#  · registra el proveedor de animaciones en la configuración de la aplicación
#  · añade la tipografía Roboto y la fuente de iconos a index.html (puedes quitarlas)
#  · aplica la clase de tipografía global al <body>

import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
import { provideNativeDateAdapter } from '@angular/material/core';
import { MAT_FORM_FIELD_DEFAULT_OPTIONS } from '@angular/material/form-field';

export const appConfig: ApplicationConfig = {
  providers: [
    // Carga el paquete de animaciones de forma diferida (Angular 17+).
    // Alternativas: provideAnimations() para cargarlo de inmediato
    //               provideNoopAnimations() para desactivarlas (útil en tests).
    provideAnimationsAsync(),

    // Necesario si usas el selector de fechas (Angular Material 17+).
    provideNativeDateAdapter(),

    // Fija la apariencia de TODOS los campos sin repetirla en cada plantilla.
    { provide: MAT_FORM_FIELD_DEFAULT_OPTIONS,
      useValue: { appearance: 'outline', subscriptSizing: 'dynamic' } },

    provideZonelessChangeDetection(),
  ],
};

Ese último proveedor ya es una lección de arquitectura: casi todos los módulos de Material exponen un token de opciones por defecto. Antes de repetir appearance="outline" en ciento veinte campos, o de escribir CSS para corregir un espaciado, busca si existe el token correspondiente. Es configuración de verdad, no un parche.

24.6.3 El sistema de temas

El planteamiento conceptual, en cambio, es estable y es lo que conviene entender: tú declaras un tema en Sass y Material genera a partir de él un conjunto de tokens, que los componentes consumen. Personalizar bien significa intervenir en esa generación de tokens, no en el CSS resultante.

@use '@angular/material' as mat;

html {
  // Un único mixin declara color, tipografía y densidad.
  // El resultado son variables CSS de sistema (--mat-sys-*) que puedes leer.
  @include mat.theme((
    color: (
      primary: mat.$azure-palette,     // paletas prefabricadas de M3
      tertiary: mat.$violet-palette,
    ),
    typography: Roboto,
    density: 0,                        // 0 = cómodo; valores negativos = compacto
  ));
}

// El modo oscuro se declara en el mismo sitio que el resto de nuestros tokens:
// Material lee color-scheme, así que basta con mantenerlo coherente.
:root[data-theme='dark'] { color-scheme: dark; }

// PUENTE entre el sistema de tokens de Material y el nuestro (sección 24.5):
// nuestros componentes siguen usando --tf-*, y aquí decidimos qué significa cada uno.
:root {
  --tf-accent: var(--mat-sys-primary);
  --tf-on-accent: var(--mat-sys-on-primary);
  --tf-surface-2: var(--mat-sys-surface-container);
  --tf-text: var(--mat-sys-on-surface);
}

@use '@angular/material' as mat;

@include mat.core();   // estilos base comunes, una sola vez en todo el proyecto

$tf-primary: mat.define-palette(mat.$indigo-palette, 500);
$tf-accent:  mat.define-palette(mat.$pink-palette, A200, A100, A400);
$tf-warn:    mat.define-palette(mat.$red-palette);

$tf-light: mat.define-light-theme((
  color: (primary: $tf-primary, accent: $tf-accent, warn: $tf-warn),
  density: 0,
));

$tf-dark: mat.define-dark-theme((
  color: (primary: $tf-primary, accent: $tf-accent, warn: $tf-warn),
));

@include mat.all-component-themes($tf-light);

// Solo los COLORES se repiten para el tema oscuro: repetir el tema entero
// duplicaría tipografía y densidad y engordaría el CSS sin motivo.
:root[data-theme='dark'] { @include mat.all-component-colors($tf-dark); }

24.6.4 Personalizar de verdad, sin ::ng-deep

Esta es la subsección que más disgustos ahorra. Cuando algo de Material no se ve como quieres, hay cinco mecanismos legítimos, y conviene probarlos en este orden antes de pensar siquiera en perforar la encapsulación:

1. Tokens del tema. Si el color primario no es el que quieres, cámbialo en el tema, no en el componente.
2. Mixins de sobrescritura de tokens. Las versiones recientes de Material publican mixins que permiten redefinir tokens concretos de un componente (por ejemplo el radio de un botón o el fondo de una tarjeta) de forma global o dentro de un selector. Comprueba en la documentación de tu versión cómo se llaman exactamente los que necesitas y qué tokens admiten.
3. Variables CSS de sistema. En las versiones con Material Design 3 puedes redefinir --mat-sys-* dentro de un selector para afectar solo a una zona de la aplicación.
4. Tokens de opciones por defecto. MAT_FORM_FIELD_DEFAULT_OPTIONS, MAT_DIALOG_DEFAULT_OPTIONS, MAT_SNACK_BAR_DEFAULT_OPTIONS y sus equivalentes cambian el comportamiento por configuración.
5. Clases de panel. Los componentes que se pintan fuera del árbol del componente (diálogos, menús, selectores, avisos) aceptan una clase propia (panelClass) que puedes estilar desde la hoja global, donde no hay encapsulación que perforar.

/* 1. Sin :host, esta regla es GLOBAL: afecta a todos los
      diálogos de la aplicación, incluidos los de otros equipos */
::ng-deep .mat-mdc-dialog-surface {
  border-radius: 20px;
  background: #161b2e;
}

/* 2. Depende de un nombre de clase INTERNO de la librería,
      que cambió en la versión 15 y puede volver a cambiar */
::ng-deep .mat-mdc-form-field-subscript-wrapper { display: none; }

/* 3. Guerra de especificidad: la siguiente parada es !important */
::ng-deep .mat-mdc-raised-button.mat-primary .mdc-button__label {
  color: #fff;
}

// task-list.component.ts — se pide la personalización al abrir
this.dialog.open(TaskDialogComponent, {
  panelClass: 'tf-dialog',      // clase propia, nuestra, documentada
  width: 'min(560px, 92vw)',
  autoFocus: 'first-tabbable',
  restoreFocus: true,
  data: { taskId },
});

/* styles.css — hoja GLOBAL: es donde deben vivir los estilos de
   elementos que se renderizan fuera del árbol del componente */
.tf-dialog .mat-mdc-dialog-surface {
  border-radius: var(--tf-radius-lg);
  background: var(--tf-surface-2);
}

/* Y el subscript se oculta por configuración, no por CSS: */
// { provide: MAT_FORM_FIELD_DEFAULT_OPTIONS,
//   useValue: { subscriptSizing: 'dynamic' } }

La diferencia de fondo entre las dos columnas no es de estilo, es de acoplamiento. La izquierda depende de nombres de clase internos de una librería que no controlas y que cambian entre versiones mayores; la derecha depende de una API pública. Cuando actualices Angular Material, la izquierda se romperá en silencio —recuerda: el CSS no da errores— y la derecha seguirá funcionando o fallará ruidosamente en la compilación.

24.6.5 Los componentes que de verdad se usan

La librería tiene decenas de componentes, pero en una aplicación de gestión como TaskFlow el noventa por ciento del uso se concentra en unos pocos. Estos son, con la advertencia que importa de cada uno:

24.6.6 Formularios con Material y tipado estricto

Este ejemplo conecta con el capítulo 5: formulario reactivo tipado, validación, errores del servidor y accesibilidad, con los componentes de Material puestos donde toca.

import { ChangeDetectionStrategy, Component, inject, input, output } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { MatButtonModule } from '@angular/material/button';
import { MatDatepickerModule } from '@angular/material/datepicker';
import { MatFormFieldModule } from '@angular/material/form-field';
import { MatInputModule } from '@angular/material/input';
import { MatSelectModule } from '@angular/material/select';
import { Project } from '../projects/project.model';

@Component({
  selector: 'tf-task-form',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [
    ReactiveFormsModule, MatFormFieldModule, MatInputModule,
    MatSelectModule, MatDatepickerModule, MatButtonModule,
  ],
  templateUrl: './task-form.component.html',
})
export class TaskFormComponent {
  readonly projects = input.required<Project[]>();
  readonly saved = output<TaskFormValue>();

  private readonly fb = inject(FormBuilder);

  protected readonly form = this.fb.nonNullable.group({
    title: ['', [Validators.required, Validators.maxLength(120)]],
    projectId: ['', Validators.required],
    priority: ['medium' as Priority],
    dueDate: this.fb.control<Date | null>(null),
    description: [''],
  });

  protected submit(): void {
    if (this.form.invalid) {
      this.form.markAllAsTouched();   // dispara los mat-error de todos los campos
      return;
    }
    this.saved.emit(this.form.getRawValue());
  }
}

<form [formGroup]="form" (ngSubmit)="submit()" class="task-form">

  <mat-form-field>
    <mat-label>Título de la tarea</mat-label>
    <input matInput formControlName="title" maxlength="120" required>
    <mat-hint align="end">{{ form.controls.title.value.length }}/120</mat-hint>

    <!-- Un mat-error por caso: Material ya gestiona cuándo mostrarlo
         (control inválido y tocado o formulario enviado) -->
    @if (form.controls.title.hasError('required')) {
      <mat-error>El título es obligatorio.</mat-error>
    }
    @if (form.controls.title.hasError('maxlength')) {
      <mat-error>Máximo 120 caracteres.</mat-error>
    }
  </mat-form-field>

  <mat-form-field>
    <mat-label>Proyecto</mat-label>
    <mat-select formControlName="projectId">
      @for (p of projects(); track p.id) {
        <mat-option [value]="p.id">{{ p.name }}</mat-option>
      }
    </mat-select>
    <mat-error>Selecciona un proyecto.</mat-error>
  </mat-form-field>

  <mat-form-field>
    <mat-label>Fecha límite</mat-label>
    <input matInput [matDatepicker]="picker" formControlName="dueDate">
    <mat-datepicker-toggle matIconSuffix [for]="picker" />
    <mat-datepicker #picker />
  </mat-form-field>

  <div class="task-form__actions">
    <button mat-button type="button">Cancelar</button>
    <button mat-flat-button color="primary" type="submit">Guardar tarea</button>
  </div>
</form>

24.6.7 La accesibilidad que traen de serie (y la que no)

Es probablemente el mejor argumento a favor de Material, y el más ignorado. Sus componentes implementan los patrones del estándar de autoría ARIA con un nivel de detalle que ningún equipo replica en un sprint:

• Navegación por teclado completa: flechas dentro de menús y selectores, Home y End, búsqueda por escritura, Escape para cerrar.
• Gestión del foco: trampa de foco en diálogos, restauración del foco al elemento que abrió el overlay, y foco inicial configurable.
• Roles y estados ARIA correctos y sincronizados con el estado real del componente, incluido aria-expanded, aria-selected y aria-activedescendant donde procede.
• Asociación de etiquetas, pistas y errores: mat-form-field conecta mat-label, mat-hint y mat-error con el campo mediante aria-describedby. Hacerlo a mano y mantenerlo sincronizado es tedioso y se olvida.
• Modo de alto contraste del sistema operativo contemplado en los estilos.

24.7 El CDK a fondo: la parte infravalorada

Si tuviera que quedarme con una sola idea de este capítulo, sería esta: el Component Dev Kit es más valioso que Angular Material, y casi nadie lo usa directamente. El CDK resuelve los problemas que de verdad son difíciles —posicionar un elemento flotante que no se salga de la pantalla, atrapar el foco dentro de un diálogo, renderizar diez mil filas sin morir, anunciar un cambio a un lector de pantalla— y no impone ni un solo píxel de estilo. Es exactamente lo que necesita un equipo que tiene su propio sistema de diseño y no quiere pelearse con el de Google.

24.7.1 Overlay: la base de todo lo flotante

Un menú, un desplegable, un diálogo, un aviso emergente y un panel de filtros son el mismo problema con distinta apariencia: pintar contenido fuera del flujo del documento, encima de todo lo demás, en una posición relacionada con otro elemento, sin que se salga de la ventana y sin romper el foco. Ese problema es sorprendentemente difícil, y el overlay del CDK lo tiene resuelto.

  ANATOMÍA DE UN OVERLAY DEL CDK

  <body>
   ├── <div class="layout"> … tu aplicación entera …
   │      └── <button #trigger>Filtros</button>   ← ORIGEN (solo se usa como referencia)
   │
   └── <div class="cdk-overlay-container">          ← creado UNA vez, al final del body
          │                                            (por eso ningún overflow lo recorta)
          ├── <div class="cdk-overlay-backdrop">    ← opcional: hasBackdrop
          │      captura los clics de fuera y emite backdropClick()
          │
          └── <div class="cdk-overlay-connected-position-bounding-box">
                 │   lo coloca la PositionStrategy; define el área donde
                 │   el panel puede crecer o encogerse
                 └── <div class="cdk-overlay-pane">  ← aquí se ANCLA el Portal
                        └── tu componente o tu ng-template

  PIEZAS QUE SE COMBINAN
  ┌────────────────────┬────────────────────────────────────────────────────────┐
  │ PositionStrategy   │ global()  → centrado o pegado a la ventana (diálogos)   │
  │                    │ flexibleConnectedTo(origen) → pegado a un elemento,     │
  │                    │   con lista ORDENADA de posiciones alternativas         │
  ├────────────────────┼────────────────────────────────────────────────────────┤
  │ ScrollStrategy     │ noop()       → no hace nada                             │
  │                    │ reposition() → recalcula al hacer scroll (menús)        │
  │                    │ block()      → bloquea el scroll (diálogos modales)     │
  │                    │ close()      → cierra al hacer scroll (autocompletado)  │
  ├────────────────────┼────────────────────────────────────────────────────────┤
  │ Portal             │ ComponentPortal  → instancia un componente              │
  │                    │ TemplatePortal   → usa un <ng-template> ya existente    │
  ├────────────────────┼────────────────────────────────────────────────────────┤
  │ OverlayRef         │ attach() detach() dispose() updatePosition()            │
  │                    │ backdropClick()  keydownEvents()  detachments()         │
  └────────────────────┴────────────────────────────────────────────────────────┘

  CICLO DE VIDA
    create() ──► attach(portal) ──► [visible] ──► detach() ──► dispose()
       │                                            │            │
   reserva el pane                        vacía el pane   destruye el pane
   (aún no hay DOM del contenido)         (se puede       (ya NO se puede
                                           volver a         reutilizar)
                                           attach)

La distinción entre detach() y dispose() es la fuente número uno de fugas de memoria con el overlay: si abres un menú cien veces y creas cien OverlayRef sin destruirlos, tienes cien paneles vivos escuchando eventos. La regla es simple: crea el overlay una vez, adjunta y desadjunta tantas veces como haga falta, y destruye en ngOnDestroy.

import { DestroyRef, Directive, ElementRef, TemplateRef, ViewContainerRef,
         inject, input } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { Overlay, OverlayRef } from '@angular/cdk/overlay';
import { TemplatePortal } from '@angular/cdk/portal';
import { filter } from 'rxjs';

@Directive({ selector: '[tfPopover]', host: { '(click)': 'toggle()' } })
export class PopoverDirective {
  /** Plantilla que se mostrará dentro del panel flotante. */
  readonly content = input.required<TemplateRef<unknown>>({ alias: 'tfPopover' });

  private readonly overlay = inject(Overlay);
  private readonly host = inject(ElementRef<HTMLElement>);
  private readonly vcr = inject(ViewContainerRef);
  private overlayRef?: OverlayRef;

  constructor() {
    inject(DestroyRef).onDestroy(() => this.overlayRef?.dispose());
  }

  toggle(): void {
    if (this.overlayRef?.hasAttached()) { this.close(); return; }
    this.open();
  }

  private open(): void {
    this.overlayRef ??= this.createOverlay();
    this.overlayRef.attach(new TemplatePortal(this.content(), this.vcr));
  }

  private close(): void { this.overlayRef?.detach(); }

  private createOverlay(): OverlayRef {
    const position = this.overlay.position()
      .flexibleConnectedTo(this.host)
      // Lista ORDENADA: el CDK prueba de arriba abajo y usa la primera que cabe.
      .withPositions([
        { originX: 'start', originY: 'bottom', overlayX: 'start', overlayY: 'top',    offsetY: 6 },
        { originX: 'start', originY: 'top',    overlayX: 'start', overlayY: 'bottom', offsetY: -6 },
        { originX: 'end',   originY: 'bottom', overlayX: 'end',   overlayY: 'top',    offsetY: 6 },
      ])
      .withPush(true);          // si ninguna cabe, lo empuja para que se vea entero

    const ref = this.overlay.create({
      positionStrategy: position,
      scrollStrategy: this.overlay.scrollStrategies.reposition(),
      hasBackdrop: true,
      backdropClass: 'cdk-overlay-transparent-backdrop',  // invisible pero captura clics
      panelClass: 'tf-popover',
      disposeOnNavigation: true,
    });

    ref.backdropClick()
      .pipe(takeUntilDestroyed())
      .subscribe(() => this.close());

    ref.keydownEvents()
      .pipe(filter((e) => e.key === 'Escape'), takeUntilDestroyed())
      .subscribe(() => { this.close(); this.host.nativeElement.focus(); });

    return ref;
  }
}

<button type="button" [tfPopover]="filtros" aria-haspopup="dialog">
  Filtros ({{ activos() }})
</button>

<ng-template #filtros>
  <div class="tf-popover__panel" role="dialog" aria-label="Filtros de tareas" cdkTrapFocus>
    <h3 class="tf-popover__title">Filtrar tareas</h3>
    <!-- El contenido se declara aquí, pero se RENDERIZA en el overlay container.
         El contexto de inyección y el enlace de datos siguen siendo los de este componente. -->
    <tf-tag-picker [(selected)]="etiquetas" />
  </div>
</ng-template>

24.7.2 Portal: renderizar aquí lo que se declara allí

El portal es la abstracción que hay debajo del overlay, y se puede usar por separado. Resuelve un problema muy concreto: separar el lugar donde se declara un contenido del lugar donde se pinta. Es lo que permite que la barra superior de TaskFlow muestre acciones contextuales definidas por la pantalla activa sin que la barra sepa nada de ellas.

import { Injectable, signal } from '@angular/core';
import { Portal } from '@angular/cdk/portal';

@Injectable({ providedIn: 'root' })
export class ToolbarSlotService {
  /** El portal que la barra superior debe pintar en este momento, si hay alguno. */
  readonly portal = signal<Portal<unknown> | null>(null);

  set(portal: Portal<unknown>): void { this.portal.set(portal); }
  clear(): void { this.portal.set(null); }
}

// toolbar.component.html (la barra superior, que no conoce ninguna pantalla)
// <ng-template [cdkPortalOutlet]="slot.portal()" />

// task-list.component.ts (la pantalla, que aporta sus acciones)
// constructor() {
//   afterNextRender(() => this.slot.set(new TemplatePortal(this.acciones(), this.vcr)));
//   inject(DestroyRef).onDestroy(() => this.slot.clear());
// }

24.7.3 Arrastrar y soltar

El tablero de proyecto de TaskFlow es el ejemplo canónico: tres columnas y tarjetas que se mueven entre ellas. El CDK lo resuelve con dos directivas y dos funciones auxiliares, y —esto es lo importante— no toca tus datos: te dice qué ha pasado y tú decides.

<!-- cdkDropListGroup conecta automáticamente todas las listas descendientes -->
<div class="board" cdkDropListGroup>
  @for (column of columns(); track column.status) {
    <section class="board__column">
      <h3>{{ column.label }} ({{ column.tasks.length }})</h3>

      <div class="board__list"
           cdkDropList
           [cdkDropListData]="column"
           (cdkDropListDropped)="onDrop($event)">
        @for (task of column.tasks; track task.id) {
          <article class="task-card" cdkDrag [cdkDragData]="task">
            <span class="task-card__grip" cdkDragHandle aria-hidden="true">⋮⋮</span>
            {{ task.title }}

            <!-- Hueco que queda en el sitio original mientras se arrastra -->
            <div class="task-card__placeholder" *cdkDragPlaceholder></div>
          </article>
        }
        @empty {
          <p class="board__empty">Arrastra tareas aquí</p>
        }
      </div>
    </section>
  }
</div>

import { CdkDragDrop, moveItemInArray, transferArrayItem } from '@angular/cdk/drag-drop';

protected onDrop(event: CdkDragDrop<BoardColumn>): void {
  const task = event.item.data as Task;

  if (event.previousContainer === event.container) {
    // Reordenar dentro de la misma columna: solo cambia la posición
    moveItemInArray(event.container.data.tasks, event.previousIndex, event.currentIndex);
    this.api.reorder(task.id, event.currentIndex).subscribe();
    return;
  }

  // Mover entre columnas: cambia el estado de la tarea.
  // Actualizamos la interfaz PRIMERO (respuesta inmediata) y revertimos si falla.
  transferArrayItem(
    event.previousContainer.data.tasks,
    event.container.data.tasks,
    event.previousIndex,
    event.currentIndex,
  );

  const nuevoEstado = event.container.data.status;
  this.api.updateStatus(task.id, nuevoEstado).subscribe({
    error: () => {
      // Deshacer el movimiento optimista y avisar
      transferArrayItem(
        event.container.data.tasks,
        event.previousContainer.data.tasks,
        event.currentIndex,
        event.previousIndex,
      );
      this.announcer.announce('No se ha podido mover la tarea', 'assertive');
    },
  });
}

24.7.4 Scroll virtual: el problema de las listas grandes, medido

Renderizar una lista de cinco mil tareas no es «un poco más lento»: es un cambio de categoría. Cada tarjeta de TaskFlow genera del orden de una docena de nodos del DOM entre el contenedor, el título, la fecha, el responsable y las etiquetas. Cinco mil tarjetas son unos sesenta mil nodos, y el navegador tiene que construirlos, calcular su estilo, disponerlos y mantenerlos en memoria. Angular, además, tiene que comprobarlos en cada ciclo de detección de cambios.

Las cifras son órdenes de magnitud medidos en un portátil de gama media con una tarjeta de complejidad realista; lo que importa no es el número exacto, sino que la diferencia es de dos órdenes de magnitud y que crece con el tamaño de la lista.

import { ScrollingModule } from '@angular/cdk/scrolling';

@Component({
  selector: 'tf-task-list',
  imports: [ScrollingModule, TaskCardComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <cdk-virtual-scroll-viewport
      [itemSize]="72"
      [minBufferPx]="288"
      [maxBufferPx]="576"
      class="task-list">

      <tf-task-card
        *cdkVirtualFor="let task of tasks(); trackBy: trackById; templateCacheSize: 20"
        [task]="task" />
    </cdk-virtual-scroll-viewport>
  `,
  styles: `
    .task-list { block-size: 70vh; }   /* ALTURA EXPLÍCITA: obligatoria */
    tf-task-card { display: block; block-size: 72px; }  /* debe coincidir con itemSize */
  `,
})
export class TaskListComponent {
  readonly tasks = input.required<Task[]>();
  protected trackById = (_: number, t: Task) => t.id;
}

24.7.5 Layout: puntos de ruptura desde TypeScript

BreakpointObserver permite reaccionar a un punto de ruptura desde la clase, no desde el CSS. La distinción importante —y la desarrolla la sección 24.9— es que si solo cambia la apariencia, debe hacerlo el CSS; el observador se justifica cuando cambia la estructura o el comportamiento: renderizar un componente distinto, cambiar el modo de un panel lateral o desactivar una interacción.

import { BreakpointObserver, Breakpoints } from '@angular/cdk/layout';
import { toSignal } from '@angular/core/rxjs-interop';
import { map } from 'rxjs';

export class ShellComponent {
  private readonly breakpoints = inject(BreakpointObserver);

  /** Señal booleana lista para usar en la plantilla. */
  protected readonly isHandset = toSignal(
    this.breakpoints.observe([Breakpoints.Handset, Breakpoints.TabletPortrait])
      .pipe(map((state) => state.matches)),
    { initialValue: false },
  );

  /** Aquí sí está justificado: cambia el COMPORTAMIENTO del panel lateral. */
  protected readonly sidenavMode = computed(() => this.isHandset() ? 'over' : 'side');

  // Consulta puntual, sin suscripción
  protected get prefiereMenosMovimiento(): boolean {
    return this.breakpoints.isMatched('(prefers-reduced-motion: reduce)');
  }
}

Breakpoints incluye constantes como Handset, Tablet, Web y sus variantes de orientación, además de la escala XSmall a XLarge. Son los puntos de ruptura de Material Design; si tu sistema de diseño usa otros, pasa directamente una cadena de consulta de medios, que es igual de válida y evita mezclar dos escalas distintas en el mismo proyecto.

24.7.6 Accesibilidad: foco, trampas de foco y anuncios

El paquete de accesibilidad del CDK es el que más código propio ahorra, porque implementa cosas que la gente cree fáciles y no lo son.

import { LiveAnnouncer } from '@angular/cdk/a11y';

export class TaskListComponent {
  private readonly announcer = inject(LiveAnnouncer);

  protected aplicarFiltro(texto: string): void {
    const resultados = this.filtrar(texto);
    this.tasks.set(resultados);

    // 'polite' espera a que el lector termine lo que esté diciendo.
    // 'assertive' interrumpe: resérvalo para errores y acciones destructivas.
    this.announcer.announce(
      resultados.length === 0
        ? 'Ningún resultado para el filtro aplicado'
        : `${resultados.length} tareas encontradas`,
      'polite',
    );
  }

  protected eliminar(task: Task): void {
    this.api.delete(task.id).subscribe(() => {
      this.announcer.announce(`Tarea ${task.title} eliminada`, 'assertive');
    });
  }
}

<!-- Diálogo casero: el tabulador sale por detrás, el lector
     de pantalla sigue leyendo la página de debajo y al cerrar
     el foco se pierde al principio del documento -->
<div class="mi-dialogo">
  <h2>Eliminar tarea</h2>
  <button (click)="cerrar()">Cancelar</button>
  <button (click)="borrar()">Eliminar</button>
</div>

<div class="mi-dialogo"
     role="dialog"
     aria-modal="true"
     aria-labelledby="dlg-titulo"
     cdkTrapFocus
     cdkTrapFocusAutoCapture>
  <h2 id="dlg-titulo">Eliminar tarea</h2>
  <button (click)="cerrar()">Cancelar</button>
  <button cdkFocusInitial (click)="borrar()">Eliminar</button>
</div>

24.7.7 Clipboard y text field: dos utilidades pequeñas y muy rentables

<!-- Copiar el enlace de la tarea: directiva declarativa -->
<button type="button"
        [cdkCopyToClipboard]="enlaceTarea()"
        (cdkCopyToClipboardCopied)="onCopiado($event)">
  Copiar enlace
</button>

<!-- Textarea que crece con el contenido, entre 3 y 10 filas.
     Sin saltos de diseño y sin medir alturas a mano en TypeScript. -->
<textarea matInput
          cdkTextareaAutosize
          cdkAutosizeMinRows="3"
          cdkAutosizeMaxRows="10"
          formControlName="description"
          placeholder="Descripción de la tarea"></textarea>

24.7.8 Construir en lugar de importar: un selector de etiquetas

Éste es el ejemplo que resume la sección. TaskFlow necesita un selector de etiquetas con búsqueda, navegación por teclado y creación al vuelo. La tentación es instalar una librería de selectores múltiples de 80 KB. La alternativa es componer tres piezas del CDK que ya tienes instaladas y quedarte con el control total del marcado y de los estilos.

import { ActiveDescendantKeyManager, LiveAnnouncer } from '@angular/cdk/a11y';
import { OverlayModule } from '@angular/cdk/overlay';
import { AfterViewInit, ChangeDetectionStrategy, Component, ElementRef,
         computed, inject, model, signal, viewChild, viewChildren } from '@angular/core';
import { TagOptionComponent } from './tag-option.component';

@Component({
  selector: 'tf-tag-picker',
  imports: [OverlayModule, TagOptionComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <input
      #input
      class="tag-picker__input"
      role="combobox"
      aria-autocomplete="list"
      aria-controls="tag-listbox"
      [attr.aria-expanded]="abierto()"
      [attr.aria-activedescendant]="activeId()"
      [value]="consulta()"
      (input)="consulta.set($any($event.target).value)"
      (focus)="abierto.set(true)"
      (keydown)="onKeydown($event)"
      cdkOverlayOrigin
      #origen="cdkOverlayOrigin">

    <ng-template
      cdkConnectedOverlay
      [cdkConnectedOverlayOrigin]="origen"
      [cdkConnectedOverlayOpen]="abierto()"
      [cdkConnectedOverlayWidth]="anchoOrigen()"
      (overlayOutsideClick)="abierto.set(false)">

      <ul class="tag-picker__list" id="tag-listbox" role="listbox">
        @for (tag of filtradas(); track tag.id) {
          <tf-tag-option [tag]="tag" (selected)="alternar(tag)" />
        } @empty {
          <li class="tag-picker__empty">Sin coincidencias. Pulsa Intro para crearla.</li>
        }
      </ul>
    </ng-template>
  `,
})
export class TagPickerComponent implements AfterViewInit {
  readonly selected = model<Tag[]>([]);
  readonly disponibles = input.required<Tag[]>();

  protected readonly consulta = signal('');
  protected readonly abierto = signal(false);
  protected readonly filtradas = computed(() => {
    const q = this.consulta().trim().toLowerCase();
    return this.disponibles().filter((t) => t.name.toLowerCase().includes(q));
  });

  private readonly opciones = viewChildren(TagOptionComponent);
  private readonly announcer = inject(LiveAnnouncer);
  private keyManager?: ActiveDescendantKeyManager<TagOptionComponent>;

  ngAfterViewInit(): void {
    // El CDK aporta flechas, Home/End, búsqueda por escritura y ciclado.
    this.keyManager = new ActiveDescendantKeyManager(this.opciones())
      .withWrap()
      .withTypeAhead(200);
  }

  protected onKeydown(event: KeyboardEvent): void {
    if (event.key === 'Escape') { this.abierto.set(false); return; }
    if (event.key === 'Enter' && this.keyManager?.activeItem) {
      this.alternar(this.keyManager.activeItem.tag());
      event.preventDefault();
      return;
    }
    this.keyManager?.onKeydown(event);
  }

  protected alternar(tag: Tag): void {
    const actuales = this.selected();
    const yaEsta = actuales.some((t) => t.id === tag.id);
    this.selected.set(yaEsta ? actuales.filter((t) => t.id !== tag.id) : [...actuales, tag]);
    this.announcer.announce(`${tag.name} ${yaEsta ? 'quitada' : 'añadida'}`, 'polite');
  }
}

24.8 Tailwind con Angular

Tailwind propone algo que a mucha gente le parece un retroceso: volver a poner las clases de presentación en el marcado. La justificación es sólida y conviene entenderla antes de opinar. El problema que ataca no es escribir CSS, sino nombrarlo: si cada componente inventa nombres de clase, la hoja de estilos crece con el número de pantallas y nadie se atreve a borrar nada. Con utilidades atómicas, el conjunto de clases es cerrado y el CSS generado deja de crecer a partir de cierto punto, por muchas pantallas que añadas.

24.8.1 Integración y por qué funciona pese a la encapsulación

La pregunta que todo el mundo hace la primera vez es cómo puede funcionar Tailwind si Angular aísla los estilos. La respuesta desmonta un malentendido frecuente: la encapsulación emulada reescribe los selectores de las hojas de tus componentes, no los atributos class de tu plantilla. Las utilidades de Tailwind viven en la hoja global, y una regla global se aplica a cualquier elemento que tenga la clase, esté donde esté. No hay conflicto porque no hay competencia: son dos mecanismos ortogonales.

# Instalación (la configuración exacta depende de la versión mayor de Tailwind:
# la 3 usa tailwind.config.js con la clave content; la 4 se configura desde CSS
# con @import y @theme. Sigue la guía oficial de TU versión).
npm install -D tailwindcss

# Tailwind 3 · src/styles.css        Tailwind 4 · src/styles.css
#   @tailwind base;                    @import "tailwindcss";
#   @tailwind components;              @theme { --color-tf-accent: #4571e8; }
#   @tailwind utilities;

24.8.2 Cuándo acelera y cuándo produce plantillas ilegibles

Tailwind acelera de verdad en la fase de exploración: maquetar una pantalla nueva sin cambiar de archivo es notablemente más rápido. Se degrada cuando la misma cadena de veinte clases aparece en once sitios, porque entonces has reinventado la duplicación que el CSS con nombres al menos permitía centralizar. El patrón correcto es el mismo de siempre: extraer un componente en cuanto una combinación se repite. No una clase con @apply —eso reintroduce el problema del nombrado sin ganar nada—, sino un componente de Angular con su API.

<!-- La misma cadena repetida en cada pantalla. Cambiar el radio
     de las tarjetas exige buscar y reemplazar en 11 archivos -->
<article class="flex items-center gap-3 rounded-lg border border-slate-200
                bg-white p-4 shadow-sm hover:shadow-md transition-shadow
                dark:border-slate-700 dark:bg-slate-800">
  <h3 class="flex-1 min-w-0 truncate text-sm font-medium
             text-slate-900 dark:text-slate-100">{{ task.title }}</h3>
  <span class="shrink-0 rounded-full bg-amber-100 px-2 py-0.5 text-xs
               font-semibold text-amber-800">{{ task.priority }}</span>
</article>

// Las utilidades viven UNA vez, dentro del componente que las justifica
@Component({
  selector: 'tf-task-card',
  host: { class: 'flex items-center gap-3 rounded-lg border p-4' },
  template: `
    <h3 class="flex-1 min-w-0 truncate text-sm font-medium">{{ task().title }}</h3>
    <tf-badge [tone]="tone()">{{ task().priority }}</tf-badge>
  `,
})
export class TaskCardComponent {
  readonly task = input.required<Task>();
  protected readonly tone = computed(() =>
    this.task().priority === 'high' ? 'danger' : 'neutral');
}

// Y en las 11 pantallas:  <tf-task-card [task]="task" />

24.9 Diseño responsive

24.9.1 Móvil primero no es una preferencia estética

Escribir primero los estilos del caso estrecho y ampliar con min-width tiene tres consecuencias técnicas concretas: el CSS base es el más simple (menos declaraciones que sobrescribir), los dispositivos menos potentes ejecutan menos reglas, y —la más importante— obliga a decidir la jerarquía de la información. En 360 píxeles no cabe todo, así que hay que responder a «¿qué es lo imprescindible de una tarea?» antes de maquetar. Esa respuesta mejora también la versión de escritorio.

/* Base: el caso más restrictivo, sin ninguna consulta de medios */
.task-list { display: grid; gap: var(--tf-space-2); }
.task-list__filters { display: none; }        /* en móvil van en un panel aparte */

/* Ampliación progresiva: solo se AÑADE, nunca se deshace */
@media (min-width: 48rem) {                   /* en rem, para respetar el zoom */
  .task-list { grid-template-columns: 1fr 280px; gap: var(--tf-space-4); }
  .task-list__filters { display: block; }
}

Los puntos de ruptura se eligen por el contenido, no por dispositivos. Perseguir los tamaños de los modelos de teléfono de moda es una carrera perdida: hay cientos y cambian cada año. El criterio correcto es ensanchar la ventana hasta que la maquetación se vea mal y poner ahí el punto de ruptura. Con las técnicas de la sección 24.4 —auto-fit, clamp() y contenedores de consulta— una aplicación como TaskFlow necesita dos o tres puntos de ruptura globales, no siete.

24.9.2 CDK de layout frente a consultas de medios

24.9.3 Imágenes adaptativas

Servir una imagen de 2000 píxeles de ancho a un teléfono es de los desperdicios más caros que existen: consume datos del usuario, retrasa la pintura y ocupa memoria de decodificación. Angular incluye una directiva que aplica las buenas prácticas por defecto y avisa en consola cuando algo está mal.

<!-- NgOptimizedImage: genera el srcset, exige dimensiones (evita saltos de
     diseño) y aplica carga diferida salvo que marques la imagen como prioritaria -->
<img [ngSrc]="project.coverUrl"
     width="640" height="360"
     sizes="(min-width: 64rem) 320px, 100vw"
     [priority]="esPrimeraVisible"
     alt="Portada del proyecto {{ project.name }}">

<!-- Avatar del responsable: decorativo junto a un nombre visible → alt vacío -->
<img [ngSrc]="user.avatarUrl" width="32" height="32" alt="" class="avatar">

• Siempre width y height (o fill con un contenedor posicionado): sin ellos el navegador no reserva espacio y el contenido salta al cargar la imagen, que es la principal causa de mala puntuación en desplazamiento acumulado del diseño.
• priority solo en la imagen más grande visible al cargar, típicamente una por página. Marcarlo todo como prioritario equivale a no priorizar nada.
• sizes importa tanto como srcset: sin él el navegador supone que la imagen ocupa todo el ancho y descarga la variante más grande aunque tu tarjeta mida 320 píxeles.

24.10 Animaciones

24.10.1 Cuándo aportan y cuándo estorban

Una animación es útil cuando explica un cambio: de dónde viene ese panel, adónde ha ido la tarea que acabo de archivar, qué elemento es el que ha cambiado. Estorba cuando decora sin informar, cuando se interpone entre la intención del usuario y el resultado, o cuando se repite cientos de veces al día. Ese último punto es el que más se olvida: una animación de 400 milisegundos es deliciosa la primera vez y una tortura la número doscientas.

• Duraciones: entre 120 y 200 milisegundos para elementos pequeños (un menú, una casilla), entre 200 y 320 para paneles y diálogos. Por encima de 400 se percibe como lentitud, no como elegancia.
• Curvas: salidas rápidas y entradas suaves. Un elemento que aparece debe frenar al llegar; uno que desaparece debe irse deprisa, porque el usuario ya ha decidido.
• Nunca bloquees: si el usuario pulsa dos veces seguidas, la segunda acción no puede esperar a que termine la primera animación.

24.10.2 CSS frente a la API de animaciones de Angular

import { animate, animateChild, query, stagger, style,
         transition, trigger } from '@angular/animations';

@Component({
  selector: 'tf-task-list',
  animations: [
    trigger('listaTareas', [
      transition('* => *', [
        // El escalonado da sensación de orden; 40 ms por elemento es suficiente.
        query(':enter', [
          style({ opacity: 0, transform: 'translateY(8px)' }),
          stagger(40, animate('180ms cubic-bezier(.2,0,0,1)',
                              style({ opacity: 1, transform: 'none' }))),
        ], { optional: true }),

        query(':leave', [
          animate('120ms ease-in', style({ opacity: 0, transform: 'translateY(-4px)' })),
        ], { optional: true }),
      ]),
    ]),
  ],
  template: `
    <ul [@listaTareas]="tasks().length">
      @for (task of tasks(); track task.id) {
        <li><tf-task-card [task]="task" /></li>
      }
    </ul>
  `,
})
export class TaskListComponent {}

24.10.3 Rendimiento: qué se puede animar y qué no

Para entender por qué unas propiedades van fluidas y otras a tirones hay que saber qué hace el navegador en cada fotograma. El proceso tiene tres etapas encadenadas: diseño (calcular la geometría de cada elemento), pintado (rellenar los píxeles de cada capa) y composición (combinar las capas en la imagen final). Animar una propiedad obliga a repetir su etapa y todas las posteriores, sesenta veces por segundo.

De ahí la regla que conviene grabarse: anima transform y opacity; todo lo demás, replantéalo. Casi cualquier animación se puede reescribir en esos términos: mover es translate, crecer es scale, aparecer es opacity.

/* Recálculo de diseño en CADA fotograma: el panel va
   a tirones y arrastra a toda la página con él */
.sidebar {
  left: -320px;
  transition: left 250ms ease, width 250ms ease;
}
.sidebar.is-open { left: 0; }

/* Y esto es aún peor: anima 'height' desde auto,
   que además ni siquiera es interpolable */
.task-details { height: 0; transition: height 200ms; }
.task-details.is-open { height: auto; }

/* Solo composición: fluido incluso en un móvil modesto */
.sidebar {
  transform: translateX(-100%);
  transition: transform var(--tf-dur-base) var(--tf-ease);
  will-change: transform;      /* solo si de verdad se anima a menudo */
}
.sidebar.is-open { transform: none; }

/* Para desplegar contenido, usa una rejilla: la fracción SÍ interpola
   y no necesitas conocer la altura de antemano */
.task-details { display: grid; grid-template-rows: 0fr;
                transition: grid-template-rows var(--tf-dur-base) var(--tf-ease); }
.task-details.is-open { grid-template-rows: 1fr; }
.task-details > * { overflow: hidden; }

24.10.4 Movimiento reducido: es un requisito, no un detalle

Hay personas para las que el movimiento en pantalla provoca mareo, náuseas o crisis vestibulares reales. Por eso todos los sistemas operativos tienen un ajuste de «reducir movimiento», y por eso las WCAG lo recogen explícitamente. Respetarlo cuesta cinco líneas de CSS y no respetarlo puede hacer tu aplicación literalmente inutilizable para alguien.

@media (prefers-reduced-motion: reduce) {
  /* Ojo: NO se elimina la transición, se acorta a un valor imperceptible.
     Poner 0s puede romper componentes que esperan el evento transitionend. */
  *, *::before, *::after {
    animation-duration: .01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: .01ms !important;
    scroll-behavior: auto !important;
  }
}

/* Mejor aún: que las duraciones vengan de tokens y cambiar el token */
@media (prefers-reduced-motion: reduce) {
  :root { --tf-dur-fast: .01ms; --tf-dur-base: .01ms; --tf-dur-slow: .01ms; }
}

24.11 Componentes de interfaz propios bien diseñados

Antes de escribir un componente conviene decidir si hay que escribirlo. Este es el árbol de decisión que uso en revisiones de arquitectura:

  ¿NECESITO UN COMPONENTE DE INTERFAZ?  →  ¿DE DÓNDE LO SACO?

            ¿existe ya en NUESTRA librería interna?
                     │ sí → úsalo. Si no encaja, MEJÓRALO ahí (no lo copies)
                     │ no
                     ▼
            ¿es un patrón COMPLEJO y estándar?
            (diálogo, selector de fecha, tabla con orden y paginación,
             autocompletado, árbol, deslizador)
                     │ no ──────────────────────────────┐
                     │ sí                               │
                     ▼                                  ▼
        ¿usamos Angular Material               ¿necesita COMPORTAMIENTO difícil?
         y su estética nos vale?               (posicionar flotantes, atrapar el
                     │                          foco, virtualizar, arrastrar,
          ┌──────────┴──────────┐               navegar con flechas)
          │ sí                  │ no                    │
          ▼                     ▼              ┌────────┴────────┐
    ┌───────────┐      ┌──────────────┐        │ sí              │ no
    │  MATERIAL │      │ CDK + estilos│        ▼                 ▼
    │  + tokens │      │    propios   │  ┌──────────┐     ┌─────────────┐
    └───────────┘      └──────────────┘  │   CDK    │     │ CSS + HTML  │
                                          │ + estilos│     │   propios   │
                                          │  propios │     │ (lo más     │
                                          └──────────┘     │  barato)    │
                                                            └─────────────┘

  COSTE TOTAL DE PROPIEDAD (mantenimiento a 3 años, de menor a mayor):
    CSS propio  <  CDK + estilos propios  <  Material con tokens
       <  Material muy personalizado  <<  librería externa sin mantenimiento

  SEÑAL DE ALARMA: si has escrito ::ng-deep tres veces sobre el mismo
  componente de Material, estabas en la rama equivocada del árbol.

24.11.1 La API pública: entradas, salidas y contenido

Un componente de interfaz es una API, y las reglas del buen diseño de API se le aplican enteras. La más importante: una entrada por decisión, no una entrada por detalle visual. En cuanto veas un componente con [paddingTop], [borderColor] y [titleFontSize], sabes que alguien está reimplementando el CSS a través de TypeScript, con el coste añadido de que cada una de esas entradas pasa por la detección de cambios.

@Component({
  selector: 'tf-panel',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <section class="panel" [class]="'panel--' + tone()">
      <header class="panel__head">
        <h3 class="panel__title">{{ heading() }}</h3>
        <!-- Ranura con selector: el consumidor decide las acciones -->
        <div class="panel__actions"><ng-content select="[panelActions]" /></div>
      </header>

      @switch (state()) {
        @case ('loading') { <tf-skeleton rows="3" /> }
        @case ('error')   { <ng-content select="[panelError]" /> }
        @case ('empty')   { <ng-content select="[panelEmpty]" /> }
        @default          { <div class="panel__body"><ng-content /></div> }
      }
    </section>
  `,
  styles: `
    /* Tokens del componente: puntos de extensión PUBLICADOS y documentados.
       El consumidor los redefine desde fuera sin ::ng-deep y sin entradas. */
    :host {
      display: block;
      --tf-panel-bg: var(--tf-surface-2);
      --tf-panel-radius: var(--tf-radius-md);
      --tf-panel-pad: var(--tf-space-4);
    }
    .panel { background: var(--tf-panel-bg); border-radius: var(--tf-panel-radius);
             padding: var(--tf-panel-pad); border: 1px solid var(--tf-border); }
    .panel--danger { --tf-panel-bg: color-mix(in srgb, var(--tf-danger) 8%, var(--tf-surface-2)); }
  `,
})
export class PanelComponent {
  readonly heading = input.required<string>();
  readonly tone = input<'neutral' | 'danger' | 'success'>('neutral');
  readonly state = input<'idle' | 'loading' | 'empty' | 'error'>('idle');
}

// Uso: la personalización visual va por CSS, no por entradas
// <tf-panel heading="Tareas urgentes" [state]="state()" style="--tf-panel-radius: 20px">
//   <button panelActions (click)="crear()">Nueva</button>
//   <p panelEmpty>No hay tareas urgentes. Buenas noticias.</p>
//   <tf-task-list [tasks]="tasks()" />
// </tf-panel>

24.12 Estados vacíos, esqueletos y percepción de velocidad

La velocidad percibida y la velocidad medida no son lo mismo, y la percibida es la que decide si tu aplicación «va bien». Un indicador de progreso giratorio comunica «espera, no sé cuánto»; un esqueleto comunica «esto es lo que va a llegar y llega ya». Con el mismo tiempo real, el esqueleto se percibe más rápido por dos motivos: mantiene al usuario orientado —la estructura de la página ya está ahí— y le da algo que procesar mientras espera, lo que acorta la percepción del tiempo muerto.

@Component({
  selector: 'tf-skeleton',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @for (row of rows(); track $index) {
      <div class="sk" [style.inline-size.%]="row" aria-hidden="true"></div>
    }
    <span class="sr-only" role="status">Cargando tareas</span>
  `,
  styles: `
    :host { display: grid; gap: var(--tf-space-2); }
    .sk {
      block-size: 1rem; border-radius: var(--tf-radius-sm);
      background: linear-gradient(90deg, var(--tf-surface-3) 25%,
                  var(--tf-surface-2) 37%, var(--tf-surface-3) 63%);
      background-size: 400% 100%;
      animation: sk 1.2s ease-in-out infinite;   /* transform/opacity no valen aquí:
                                                    es background-position, coste medio */
    }
    @keyframes sk { from { background-position: 100% 50% } to { background-position: 0 50% } }
    @media (prefers-reduced-motion: reduce) { .sk { animation: none } }
  `,
})
export class SkeletonComponent {
  readonly count = input(3, { transform: numberAttribute });
  protected readonly rows = computed(() =>
    Array.from({ length: this.count() }, (_, i) => (i % 3 === 2 ? 60 : 100)));
}

• El esqueleto debe tener las dimensiones del contenido real. Si la tarjeta mide 72 píxeles y el esqueleto 40, al llegar los datos todo salta: has cambiado un problema de espera por uno de desplazamiento acumulado del diseño, que es peor porque provoca clics erróneos.
• Umbral de aparición. Si la respuesta llega en 150 milisegundos, mostrar un esqueleto produce un parpadeo molesto. Muéstralo solo a partir de unos 200-300 milisegundos, y una vez mostrado mantenlo un mínimo para que no desaparezca de golpe.
• Marca el estado para la tecnología asistiva con role="status" y oculta las barras decorativas con aria-hidden; un lector de pantalla no debe leer doce rectángulos.
• Un estado vacío es una oportunidad, no un error. «No hay tareas» es información inútil. «Todavía no hay tareas en este proyecto» más un botón de «Crear la primera tarea» y una frase sobre qué se puede hacer aquí convierte un callejón sin salida en el mejor momento para enseñar el producto. Distingue siempre vacío por primera vez de vacío por un filtro: en el segundo caso lo útil es ofrecer quitar el filtro.

24.13 Storybook: qué aporta y qué cuesta

Storybook es un entorno que renderiza tus componentes aislados de la aplicación, con controles para cambiar sus entradas en vivo. Su valor no es la galería bonita, sino cuatro cosas concretas: desarrollar un componente sin navegar por la aplicación hasta el estado que quieres reproducir; forzarte a declarar todos los estados (incluidos los feos, que es donde están los fallos); dar a diseño y a producto un sitio donde ver lo que existe sin pedir un despliegue; y servir de base para pruebas de regresión visual e inspección de accesibilidad automatizada.

import type { Meta, StoryObj } from '@storybook/angular';
import { TaskCardComponent } from './task-card.component';

const meta: Meta<TaskCardComponent> = {
  title: 'Tareas/TaskCard',
  component: TaskCardComponent,
  tags: ['autodocs'],
  argTypes: { variant: { control: 'inline-radio', options: ['default', 'compact'] } },
};
export default meta;
type Story = StoryObj<TaskCardComponent>;

export const PorDefecto: Story = { args: { task: unaTarea() } };

/* Los estados incómodos: son los que rompen la maquetación en producción */
export const TituloMuyLargo: Story = {
  args: { task: unaTarea({ title: 'Revisar y consolidar el informe trimestral de incidencias '.repeat(3) }) },
};
export const SinResponsableNiFecha: Story = {
  args: { task: unaTarea({ assignee: null, dueDate: null }) },
};
export const ConCatorceEtiquetas: Story = { args: { task: unaTarea({ tags: muchasEtiquetas(14) }) } };
export const Cargando: Story = { args: { state: 'loading' } };

24.14 Rendimiento de la capa visual

El JavaScript se lleva toda la atención, pero en muchas aplicaciones el camino crítico está en los estilos, las fuentes y las imágenes. Un detalle decisivo: el CSS bloquea la pintura. Mientras el navegador descarga y analiza una hoja de estilos referenciada en el <head>, no pinta nada. Un archivo de estilos de 900 KB no es «un poco de peso extra»: es medio segundo de pantalla en blanco en una conexión mediocre.

24.15 Errores comunes y cómo solucionarlos

24.16 Buenas y malas prácticas

24.17 Preguntas frecuentes

24.18 Ejercicios

/* ANTES: tres reglas acopladas que hay que mantener sincronizadas */
/* h1 { font-size: 22px }
   @media (min-width: 640px)  { h1 { font-size: 28px } }
   @media (min-width: 1024px) { h1 { font-size: 34px } } */

/* DESPUÉS. Cómo se obtienen los coeficientes:
   queremos 22px (1.375rem) a 360px de ancho y 34px (2.125rem) a 1280px.
   pendiente = (34 - 22) / (1280 - 360) = 0.01304  →  1.304vw
   base      = 22 - 0.01304 * 360 = 17.3px = 1.081rem                       */
:root {
  --tf-fs-h1: clamp(1.375rem, 1.081rem + 1.3vw, 2.125rem);
  --tf-fs-h2: clamp(1.125rem, 0.98rem + 0.65vw, 1.5rem);
  --tf-pad-seccion: clamp(0.75rem, 0.4rem + 1.4vw, 2rem);
}

h1 { font-size: var(--tf-fs-h1); }
h2 { font-size: var(--tf-fs-h2); }
.section { padding-block: var(--tf-pad-seccion); }

/* Verificación: con zoom al 200 % el navegador duplica el valor de rem,
   así que el mínimo pasa de 22px a 44px. Si hubiéramos escrito
   clamp(22px, 4vw, 34px) el texto NO habría crecido: fallo de accesibilidad. */

:host {
  display: block;
  container-type: inline-size;
  container-name: task-card;
}

/* Base: el caso más estrecho. Todo apilado, solo lo imprescindible. */
.task-card { display: grid; gap: var(--tf-space-2); padding: var(--tf-space-3);
             background: var(--tf-surface-2); border-radius: var(--tf-radius-md); }
.task-card__title { font-size: var(--tf-fs-md); min-width: 0;
                    overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.task-card__assignee,
.task-card__project,
.task-card__description { display: none; }

/* ≥ 380px de CONTENEDOR: cabe una segunda columna con el responsable */
@container task-card (min-width: 380px) {
  .task-card { grid-template-columns: 1fr auto; align-items: center;
               column-gap: var(--tf-space-4); }
  .task-card__assignee { display: flex; }
}

/* ≥ 620px: hay sitio para proyecto y descripción resumida */
@container task-card (min-width: 620px) {
  .task-card { grid-template-columns: 1fr auto auto; padding: var(--tf-space-4); }
  .task-card__project { display: inline-flex; }
  .task-card__description { display: block; grid-column: 1 / -1;
                            color: var(--tf-text-muted); }
}

/* Comprobación: colócala en .board__column (300px) y en .task-detail (700px).
   El MISMO componente, sin entradas y sin que el padre sepa nada de él,
   se muestra compacto en una y completo en la otra. Con consultas de medios
   esto era imposible: la ventana mide lo mismo en los dos casos. */

/* --- Panel lateral: de 'left' a 'transform' --- */
.sidebar {
  position: fixed; inset-block: 0; inset-inline-start: 0; inline-size: 320px;
  transform: translateX(-100%);          /* fuera de pantalla, sin animar 'left' */
  transition: transform var(--tf-dur-base) var(--tf-ease);
  will-change: transform;                /* solo aquí: se anima muy a menudo */
}
.sidebar.is-open { transform: translateX(0); }

/* El fondo oscuro entra con opacidad, que también es de composición.
   visibility se transiciona con 'step-end' para que no capture clics al cerrarse. */
.backdrop { opacity: 0; visibility: hidden;
            transition: opacity var(--tf-dur-base) var(--tf-ease),
                        visibility 0s linear var(--tf-dur-base); }
.backdrop.is-open { opacity: 1; visibility: visible; transition-delay: 0s; }

/* --- Detalles de la tarea: altura desconocida sin animar 'height' --- */
.task-details {
  display: grid;
  grid-template-rows: 0fr;               /* 0fr y 1fr SÍ interpolan */
  transition: grid-template-rows var(--tf-dur-base) var(--tf-ease);
}
.task-details.is-open { grid-template-rows: 1fr; }
.task-details > .task-details__inner { overflow: hidden; }  /* imprescindible */

@media (prefers-reduced-motion: reduce) {
  .sidebar, .backdrop, .task-details { transition-duration: .01ms; }
}

/* Medición esperada en el panel de rendimiento del navegador:
   la versión con 'left' muestra barras moradas de recálculo de diseño en
   cada fotograma; la de 'transform' solo muestra composición, y en un móvil
   modesto la diferencia entre 60 y ~25 fotogramas por segundo es evidente
   a simple vista. La de grid-template-rows sí recalcula el diseño, pero solo
   dentro del panel desplegado y no en todo el documento. */

24.19 Resumen del capítulo

24.20 Recursos adicionales

• angular.dev — documentación oficial de Angular: estilos de componente, encapsulación de vistas, animaciones y la directiva de imagen optimizada. Es la referencia para saber qué ofrece tu versión.
• material.angular.io — Angular Material: guía de temas, catálogo de componentes con ejemplos vivos y notas de migración entre versiones mayores (el sitio redirige a la documentación actual del proyecto).
• Angular CDK — overlay, portal, arrastrar y soltar, scroll virtual, layout, accesibilidad, portapapeles y campos de texto, cada uno con su API y sus ejemplos.
• MDN · CSS — la referencia del lenguaje, con tablas de compatibilidad. Imprescindible para @container, :has(), @layer, @property y light-dark().
• MDN · CSS Grid Layout — guías completas de rejilla, incluidas las áreas nombradas y las funciones de repetición automática.
• Tailwind CSS — documentación oficial, con las guías de instalación y de configuración, que cambian de forma notable entre versiones mayores.
• Storybook — documentación oficial, incluida la guía específica para Angular y los complementos de accesibilidad y pruebas.
• ARIA Authoring Practices Guide — los patrones de teclado y ARIA que implementan Material y el CDK, y la referencia obligada si construyes un componente propio.
• web.dev · Core Web Vitals — definición y medición de las métricas de rendimiento percibido citadas en la sección 24.14.