Temas empresariales

Cada empresa (dominio) puede definir toda su paleta y toda la aplicación se adapta a ella: modo claro y oscuro, radio de esquinas, tipografía y qué temas genéricos puede elegir el usuario. El motor garantiza contraste WCAG 2.1 AA por defecto. El tema se guarda en Domain.theme (backend) y se sirve por GET /api/config.

Modelo de configuración#

Cómo se interpreta#

• Con algún color (campo antiguo o palette) se generan dos temas completos, brand-light y brand-dark. Radio, fuente o modo solos no crean temas de empresa.
• Si defines un solo modo, el otro se deriva del fondo del primero (conserva el matiz; luminosidad 8 % en oscuro y 97.5 % en claro).
• Un fondo de esquema contrario (oscuro en palette.light o claro en palette.dark) se descarta con aviso: nunca se pinta un lienzo oscuro con tokens claros.
• Un muted, borde o secundario casi idéntico al fondo (por ejemplo #ffffff sobre #ffffff) se descarta y se deriva uno visible (solo con autoFixContrast distinto de false).
• Con autoFixContrast: true, un color que no cumple AA se ajusta al más cercano que sí cumple. El editor del panel muestra el color elegido, el aplicado y su ratio.
• Las claves desconocidas se descartan al guardar (el backend y el frontend usan el mismo saneador, con hex normalizado a #rrggbb).

Tokens y su función#

Hay 49 tokens (--color-<token> y utilidades Tailwind bg-<token>, text-<token>, border-<token>, ring-<token>, con opacidad como bg-primary/10). Los componentes de BloomX solo usan estos tokens, nunca hex ni paletas crudas.

Además del color: --radius (todas las clases rounded-* derivan de él; rounded-full no cambia) y las variables de fuente --font-body y --font-title.

Guía para diseñadores#

1. Empieza con 2–3 colores: primary (marca), brand-accent (segundo color) y background. El motor deriva los otros 40+ tokens y garantiza AA. Define foreground, card, muted, border solo si la marca los exige.
2. Elige `primary` pensando en dos usos: relleno de botón (con primary-foreground encima) y texto/enlace sobre el fondo (text-primary debe llegar a 4.5:1 sobre background y card). Un primario muy claro suele fallar como texto en modo claro; usa uno más oscuro en palette.light y uno más claro en palette.dark.
3. Define el modo oscuro por separado cuando tengas una versión de marca oscura: los tonos que funcionan sobre blanco casi nunca funcionan sobre #101418.
4. Fondos oscuros: evita negros puros (#000000) salvo intención AMOLED; un fondo muy oscuro y otro card apenas más claro mantienen la jerarquía.
5. Estados (destructive, success, warning, info): conservan su matiz semántico y solo se corrige el contraste. No los cambies a menos que la marca lo exija.
6. Radio y fuente cambian la personalidad sin tocar contraste: radius: "none" para un estilo corporativo recto, "xl" para uno amable; fontFamily solo admite la lista blanca (sin fuentes web propias).
7. Verifica con npm run check:themes añadiendo tu paleta a BRAND_FIXTURES (src/lib/theme-fixtures.ts) y con el editor del panel, que avisa en vivo de cada par que incumple.

Contraste AA: qué se exige#

Ejemplos JSON#

{
  "primaryColor": "#0b5fff",
  "accentColor": "#f59e0b"
}

{
  "defaultMode": "system",
  "radius": "lg",
  "fontFamily": "humanist",
  "allowedThemes": ["midnight", "contrast"],
  "lockBrand": false,
  "autoFixContrast": true,
  "palette": {
    "light": {
      "background": "#fafaf7",
      "foreground": "#1c1b18",
      "primary": "#0b5fff",
      "primary-foreground": "#ffffff",
      "brand-accent": "#b45309",
      "sidebar": "#f1efe8",
      "header": "#ffffff"
    },
    "dark": {
      "background": "#101418",
      "foreground": "#eef1f5",
      "primary": "#6ea8ff",
      "primary-foreground": "#0a0f1a",
      "brand-accent": "#fbbf24",
      "sidebar": "#0b0e12"
    }
  }
}

{
  "lockBrand": true,
  "defaultMode": "light",
  "palette": {
    "light": { "primary": "#7c3aed", "background": "#faf5ff" },
    "dark":  { "primary": "#c4b5fd", "background": "#120a1f" }
  }
}

# Guardar el tema de la empresa (sesión de manager). El cuerpo REEMPLAZA todo el tema, incluida la landing.
curl -sS -X PUT "$BACKEND/api/admin/domain" \
  -H 'content-type: application/json' -b 'auth_session=<cookie>' \
  -d '{"theme": { "primaryColor": "#0b5fff", "radius": "lg", "landing": { "layout": "split-right" } } }'

Qué ve el usuario#

• Con colores de empresa, el selector muestra primero "<Empresa> · Claro" y "<Empresa> · Oscuro" y luego los genéricos permitidos (light y dark se ocultan porque los sustituyen, salvo que estén en allowedThemes).
• defaultMode solo aplica si el usuario no ha elegido (sin cookie, localStorage ni BD). Una elección explícita, incluido "Sistema", gana siempre.
• Una preferencia guardada que ya no es elegible se remapea al tema por defecto de su mismo esquema, sin borrar lo guardado. Con lockBrand, todas.
• Sin configuración de empresa: los 8 temas genéricos y system, como siempre. El tema se inyecta en el servidor (<style id="bx-brand">) y hay un script anti-parpadeo.

Probar en local#

1. Sin backend: define NEXT_PUBLIC_BLOOMX_THEME_OVERRIDE en .env.local y reinicia next dev. Sustituye el tema de /api/config (servidor y cliente) y se ignora en producción. Borra la cookie bloomx-theme y localStorage["bloomx:theme:v1"] para ver defaultMode.
2. Contraste: npm run check:themes.
3. Tests: los de tema y selección.
4. Avisos por token: buildBrandThemes(cfg)?.warnings (o analyzeBrandTheme(cfg)) devuelve, por token, el valor elegido, el aplicado, los ratios y si se corrigió.

# .env.local (solo desarrollo; se ignora en producción). Una línea, JSON válido.
NEXT_PUBLIC_BLOOMX_THEME_OVERRIDE={"primaryColor":"#7c3aed","backgroundColor":"#faf5ff","defaultMode":"dark","radius":"lg","fontFamily":"humanist","palette":{"dark":{"background":"#120a1f","sidebar":"#0d0716"}}}

npm run check:themes            # contraste AA de los 8 temas y de los 12 ejemplos de empresa
npm run check:themes -- --md    # tabla en Markdown
npx vitest run src/lib/__tests__/brand-theme.test.ts src/lib/__tests__/theme-config.test.ts src/lib/__tests__/theme-selection.test.ts

Temas genéricos#

Sin configuración de empresa hay 8 temas: light, dark, midnight, amoled, ocean, forest, rose y contrast (alto contraste), más Sistema. La preferencia se guarda en cookie, localStorage y en la cuenta. El correo entrante tiene además su propia opción de modo (oscurecer, por defecto, o papel claro; mailDarkMode).

Límites conocidos#

• Solo overlay admite alfa; el resto de colores se rechaza si trae alfa distinto de ff.
• La red de seguridad que remapea las escalas crudas de Tailwind en temas oscuros existe para código antiguo; el código nuevo no debe contar con ella.
• Las fuentes son solo las de la lista blanca (sin cargar fuentes propias).
• Los colores de agenda, calendarios y etiquetas de usuario los elige cada usuario; el texto encima se calcula por contraste.