Product Craft Bible
Deprecation & migration UX
Inicio SaaS y Admin Deprecation & migration UX
SaaS y Admin

Deprecation & migration UX

8 reglas GitHub REST API versions (24 meses) · AWS Service Lifecycle (~12 meses) · Slack Design "On writing for deprecation" (60 días) · Caso UserIntuitionNN/g "3 I's of Microcopy" (razón + que cambia + que no) · NN/g "Visibility of System Status" · Slack Design "On writing for deprecation"Stripe API upgrades (checklist por versión) · GitHub Teams API sunset (endpoint alterno) · Nordic APIs · Caso UserIntuition (-$830K, dato de caso)NN/g "Indicators, Validations, and Notifications" · NN/g "Onboarding Tutorials" (pull > push) · Slack Design · Appcues
133

Deprecation & migration UX

8 reglas
1174

Anuncia con una fecha de sunset concreta y suficiente anticipación

Las deprecaciones sorpresa destruyen la confianza. El aviso debe incluir una fecha calendario fija (no "proximamente") y publicarse con tiempo para que el usuario planifique. La industria convergio en ventanas según el alcance: GitHub mantiene cada versión de su REST API por al menos 24 meses tras liberar la siguiente, AWS retira servicios con timelines típicos de 12 meses, y Slack muestra el banner in-app 60 días antes del retiro. La fecha no debe cambiar después de anunciada, salvo pausa justificada publicamente.

GitHub REST API versions (24 meses) · AWS Service Lifecycle (~12 meses) · Slack Design "On writing for deprecation" (60 días) · Caso UserIntuition
Preferir
Esta función se elimina el 31 de octubre de 2026.
Faltan 135 días
Evitar
Planeamos deprecar esta función en el futuro cercano.
1175

Explica el porque del cambio y el beneficio concreto al migrar

Un aviso de deprecación sin justificación se percibe como arbitrario y genera resistencia. El usuario necesita entender la razón real (seguridad, deuda técnica, mejor alternativa) y la ganancia tangible al migrar. NN/g documenta el patrón correcto: anunciar que cambia, por que cambia y que permanece igual; su heuristica #1 establece que ninguna acción con consecuencias debe tomarse sin informar al usuario. El lenguaje corporativo vago ("optimizando nuestra plataforma") activa desconfianza; la honestidad sobre las restricciones se acepta mejor.

NN/g "3 I's of Microcopy" (razón + que cambia + que no) · NN/g "Visibility of System Status" · Slack Design "On writing for deprecation"
Preferir
Por que cambia
Estamos retirando la exportación en CSV porque el nuevo formato XLSX conserva formato, formulas y soporta archivos >65k filas. Tu flujo actual funcionara igual hasta el 1 de enero de 2027.
Evitar
Aviso
Esta función ha sido descontinuada. Por favor actualiza tu integración.
1176

Ofrece una ruta de migración guiada, no solo "esto desaparece"

Anunciar que algo desaparece sin decir adonde ir es una notificación a medias. Cada aviso debe incluir que reemplaza la feature, pasos concretos para migrar y un enlace a documentación accionable. Stripe define explicitamente cambios backward-compatible vs. breaking y entrega un checklist de migración por versión mayor; GitHub, al deprecar endpoints del Teams API, incluyo el endpoint alternativo exacto. En un caso documentado por UserIntuition, la ausencia de soporte a la migración costo neto -$830K en el año 1 (caso único, no estudio controlado).

Stripe API upgrades (checklist por versión) · GitHub Teams API sunset (endpoint alterno) · Nordic APIs · Caso UserIntuition (-$830K, dato de caso)
Preferir
Migra en 3 pasos antes del 1 de octubre
1Descarga tu historial desde Reportes > Exportar.
2Activa el nuevo módulo en Configuración > Reportes.
3Tus automatizaciones existentes se migraran automáticamente.
Ver guía completa
Evitar
El módulo de reportes legacy fue removido. Contactanos si tienes preguntas.
1177

Muestra el aviso en contexto, no solo por correo

Los correos de deprecación solos no bastan: el usuario puede no leerlos o no conectarlos con su flujo real. El aviso contextual, colocado en la UI de la propia feature deprecada, alcanza al usuario en el momento exacto en que le es relevante. NN/g documenta el fracaso de notificaciones pasivas descontextualizadas (una usuaria espero 5 minutos porque no vio el mensaje al pie de pantalla) y recomienda revelaciones pull (contextuales) sobre push (globales). Slack confirma que el canal in-product es el primario; el email es el respaldo para usuarios inactivos.

NN/g "Indicators, Validations, and Notifications" · NN/g "Onboarding Tutorials" (pull > push) · Slack Design · Appcues
Preferir
Editor legacy
Este editor se retira el 31 de marzo. Probar el nuevo →
Evitar
Editor legacy
solo por email
1178

Manten lo viejo y lo nuevo en paralelo: periodo de coexistencia

La migración forzada crea fricción máxima. El patrón correcto ofrece un periodo de coexistencia donde el usuario usa ambas versiones y migra a su ritmo. Google Cloud AIP-185 establece que distintas versiones de la misma API deben poder convivir en un mismo cliente durante una transición razonable; Stripe fija la versión por cuenta y permite probar la nueva con el header Stripe-Versión sin alterar la cuenta, con ventana de reversión. NN/g recuerda que los usuarios odian el cambio: las quejas no implican que el nuevo diseño sea peor. Deprecación y sunset son fases distintas.

Google Cloud AIP-185 (versiones en paralelo) · Stripe API versioning (pinned por cuenta) · NN/g "Users Hate Change" · Nordic APIs
Preferir
Elige tu editor (ambos disponibles hasta el 1 jun 2027)
Editor actual
Disponible hasta jun 2027
Editor nuevo
Probalo ahora
Cambia entre ambos desde Preferencias. Migra cuando quieras.
Evitar
El 1 de noviembre todos los usuarios fueron migrados automáticamente al nuevo editor, sin opción de retorno.
1179

Escala la urgencia del aviso conforme se acerca la fecha

Un aviso informacional dado 90 días antes tiene el mismo peso visual que uno dado 3 días antes si no se escala. El sistema correcto usa tres fases: awareness pasivo (chip dismissable, tono neutro), advertencia activa (banner persistente, acción requerida) y bloqueo final (dialog no-dismissable que reempaca todo el contexto). Slack documenta esas tres fases; NN/g reserva el modal para acciones destructivas o cuando falta información para continuar. Usar tono critico desde el día uno es gritar "lobo": el usuario aprende a ignorarlo.

Slack Design (3 fases: 60+/30/final) · NN/g "Modal & Nonmodal Dialogs" · GitHub Deprecation + Sunset headers
Preferir
Día 90Retiro programado: 1 jun 2027 · Saber más
Día 30Quedan 30 días. Migra tu flujo →
Día 7Se retira en 7 días. Completa la migración ahora.
Evitar
Día 90Critico: se retira pronto
Día 30Critico: se retira pronto
Día 7Critico: se retira pronto (ya ignorado)
1180

Nunca rompas un flujo activo sin ruta de rescate de datos

Hay una diferencia fundamental entre deprecar una comodidad y deprecar algo que contiene datos del usuario o soporta un flujo de negocio activo. Para el segundo caso la regla es absoluta: no cortar el acceso sin garantizar que los datos son exportables, migrables o transferidos antes del cutoff. AWS exige en su politica proveer alternativas y soporte a la migración para minimizar disrupciones; GitHub pauso el sunset del Teams API en marzo 2022 por presión de la comunidad, evidencia de que ejecutar sin ruta de rescate es reversible pero costoso en reputación. La protección aplica a features estables, no a betas/previews. Planear la ruta es prerrequisito del anuncio, no su consecuencia.

AWS Service Lifecycle (alternativas + soporte) · GitHub Teams API sunset pausado (mar 2022) · GitHub ToS (betas sin garantía) · UserIntuition (planear antes de anunciar)
Preferir
Facturación legacy se cierra el 31 de diciembre
Exporta todas tus facturas PDFXML
Tus facturas de 2024 en adelante ya están en el nuevo módulo. Exporta el historial completo desde Configuración > Exportar datos antes del cierre.
Evitar
Facturación legacy cerrada el 31 de diciembre
No hay exportación disponible. Los usuarios que no migraron pierden acceso a su historial.
1181

Avisos accesibles y claros, sin urgencia falsa

Los avisos de deprecación deben cumplir WCAG 2.1 AA para ser perceptibles por todos. Esto implica anunciar el mensaje con role="alert" o role="status" (SC 4.1.3, el contenedor debe existir vacio en el DOM al cargar), no depender solo del color para la severidad (SC 1.4.1: icono o etiqueta de texto redundante), y mantener contraste de texto >= 4.5:1 (SC 1.4.3). La urgencia falsa, un countdown que se reinicia o "actua ahora" sin deadline real, es un dark pattern inverificable que erosiona la credibilidad de todos los avisos futuros: usa la fecha fija, no un contador.

WCAG 2.1 SC 4.1.3 (Status Messages) · SC 1.4.1 (Use of Color) · SC 1.4.3 (Contrast) · W3C ARIA APG Alert · think.design "False urgency"
Preferir
Aviso de deprecación
Esta función se retira el 31 de marzo de 2027. Contraste verificado 7.2:1.
role="alert"
Evitar
Esta función se elimina. Actua ahora.
¡Quedan 3 días! (se reinicia al recargar)