# Theming del widget Findalo con tokens --fdl-*

> Documentación para desarrolladores de Findalo (buscador SaaS para tiendas online). Versión HTML: https://findalo.io/devs/theming/
> Contrato estable: los tokens, clases, variables y eventos documentados solo se amplían, nunca se renombran ni eliminan. Todo lo NO documentado es interno del widget y puede cambiar sin aviso.

Los tokens `--fdl-*` son custom properties CSS versionadas: la vía soportada de personalizar el aspecto del buscador con CSS. Se aplican por encima de la configuración del panel y del preset visual activo.

## Uso

Desde cualquier hoja de estilos de la tienda (atraviesan el shadow DOM):

```css
.findalo-search-host {
  --fdl-primary: #0d7a5e;
  --fdl-radius-md: 14px;
  --fdl-card-shadow: 0 4px 12px rgba(0, 0, 0, 0.06);
}
```

O desde el Custom CSS del panel (Apariencia → Avanzado), sobre `.kos-search`.

**Precedencia** (mayor a menor): tokens del dev → ajustes del panel → preset visual → defaults.

**Responsive**: declarar el token siempre (fuera de media queries) y variar su VALOR dentro de ellas — la presencia se detecta al cargar, el valor se sigue en vivo.

## Referencia

### Color

| Token | Default | Controla |
|---|---|---|
| `--fdl-primary` | `#18181b` | Color principal: botones, foco, elementos activos. Equivale al «Color principal» del panel. |
| `--fdl-primary-soft` | `#f4f4f5` | Versión suave del color principal (fondos de chips activos, hovers marcados). |
| `--fdl-accent` | `#dc2626` | Color de acento: precios en oferta, badges de descuento. Equivale al «Color de acento» del panel. |
| `--fdl-text` | `#18181b` | Color del texto principal. |
| `--fdl-text-muted` | `#71717a` | Texto secundario: categorías, contadores, subtítulos. |
| `--fdl-bg` | `#fafafa` | Fondo general del buscador. |
| `--fdl-surface` | `#ffffff` | Fondo de superficies elevadas: cards, paneles, dropdowns. |
| `--fdl-border` | `#e4e4e7` | Color de bordes y separadores. |
| `--fdl-hover` | `#f4f4f5` | Fondo de elementos al pasar el ratón. |

### Carrito

| Token | Default | Controla |
|---|---|---|
| `--fdl-cart-btn-bg` | `color principal` | Fondo del botón «Añadir al carrito». |
| `--fdl-cart-btn-text` | `#ffffff` | Texto e icono del botón «Añadir al carrito». |
| `--fdl-cart-btn-hover-bg` | `auto (aclarado)` | Fondo del botón al hacer hover. |
| `--fdl-cart-btn-hover-text` | `hereda` | Texto del botón al hacer hover. |
| `--fdl-cart-badge-bg` | `verde` | Fondo del contador de unidades de la cesta (cabecera). |

### Imagen

| Token | Default | Controla |
|---|---|---|
| `--fdl-img-bg` | `gris suave` | Fondo de la caja de imagen de producto en las cards. |

### Forma

| Token | Default | Controla |
|---|---|---|
| `--fdl-radius-sm` | `0px` | Radio de borde pequeño (inputs, chips internos). |
| `--fdl-radius-md` | `0px` | Radio de borde medio (cards, paneles). |
| `--fdl-radius-lg` | `0px` | Radio de borde grande (modal, sheets). |
| `--fdl-btn-radius` | `999px` | Radio del botón «Añadir al carrito» (999px = píldora). |
| `--fdl-chip-radius` | `999px` | Radio de chips y sugerencias. |
| `--fdl-card-pad` | `0px` | Padding interior de la card de producto. |
| `--fdl-card-shadow` | `none` | Sombra de las cards de producto. |
| `--fdl-modal-shadow` | `0 20px 60px rgba(0,0,0,.18)` | Sombra del modal del buscador. |

### Tipografía

| Token | Default | Controla |
|---|---|---|
| `--fdl-font-display` | `hereda` | Tipografía de títulos y nombres de producto. |
| `--fdl-font-body` | `hereda` | Tipografía del resto de textos. |

### Animación

| Token | Default | Controla |
|---|---|---|
| `--fdl-anim-duration` | `180ms` | Duración de las transiciones del widget. |
| `--fdl-anim-easing` | `ease` | Curva de las transiciones del widget. |