whatsapp-api-mockup/docs/research-ui.md

# Research UI — WhatsApp Business/Cloud API renderizado en WhatsApp iOS

> Objetivo: especificación orientada a CSS para replicar cómo se ven los mensajes de la
> Cloud API en la app de WhatsApp para iPhone (diseño unificado 2022+, con notas del
> rediseño iOS 2024–2025). Valores en px sobre un layout de 393 pt de ancho.

## 0. Fiabilidad de las fuentes

Meta **no publica** hex oficiales del cliente móvil; su documentación describe estructura
(orden de componentes, límites de caracteres) pero no colores. Los hex del cliente son
**medidos por la comunidad** (Figma kits, clones de código abierto, WABetaInfo) y
coinciden entre fuentes independientes, por lo que se consideran fiables. Marcado usado:

- `[META]` — confirmado en developers.facebook.com (estructura/límites, no hex).
- `[COM]` — hex/medidas de comunidad (Múltiples kits Figma y clones coinciden).
- `[WBI]` — WABetaInfo vía PocketNow (cambio de color de burbuja iOS, beta 2.21.200.11).
- `[APL]` — Apple/screensizes.app (geometría del dispositivo).

---

## 1. Modo claro

```css
.wa {
  /* Fondo del chat: beige con patrón doodle */
  --wa-bg-chat: #efeae2;            /* [COM] variantes citadas: #efe7de / clásico #e5ddd5 */
  --wa-doodle-opacity: 0.045;       /* [COM] doodles al ~4–6% sobre el fondo */

  /* Burbujas */
  --wa-bubble-in: #ffffff;          /* [COM] iOS entrante blanca; Web/Android #f0f0f0; clásico #ece5dd */
  --wa-bubble-out: #d9fdd3;         /* [COM] saliente verde claro; clásico iOS #dcf8c6 */
  /* [WBI] beta iOS 2.21.200.11: #e1f6ca → #e2fdd5 (misma familia de verde) */

  /* Texto */
  --wa-text: #111b21;               /* [COM] texto de burbuja, casi negro */
  --wa-text-meta: #667781;          /* [COM] hora, fechas, "escribiendo…", footer de plantilla */
  --wa-link: #027eb5;               /* [COM] enlaces dentro de burbuja (azul WhatsApp, no iOS blue) */
  --wa-tick: #667781;               /* [COM] ✓ enviado y ✓✓ entregado (mismo gris que la hora) */
  --wa-tick-read: #53bdeb;          /* [COM] ✓✓ leído (celeste) — igual en claro y oscuro */

  /* Chrome (header + barra inferior): iOS usa gris muy claro, no blanco puro */
  --wa-chrome: #f6f6f6;             /* [COM] header y compose bar iOS; WhatsApp Web usa #f0f2f5 */
  --wa-chrome-text: #000000;
  --wa-compose-field: #ffffff;      /* [COM] campo "Mensaje" blanco redondeado */
  --wa-separator: rgba(0,0,0,.08);  /* [COM] hairlines */
  --wa-accent: #00a884;             /* [COM] verde de acento actual (iconos, botones) */
  --wa-accent-deep: #008069;        /* [COM] variante oscura del acento */
}
```

Brand histórico (único hex "oficial" publicado en paletas de marca) `[COM/Mobbin]`:
`#075e54` teal header clásico · `#128c7e` teal secundario · `#25d366` verde marca.
El teal de header desapareció del chat en el rediseño de 2022; solo sirve para
ilustraciones de marca.

## 2. Modo oscuro

```css
.wa.dark {
  --wa-bg-chat: #0b141a;            /* [COM] Web/Android unificado; iOS AMOLED tiende a #000000 */
  --wa-doodle-opacity: 0.04;

  --wa-bubble-in: #202c33;          /* [COM] entrante; variante iOS citada #1f2c33 */
  --wa-bubble-out: #005c4b;         /* [COM] saliente verde oscuro; [WBI] beta iOS: #204f46 */

  --wa-text: #e9edef;               /* [COM] casi blanco */
  --wa-text-meta: #8696a0;          /* [COM] hora/meta en oscuro */
  --wa-link: #53bdeb;               /* [COM] enlaces toman el celeste de acento en oscuro */
  --wa-tick: #8696a0;
  --wa-tick-read: #53bdeb;

  --wa-chrome: #202c33;             /* [COM] header/compose Web; iOS oscuro puro: #1c1c1e–#000000 */
  --wa-chrome-text: #e9edef;
  --wa-compose-field: #2a3942;      /* [COM] campo "Mensaje" en oscuro */
  --wa-separator: rgba(255,255,255,.10);
  --wa-accent: #00a884;
}
```

Nota iOS 2024–2025: el rediseño de WhatsApp iOS usa fondo **negro puro** en oscuro y
burbujas aún más redondeadas (guías de personalización WWeb; ithinkdiff sobre beta
26.29.10.70). Si el mockup representa "iOS hoy": `--wa-bg-chat:#000`,
`--wa-bubble-in:#1c1c1e`–`#202c33`, `--wa-bubble-out:#005c4b`, chrome `#000/#1c1c1e`.

## 3. Tipografía

```css
.wa {
  font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text",
               "Helvetica Neue", Helvetica, Arial, sans-serif; /* [APL/COM] stack iOS */
  -webkit-font-smoothing: antialiased;
}
.wa .bubble { font-size: 17px; line-height: 1.3; }        /* 17 pt = .body de iOS [COM] */
.wa .meta   { font-size: 11px; line-height: 1; }          /* hora + ticks dentro de burbuja */
.wa .header-title { font-size: 17px; font-weight: 600; }  /* nombre contacto, semibold */
.wa .header-sub   { font-size: 13px; font-weight: 400; }  /* "en línea" / "escribiendo…" */
.wa .btn-label    { font-size: 17px; }                    /* botones de plantilla, texto centrado */
.wa .template-footer { font-size: 12px; color: var(--wa-text-meta); }
.wa .btn-domain   { font-size: 12px; color: var(--wa-text-meta); } /* dominio del CTA URL */
```

- Enlaces de burbuja sin subrayado; `color: var(--wa-link)`.
- Hora y ticks van **dentro** de la burbuja, alineados abajo-derecha; el texto del
  mensaje se rellena con un espaciador para no pisarlos (ver §4).

## 4. Geometría de burbujas

```css
.wa .row { display:flex; padding:1px 16px 0; }          /* fila de mensaje */
.wa .row + .row { margin-top:2px; }                      /* mismo emisor: 2–3px [COM] */
.wa .row.new-group { margin-top:10px; }                  /* cambia emisor: 8–12px [COM] */
.wa .row.out { justify-content:flex-end; }
.wa .bubble {
  position:relative;
  max-width:78%;                                         /* ~75–80% del ancho [COM] */
  padding:6px 9px 8px 7px;                               /* izq≠der por la cola [COM] */
  border-radius:18px;                                    /* esquinas continuas (squircle) [COM] */
  background:var(--wa-bubble-in);
}
.wa .row.out .bubble { background:var(--wa-bubble-out); }

/* Cola: entrante arriba-izquierda, saliente arriba-derecha.
   La esquina del lado de la cola se afila; el rabito curvo se dibuja con ::before */
.wa .row.in  .bubble { border-top-left-radius:5px; }
.wa .row.out .bubble { border-top-right-radius:5px; }

.wa .row.in  .bubble::before {   /* cola entrante */
  content:""; position:absolute; top:0; left:-8px;
  width:8px; height:13px; fill:var(--wa-bubble-in);
  /* clip-path con curva tipo cola; alternativa: SVG inline */
  clip-path: path("M8 0 H0 C4 4 6 8 8 13 Z");
}
.wa .row.out .bubble::before {   /* cola saliente (espejo) */
  content:""; position:absolute; top:0; right:-8px;
  width:8px; height:13px; fill:var(--wa-bubble-out);
  clip-path: path("M0 0 H8 C4 4 2 8 0 13 Z");
}
```

- Rediseño iOS 2025: burbujas todavía más redondas (WABetaInfo/ithinkdiff) — para un
  look "última generación" usar `border-radius:20–22px` y esquina de cola `6px`.
- Media (foto/vídeo) sin padding lateral: la imagen ocupa toda la burbuja
  (`padding:0`), esquinas redondeadas iguales, hora encima con gradiente inferior.

Hora + ticks dentro de la burbuja:

```css
.wa .meta {
  display:flex; align-items:center; gap:2px;
  justify-content:flex-end;
  float:right;                 /* o grid: el texto envuelve alrededor */
  margin:6px 0 -2px 12px;      /* el texto del mensaje reserva este hueco */
  color:var(--wa-text-meta); font-size:11px; user-select:none;
}
.wa .meta .tick-read { color:var(--wa-tick-read); }
```

Estados de tick `[META/COM]`: reloj (pendiente) → `✓` enviado → `✓✓` gris entregado →
`✓✓` celeste `#53bdeb` leído. El doble tick son dos marcas solapadas ~2px.

## 5. Chrome del chat

```css
.wa .header {
  display:flex; align-items:center; gap:12px;
  padding:8px 12px; background:var(--wa-chrome);
  border-bottom:1px solid var(--wa-separator);
  /* con Dynamic Island el header arranca bajo la status bar (54pt) */
}
.wa .back-chevron { width:22px; }            /* chevron fino, color acento azul iOS o gris */
.wa .avatar { width:40px; height:40px; border-radius:50%; object-fit:cover; }
.wa .header-title { flex:1; }                /* nombre bold + subtítulo debajo */
.wa .icon-video, .wa .icon-call { width:24px; margin-left:16px; } /* videollamada, llamada */
```

- Subtítulo: "en línea" estático gris; "escribiendo…" en verde acento `[COM]`.
- Barra inferior (compose):

```css
.wa .compose {
  display:flex; align-items:center; gap:8px;
  padding:8px 12px calc(8px + env(safe-area-inset-bottom));
  background:var(--wa-chrome);
}
.wa .attach  { width:28px; }                    /* + o clip: cámara/fotos/adjuntos */
.wa .field {
  flex:1; display:flex; align-items:center; gap:8px;
  height:38px; padding:0 12px; border-radius:19px;   /* píldora [COM] */
  background:var(--wa-compose-field);
  color:var(--wa-text-meta);                          /* placeholder "Mensaje" */
}
.wa .mic { width:26px; }                            /* micrófono cuando el campo está vacío */
```

## 6. Renderizado de mensajes de la Cloud API `[META]` + observación `[COM]`

### 6.1 Botones de respuesta rápida (interactive `type:"button"`)
- Estructura: header opcional + body (≤1024) + footer (≤60) + **hasta 3 botones**
  (título ≤20 caracteres `[META]`).
- En iOS: **apilados verticalmente a todo el ancho del cuerpo**, dentro de una tarjeta
  continua con hairline entre ellos; texto **centrado** en verde acento
  (`--wa-accent` claro / `#53bdeb`-verde según versión en oscuro) `[COM]`.

```css
.wa .qr-btns { display:flex; flex-direction:column; background:var(--wa-bubble-in);
               border-radius:14px; overflow:hidden; margin-top:8px; width:min(78%,340px); }
.wa .qr-btn  { padding:12px 8px; text-align:center; font-size:17px;
               color:var(--wa-accent); }
.wa .qr-btn + .qr-btn { border-top:1px solid var(--wa-separator); }
```

### 6.2 Botón CTA URL
- Un botón tipo lista bajo la burbuja: icono de **enlace** (o teléfono) a la izquierda,
  etiqueta centrada ≤25 caracteres, **dominio en gris pequeño (12px) al pie del botón**
  `[COM]`; abre el navegador externo `[META]`.
- Añadir un icono de enlace y en el borde inferior una fila de dominio:
  `.cta-domain { border-top:1px solid var(--wa-separator); font-size:12px; color:var(--wa-text-meta); text-align:center; }`

### 6.3 Mensajes de lista (`type:"list"`)
- Burbuja con header (≤60, semibold), body (hasta 4096), footer (≤60) y **un único
  botón** (≤20 caracteres) `[META]`.
- Al pulsarlo, iOS abre un **modal/sheet** con las secciones (≤10) y filas (≤10;
  título 24, descripción 72) — no filas inline `[META]`. En el mockup basta la burbuja
  con botón; el sheet es una vista modal con chevrons/grupo agrupado estilo iOS.

### 6.4 Plantillas (message templates)
Orden renderizado `[META]`: **header → body → footer → botones**.

```css
.wa .template { width:min(78%,340px); border-radius:14px; overflow:hidden;
                background:var(--wa-bubble-in); display:flex; flex-direction:column; }
.wa .tpl-media { width:100%; aspect-ratio:16/9; object-fit:cover; } /* header media full-bleed */
.wa .tpl-body   { padding:8px 10px; font-size:15px; white-space:pre-wrap; } /* ≤1024 */
.wa .tpl-footer { padding:0 10px 8px; font-size:12px; color:var(--wa-text-meta); }
.wa .tpl-btns   { border-top:1px solid var(--wa-separator); } /* reusar .qr-btns */
```

- Header puede ser imagen/vídeo (16:9 recortado a ancho de burbuja), documento
  (icono + nombre), texto (≤60, semibold) o ubicación genérica `[META]`.
- Footer gris pequeño (≤60) pegado al body.
- Botones: quick replies (≤25 en plantillas) agrupados, URL ≤2, teléfono ≤1, total ≤10;
  si hay >3 botones, el resto se pliega en "See all options" `[META]`.

### 6.5 Carrusel (carousel template) `[META]`
- 2–10 tarjetas, swipe horizontal con **scroll-snap**; cada tarjeta: media del header
  (recortada automática a proporción ancha según dispositivo) + body ≤160 + hasta
  2 botones; todas las tarjetas comparten componentes.
- Tarjeta ~ 78% del ancho menos padding, con indicador de página (puntos) abajo `[COM]`.

```css
.wa .carousel { display:flex; gap:8px; overflow-x:auto; scroll-snap-type:x mandatory;
                padding:2px 16px 8px; }
.wa .card { flex:0 0 78%; scroll-snap-align:center; border-radius:14px; overflow:hidden;
            background:var(--wa-bubble-in); }
```

### 6.6 Documento `[META]`
Burbuja blanca/color entrante con: **icono de página coloreado según extensión** (el
cliente elige el icono por extensión), nombre de archivo (`filename`) en negro/texto
medio, extensión + nº páginas en gris pequeño, y botón circular de descarga a la
derecha `[META: icono+nombre+tap para descargar; COM: disposición]`. Caption opcional
(≤1024) debajo.

### 6.7 Audio / nota de voz `[META]`
Burbuja con reproductor: botón play/pausa circular, **waveform** (barras verticales de
~2px con huecos, altura variable), duración en gris y avatar del emisor en notas de voz
propias `[COM: geometría del waveform]`. En la Cloud API se envía como `type:"audio"`
(`audio`/`voice`), se renderiza igual que una nota de voz del usuario `[META]`.

### 6.8 Ubicación `[META]`
Burbuja con **miniatura de mapa estático** (cuadrada redondeada arriba, con pin rojo
centrado `[COM]`), nombre del sitio en semibold y dirección en gris debajo; tap abre
mapa. Campos que llegan: `latitude`, `longitude`, `name`, `address` `[META]`.

### 6.9 Contacto `[META]`
**Tarjeta** con iniciales/avatar redondo, nombre formateado en semibold y **flecha de
perfil** (chevron); al pulsar abre vista de perfil estilo iOS con teléfonos, emails,
direcciones, empresa, cumpleaños y webs, más botones "Message + Save contact" (con
`wa_id`) o "Invite to WhatsApp" (sin `wa_id`) `[META]`.

## 7. Marco de iPhone moderno `[APL]` (iPhone 15/16 Pro base)

```css
.iphone { width:393px; height:852px; border-radius:55px; background:#000;
          padding:0; position:relative; overflow:hidden; }   /* 393×852pt, radio 55pt */
.island  { position:absolute; top:11px; left:50%; transform:translateX(-50%);
           width:126px; height:37px; border-radius:20px; background:#000; } /* [COM] */
.statusbar { position:absolute; top:0; height:54px; width:100%;
             display:flex; justify-content:space-between; align-items:center;
             padding:18px 32px 0; color:#fff; font-size:15px; font-weight:600; }
/* hora "9:41" a la izquierda; derecha: señal (4 barras), wifi, batería (iconos SF) */
.home-indicator { position:absolute; bottom:8px; left:50%; transform:translateX(-50%);
                  width:139px; height:5px; border-radius:3px; background:#fff; } /* [COM] 134–139 */
```

- Status bar 54 pt de alto en modelos con Dynamic Island `[APL/useyourloaf]`; la hora
  "9:41" es la convención de Apple en marketing `[APL]`.
- En modo claro la status bar del chat es **oscura** (texto negro sobre header claro);
  en oscuro, blanca.
- El contenido del chat corre **debajo** del header con `backdrop-filter: blur` en iOS
  `[COM]` — opcional en mockup; los safe-area (59 pt arriba, 34 pt abajo) delimitan el
  header/compose reales.

## 8. Resumen de decisiones para el mockup

1. Usar el set 2022+ unificado (`#efeae2/#ffffff/#d9fdd3` claro, `#0b141a/#202c33/#005c4b`
   oscuro) como base; si el objetivo es "iOS 2025", fondo oscuro `#000` y burbujas 20–22px.
2. Cola arriba (no abajo como WhatsApp Web): entrante `top-left`, saliente `top-right`.
3. Hora+ticks flotan abajo-derecha dentro de la burbuja con espaciador de texto.
4. Botones = tarjeta apilada con hairlines, texto centrado en acento verde.
5. Los hex de cliente son mediciones de comunidad (Meta no publica token UI);
   documentar en el mockup como "aproximados".

## Fuentes consultadas

- Meta — Carousel templates: developers.facebook.com/docs/whatsapp/business-management-api/message-templates/carousel-templates
- Meta — Template components (nueva ruta): developers.facebook.com/documentation/business-messaging/whatsapp/templates/components
- Meta — Reply buttons: developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-reply-buttons-messages
- Meta — List messages: developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages
- Meta — Document / Location / Contacts messages: developers.facebook.com/documentation/business-messaging/whatsapp/messages/{document,location,contacts}-messages
- PocketNow/WABetaInfo (hex burbuja iOS beta): pocketnow.com/whatsapp-redesigned-chat-bubble-iphone
- Tokens de comunidad: ui.shreshtharora.com/components/bubble · whatsapp-components.crafter.run · styles.refero.design · gists github.com/13swat · nextwork.ai · codewithcurious.com · mobbin.com/colors/brand/whatsapp · color-hex.com/color-palette/110833
- Dispositivo: screensizes.app/?model=iphone-15-pro · useyourloaf.com/blog/iphone-15-screen-sizes · behance.net/gallery/153642485 (Dynamic Island) · support.apple.com/en-us/111829
- Rediseño iOS oscuro: wwebcustomizer.com/blog/how-to-make-whatsapp-web-look-like-an-iphone-2026 · ithinkdiff.com (burbujas más redondas, beta 26.29.10.70)