Weekly update – 30 May 2025 – Customizing default theme in AdminThemeUikit

[adrian]

I really agree with @teppo here - setting css vars outside of the root context seems dangerous.

I am not expecting an infinite number of css vars, just not reusing of ones that don't seem semantically correct, like my example of --masthead-active-color also being used for all submenu items and --muted-color being used for hidden pages along with page list actions. It honestly feels like --muted-color may as well be called --light-grey in the sense that it's describing a color, rather than a usage which defeats the flexibility of css vars.

I'd be happy to compile a starting list of the vars that I think we need (and what they should be used for) and then have other passionate and skilled folks her chime in to help refine. I think with a little brainstorming we can end up with something really powerful and flexible and all defined at the root level.

[bernhard]

What we are doing here is basically reinventing the wheel. We are trying to invent a new design system that makes it easy for developers to be used and to be customised. But we already have this design system. It is called UIkit. It is in the core. It is built on logical and semantical components (base, text, buttons, background, utilities, ...) and it has thoughtfully defined and well documented (!) variables and concepts.

Yes, it uses LESS (or SASS), which is not the coolest technology on earth. But this decision has been taken by @ryan in 2017.

If the decision was that CSS variables are superior and we proceed with them: More than happy! I'm using CSS variables all over in my projects (on the frontend). But keeping UIkit/LESS as the foundation and then adding a new theme with 3200+ lines of overrides just does not fit with the genius and beautiful image that I have had of ProcessWire.

To me it looks like somebody was decorating a cake here. Adding layer over layer to make the cake look good. For me it just doesn't taste 😞 It never really did (ui-button vs. uk-button-primary, etc), but it was ok. It was the reality that I grew up with. Now it's different. Now things got a lot worse and I think this was not necessary.

I guess I was hoping that all the effort that was put into a new admin style would bring some fundamental improvements of the overall situation. @ryan, you have pushed so many great updates over all those years and you have solved so many problems in a way that just left me behind with deep respect and amazement. Now we have yet another layer of complexity to deal with when working on backend modules. I'm not happy this time 😞 

I appreciate all the effort that you put into making PW attract new users and I understand that it must be frustrating to get such a harsh feedback by some of us. Especially after putting so much work into it. The thing is: It did not have to be like this. Why not ask the community upfront? Before all the work has gone into it? To have an unbiased view? To keep the risk and emotions low (for everybody)? To hear what others might think of such a fundamental change? To get feedback and maybe even good ideas? Or to explain what is considered to be fundamental and what is considered to be experimental?

The question is: What now?

The decision was obviously taken long time ago, so I guess we have to deal with it (even though I think it would be the best to take it back completely). If you ask me - as a long term member and contributor - what I'd like to see to make things less painful for now and make things better long term, here are my suggestions:

• make the css variables used in the new theme be aligned with UIkits less variables (--main-color vs. @global-primary-background ...)
• remove dark mode completely, or, at least, disable it by default and add a warning that it is experimental - I think it will cause 99% of work for very little benefit
• add docs for the new theme and the concepts it uses
• rewrite the whole admin theme/framework from ground up with a modern stack (css variables + Alpine JS + darkmode) as soon as possible

Thank you and all the best for the future of ProcessWire

[bernhard]

23 hours ago, ryan said:

No, it is not a matter of time before the old one is no longer supported. I've said this a few times already, but the Original theme is not leaving. It is "base" theme of ProcessWire, and the one which the new Default theme depends upon. If some new feature is added, it has to be accounted for in the Original theme before the new Default one. If these themes were like PHP classes, then the Original would be like WireArray, and the new Default would be like PageArray... one inherits from and depends on the other. The new Default theme is not a separate theme the way that AdminThemeReno was a separate theme. If the Original style suits your needs better, there is no reason to transition.

That sounds too good to be true. I'm not sure I understand how that is supposed to work, for example:

• Does that mean that the sticky navbar, which is great, will somehow also be moved to the base theme to make the rock and reno themes benefit from that addition as well?
• Does that mean that the CMD+K hotkey will be moved to the base theme as well?

If that is the case, I apologise. Because then it means that I misinterpreted the current setup. My interpretation from what I saw in the code and folder structure was that there is a lot of stuff going on in the new theme that seemed to me like it was designed to be part of the new theme only.

On 5/30/2025 at 9:46 PM, ryan said:

You can adjust the button-background CSS variable:

.light-theme {
    /* if you prefer not to have black buttons on light theme... */ 
    /* use main color for button color */
    --button-background: var(--main-color);
}

.pw .ui-button.ui-state-hover {
    /* highlight button when hovered */
    filter: brightness(1.08);
}

Sorry @ryan, but this does not work! If you have a <button class='uk-button uk-button-primary'> anywhere in the backend the hover effect that you showed will not be applied to that button. If that's expected and "uk-button-primary" is not supposed to be used, then it would be great if you could add docs about how to add basic UI elements like a primary button to the PW backend in a correct and reliable way. Thx.

On 5/31/2025 at 3:01 PM, diogo said:

In your specific case, you would style the headlines with

color: var(--text-color, #000);

Sorry @diogo but what might look like a simple line of css to you is actually much more. First, I can't just fallback to #000 when supporting other themes (like reno or rock), it needs to be a LESS variable. So it would probably be something like var(--text-color, @global-color). This also shows why I think it would be great for module authors to have css variables and uikit variables at least follow the same naming conventions, if we have to support both from now on.

Second, this line of css is one line that was not necessary before. This might mean for many modules that they need to provide a CSS file now. Still sounds like I'm making a mountain out of a molehill? I'm not. Having to provide no css file compared to 1 css file means that we need to deal with a lot. We might need to add an additional build step. Maybe even an automated CI workflow. Or we need to add a dependency (like RockDevTools) that watches our LESS assets and compiles them to CSS that every module user can use without any hassle.

These are all a lot of costs. I'm just wondering whether they have been considered.

On 5/31/2025 at 3:01 PM, diogo said:

<button class="uk-button uk-button-default">normal button</button>
<button class="uk-button uk-button-primary">primary button</button>

styles the buttons correctly for me

@diogo you are taking my example out of context! I was trying to explain the problems that evolve from the PW backend using different classes for different things (ui-button vs. uk-button-primary etc). And your out-of-context reply shows me that there seems to be a blind spot about the fundamental problems that we are facing now. UIkit has hundreds of classes. My point is that trying to override them instead of actually using them is a very bad idea!

So please try <h1 class='uk-text-primary'>Hello World</h1>

This is what I mean by the cake does not taste. Having to file github issues for all UIkit classes that are not yet "properly" overridden by the new default theme is... Not elegant. It's not what ProcessWire has been for me for such a long time. It's not fun.

---

PS: Don't want to restart the discussion about details here. I just tried to respond to answers that are related to and underline what I wrote above. For me it's not about details. For me it's about the bigger picture.

[bernhard]

Ok so here I am again. Very sorry for that. Maybe I'm overreacting. I hope so! But I tried to go on and work on support requests for my modules just to get confronted with the next missing override (uikit progress bar) a few clicks later 😞 So I went ahead as requested and created an issue on github to collect and report all problems caused by missing overrides in the new theme.

While posting this screenshot I realised something concerning though 😞 

Now I'm wondering: Why are these elements actually showing up in RENO green?

Why does that matter so much? Some background...

Spoiler

When I started working on the same goals that seem to be driving this new theme's development back in 2021 I tried to understand how the PW backend was built and how it worked. I looked at the reno theme and first was overwhelmed by how many lines of code this file had. No offence in that case - it just look like an impossible task to create a custom style for the PW backend that does NOT rely on the quite specific reno pink/green combo.

But I didn't give up so fast. So I tried to remove all of those reno-styles and see what happens. This was the result:

I was quite surprised!! This looked... ok. Not perfect, but it looked like... UIkit!

This was the moment when I understood which parts actually come from UIkit and which are part of the reno theme. And as I knew UIkit quite well I thought it could not be that hard to create a style that uses some of the available UIkit less variables and combines them to make it possible to change the primary color easily to match the backend to the clients' UI.

The "rock" style was born:

If you compare both screenshots you see that the primary color was changed, which is a thing of changing one single LESS variable (@rock-primary) and the message style was changed to a neutral grey instead of the default primary color (which could be green or red if the main color is one of those, which could result in a regular message looking like a red warning). And the space on top of this bar has been removed.

All that was done with 65 lines of code.

So I created a PR and it was luckily merged by @ryan and explained in a blog post: https://processwire.com/blog/posts/pw-3.0.179/

Yes, it clearly lacked contrast, but the key achievement was to split the old monolith reno theme into a base style (pw.less) and on top of that build whatever style you want (/styles/reno.less and /styles/rock.less). You can see that here on github.

It also came with a readme that explained how it was supposed to work and how it was supposed to be called. For example I have been asking to call new designs "style" and not "theme", because I think this would help to avoid a lot of confusion. We already had three themes (AdminThemeDefault, AdminThemeReno, AdminThemeUikit) back then, so I thought it would be a good idea to call these "themes" (as that term has been used for it all the time) and call the new "styles" differently to make it more obvious what we are talking about.

Now we just witnessed a launch of a new "default theme" and @ryan had to explain, that it's not a new theme, but just a new style on top of UIkit. Look at the title of this thread... We have a new theme! Look at where the new style has been placed in the core (wire/modules/AdminTheme/AdminThemeUikit/themes/default). We have a new theme! Not blaming anybody and it's obviously Ryan's decision how to call things and where to place them. I just try to explain why the confusion and frustration is not a surprise to me and what I think are the underlying problems that have to be tackled (or should have to be tackled).

And I can't help but wonder why the new "theme" breaks with many of these old principles that have been around for so long. That have been our common ground for building modules for the PW backend.

I hope that now, @ryan, you can better understand, why I can't really believe what you wrote above. That the new "theme" works like extending PHP classes. That it is just extending the base theme and all other themes (like rock and reno) will continue to just work. I'd love to believe it. But I did just a few clicks and already see a lot of issues.

So with all the context I can't believe it 😞 That's why I got so concerned when seeing these elements showing up in RENO green.
(and not in the default UIkit blue from the global PW base style without any overrides applied)

IMHO it shows a design layer that should not be there which shows what I'd consider to be a fundamental problem with the approach that this theme takes.

So I want to add to my list from above:

• Can the new "theme" please use the base style (pw.less) as a foundation?
  I fear that the more layers we have that override each other the more complex and the more prone to errors it will get
• Is there any chance that the new theme properly uses UIkit hooks to add support for CSS variables instead of overriding everything?
  I think that the readability and the long time maintainability of the new theme would benefit a lot from that. Especially when the same convention for variable names is being used (which I already asked for).

[adrian]

5 hours ago, bernhard said:

Does that mean that the sticky navbar, which is great, will somehow also be moved to the base theme to make the rock and reno themes benefit from that addition as well?

On this note, I have already noted that this has affected Tracy and the z-index I need to set for its panels. How can I support it to work properly for the base UIKit and the new theme? 

[teppo]

On 6/1/2025 at 2:35 AM, adrian said:

I'd be happy to compile a starting list of the vars that I think we need (and what they should be used for) and then have other passionate and skilled folks her chime in to help refine. I think with a little brainstorming we can end up with something really powerful and flexible and all defined at the root level.

In my opinion this would be a good idea.

I get that the idea was to have an easily themeable look. That's a good goal. But — again, in my opinion — real world use cases are pretty much bound to bring in situations where more specificity is required, so we may have some work to do to find the sweet spot between control and simplicity.

(By the way, I am not dismissing Bernhard's worries or the points he's made. I'm not particularly familiar with Uikit, so can't say if e.g. aligning our new CSS variables more with the variables it has would make sense or be feasible.)

[Mikel]

Thanks a lot, @ryan, for posting such detailed examples!

I agree with many of the concerns regarding having multiple “style” layers stacked on top of each other, as well as what @bernhard wrote about “reinventing the wheel.” It reminds me of the horrible experiences we had when a client decided to purchase a “professional” Bootstrap theme… I counted four different style systems overwriting each other countless times. It was a mess to work with and almost impossible to make any changes without writing a lot of extra code.

We’re still experimenting with the new admin style, showing it to some clients and collecting feedback. The main response we’ve received so far is that everyone felt somewhat uncomfortable with the non-white background (“dull”, “depressive”) and missed the colors on the input elements. What everyone did like were the productivity improvements like the fixed navigation and the hover-toolbar in the page tree.

Maybe I’m wrong—time will tell—but from a strict UI designer’s standpoint (which is my profession), the hype around “dark modes” introduced by operating systems is… well, just hype when it comes to software like a CMS. Most “regular” users are happy once they’ve learned an interface well enough to complete their tasks. If that interface suddenly changes just because it gets dark outside, it’s… let’s say, at the very least, irritating.

Lastly, I think there’s a typo in the custom CSS example linked in the admin style config:

/* -------------------------------------------------------------------- */
/* ---- THEME WITH COLOR MASTHEAD VARIABLES -------------------------- */
/* ---- (these depend on the default theme variables) --------------- */
/* ----------------------------------------------------------------- */

:root {
    ...
    --masthead-menu-item-backgroud-hover: rgba(255,255,255,.2);
}

I believe there’s an “n” missing—shouldn’t the variable be like this?

 --masthead-menu-item-background-hover

Cheers to all of you—have a pleasant and productive week!

Edited June 2 by Mikel
fixed some typos

[cwsoft]

After using the new style/theme from the dev branch for about a week now, I switched back to the default theme from the main branch recently. I wasn‘t able to adjust to the light grey background and the reduced colors on input elements or background of notes and messages.

However I guess I am not the intended audience to be attracted by the new style/theme either. I only use dark themes when it comes to VS Code Editor, all other Apps stay in light mode. But that was only after finding a dark color scheme, which pleased my eyes, which took about half a year of trial and error. The 15+ last years I used light themes for coding too. Only setting I do at night is to dim the iPad display for reading. 

Usually I stick with the defaults offered by the OS system or Apps, as I do find this look the awesome my Posh terminal adjustments just a waste of my lifetime. So I would not bother to have a new light style/theme which covers the edge cases for the most popular modules and pro modules out there and see the dark themes more as a yes we have that too, but it might be involving some tweaks of the CSS to get it working with the modules out there. 

Hope this won‘t lead to a split in the community or the leaving of PW supporters and module authors out there, as it could be seen on other CMS/CMF systems before.

So keep up the good work, just setup a list with reported (real) issues - ideally focusing on light themes first and try to keep out personal preferences as good as possible. 

Edited June 2 by cwsoft

[adrian]

6 hours ago, teppo said:

(By the way, I am not dismissing Bernhard's worries or the points he's made. I'm not particularly familiar with Uikit, so can't say if e.g. aligning our new CSS variables more with the variables it has would make sense or be feasible.)

I agree with a lot of @bernhard's issues, but if I am understanding his suggestions about aligning CSS vars with UiKit's classes, then I don't agree with that suggestion. I think the CSS vars need to be agnostic in this regard (for when PW moves away from Uikit at some point). This is why I am wanting things like:

--text-color
--text-color-hidden
--text-color-active
--text-color-hover
--top-menu-text-color
--top-menu-background-color
--top-menu-text-color-active
--top-menu-background-color-active
--top-menu-text-color-hover
--top-menu-background-color-hover
--dropdown-menu-text-color
--dropdown-menu-background-color
--dropdown-menu-text-color-active
--dropdown-menu-background-color-active
--dropdown-menu-text-color-hover
--dropdown-menu-background-color-hover

Same for button text, color, background, border-radius including hover state, etc. It's really not that many but will mean that we don't have situations like where --blocks-background is used for the text color of a button.

I haven't put proper thought into these yet, but hopefully you get the idea. And, definitely no vars that reference other vars meaning that you can't override one without affecting the other.

There are actually a lot of good articles online for css variable best practices - I know I need to read more about this.
 

[BrendonKoz]

If not targeting UiKit variables which will exist globally for all "modern" themes (regardless of user choice), how would you be sure to properly assign/override something like a primary color? That would only allow you to custom-target this new theme/style, unless the goal is to make those named CSS variables part of the base theme? I understand that easier-to-read names make things simpler, but as PW has used UiKit for so long, its usage is fairly well entrenched, even in the many Pro Modules (ryan's, jploch's, and bernhard's, maybe kongodongo's too but I'm not familiar with his).

Forgive me if I'm mistaken, but doesn't the standard admin style (css/less file) override affect all admin themes by default? If so, is there a way to ensure we're properly targeting overrides for the intended theme/style, or applying a global override? I haven't messed with that for this very reason of uncertainty.

[bernhard]

6 hours ago, adrian said:

I agree with a lot of @bernhard's issues, but if I am understanding his suggestions about aligning CSS vars with UiKit's classes, then I don't agree with that suggestion. I think the CSS vars need to be agnostic in this regard (for when PW moves away from Uikit at some point). This is why I am wanting things like:

I hope I suggested aligning css variables and less variables, not uikit classes 🙂 At least that's what I meant!

But to be honest I'm not sure about this suggestions either. I think part of the suggestion was to make it feel less wrong. Having css variables and less variables side by side just hurts and having them follow different naming conventions - if any - hurts even more. I probably hoped that having them at least named equally would make it less painful. But if that really worked at all or was even possible to achieve? I don't know. This question should have been asked long time ago. I have raised my concerns regarding css variables right from the beginning by pointing to an open request for UIkit to support css variables from 2021.

Anyway - I appreciate your efforts to help to improve the situation! I hope I can add something useful:

• --dropdown-menu-background-color
• @navbar-dropdown-background

UIkit uses semantic variable names. The component is called "navbar" (not "menu" like you suggest). Here are all UIkit components. Also UIkit uses the term "background" for background colors and "color" for text colors. You are using "--text-color" where - in UIkit - the "text" would be redundant (and thus left away) and the less variable would be something like "@global-color", which would tell any UIkit user that it's the text color from the global component. For an example look here: https://github.com/uikit/uikit/blob/develop/src/less/components/navbar.less

@navbar-dropdown-color as another example tells anybody knowing UIkit that this is the variable for the text color of the dropdown (not the background). Now one could argue that this can be confusing for anybody not knowing UIkit, and I agree. I just wanted to mention that these conventions are there and they have been there since 2017, so any change should (have) IMHO be well considered.

Following these conventions would make your variable names a bit less verbose (--top-menu-background vs. --top-menu-background-color). Though that alone can be the fuel for a lot of discussion. So I'm not sure what would be best. I still can't believe that we opened this can of worms...

On the positive side, what LESS can NOT do: If you have multiple navigations on one page and you want to style them differently (eg one background red and one background blue) you simply can't do that. There is only one variable and that applies to all dom elements using the .uk-navbar class.

This is where CSS variables shine! There we could do this:

:root {
  --navbar-dropdown-background: red;
}

#my-custom-nav {
  --navbar-dropdown-background: blue;
}

This could mean that we probably COULD more or less stick to uikit variable names but at the same time have the flexibility to style different sections of the UI differently. Though I wonder how such a setup would be translated to the old LESS based themes.

Whatever, it would result in something like this:

• DOM: <div class="uk-navbar-dropdown">
• LESS: @navbar-dropdown-background
• CSS: --navbar-dropdown-background

My feeling is that this would make a LOT more sense then what we have so far. But I admit I didn't think that that through, so there might be culprits.

Your example on the other hand would result in this:

• DOM: <div class="uk-navbar-dropdown">
• LESS: @navbar-dropdown-background
• CSS: --dropdown-menu-background-color

Which does not really look beautiful to me 🙂 But maybe your setup works better in real life. In the rock theme I invented the @rock-primary color that sets several uikit variables once, for example. So I understand that we probably don't need a 100% match.

As much as I would have loved to help with this, I just fear that any effort in that direction is wasted love (word pun as we won the ESC with that song recently and I have to take this admin theme stuff less seriously ^^). I guess - like you already mentioned - what is likely going to happen is that the new theme will receive updates, make use of cool new features (why wouldn't we) and then the old ones are going to die, which means many of the 1200+ modules in the modules directory will have to be checked and updated or will sooner or later break or at least look ugly in at least one theme. I think that's the reality that we are facing.

To be fair: I have spent many hours already in the new theme and all technical implications and flaws aside I have to say I like it. I like many aspects, and it definitely looks and feels more modern. Maybe this step was necessary and maybe many new users will join our community. Maybe many of them will buy my modules and messing around with those new css variables and overrides will pay off one day. Who knows 😄 It's just that I didn't choose ProcessWire to make a lot of money. I chose it to enjoy my job.

[Gideon So]

Hi @bernhard

Quote

It's just that I didn't choose ProcessWire to make a lot of money. I chose it to enjoy my job.

This is one of the greatest quote I have ever quoted.😄

[bernhard]

14 hours ago, adrian said:

I think we just need some refactoring (to prevent the reported issues with the core and modules) and other bug fixes along with more distinct css vars so that any aspects of the new theme's color scheme can be modified easily and so that these css vars will work in the future should PW ditch UiKit at some point.

Quoting a statement from the other thread here, as that explains a lot and with that context I can totally understand why you disagree with me in aligning css variable names with uikit less variables. In that case it's a valid strategy 🙂 

[jploch]

Thanks for your feedback for the new skin/theme. I would suggest we keep the feedback to this thread to make it easier for everyone to contribute and follow along: