# Paleta API

Generador determinista de design systems con teoria del color. Un solo
endpoint PHP sin dependencias devuelve, en JSON: paleta verificada WCAG
(AA o AAA, con ajuste automatico garantizado), tokens de estilo UI para
14 lenguajes visuales, tipografia sugerida (Google Fonts), chequeo de
daltonismo con Delta E, rampas tonales 50-900, par de temas claro/oscuro
coherentes y exports listos para CSS, SCSS, Tailwind v4 y W3C Design
Tokens.

- **Demo interactiva:** `index.html`
- **Documentacion navegable:** `docs.html`
- **Contrato OpenAPI 3.1:** `openapi.json`

## Instalacion

Subir `paleta.php` e `index.html` (y opcionalmente `docs.html` +
`openapi.json`) a cualquier hosting con PHP 8.1+. Sin base de datos,
sin Composer, sin dependencias externas.

Si el sitio esta detras de Cloudflare, poner `RL_CONFIA_CF = true` en
`paleta.php` para que el rate limit use la IP real del visitante.

## Uso rapido

```bash
# Paleta aleatoria
curl https://tu-dominio/paleta.php

# Determinista: misma semilla + mismos parametros = misma salida
curl "https://tu-dominio/paleta.php?seed=VX-2741&estilo=glass&layout=bento"

# Par claro/oscuro con objetivos AAA, JSON compacto
curl "https://tu-dominio/paleta.php?seed=VX-2741&modo=par&nivel=aaa&pretty=0"
```

## Parametros GET

| Parametro   | Valores                                                                                    | Default   | Descripcion |
|-------------|--------------------------------------------------------------------------------------------|-----------|-------------|
| `seed`      | texto (max 64)                                                                               | aleatoria | Semilla determinista. Con semilla explicita la respuesta es cacheable (`max-age=86400`). |
| `armonia`   | `auto` `monocromatica` `analoga` `complementaria` `split` `triadica` `tetradica`             | `auto`    | Esquema de hues derivados del hue base. |
| `registro`  | `auto` `profundo` `claro` `pastel` `oscuro` `desaturado` `neobrutal`                         | `auto`    | Receta tonal (S/L por rol). En `auto` se sortea solo entre los compatibles con el estilo. |
| `estilo`    | `auto` `minimal` `maximal` `glass` `liquid` `clay` `neobrutal` `espacial` `neumo` `skeu` `y2k` `flat` `aurora` `ilustrativo` `doodle` | `auto` | Lenguaje visual: define los 14 tokens de superficie (radius, sombras, blur, bordes...). |
| `layout`    | `classic` `bento` `auto`                                                                     | `classic` | Sugerencia de layout para la preview/consumidor. |
| `modo`      | `uno` `par`                                                                                  | `uno`     | Con `par` agrega `temas.claro`, `temas.oscuro` y `css_par` (mismos hues, cada tema con su garantia). |
| `nivel`     | `aa` `aaa`                                                                                   | `aa`      | Objetivos de contraste. AAA: texto 4.5 -> 7.0, UI 3.0 -> 4.5. |
| `ajuste_aa` | `1` `0`                                                                                      | `1`       | Con `1`, ajusta la luminosidad hasta cumplir cada objetivo. Con `0` solo reporta. |
| `excluir`   | hues CSV (ej. `210,175,42`)                                                                  | -         | Con 2+ hues, el hue base sale del hueco mas ancho de la rueda; con 1, del opuesto. |
| `pretty`    | `1` `0`                                                                                      | `1`       | Con `0` el JSON sale compacto (sin saltos de linea). |
| `mood`      | pastel · vintage · neon · calido · frio · otono · invierno · primavera · verano · naturaleza · cafe · atardecer · mar · dorado | -         | Hue base dentro del rango del mood; si el registro viene en auto, aplica su registro y limita el pool de estilos a los compatibles. |
| `hue`       | 0-359                                                                                        | -         | Fija el hue base manualmente (sin consumir RNG). |
| `marca`     | RRGGBB (con o sin #)                                                                         | -         | Ancla el hue base al color de marca del cliente. Prioridad: marca > hue > mood > excluir. |
| `lote`      | 2-24                                                                                         | -         | N paletas ligeras (semillas seed-1..N) en una sola peticion; cuenta como 1 para el rate limit. seed-i con los mismos parametros reproduce la paleta completa. |
| `imagen`    | `1`                                                                                          | -         | Tarjeta PNG 1200x630 (tamano OG) del tema principal. Requiere GD. |

Los parametros tambien se aceptan via PATH (`/paleta.php/seed/VX-2741/estilo/glass`),
util cuando una redireccion recorta el query string. En `excluir` por PATH
se aceptan guiones: `210-175-42`.

## Respuesta (campos principales)

| Campo           | Descripcion |
|-----------------|-------------|
| `meta`          | seed, armonia, registro, estilo, layout, modo, nivel, tema_principal, hue_base, hues, excluidos, nota, version. |
| `colores`       | 12 roles HEX: fondo, superficie, primario, secundario, acento, acento_suave, texto, texto_muted y los 4 `sobre_*` (texto con contraste garantizado encima de cada rol cromatico). |
| `wcag`          | Pares criticos con `ratio`, `objetivo`, `aa`, `aa_grande`. Con `ajuste_aa=1`, todo par cumple su objetivo. |
| `ajustes_aa`    | Roles cuya luminosidad se movio para cumplir (antes/despues). |
| `estilo`        | nombre, layout, registros_recomendados y los 14 `tokens` (radius, radius_control, borde, sombra, sombra_elevada, blur, saturacion, alpha_superficie, superficie_translucida, espaciado, transicion, highlight, gradiente, fondo_decorado). |
| `tipografia`    | Pareja display + cuerpo (familia, pesos, fallback) y `google_fonts_url` lista para cargar. Maximo 2 familias por sistema. |
| `daltonismo`    | Simulaciones de protanopia, deuteranopia y tritanopia (Machado et al. 2009, RGB lineal) del trio primario/secundario/acento, con 9 pares medidos en Delta E CIE76: `ok` >= 20, `justo` >= 10, `riesgo` < 10. |
| `rampas`        | Escalas 50-900 para primario, secundario, acento y neutro (L fija, S suavizada en extremos). Compartidas entre temas. |
| `css_variables` | Bloque `:root` con colores + tokens + fuentes, listo para pegar. |
| `exports`       | `scss` (variables planas), `tailwind` (bloque `@theme` v4) y `tokens_w3c` (grupos color, rampa, fontFamily y dimension del formato W3C Design Tokens). Generados del tema principal. |
| `temas`         | Solo con `modo=par`: `claro` y `oscuro`, cada uno con registro, colores, wcag, ajustes_aa, tokens y css_variables. |
| `css_par`       | Solo con `modo=par`: `:root` claro + `[data-tema="oscuro"]` + `@media (prefers-color-scheme: dark)`. |
| `uso`           | Resumen de parametros y ejemplo. |

## Garantias

- **Determinismo.** Misma semilla + mismos parametros = misma salida,
  dentro de cada version. El orden de consumo del RNG esta documentado
  en la cabecera de `paleta.php` (armonia -> estilo -> registro ->
  layout -> tipografia); `modo`, `nivel` y `pretty` no consumen RNG.
- **Contraste garantizado.** Con `ajuste_aa=1` (default), cada par
  critico cumple su objetivo AA o AAA; el motor mueve la luminosidad de
  los roles no-base hasta lograrlo. Verificado en suite sobre cientos de
  paletas.
- **Regresion dorada.** Cada version se valida contra un snapshot de 40
  combinaciones de parametros de la version anterior; los cambios son
  aditivos y documentados. El kit de pruebas (runner de 12 secciones +
  script dorado + linea base v1.5) se distribuye aparte.

## Rate limit

60 peticiones por minuto por IP (constantes `RL_LIMITE` / `RL_VENTANA`
en `paleta.php`). Al exceder: HTTP `429` con cabecera `Retry-After` y
cuerpo `{ok:false, error:"rate_limit", mensaje, reintentar_en}`. Usa
APCu si esta disponible; si no, archivos con `flock` en el tmp del
sistema. Desactivado en CLI. La galeria del frontend (14 peticiones)
queda holgada dentro del limite.

## Frontend (index.html)

Demo completa: selectores de todos los parametros, vista previa en vivo
que renderiza el estilo con sus tokens y tipografia, toggle claro/oscuro
en modo par, galeria comparadora de los 14 estilos con la misma semilla,
rampas y simulaciones de daltonismo clic-para-copiar, pestañas de export
(CSS/SCSS/Tailwind/W3C), historial de semillas (localStorage), compartir
enlace y URLs compartibles con todos los parametros.

## Historia de versiones

- **1.0** Paleta base: armonias, registros, analisis de huecos, angulo
  aureo, verificacion WCAG, variables CSS, preview.
- **1.1** Estilos UI (7) con 14 tokens uniformes, layout bento, colores
  `sobre_*`, garantia AA con ajuste automatico, cache condicional,
  correccion de XSS en la semilla y del boton de copiado.
- **1.2** 7 estilos mas (14 en total): neumo, skeu, y2k, flat, aurora,
  ilustrativo, doodle.
- **1.3** Refactor a `generar_tema()`, `modo=par` (claro/oscuro
  coherentes), rampas 50-900, exports SCSS/Tailwind/W3C, `css_par`.
- **1.4** Tipografia por estilo (28 parejas Google Fonts), chequeo de
  daltonismo con Delta E, galeria comparadora.
- **1.5** Rate limit por IP, `nivel=aaa`, `pretty=0`, historial de
  semillas, compartir enlace, aria-live, favicon.
- **1.6** Lanzamiento: README, `docs.html` (auto-tematizada con su
  propia paleta) y `openapi.json`.
- **1.7** Explorar y control creativo: `lote` (N paletas por peticion),
  14 moods generativos, `hue` fijo, `marca` (anclar al color corporativo),
  tarjeta PNG (`imagen=1`) y panel Explorar en el frontend. Resolucion
  centralizada en `resolver()` con regresion dorada 40/40.