Portal Theme Consumption

Receive themeObject from the Portal Shell via ThemeResponseMessage and wire it to ThemeProvider for @by/experience-system.

Portal MFEs can align @by/experience-system with the shell’s Fractal theme settings by listening for ThemeResponseMessage and applying themeObject to ThemeProvider. The Portal Shell pushes theme updates; on startup your app should also request the current theme so the initial render matches the user’s selection.

Prerequisites

@jda/lui-portal-utilities ≥ 3.65.0 — PortalMessageService, MessageActions, ThemeResponseMessage, ThemeRequestMessage.
@by/plat-lui-portal-mui5 ≥ 2.20.0 — typings and payloads aligned with the Portal theme contract for @by/experience-system.
@by/experience-system — ThemeProvider and theming; complete Installation (Tailwind / theme.css, peers) first.

What to use from the message

For @by/experience-system, read themeMessage.themeObject from ThemeResponseMessage when message.action === MessageActions.ThemeResponse. It carries the fields ThemeProvider needs: theme, color, spacing, and direction.

Older ThemeSwitchRequestMessage / ThemeSwitchResponseMessage flows remain available for backward compatibility; prefer ThemeRequestMessage and ThemeResponseMessage with MessageActions.ThemeRequest and MessageActions.ThemeResponse for new work.

Avoid message.theme or unrelated themeObject shapes meant only for legacy CCL/MUI layers (LuiThemeProvider). Snippets below wire themeMessage.themeObject into ThemeProvider only.

Listen and request the theme

Register a handler with PortalMessageService.getInstance().registerListener.
On MessageActions.ThemeResponse, cast the message to ThemeResponseMessage and read themeObject (for example into React state).
On mount, send ThemeRequestMessage so the shell responds with the current theme.
On unmount, clean up with the API your version exposes (destroy() or removeListener) so you do not leak listeners.

Wire ThemeProvider

Store themeObject (or destructure it) and pass theme, color, spacing, and direction into ThemeProvider at the root of the tree that renders Experience System components.

'use client';

import { ThemeProvider } from '@by/experience-system';
import {
  Message,
  MessageActions,
  PortalMessageService,
  ThemeRequestMessage,
  ThemeResponseMessage,
} from '@jda/lui-portal-utilities';
import { useEffect, useState } from 'react';

const defaultPortalTheme = {
  theme: 'fractal' as const,
  color: 'light' as const,
  spacing: 'standard' as const,
  direction: 'ltr' as const,
};

export function AppWithPortalTheme({ children }: { children: React.ReactNode }) {
  const [portalTheme, setPortalTheme] = useState(defaultPortalTheme);

  useEffect(() => {
    const portalEventsHandler = (message: Message) => {
      if (message.action === MessageActions.ThemeResponse) {
        const themeMessage = message as ThemeResponseMessage;
        const themeObject = themeMessage.themeObject;
        setPortalTheme({
          theme: themeObject.theme,
          color: themeObject.color,
          spacing: themeObject.spacing,
          direction: themeObject.direction ?? 'ltr',
        });
      }
    };

    const portalMessageService = PortalMessageService.getInstance();
    portalMessageService.registerListener(portalEventsHandler);

    const themeRequestMessage = new ThemeRequestMessage();
    portalMessageService.sendMessageToPortal(themeRequestMessage);

    return () => {
      portalMessageService.destroy();
    };
  }, []);

  return (
    <ThemeProvider
      theme={portalTheme.theme}
      color={portalTheme.color}
      spacing={portalTheme.spacing}
      direction={portalTheme.direction}
    >
      {children}
    </ThemeProvider>
  );
}

Adjust defaults and cleanup to match your app. The important contract is themeMessage.themeObject → ThemeProvider props only.

Agent workflow

For a step-by-step setup (new app or migrating an existing listener), install the portal-theme-message-skill from the Skills page via the @by-es registry.

Installation — Tailwind, theme.css, and ThemeProvider
Skills — portal-theme-message-skill registry item