Sistemas de diseño y su documentación

1) ¿Qué es un sistema de diseño y por qué lo necesita?

El sistema de diseño es una única fuente de verdad para la interfaz: un conjunto de tokens, componentes, prácticas y documentación que proporciona previsibilidad UX, velocidad de desarrollo y escalabilidad.

• Consistencia de la capa visual y conductual en todos los productos.
• Velocidad: reutilización de componentes, menos costos de rugido.
• Calidad: patrones generales de A11y, localización, pruebas, estándares de contenido.
• Manejabilidad: responsabilidad clara, lanzamientos, hoja de ruta.

2) Arquitectura del sistema de diseño (capas)

1. Fichas de diseño (fundación): colores, tipografía, dimensiones, radios, sombras, sangrías, estados, así como fichas semánticas ('color. surface. warning`, `space. xs`).
2. Componentes de IU: botones, campos de entrada, ventanas modales, dropdowns, tablas, tostadas, pancartas, alertas, estados vacíos, esqueletos.
3. Patrones y composiciones: formularios KYC, flow de pago, resultados nulos, asistentes paso a paso, tarjetas de contenido.
4. Contenido hyde (microcopy): tono, diccionario de términos, patrones de error/éxito, push/banners.
5. Infraestructura: hyde por A11y, pruebas, localización, versiones, pestañas (contributing).

3) Tokens de diseño: principios

Semántica> estilo «crudo». Use 'color. text. muted 'en lugar de' # 6B7280 '.
Tematización y plataformas. Tokens fuente → plataformas mappings (Web, iOS, Android, email).
Tema claro/oscuro y contraste de WCAG a nivel de tokens.
Escalas globales y contextuales: 'espacio. 2`, `radius. md`, `elevation. 1`, `opacity. disabled`.
Versionar tokens: cambios - a través de políticas de depreción y notas de migración.

4) Componentes: requisitos y composición de la página en la documentación

• Descripción y destino. Cuándo usar/no utilizar.
• Opciones/estados. Dimensiones, vistas (primary/secondary/ghost), disabled, loading, destructive.
• Disponibilidad. Papel, navegación por teclado, 'aria-', contraste, anillos de enfoque.
• Texto y ejemplos de microcopia. Etiquetas válidas/playsholder, errores, ayuda.
• Ejemplos de código. APIs mínimas, controladas/desactivadas.
• Integración con formularios e i18n. Casos de líneas largas, números/monedas/fechas.
• Ejemplos anti. Patrones de uso erróneos.
• La matriz de prueba. Snapshots visuales, unit/interaction, screenriders.

5) Patrones de composición (Recipes)

Formularios de registro/CUS: paso a paso, progreso, validación en línea + resumen, patrones de error.
flow de pago: selección de método, comisiones, plazos, regla de same-method, confirmación y estado.
Estados vacíos: contexto + valor + CTA, resultados de búsqueda nulos.
Mensajes de éxito/error: jerarquía de estados, señales visuales, tostadas/banners/modales.
Navegación y filtros: búsqueda global, presets rápidos, etiquetas.
Las páginas de patrones deben mostrar una composición de componentes lista para copiar, con microcopia y notas A11y.

6) Hyde de contenido (voz y tono, microcopy)

Voz: profesional, clara; el tono depende del contexto (onboarding, pago, seguridad).
Diccionario único de términos: pagos, bonos, límites, KYC - un valor por producto.
Plantillas: CTA, errores, advertencias, aciertos, estados vacíos, notificaciones.
Localización-primero: stock por longitud de línea, número/moneda/fecha por región.
A11y-vocabulario: etiquetas claras, descripciones aria, sin ambigüedades.

7) Accesibilidad (A11y) como estándar del sistema

Criterios básicos: WCAG 2. 1 AA para contrastar, el enfoque es visible siempre, navegando desde el teclado.
Roles y atributos: los componentes describen 'role', 'aria-label', 'aria-describedby', regiones en vivo para tostadas/alertas.
Lectores de pantalla: frases de ejemplo, orden de lectura, estados correctos ('assertive/polite').
Procedimientos de prueba: comprobaciones automáticas + scripts manuales.

8) Localización e internacionalización

i18n-keys junto al código del componente + descripción del contexto.
Números/monedas/fechas a través de utilidades de formato; no codificar el texto en plantillas.
Pruebas de longitud: «alemán largo», «móvil estrecho», opciones RTL.
Tono en idiomas: tone-map para pasos críticos (pagos/seguridad).

9) Documentación: estructura y navegación

1. Introducción: misión, principios, áreas de responsabilidad.

2. Tokens: colores, tipografía, cuadrícula, dimensiones, sombras, estados, temas.

3. Componentes: directorio con filtros (por rol, por plataforma, por A11y).

4. Patrones: scripts (formularios, pagos, estados vacíos, aciertos/errores).

5. Contenido: voz y tono, diccionario, patrones de microcopía.

6. Accesibilidad: estándares, hojas de cheques, casos de prueba.

7. Localización: principios, ejemplos, glosarios por mercados.

8. Integración y código: instalación, versiones, ejemplos, «how-to migrate».

9. Contributing: procesos de contribución, rugido de diseño, rugido de código, definición de done.

10. Changelog y Roadmap: lanzamientos, depresiones, plan de desarrollo, conocimientos.

10) Gestión y procesos (gobierno)

Roles: propietario del sistema (DesignOps/UX Platform), maintainers (design/FE), consultores (BE, A11y, localización).
Comité de cambios: evaluación de solicitudes, priorización, negociación de API/tokens.
Procesos: RFC en nuevos componentes, formularios issue internos, SLA por bugs.
Definición de Done: diseño (Figma) ↔ código (UI-pack) ↔ dock (ejemplo + hyde) ↔ pruebas.

11) Contributing: cómo agregar/cambiar

El modelo RFC: el problema → las variantes → la decisión escogida → A11y → i18n → la migración → los riesgos.
Flow PR: rugido de diseño → rugido → redactor de UX → A11y-cheque → notas de lanzamiento.
Reglas de compatibilidad retroactiva: menor/patch para no destructivos, mayor - con deprecación y migración automática, siempre que sea posible.

12) Versificación, lanzamientos, migraciones

SemVer para paquetes ('@ company/ds-core', '@ company/ds-forms',' @ company/ds-charts').
Notas de release: cambios de tokens, API de componentes, comportamiento predeterminado, cambios de breaking, gaides de migración.
Depresiones: marcas en el muelle, reglas linter, códigos de moda para el reemplazo masivo.
Diseño-tokens pipeline: fuente única (JSON/YAML) → builds de plataforma (CSS vars, iOS, Android).

13) Pruebas de calidad

Pruebas unitarias de comportamiento y condiciones.
Snapshots visuales (regresión de temas/estados).
Pruebas A11Y: scripts de screenrider automáticos + manuales.
Casos E2E para flow crítico (registro, pagos, KYC).
Presupuestos Perf: Límites a Bandl/Render y prohibiciones a las adicciones severas.

14) Métricas de madurez del sistema de diseño

Adopción:% de las pantallas/repositorios que utilizan DS.
Velocity: tiempo desde el diseño hasta la entrega.
Calidad: defectos de UI/A11y en 1 lanzamiento.
Consistencia: número de componentes/estilos «desechables» fuera de DS.
Docs: cobertura de componentes Dokoy, NPS de audiencia interna (diseñadores/desarrolladores/analistas).

15) Anti-patrones

Los tokens son como una paleta sin semántica («simplemente color»).
Componentes sin documentación y sin ejemplos de casos extremos.
Ignorar la A11y (sin enfoque, bajo contraste, sin 'aria').
Versificación disruptiva sin depreción y guida migratoria.
Lógica oculta en los componentes (reglas de negocio en lugar de comportamiento de IU).
Duplicar componentes para casos estrechos en lugar de ampliar la API.

16) Hojas de cheques

• Nombres semánticos y nombramiento.
• Contraste de AA en ambos temas.
• Skale y principios de uso están documentados.

• Las opciones/estados están cubiertos.
• A11y-descripción, 'aria-', enfoque.
• Ejemplos de microcopia (etiquetas, errores, pistas).
• Ejemplos de código y casos edge (líneas largas, carga, en blanco).
• Las pruebas de unidad/visual/A11y son verdes.

• Notas de release con ejemplos antes/después.
• Migration guide и deprecations.
• Stories/demo actualizados, enlaces en el muelle.

17) Ejemplos «antes/después»

• Diferentes botones primarios: los colores/radios/sangría no coinciden; diferentes textos CTA.

• Un solo 'Button' con tokens: 'size = md',' variant = primary ',' radius = lg ',' spacing = md', texto de estilo «acción + objeto».

• Mensajes técnicos, sin pistas.

• Componente ' Formato de fecha incorrecto. Use DD. MM. GGG. '+ enfoque automático.

18) Plantilla de página del componente (esqueleto)

Título: Button

Descripción: inicia la acción; 1 principal por pantalla.
Opciones: primary, secondary, ghost, destructive; dimensiones sm/md/lg.
Estados: hover, focus, active, loading, disabled.
A11y: disponible desde el teclado; 'aria-pressed' para conmutables.
Microcopy: «Guardar cambios», «Continuar verificación». Evitar «OK».
Código (API de ejemplo): 'Button {variant, size, icon, loading}'.
Anti-ejemplos: doble primary en un nivel de jerarquía.
Pruebas: snapshots visuales, contraste, focus-ring.

19) Playbook de la introducción del sistema de diseño (rollout)

1. Auditoría de interfaces: inventario de colores/tipografías/componentes/patrones.
2. MVP de tokens y componentes principales: Button, Input, Select, Modal, Alert, EmptyState, Toast.
3. Documentación y storybuk: ejemplos en vivo, código-snippets, gaids.
4. Producto piloto: reemplazo de widgets, recogida de comentarios.
5. Hyde de migración: códigos de moda, reglas de depreciación.
6. Extensión de conjunto: tablas, paginación, foros de formularios, pasos del asistente.
7. Escala: patrones de productos (pagos, KYC), integración con análisis y A/B.
8. Soporte: canal de preguntas, SLA, workshops internos.

20) Plantillas de documentación rápidas

• Nombre: 'color. border. warning`
• Propósito: marcos de avisos y banners Notice/Warning
• Contraste: AA en el fondo 'color. surface. default`
• No se puede: utilizar para texto pequeño kegl
• Relacionado: 'color. surface. warning`, `icon. warning`

Plantilla de patrón: Estado vacío (noResultados)

Objetivo: ajustar la solicitud sin sentir «error»

Composición: título (ops.) , texto (1-2 frases), CTA, CTA secundaria, icono/ilustración

Microcopy: "Por "{query}" no se encontró nada. Restablezca los filtros o refine la solicitud"

A11y: `role="status"`, `aria-live="polite"`

Parche final

Tokens semánticos + disciplina A11y = base.
Páginas de componentes completas: propósito, opciones, A11y, microcopy, código, pruebas.
Patrones = composiciones de componentes con textos y reglas terminados.
Docs - producto: versión, versiones, migraciones, proceso de contribución.
Mida la madurez: adaptación, velocidad, defectos, consistencia, NPS de comandos internos.