Hi Ole, first of all, thank you. Taking the time to write this up and to build a working proposal is a very valuable contribution, and it is exactly the kind of feedback that helps us prioritise. Sorry as well for the detour: the page Victor linked covers the administration dark mode only, which is not what you asked about in March.
I am not sure you have had the chance to see it, but with 2026.Q3 we also shipped a second theme, Prism, that already carries the double value per token. It is behind the same Beta flag (Dark and Light Mode, LPD-57922, or Clay’s Global Frontend Token Definitions, LPD-84497), and once the flag is on it becomes the default theme for new sites. Its frontend-token-definition.json defines the colour tokens as pairs, for example light-dark(#fff, #111116) for white or light-dark(#f7f8f9, #272833) for gray-100; 158 of its 305 tokens work that way. Clay resolves them through color-scheme and the data-color-scheme attribute on html, and the Style Book colour picker accepts light-dark() values since Q3, so a Style Book based on Prism can already hold a light and a dark value for every colour token.
What Prism does not offer yet is a comfortable way to manage those double tokens: today you write the pair in the token field. That is deliberate for now, and the reason is the paragraph below. We do not want to be prescriptive about how each site solves light and dark, or whether it needs more skins (High Contrast variants are coming for the administration and whatever we build has to scale to four colour schemes, not two), and the same goes for whether the scheme should follow the operating system or a control on the site.
That is also why we split the themes: Classic stays exactly as it was, so nothing breaks for existing sites, and Prism is the example of how a theme collects dark and light values on top of Clay tokens. And I do mean an example, not the way to do it. The token pair in Prism is one option; a theme can just as well ship two Style Books and switch between them, or resolve the scheme in its own CSS with prefers-color-scheme, or expose only the tokens it wants to expose and keep the rest fixed. In fact, other customers have implemented dark mode in completely different ways, and those are just as valid. Our job is to make sure the token system does not get in the way of any of them, not to pick one for you.
One more piece that may help: with the flag on, the Product Menu has a global light/dark switch (the moon/sun button). It stores the choice in the session of the signed-in user and writes it as data-color-scheme on the html element, which is what Clay and the Prism tokens react to. If your theme picks that attribute up the way Prism’s portal_normal.ftl does, editors and administrators switch schemes with that button while they work, and no extra switch is needed inside the page editor: the page simply renders whatever the Style Book resolves to for the active scheme. Note that this covers signed-in users only. For the anonymous visitor of the site, whether the scheme follows the operating system or a control you add is still your decision, which is exactly the point above about not being prescriptive.
The editing experience for the tokens themselves is designed and on the roadmap: a light/dark switch in the Style Book editor, which is where we believe colour tokens should be managed, rather than in the page editor.
We will take your feedback into account as we finish that work, in particular the need you describe for editors to manage both schemes without leaving the low-code tools. Thanks again for pushing on this.
Prism token definition, for reference: modules/apps/frontend-theme/frontend-theme-prism/src/WEB-INF/frontend-token-definition.json in master.
