2026-05-07 Frontend Working Group Meeting Notes: All Good for Verawood

All public Working Group meetings follow the Recording Policy for Open edX Meetings

Time, location

Time: 15:00 UTC
Location: https://meet.google.com/wxe-myxy-uei

Agenda

Shimming the Paragon theme
Where are we in frontend-base land (@Adolfo Brandes)
- All good for Verawood!
- Help button
- Course bar: navigation + masquerade
- frontend-base-compat
What’s next in frontend-base land (@Adolfo Brandes)
- For the conference:
  - Operator and developer documentation
- For Willow:
  - Convert every remaining MFE (with the potential exception of Authoring)
  - All enabled by default on Tutor
- For Xylon:
  - Merge all frontend-base branches to main
- If any MFEs other than Authoring cannot be completed (for example Learning), the deadline gets pushed back one release

📝Notes

A shim for env.config:PARAGON_THEME_URLS → site.config:theme

Where before we had:

// env.config.jsx

const config = {
  PARAGON_THEME_URLS: {
    "variants": {
      "light": {
        "urls": {
          "default": "https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/light.min.css",
          "brandOverride": "https://cdn.jsdelivr.net/gh/openedx/sample-plugin@main/brand/dist/light.min.css"
        },
        "url": "https://cdn.jsdelivr.net/gh/openedx/sample-plugin@main/brand/dist/light.min.css"
      }
    }
  }
}

Where variants.light.urls.default is equivalent to variants.light.url.

Now we have:

// site.config

const siteConfig = {
  theme: {
    variants: {
      light: {
        url: "https://cdn.jsdelivr.net/gh/openedx/sample-plugin@main/brand/dist/light.min.css"
      }
    }
  }
}

Where variants.light.url is equivalent to env.config.jsx’s variants.light.urls.brandOverride (but NOT variants.light.url).

Use these two as a Rosetta stone for the shim:

Also look into the sample plugin brand for a way to test the shim:

https://github.com/openedx/sample-plugin/tree/main/brand

Decisions

Action items

Shim the PARAGON_THEME_URLS mfe_config variable @Adolfo Brandes

Previous Action Items

🎥Recording

Participants

Adolfo, Brian

🤖 Summary

Adolfo Brandes and Brian Smith discussed the frontend-base migration, the compatibility shim, MFE conversion plans, Paragon theming compatibility, documentation gaps, and how to treat app-level design tokens as API surface. References to micro-frontends have been normalized to MFE/MFEs.

Key points

The team acknowledged that the compatibility shim is useful for helping downstream consumers upgrade, but it creates engineering and maintenance pain. They want to treat it as an “expand-contract” mechanism: take on temporary complexity now to make adoption easier, then deprecate and remove the shim once consumers have migrated.

They emphasized that documentation needs to be written from the consumer’s point of view. Existing information is scattered, and even the maintainers sometimes struggle to find the right configuration examples. The docs should make it clear where consumers can use legacy slots, where the shim makes things work automatically, and where they need to change their implementation.

A substantial part of the discussion focused on Paragon theme URL compatibility between existing MFE configuration and frontend-base configuration. The team determined that the compatibility layer needs to translate the old PARAGON_THEME_URLS-style configuration into the frontend-base theme configuration. The important mapping is to use the old brandOverride URL as the new frontend-base theme URL, while ignoring the old default URL because frontend-base assumes the installed Paragon styles are already present.

They also discussed edge cases around custom theme variants. In frontend-platform, the old setup could load a default theme plus a brand override, while frontend-base simplifies this. Some complex variant cases may need more testing, but the immediate compatibility mapping appears straightforward.

Project status

Frontend-base is in good shape for the Verawood timeframe. The instructor dashboard work, including the course bar and masquerade bar, has landed and should reach sandboxes for testing. Brian’s help button work addressed another missing header feature. Adolfo’s compatibility layer is already in Tutor MFE and documented there, though they do not expect heavy usage because existing MFEs are not enabled by default.

For the next phase, the team wants to focus heavily on documentation before the release. They want every frontend-plugin-framework slot example to indicate whether it works with the compatibility shim and, when it does not, what consumers should do instead.

Release planning

For Willow, the goal is to convert the remaining MFEs, with authoring likely being the main exception. The plan is for Willow to be the transition release. Once Willow is released and the next development cycle opens, the team expects to merge frontend-base work back into main and stop maintaining separate frontend-base branches.

The largest risk is the learning MFE. Brian described authoring as the “beast” and learning as a “mini boss.” If learning cannot be converted to production quality in time for Willow, the broader deprecation and default-enablement plan may slip by one release. Still, the target remains Willow, with the understanding that they should not mark something as done merely to hit the deadline.

They agreed that conversions should follow the frontend-base architecture. Porting some existing technical debt is acceptable inside the frontend-base model, but they do not want to bring over strange MFE-specific architecture, especially around headers or other shell-level behavior.

Learning MFE concerns

The learning MFE will be a major test of both the shim and the frontend-base slot system. The team expects a significant number of slots and downstream extensions to handle, because learning is one of the most commonly customized areas. They specifically called out the sidebar and header behavior as areas that may require careful porting.

The masquerade-related work is already mostly handled, which reduces some risk. The remaining uncertainty is around hidden complexity: places where the learning MFE may not fit cleanly into the frontend-base shell.

Application tokens and theming API

Brian noted that application token support has landed in Paragon. The team then discussed how apps should name and expose CSS variables for theme customization.

They agreed that adding app-level variables is similar to adding slots: it creates API surface that maintainers may need to support over time. Therefore, new variables should be added sparingly and reviewed carefully. Whenever possible, apps should use existing Paragon variables instead of creating app-specific ones.

They pushed back on the idea of exposing many variables tied to specific DOM elements, such as sidebar heading wrapper borders. That would effectively make internal HTML structure part of the public API, which they do not want. Instead, customization should target stable product or design concepts, not implementation details.

For now, app-level variables are considered “v0” or “wild west” unless they are namespaced, documented, and covered by an ADR or deprecation policy. The team will still try not to break them unnecessarily, but they are not yet treated as stable public APIs.

Decisions and agreements

The shim should remain temporary and should eventually be deprecated.

Documentation should be improved around legacy slots, frontend-base slots, shim behavior, and migration examples.

Paragon theme compatibility should map old brandOverride URLs into the new frontend-base theme URL configuration.

Frontend-base is considered production-ready for the MFEs that have already been converted.

Willow remains the target for converting the remaining MFEs, except likely authoring.

Learning is the biggest schedule risk among the MFEs targeted for Willow.

App-level theme variables should be treated like API surface and reviewed with similar care to plugin slots.

Existing Paragon variables should be preferred over introducing new app-specific variables.

App-specific variables are not stable APIs until they are properly namespaced and documented.

Action items

Adolfo will add a shim translation for Paragon theme URLs based on the mapping discussed.

The team should improve documentation for frontend-base slot compatibility, including which examples work with the shim and which require changes.

The team should consider writing an ADR documenting the shim’s Paragon theme URL behavior after the implementation lands.

The team should test more complex theme variant cases to confirm how well the compatibility mapping works.

Brian will use the application-token discussion to shape guidance for his conference talk, especially around when app-level customization should be accepted upstream versus kept in a downstream fork.