diff -u b/core/lib/Drupal/Core/Theme/ThemeNegotiatorInterface.php b/core/lib/Drupal/Core/Theme/ThemeNegotiatorInterface.php --- b/core/lib/Drupal/Core/Theme/ThemeNegotiatorInterface.php +++ b/core/lib/Drupal/Core/Theme/ThemeNegotiatorInterface.php @@ -12,11 +12,18 @@ /** * Defines an interface for classes which determine the active theme. * - * In order to set the active theme you have to create a new service tagged - * with 'theme_negotiator', see user.services.yml as example. The only method - * this service has to implement is determineActiveTheme. Return the name of the - * theme or NULL, if other negotiators like the configured default one should - * kick in instead. + * To set the active theme, create a new service tagged with 'theme_negotiator' + * (see user.services.yml for an example). The only method this service needs + * to implement is determineActiveTheme. Return the name of the theme, or NULL + * if other negotiators like the configured default one should kick in instead. + * + * If you are setting a theme which is closely tied to the functionality of a + * particular page or set of pages (such that the page might not function + * correctly if a different theme is used), make sure to set the priority on + * the service to a high number so that it is not accidentally overridden by + * other theme negotiators. By convention, a priority of "1000" is used in + * these cases; see \Drupal\Core\Theme\AjaxBasePageNegotiator and + * core.services.yml for an example. */ interface ThemeNegotiatorInterface {