apps-registry/workloads/docs-portal/docs/decisiones/0007-identidad-visual-propia.md

# ADR 0007 — Identidad visual propia para ARI Shopping

**Estado:** aceptada (2026-08-27, dirección corregida aprobada por el usuario)
**Fecha:** 2026-08-27

> **Corrección de dirección (2026-08-27):** la primera versión de este
> ADR proponía clonar la estética visual de Amazon (paleta ink/naranja,
> radios mínimos, densidad Amazon). El usuario corrigió el enfoque:
> **el objetivo no es imitar a Amazon, es superar sus patrones de UX
> con una identidad propia, distintiva y memorable** — se adoptan los
> *principios funcionales* que hacen que Amazon (y el mercado en
> general) funcionen bien, no su paleta ni su estética. Esta versión
> reemplaza la anterior por completo.

> Alcance (sin cambios): **solo visual** (paleta, tipografía, radios,
> densidad) — ARI Shopping sigue siendo la marca, el catálogo sigue
> siendo el mismo (juguetes, mochilas, regalos, ya multi-categoría). No
> se toca taxonomía, backend, ni la estructura de navegación ya
> construida en el ADR 0005 (header de 3 niveles, mega-menú,
> breadcrumb, conteos de filtro) — se re-expresa visualmente sobre esa
> misma estructura.

## 1. Resumen de la auditoría del estado actual

(Sin cambios respecto a la versión anterior — sigue siendo la
descripción real del código, no de la propuesta.)

El storefront hoy tiene una identidad visual deliberadamente lúdica,
tipo "juguetería", consistente en todos los componentes revisados
(`app/globals.css`, `components/ui/button.tsx`, `components/ui/badge.tsx`,
`components/layout/navbar.tsx`, `components/layout/footer.tsx`,
`components/product/product-card.tsx`, `app/page.tsx`):

- **Paleta**: tokens propios en `@theme` (`--color-ari-cyan: #06b6d4`,
  `--color-ari-magenta: #ec4899`, `--color-ari-yellow: #fde047`) más
  gradientes `cyan→violet→fuchsia` y `amber→yellow→lime` en barras,
  botones y fondos de sección. Paleta arcoíris de alta saturación, no
  una paleta de marca contenida.
- **Forma**: `rounded-full` en casi todo — botones, badges, chips,
  avatar del logo, inputs del footer. Cero variación de forma.
- **Tipografía**: `font-black`/`font-extrabold` como default en
  título, precio, botones y texto secundario — todo compite por
  atención, nada queda como "de soporte".
- **La estructura ya toma prestados patrones de mercado** (ADR 0005,
  Etapa 2 sub-fase 3): header de 3 niveles, mega-menú "Departamentos",
  footer oscuro de 4 columnas, badges de producto, breadcrumb, conteos
  de filtro. Esta propuesta **no rehace esa estructura** — cambia
  cómo se ve, no cómo funciona.

## 2. Principios de UX a adoptar (funcionales, no estéticos)

Estos son patrones que funcionan en el mercado — Amazon es la
referencia más citable, pero el principio es lo que se adopta, nunca
su paleta ni su forma:

| Principio | Por qué funciona (evidencia del mercado) | Cómo se aplica en ARI sin copiar la estética |
|---|---|---|
| **Jerarquía visual clara** entre precio/CTA/información secundaria | Cuando todo pesa igual (todo bold, todo saturado), el ojo no sabe dónde mirar primero — el usuario tarda más en decidir | El precio y el botón de acción son los únicos elementos con peso tipográfico y color reservado; categoría/SKU/colección bajan a texto liviano y gris cálido |
| **Alta densidad de información sin sentirse saturado** | Más información útil visible (variantes, stock, rating) sin agrandar la card compite mejor que decoración vacía | Los gradientes decorativos actuales ocupan espacio visual sin aportar información — se liberan para mostrar más señales reales del producto |
| **Señales de confianza visibles** | Urgencia de inventario real, garantías, tiempos de envío — leídas como información seria, no decoración | Se conservan/refuerzan elementos ya reales del sitio ("Quedan N", `TrustBar` del home) expresados en colores serios, no en el arcoíris actual |
| **Contraste suficiente para escaneo rápido** | Un usuario escanea, no lee — necesita distinguir texto/fondo/CTA en milisegundos | Cada par de color de esta propuesta se valida contra WCAG AA (ver §4.1) antes de aprobarse, no se asume |

## 3. Por qué no clonar la estética (opciones consideradas)

| Opción | A favor | En contra |
|---|---|---|
| Clonar estética Amazon (ink/naranja/gris, radios mínimos) | Reconocible como "marketplace serio" de inmediato | Es exactamente lo que el usuario pidió evitar — ARI Shopping se vuelve indistinguible de cualquier clon genérico; cero valor de marca propio |
| **Identidad propia guiada por los principios de §2** (esta propuesta) | Distintiva, memorable, defendible como marca; resuelve los mismos problemas de UX reales del sitio actual sin perder personalidad | Requiere más trabajo de diseño que copiar un sistema ya hecho — hay que justificar cada decisión, no solo imitar |
| Mantener la paleta arcoíris actual, solo bajar el peso de fuente | Cambio mínimo | No resuelve el pedido real ("ya no la tienda de juguetes") — el problema no es solo la tipografía, es la paleta completa |

**Decisión de esta sección:** identidad propia.

## 4. Identidad visual propia propuesta

### 4.1 Paleta — "cálida, confiable, ligeramente lúdica"

Evita a propósito el azul corporativo genérico y el arcoíris actual.
Parte de la propia identidad narrativa del sitio ("tesoros para cada
aventura") — una paleta de tono *tienda de tesoros/regalos cálida*,
no de bazar infantil ni de marketplace frío.

| Token | Valor | Uso | Por qué esta elección |
|---|---|---|---|
| `--color-ari-terracota` | `#C1502E` | CTA primario ("Agregar al carrito", "Comprar") — único uso reservado a acción | Cálido y terroso, no un naranja saturado tipo Amazon ni un rosa/fucsia de juguetería. Al ser el *único* color reservado a acción, refuerza la jerarquía visual del §2 |
| `--color-ari-espresso` | `#2B1B13` | Header, footer, texto sobre fondo claro cuando se necesita máximo contraste | Ancla oscura cálida (marrón profundo), no el navy frío de Amazon — mismo rol funcional (contraste fuerte para escanear), estética propia |
| `--color-ari-pino` | `#2F6F62` | Links, estados de confirmación, acentos secundarios/confianza | Reemplaza al "azul de link" genérico sin perder la legibilidad de "esto es clickeable" — un verde-azulado profundo lee como serio y confiable sin ser corporativo |
| `--color-ari-crema` | `#FBF3E7` | Fondo general fuera de las cards | Blanco cálido, no gris frío (`#EAEDED` de Amazon) ni blanco puro — sensación de catálogo de regalos, no de bodega |
| `--color-ari-carbon` | `#2E2620` | Texto principal | Negro cálido, coherente con el resto de la paleta — nunca `slate` frío |
| `--color-ari-oro` | `#E3A008` | Badge "Destacado/Top" | Reemplaza el amarillo neón actual (`#fde047`) por un dorado más rico — mismo rol (llamar la atención puntual), menos "juguete plástico" |
| `--color-ari-ladrillo` | `#A83232` | Badge de descuento | Reemplaza rosa/fucsia — un rojo ladrillo serio comunica "oferta" sin verse infantil |

**Validación de contraste (WCAG AA, calculada, no asumida):**

| Par | Contraste | Cumple AA (texto normal ≥4.5:1 / texto grande ≥3:1) |
|---|---|---|
| Carbón sobre crema (texto de cuerpo) | 13.5:1 | Sí, con margen amplio (supera incluso AAA) |
| Blanco sobre espresso (header/footer) | 16.5:1 | Sí, con margen amplio |
| Blanco sobre terracota (texto de botón CTA) | 4.7:1 | Sí, cumple normal — margen ajustado, mantener el label del botón en `font-semibold` o superior |
| Pino sobre crema (links) | 5.3:1 | Sí, cumple normal |

### 4.2 Tipografía — con carácter propio, no la default de cualquier plantilla

- **Titulares y precio**: [Fraunces](https://fonts.google.com/specimen/Fraunces)
  (serif cálida, con personalidad, cargable vía `next/font/google` sin
  costo de licencia) — usada en h1/h2 de sección, en el precio grande
  de producto, y en momentos de marca (hero). Un serif con carácter en
  estos puntos específicos es una señal de marca deliberada: casi
  ningún competidor de e-commerce usa serif, todos van 100% sans —
  conecta directo con "tesoros para cada aventura" (sensación de
  catálogo curado, no de bazar).
- **UI y cuerpo**: se mantiene **Inter** (ya integrada, probada, muy
  legible en tamaños chicos — nav, badges, filtros) pero se abandona
  el default `font-black`/`font-extrabold` en todo. Escala real:
  `font-normal` para texto de soporte, `font-semibold` para
  título/etiqueta de card, `font-bold` reservado a precio y CTA
  únicamente — el peso vuelve a significar algo en vez de ser el
  default de todo.

### 4.3 Lenguaje de forma — reconocible sin el logo

- **Radio uniforme**: `rounded-xl` (12px) en botones, cards, inputs y
  badges — ni el `rounded-full` actual (se siente "globo de juguete"),
  ni el radio mínimo tipo Amazon (se siente frío/utilitario). Un radio
  moderado y consistente en todo el sistema lee como diseño
  deliberado, no como plantilla default.
- **Sombras con tinte de marca**: sombras suaves calculadas sobre
  `--color-ari-espresso` a baja opacidad (ej.
  `shadow-[0_8px_24px_-8px_rgba(43,27,19,0.25)]`) en vez del
  `shadow-slate-900/…` genérico actual — un detalle que casi nadie
  hace (la mayoría usa el gris default del framework) y que ata la
  sombra misma a la paleta de marca.
- **Densidad**: intermedia — ni tan aireada/decorativa como hoy (mucho
  espacio ocupado por gradientes y texto sobre-dimensionado) ni tan
  comprimida como un marketplace utilitario.

### 4.4 Tres decisiones deliberadas y distintivas

Elegidas específicamente para ser difíciles de replicar "por
accidente" por un competidor genérico:

1. **Badge en forma de "etiqueta de regalo"**: los badges de
   producto (Nuevo/Top/Descuento) dejan de ser una píldora
   `rounded-full` genérica y pasan a una forma con una pequeña
   muesca en una esquina (`clip-path` CSS), evocando una etiqueta de
   precio/regalo física — coherente con "tienda de regalos", y no es
   una utilidad default de Tailwind, así que no aparece por accidente
   en ningún template genérico.
2. **Fondo crema + viñeta suave en fotografía de producto**: las
   imágenes de producto se apoyan sobre `--color-ari-crema` (no blanco
   ni gris) con una viñeta radial muy sutil — el catálogo se siente
   como una vitrina de regalos curada, no una grilla de bodega.
3. **Micro-interacción de marca en el CTA principal**: al hacer hover/
   focus en "Agregar al carrito", el ícono de bolsa hace un pequeño
   giro/rebote de ~200ms (CSS puro, sin JS) en vez del `-translate-y`
   genérico actual — reservado *solo* al CTA principal, para que el
   momento de acción tenga una firma reconocible sin volverse
   caricaturesco en el resto del sitio.

## 5. Tabla de tokens: antes → después

| Token / propiedad | Antes | Después (propuesto) |
|---|---|---|
| `--color-ari-cyan` (`#06b6d4`) | color de marca | eliminado |
| `--color-ari-magenta` (`#ec4899`) | color de marca/CTA | eliminado |
| `--color-ari-yellow` (`#fde047`) | acento | eliminado, ver `--color-ari-oro` |
| Nuevo: `--color-ari-terracota` | — | `#C1502E` — CTA único |
| Nuevo: `--color-ari-espresso` | — | `#2B1B13` — header/footer |
| Nuevo: `--color-ari-pino` | — | `#2F6F62` — links/confianza |
| Nuevo: `--color-ari-crema` | — | `#FBF3E7` — fondo general |
| Nuevo: `--color-ari-carbon` | — | `#2E2620` — texto principal |
| Nuevo: `--color-ari-oro` | — | `#E3A008` — badge destacado |
| Nuevo: `--color-ari-ladrillo` | — | `#A83232` — badge descuento |
| Radio por defecto | `rounded-full` | `rounded-xl` (uniforme) |
| Radio de card de producto | `rounded-3xl` | `rounded-xl` |
| Peso de fuente por defecto | `font-black`/`font-extrabold` en todo | `font-normal` (soporte) / `font-semibold` (títulos/labels) / `font-bold` (solo precio y CTA) |
| Fuente de titulares/precio | Inter (heredada del body) | Fraunces |
| Fondo de sección | `#fff` | `--color-ari-crema` fuera de cards, blanco dentro |
| Sombras | `shadow-slate-900/…` genérico | tintado con `--color-ari-espresso` |
| Gradientes decorativos | `cyan/violet/fuchsia`, `amber/yellow/lime` | eliminados — bloques de color sólido |

## 6. Wireframe en texto: header (antes/después)

**Antes:**
```
[ barra degradada ámbar/amarillo: "Paga a cuotas · Envíos..." ]
[ logo redondo | buscador (gradiente cyan/violeta/fuchsia) | cuenta ♡ 🛒(amarillo) ]
[ barra negra: ☰ Departamentos▾(fuchsia al activo) | Todo | ... ]
```

**Después (propuesto):**
```
[ barra espresso fina, sólida: "Envíos nacionales · Compra segura con ARI" ]
[ fondo espresso | logo | buscador (input crema, botón terracota) | cuenta ♡ 🛒(badge terracota) ]
[ barra espresso: ☰ Departamentos▾(terracota al activo) | Todo | ... ]
```

## 7. Wireframe en texto: product card (antes/después)

**Antes**: `rounded-3xl`, sombra genérica grande, badges en rosa/
fucsia/amarillo, botón "Agregar" en gradiente fucsia/pink.

**Después:** `rounded-xl`, sombra tintada espresso a baja opacidad,
fondo crema detrás de la foto con viñeta sutil, badge "etiqueta de
regalo" (ladrillo para descuento, oro para destacado), precio en
Fraunces bold sobre carbón, botón "Agregar" sólido terracota con la
micro-interacción de §4.4.3 al hover.

## 8. Decisión

Identidad visual propia (§4), ejecutada en las mismas 5 sub-fases
independientes ya planteadas — cada una su propio `fix/*`, diff
mostrado, gate visual antes de la siguiente:

1. **Tokens base**: `globals.css` (`@theme`, variables centralizadas —
   nada de valores hex sueltos en componentes), `button.tsx` (nueva
   variant `primary` en terracota), `badge.tsx`, integración de
   Fraunces vía `next/font/google`.
2. **Header + footer**.
3. **Product card + grid de catálogo**.
4. **Home**.
5. **Página de producto + drawers de carrito/wishlist**.

**Validación de la Sub-fase 1 antes de tocar todo lo demás:**
aplicar los tokens nuevos a un único elemento visible (ej. el botón
CTA de un solo componente) como *smoke test* visual antes de propagar
el cambio a todo el sistema — y, dado que el flujo de revalidación
Admin → `product.updated` → `revalidateTag` (protegido desde Fase 5,
ver ADR 0005) no debería verse afectado por un cambio puramente de
estilos, una edición real de producto vía Admin sirve como validación
cruzada de que nada de esto tocó ese flujo. Mismo mecanismo de
rama/diff/confirmación de siempre en cada paso.

## 9. Consecuencias

- Se gana una identidad de marca propia, memorable y justificable
  componente por componente — no una imitación de ningún competidor
  ni la continuación de la paleta arcoíris actual.
- Sigue siendo un cambio visible en todas las páginas del storefront a
  la vez conceptualmente, pero se implementa y valida en 5 sub-fases
  independientes, cada una revertible por separado (`git revert` del
  commit de esa sub-fase — no hay manifiestos de por medio, es código
  de frontend puro).
- El catálogo, backend, taxonomía y flujo de búsqueda/facetas (ADR
  0006) quedan completamente intactos.
- Trabajo puramente de frontend: no requiere cambios en
  `commerce-backend`, `platform-infra`, ni CI nuevo — reutiliza
  `build.yaml` tal como está.
- Costo adicional real frente a un clon de Amazon: cada decisión de
  esta propuesta tuvo que justificarse contra un principio de UX en
  vez de copiarse — más trabajo de diseño ahora, pero es lo que hace
  que el resultado sea defendible como marca propia y no un genérico
  reconocible.