Front-end architecture fundamentals
Revisiting the fundamentals of the Web that Wagtail relies on
We just shipped Wagtail 7.1! And announced a new direction for AI in the CMS. That’s a lot shiny new things, so as a counterpoint it felt worthwhile to revisit the fundamentals of front-end architecture that support Wagtail’s user interface, eight years after I started advocating for drastic improvements (time flies!).
This side of the project’s architecture plays a crucial role in our continued success, enabling regular user experience (UX) improvements in each release. The interface evolves incrementally, with careful planning to refactor code and build new features without compromising code health and maintainability. If you’re wondering how much evolution we’re talking about, all it takes is to take a peek at our public roadmap.
- Half of the items are UX-related in our current and Future releases
- 14 out of 29 of the last 12 months’ worth of features, marked either "ux" or "accessibility".
👉️ This started as a meetup talk, watch it on YouTube if you prefer!
Picking the right architecture
With the UI evolving continuously due to changing user needs and technological advancements, the architecture must adapt incrementally. Raising the bar even higher, with Wagtail’s strong Django foundations (see our Zen of Wagtail) comes an expectations from developers that a lot of this UI is customizable! Some people come to Wagtail expecting us to have a documented list of all of the templates you can override and the blocks for each. That's really hard to square with the UI evolving in any meaningful way.
Oh and – we need to keep in mind the happiness not just of developers building websites, but our contributors as well! This is particularly challenging when we want to make the project open to external contributions, with a lot of developers coming with wildly different degrees of front-end expertise!
So there’s just no way whatsoever that we could pick a UI architecture 10 years ago and it still being relevant! We need to evolve, based on the challenges we face as the project evolves. And with Django being completely devoid of any opinions when it comes to front-end development, a lot to figure out. Let’s dive a bit deeper.
Complex UI requirements
Wagtail incorporates several complex, dynamic elements, including concurrent editing notifications, a minimap interface, live previews, commenting features, and real-time accessibility feedback. Achieving this functionality within the constraints of Django templates and AJAX introduces significant technical challenges. These features demand intricate coordination between back-end logic and dynamic front-end behavior. The concurrent editing notifications are a classic example of this complexity, which we attempted to solve with Django templates, HTML, and AJAX:
And this feature is just one step on a longer journey to auto-saving and collaborative content editing. There are many more steps further increasing how dynamic the UI has to be! And a need for very fine-grained states and status indicators at multiple levels, spread across the interface.
Cross-cutting concerns: performance, security, accessibility
Front-end architecture also profoundly impacts essential cross-cutting concerns such as security and accessibility, which means we have to devise the architecture according to those requirements. A few examples:
- We currently do a lot of work on Content Security Policy compatibility. This is completely enabled by our adoption of Stimulus as a JS framework, which was the most appropriate of all options.
- A lot of our accessibility improvements depend on well-architected CSS, which requires careful thinking with so many components (16 different button variations!)
- And maintaining good performance over time takes careful thought. We measured the energy usage of loading the admin UI as part of a recent performance audit, and need to revert the current trend:
Our architecture choices
Again going deeper, if you want the short version check out our UI guidelines for contributors!
React-inspired HTML patterns
Component-driven UI development with Django has been around for a while now, and it makes a lot of sense. It promotes component reusability, helps us get better developer tooling, and maintainability. Wagtail’s components borrow most from Slippers. Here’s what our dialog component looks like as an example, focusing on the templating:
{% dropdown toggle_icon="dots-horizontal" toggle_aria_label="Actions" %} <a href="/admin/pages/2/move/">{% icon name="arrow-right-full" %} Move</a> <a href="/admin/pages/2/copy/">{% icon name="copy" %} Copy</a> <a href="/admin/pages/2/delete/">{% icon name="bin" %} Delete</a> <a href="/admin/pages/2/unpublish/">{% icon name="download" %} Unpublish</a> {% enddropdown %}
There is a lot more we could do in the future in this space! Exciting concepts like LSP for Django Templates. Possibly Wagtail providing more fundamental building blocks for website theming?
CSS strategies
CSS development in Wagtail emphasizes balancing extensive customization with maintainability, particularly when it comes to theming. We invested heavily into modern CSS capabilities that fit with our strict browser support targets, for example to build customizable light/dark modes, and enhanced contrast options, and configurability of the UI density. With a mixture of Tailwind and more traditional approaches like Sass, BEM, ITCSS (we think they do all go pretty well together). A recent big improvement for us was full adoption of logical properties and values, allowing us to support a right-to-left layout for languages like Arabic, Persian, Hebrew, without greatly expanding the amount of styles written.
JavaScript architecture
Wagtail’s choice of Stimulus allows progressive enhancement of existing Django pages rather than converting to full single-page applications. This approach maintains a lightweight front-end footprint. We’re also leaning hard into TypeScript for complex UI logic is strongly advocated, which occasionally gets in the way, but generally helps encourage good coding patterns. Practical improvements stemming from this approach:
- Being able to reach 100% coverage with unit tests for UI code, just like we would for React.
- Auto-generated JavaScript components documentation (thank you TypeDoc!)
SVG usage
Last but not least, we need to give love to SVG! From 2018 to 2022, we incrementally reworked all of our UI to switch to SVG icons. Better scalability, accessibility, and support for RTL layouts – there’s lots of excellent reasons. This careful planning and reworking has allowed us to:
- Support custom icons, that are super easy to add (or override existing ones).
- Support right-to-left icons, both biderectionnal or different designs.
- Document all of our available icons as part of our main docs!
Lessons learned and future directions
Explicit architectural decisions and UI guidelines are essential to Wagtail’s sustainable front-end development. Finding a balance between legacy support and innovation is tricky, but clear targets go a long way. Moving forward, we’ll do even more to refine and document our in-CMS UI framework, potentially make it reusable for Wagtail site implementers, and use more modern technology where appropriate (adopted stylesheets! in-browser,local AI! text fragments!).
If you want to get involved with this, come say hi at Wagtail Space 2025 🚀. Our UI team will be in attendance, and we hope to showcase more of those modern approaches that move the needle.
