Wagtail

As wagtail.org continued to grow, the team wanted to support dark mode to improve accessibility, reduce eye strain, and meet user expectations, particularly for developers spending long periods reading documentation and guides.

Working within the existing design system, we were responsible for designing and implementing a robust theming approach that supported both light and dark modes without duplicating styles or introducing unnecessary complexity. The work focused on maintainability, accessibility, and consistency across all page types and components.

Design System Extension

Rather than treating dark mode as a visual layer applied at the end, the implementation required extending the underlying design system. This included:

• Refactoring colour usage to rely on semantic design tokens rather than fixed values
• Defining light and dark theme palettes with appropriate contrast ratios
• Auditing components to ensure states, borders, icons and focus styles worked in both modes
• Updating documentation and usage patterns to support future components

This approach ensured dark mode could scale with the site as new features and content were introduced.

Front-end Implementation

On the front end, the work included:

• Implementing theme switching using modern CSS techniques
• Respecting system-level user preferences via prefers-color-scheme
• Ensuring smooth transitions without impacting performance
• Testing across devices, browsers, and assistive technologies
• Verifying WCAG contrast compliance in both themes

Outcome

The dark mode implementation provided wagtail.org users with a more comfortable, flexible reading experience while strengthening the site’s design system foundations. By embedding theming at a system level, the work improved long-term maintainability and ensured future enhancements could support multiple themes with minimal overhead.