Themes/Modes: plugin declaration proposal

Hello Duaelfr

Maybe I'm missing something but why do you care about how each Design System manages its variants?

"Themes" (or "Modes") are often a "first class" artifacts in design system, they have a name, a documentation, a purpose, and a lifecycle. So, it will convenient to manipulate them as "first class" obejcts too.

The core need is to have more than one preset of CSS vars and to be able to switch from one to another.

Not every design systems design its themes as combinations of CSS vars. Some design systems have themes but no CSS variables. Some design have both, but they are not related.

Theme definition is UI SKins will be needed for https://www.drupal.org/project/ui_suite_bootstrap/issues/3351580#comment...

We need the usual metadata:

• id, string : Machine name, unique and persistent
• label, string : Human-friendly, preferably short, name
• description, string : Human-friendly, more lengthy, explanation
• status, string : Its stage in a lifecycle: Incomplete, Draft, Published, Obsolete... No processing is made on this value.

And properties specific to theme processing:

Attachment value (string, free text)

The keyword which will be attached (as a class name or a data attribute value). If empty, it is the plugin ID, with Html:::getClass() applied.

Attachment method (string, free text)

2 values:

• If empty, the value will be merged into an HTML class attributes
• If value, this will be the HTML attribute name (it will often be a data-* attribute, but not always)

Examples:

• HTML data attribute : DSFR, Bootsrap4
• HTML class: Mozilla Protocol

Attachment target (string, enum)

3 values:

• Empty: the theme (class or data attribute) is scopable, so it can be processed in 2 different ways:
  • If selected from Drupal theme settings page, it will be added (as a class or a data attribute) to the HTML body element.
  • It will also be possible to add it to any element of the page, like the styles from UI Styles.
• "html": the theme (class or data attribute) will be added to the HTML root element
• 'body" the theme (class or data attribute) will be added to the HTML body element

Examples:

• Empty (so "scopable"): Bootstrap 5, Mozilla Protocol
• "html": DSFR

Asset library

A single assets library definition, which will be loaded if the theme is called in a render request.

Examples: Europa

Example for Bootstrap 5.3:

id: dark
label: Dark
description: ...
# No value because same as plugin ID
method: "data-bs-theme"
# No target because scopable

id: light
label: Light
description: ...
# No value because same as plugin ID
method: "data-bs-theme"
# No target because scopable

Example for Mozilla Protocol:

id: dark
label: Dark
description: ...
value: "mzp-t-dark"
# No method because class name
# No target because scopable

Example for Ant Design:

id: dark
label: "Dark"
library:
  css:
   "dist/antd.dark.min.css": {}

id: compact
label: "Compact"
library:
  css:
   "dist/antd.compact.min.css": {}

Vocabulary:

• Bootstrap5: "color mode" https://getbootstrap.com/docs/5.3/customize/color-modes/
• DSFR: "theme" or "scheme"
• Mozilla Protocol: "theme" https://protocol.mozilla.org/docs/fundamentals/brand-themes.html
• Ant Design: "theme" or "mode" https://ant.design/docs/spec/dark
• Material: "theme" https://m2.material.io/design/color/dark-theme.html

Thanks for your work.

Tested on DSFR:

system:
  label: "System"
  method: data-fr-scheme
  target: html
  
light:
  label: "Light"
  method: data-fr-scheme
  target: html
  
dark:
  label: "Dark"
  method: data-fr-scheme
  target: html

It was working well at the end but I got one fatal error:

TypeError: array_keys(): Argument #1 ($array) must be of type array, null given in array_keys() (line 75 of  Drupal\ui_skins\HookHandler\PreprocessHtml                              
Warning: Undefined property: Drupal\Core\Extension\Extension::$base_themes in Drupal\ui_skins\HookHandler\PreprocessHtml->preprocess()                                                                                          

Not related to my tests, but there is an use case not met yet, but we may need to be able to add theme as a meta element. Example: <meta name="theme" content="system">

So, my proposal:

• Rename "method" property to "key", so we have key value.
• Don't implement yet "meta" target yet, but don't make it impossible to implement later

target	key	value	result
""	""	bar	<body class="bar">
html	""	bar	<html class="bar">
body	""	bar	<body class="bar">
meta	""	bar	???
""	foo	bar	<body foo="bar">
html	foo	bar	<html foo="bar">
body	foo	bar	<body foo="bar">
meta	foo	bar	<meta name="foo" content="bar">

Also, on /admin/appearance/settings/{theme} page, the Themes select list must not be mandatory. The default value must be empty (no theme), and it is possible to select this default empty value.