IDicon

Avatares SVG únicos y deterministas a partir de un id. Dado el identificador de un cliente o usuario, idicon devuelve siempre el mismo avatar: una persona, un personaje, un objeto o una forma geométrica, con cara, sobre un fondo con patrón y una paleta de hasta 6 colores. No necesita base de datos ni servidor: el avatar se calcula, no se almacena.

El repositorio contiene dos cosas:

• El paquete npm idicon: la librería que genera los avatares (sin dependencias) y un componente opcional para React.
• Una web de demostración para probar ids, opciones y paletas, y copiar o descargar el resultado.

Índice:

1. Guía de implementación en otro proyecto
2. Referencia de la API
3. Garantías del generador
4. Estabilidad del diseño y versionado
5. Web de demostración
6. Mantenimiento del paquete

1. Guía de implementación en otro proyecto

Pasos para usar IDicon en una aplicación real, con clientes. Síguelos en orden.

Paso 0: decisiones previas (5 minutos)

Antes de escribir código, acuerda con el equipo:

• Qué versión se instala. Siempre una versión concreta (etiqueta vX.Y.Z o número en el registro), nunca "lo último de main". Ver sección 4.
• Si los avatares llevan la paleta de la empresa. Si sí, elige los 5 colores (#rrggbb) una sola vez. Si no, el generador asigna una paleta distinta a cada id.
• Qué id se usa. Debe ser el identificador estable del cliente (el id de la base de datos, el email, un UUID). No uses el nombre si puede cambiar: cambiar el id cambia el avatar.

Paso 1: instalar el paquete

Requisitos: Node.js 18 o superior (o cualquier navegador moderno). El paquete es solo módulos ES (import). React es opcional y solo hace falta para idicon/react.

El paquete está publicado en npm (npmjs.com/package/idicon). Instala una versión concreta:

npm install [email protected]

Alternativas, por si en algún entorno no hay acceso al registro de npm:

# Desde el repositorio Git, fijando una etiqueta de versión
npm install git+https://github.com/AI-Digital-Solutions-Blue/IDicon-generator.git#v0.1.0

# Desde un fichero generado con npm pack
npm install ./idicon-0.1.0.tgz

Comprueba en tu package.json que la versión queda fijada sin ^ ni ~, por ejemplo "idicon": "0.1.0". Así una actualización del paquete nunca cambia tus avatares sin que tú lo decidas.

Paso 2: centralizar la configuración

Crea un único módulo en tu aplicación que envuelva al paquete. Todas las pantallas lo usan a él, no a idicon directamente, para que las opciones (paleta, contenido) sean las mismas en toda la app y vivan en un solo sitio.

// src/lib/avatares.ts
import { generateAvatarSvg, avatarDataUri, type AvatarOptions } from "idicon";

// Opciones comunes a toda la aplicación. Cambiarlas cambia TODOS los avatares.
const OPCIONES: AvatarOptions = {
  // Paleta de marca (5 colores #rrggbb). Quita esta línea para paletas automáticas.
  palette: ["#12263F", "#2E5E8C", "#7FB2E5", "#F2C14E", "#F7F4EA"],
  // subject: "person",   // si solo quieres personas
  // pattern: "plain",    // si prefieres fondos lisos
};

/** Id estable del cliente → SVG. */
export function avatarSvg(clienteId: string, size = 96): string {
  return generateAvatarSvg(clienteId, { ...OPCIONES, size });
}

/** Igual, como URL para <img src>. */
export function avatarUrl(clienteId: string, size = 96): string {
  return avatarDataUri(clienteId, { ...OPCIONES, size });
}

Paso 3: usarlo en la interfaz

React (con el componente del paquete y las opciones centralizadas):

// src/components/AvatarCliente.tsx
import { Avatar } from "idicon/react";

const OPCIONES = { palette: ["#12263F", "#2E5E8C", "#7FB2E5", "#F2C14E", "#F7F4EA"] } as const;

export function AvatarCliente({ id, size = 40 }: { id: string; size?: number }) {
  return <Avatar id={id} size={size} {...OPCIONES} title={id} />;
}

<AvatarCliente id={cliente.id} />
<AvatarCliente id={cliente.id} size={96} />

HTML o cualquier otro framework (Vue, Angular, plantillas de servidor):

import { avatarUrl } from "./lib/avatares";

img.src = avatarUrl(cliente.id, 48);
// o en una plantilla: <img src="${avatarUrl(id)}" width="48" height="48" alt="">

Como fondo CSS:

el.style.backgroundImage = `url("${avatarUrl(cliente.id)}")`;

Paso 4: (opcional) servirlo desde el backend

Si varias aplicaciones, o apps que no son JavaScript, deben mostrar el mismo avatar, expón una URL en tu servidor. Ejemplo con Express:

import express from "express";
import { avatarSvg } from "./lib/avatares";

const app = express();

app.get("/avatar/:id.svg", (req, res) => {
  res.type("image/svg+xml");
  res.set("Cache-Control", "public, max-age=31536000, immutable"); // el avatar no cambia
  res.send(avatarSvg(req.params.id, 256));
});

Entonces cualquier cliente usa <img src="https://tu-servidor/avatar/cliente-1042.svg">. La cabecera de caché es segura porque el mismo id siempre devuelve el mismo SVG (mientras no cambie la versión del paquete; ver sección 4).

Paso 5: comprobar la integración

• [ ] El mismo cliente muestra el mismo avatar en todas las pantallas y tras recargar.
• [ ] Dos clientes distintos muestran avatares distintos.
• [ ] Con paleta de marca: todos los avatares usan solo esos colores (más tinta oscura o blanca en la cara).
• [ ] En TypeScript, subject="cualquiercosa" da error de compilación (los tipos llegan bien).
• [ ] El package.json fija la versión exacta.
• [ ] Si usas un endpoint: la respuesta tiene Content-Type: image/svg+xml.

Paso 6: política de actualización

• Lee el CHANGELOG antes de subir de versión. Si la entrada dice que altera avatares existentes, tus clientes verán avatares nuevos. Decide si lo aceptas y, si procede, avísales.
• Las versiones menores y de parche (0.1.0 → 0.1.1, 0.2.0) no cambian ningún avatar existente; son seguras.
• Las versiones mayores (0.x → 1.0, 1.x → 2.0) pueden cambiar el dibujo.
• Cada SVG lleva el atributo data-idicon-design="N" con la versión de diseño que lo generó. Sirve para comprobar, en un test o en soporte, con qué versión se dibujó un avatar.
• Si necesitas que convivan dos diseños (por ejemplo, clientes antiguos conservan el suyo y los nuevos usan el nuevo), incluye la versión en el id: generateAvatarSvg("v1:" + cliente.id) con el paquete antiguo y "v2:" + cliente.id con el nuevo. Como el id forma parte de la semilla, cada prefijo da su propio avatar estable.

2. Referencia de la API

import { generateAvatarSvg, avatarDataUri, SUBJECTS, PATTERNS, PATTERN_CHOICES, PALETTES, DESIGN_VERSION } from "idicon";
import type { AvatarOptions, Subject, Pattern, PatternChoice } from "idicon";
import { Avatar, type AvatarProps } from "idicon/react";

generateAvatarSvg(id, options?) → string

Devuelve el avatar de id como documento SVG completo (texto). El id se recorta (espacios al principio y al final) y se normaliza (NFC), así que "ana" y " ana " dan el mismo avatar. Cualquier texto vale como id: nunca se escribe dentro del SVG.

avatarDataUri(id, options?) → string

El mismo avatar como URL data:image/svg+xml;charset=utf-8,..., lista para src de una imagen o background-image en CSS.

Opciones (AvatarOptions)

| Opción | Valores | Por defecto | Qué hace | | --------- | ------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- | | subject | "random", "person", "character", "object", "shape", "none" | "random" | Qué se dibuja. random deja que el id elija entre todos; none dibuja solo el fondo. | | pattern | "random", "plain", "rings", "stripes", "blobs", "dots", "horizon" | "random" | Patrón del fondo. plain es un color liso. | | palette | 5 colores #rrggbb | automática | Paleta manual. Si no se indica, o no es válida, el id elige una de las 12 paletas incluidas. | | size | número | 256 | Ancho y alto en píxeles escritos en el <svg>. El dibujo escala por su viewBox, así que no cambia nada más. |

• "character": robot, gato, búho, fantasma o monstruo.
• "object": caja, nube, bombilla, cohete, maceta o taza.
• "shape": hexágono, triángulo, rombo, cuadrado, estrella, corazón, gota o píldora.

Constantes

• SUBJECTS: valores válidos de subject. PATTERN_CHOICES: valores válidos de pattern. PATTERNS: solo los patrones dibujables. Útiles para construir selectores.
• PALETTES: las 12 paletas incluidas (5 colores cada una), como punto de partida para una paleta manual.
• DESIGN_VERSION: versión del dibujo. Es el valor que aparece en data-idicon-design de cada SVG.

Avatar (idicon/react)

Props: id (obligatorio), subject, pattern, palette, size, className, title. Dibuja el SVG en línea dentro de un <span>. Requiere React 18 o superior.

3. Garantías del generador

• Determinista. El mismo id con las mismas opciones produce siempre el mismo SVG, en cualquier máquina, navegador o versión de Node. No usa Math.random().
• Las opciones no se mezclan. Paleta, patrón, personaje y pose se deciden con secuencias independientes derivadas del id. Cambiar el patrón o los colores nunca cambia el personaje, la pose ni la cara, y viceversa.
• Máximo 6 colores. Los 5 de la paleta más la tinta de la cara, que se elige oscura o blanca según el contraste con el color sobre el que se dibuja.
• Contraste. Los colores de la paleta se reparten entre fondo, cuerpo, cara y acento comprobando que se distingan entre sí. Con una paleta manual, cada id reparte esos colores de forma distinta; si los 5 colores son muy parecidos, la cara puede perder contraste.
• Formato. Cuadrado de esquinas rectas, viewBox="0 0 120 120", unos 3-4 KB por avatar. El personaje queda recortado dentro del cuadrado aunque esté inclinado.
• Seguro. El id nunca aparece en el SVG generado. Hay un test que lo comprueba.
• Rápido. Generar un avatar cuesta microsegundos; se puede hacer en cada render sin cachear.

4. Estabilidad del diseño y versionado

El avatar de un id es el resultado de un dibujo concreto. Cualquier cambio en el dibujo (añadir un personaje, una paleta o un patrón, o reordenar decisiones aleatorias dentro de una capa) cambia los avatares de ids ya existentes. Para un cliente que ya conoce su avatar, eso parece un error. El proyecto tiene tres mecanismos para que nunca ocurra por accidente:

Candado de diseño (test automático)

src/lib/design-lock.test.ts genera 494 avatares (38 ids × 13 combinaciones de opciones), calcula una huella de cada uno y la compara con src/lib/__snapshots__/design-lock.json. Si cualquier avatar cambia en lo más mínimo, npm test falla y muestra qué ids y opciones se vieron afectados.

Un cambio de dibujo solo puede entrar si alguien lo acepta a propósito:

# 1. Subir DESIGN_VERSION en src/lib/avatar.ts (1 → 2)
# 2. Regenerar el candado
npm run design:accept
# 3. Anotarlo en CHANGELOG.md como cambio que altera avatares existentes
# 4. Publicar como versión MAYOR

Si el test falla y no querías cambiar el dibujo, el cambio tiene un efecto secundario: revísalo antes de aceptarlo.

Versión de diseño

DESIGN_VERSION (exportada y escrita en cada SVG como data-idicon-design) identifica el dibujo. Sube con cada cambio visual aceptado; las apps pueden usarla para saber con qué diseño se generó un avatar.

Integración continua

.github/workflows/ci.yml ejecuta lint, tests (con el candado) y ambos builds en cada push y pull request. Un check rojo en GitHub significa que el cambio no es seguro para publicar.

Reglas de versión (semver)

| Cambio | Versión | Ejemplo | | ------------------------------------------------- | --------- | ----------------- | | Altera algún avatar existente | Mayor | 1.4.2 → 2.0.0 | | Opción nueva que por defecto no cambia nada | Menor | 1.4.2 → 1.5.0 | | Corrección sin efecto visual, documentación, demo | Parche | 1.4.2 → 1.4.3 |

Mientras la versión sea 0.x, el dibujo todavía puede cambiar; antes de usarlo con clientes reales, publica 1.0.0 como compromiso de estabilidad.

5. Web de demostración

npm install
npm run dev        # http://localhost:5173
npm run build:demo # versión estática en dist-demo/

La demo permite escribir un id o generar uno aleatorio, elegir contenido, patrón y paleta (automática, predefinida, manual con selector de color y cuentagotas, o guardada con nombre), copiar la imagen al portapapeles como PNG, copiar el SVG, descargar en SVG o PNG, y guardar avatares en el navegador para volver a ellos.

6. Mantenimiento del paquete

npm run build          # compila la librería a dist/ (JS + .d.ts)
npm test               # tests del generador y candado de diseño
npm run lint           # oxlint
npm run design:accept  # acepta un cambio de dibujo (ver sección 4)

Estructura:

src/
  index.ts                 Entrada pública del paquete
  react.tsx                Entrada idicon/react
  lib/
    avatar.ts              Composición del avatar: fondo, personajes, cara, pose
    palettes.ts            Paletas, contraste y reparto de colores
    random.ts              Generador aleatorio con semilla (sfc32 + xmur3)
    avatar.test.ts         Tests de reglas (determinismo, colores, opciones...)
    design-lock.test.ts    Candado de diseño
    __snapshots__/         Huellas del candado
  App.tsx, components/, lib/*.ts restantes   Solo para la demo
scripts/fix-dts.mjs        Ajusta las rutas de import en los .d.ts tras compilar
.github/workflows/ci.yml   Integración continua
CHANGELOG.md               Historial de versiones

Solo lo exportado desde src/index.ts y src/react.tsx forma parte de la API pública. El resto es interno y puede cambiar.

Publicar una versión

1. npm test, npm run lint y npm run build pasan (y el CI está en verde).
2. Añade la entrada al CHANGELOG.md, indicando si altera avatares existentes.
3. Sube la versión según la tabla de la sección 4. Esto actualiza package.json y crea la etiqueta Git vX.Y.Z:

 npm version patch   # o minor, o major
 git push --follow-tags

4. Si se publica en un registro: npm pack --dry-run para revisar el contenido (solo dist/, README.md y package.json) y después npm publish. Para un registro privado con ámbito (por ejemplo @empresa/idicon en GitHub Packages), cambia name en package.json y configura publishConfig.registry antes.

npm publish ejecuta npm run build automáticamente (prepack), así que dist/ siempre se genera a partir del código actual. Las apps que instalan desde Git con #vX.Y.Z también compilan dist/ al instalar.