Proposed by: Keha Chandrakar (BS Data Science, IIT Madras)
Potential Mentor: Sarah A (To Be Confirmed)
Problem Statement
Django’s main website and its issue tracker do not currently provide a consistent visual experience. The main website supports dark mode, but the Issues section at code.djangoproject.com uses a separate Trac-based interface with different styling. As a result, when users move from the main site to the issue tracker, the theme and overall look change suddenly.
This inconsistency affects both usability and contributor experience. The issue tracker is an important part of Django’s public infrastructure, used for browsing tickets, reading reports, and contributing to discussions. A more consistent and accessible interface would make this experience smoother, more comfortable, and more usable for all users, regardless of whether they use dark mode or not.
Since the issue tracker is maintained separately, this improvement needs dedicated work in its own templates and styles. This project aims to address that gap in a practical and maintainable way.
Technical Plan
The goal of this project is to introduce dark mode support to Django’s issue tracker (code.djangoproject.com), which is powered by Trac and uses its own styling layer. The implementation will focus on providing a maintainable theme system while keeping compatibility with the existing Trac infrastructure.
Development and testing will be performed using a local Trac instance created from the djangoproject.com repository, allowing CSS and template changes to be validated before submitting patches.
-
Local Development Environment
The project will be developed and tested using the repository setup instructions provided in the djangoproject.com codebase.
The workflow will be:
Create and activate a virtual environment.
Install development dependencies.
Initialize a local Trac environment.
Import the Django issue tracker database schema.
Run the local Trac server for testing.
This provides a working local instance of the issue tracker where UI changes can be tested across different pages such as:
ticket lists
ticket detail pages
wiki pages
timeline and reports
Outcome:
A fully functional local Trac environment used for development and testing. -
Analysis of the Existing Trac Interface
Before implementing dark mode, the structure of the Trac interface will be analyzed using browser developer tools and the repository’s CSS and template files.
Key components to analyze include:
Layout containers
(body, #content, #main)
Navigation components
(main navigation bar with WIKI, TIMELINE, ROADMAP, VIEW TICKETS, SEARCH)
Content components
(tables, forms, ticket lists, wiki pages)
Sidebar elements and auxiliary UI sections.
Outcome:
A clear mapping of Trac UI components and the selectors required to implement theme styling. -
Dark Mode Styling Architecture
A separate stylesheet will be introduced:
dark-mode.css
This stylesheet will contain overrides for Trac’s default styles.
To maintain compatibility and reduce risk:
existing styles such as trachacks.css will not be modified directly
the new stylesheet will be loaded after the existing styles
selectors will target specific UI components to avoid unintended overrides
Example structure:
html[data-theme=“dark”] body { … }
html[data-theme=“dark”] #content { … }
html[data-theme=“dark”] .listing { … }
Outcome:
A maintainable styling layer that allows dark mode without altering existing Trac CSS files. -
Theme Toggle Implementation
A theme toggle will be introduced in the issue tracker navigation bar, allowing users to switch between:
Light mode
Dark mode
System preference
Implementation approach:
A theme attribute will be applied to the root element:
- Incremental Implementation
The styling implementation will be performed incrementally to ensure stability.
Phase 1 — Base Layout Styling
Apply dark background and text colors to the main layout elements such as body, content containers, and page structure.
Phase 2 — Navigation Styling
Update the navigation bar and tab navigation elements used across Trac pages.
This includes sections such as:
WIKI
TIMELINE
ROADMAP
VIEW TICKETS
SEARCH
Hover states and active states will be adjusted to ensure readability in dark mode.
Phase 3 — Tables and Ticket Lists
Update .listing tables used in ticket listings and reports.
Changes will include:
header styling
row backgrounds
borders and separators
Phase 4 — Forms and Inputs
Style input fields, search boxes, buttons, and other form components to ensure visibility and usability in dark mode.
Phase 5 — Secondary UI Components
Update sidebar elements, wiki formatting blocks, and secondary UI components to maintain visual consistency.
Phase 6 — Edge Cases
Handle additional components such as:
wiki pages
code blocks
pagination
notifications
Outcome:
A consistent dark mode implementation across the main interface components.
-
Testing and Validation
Testing will be performed using the local Trac instance.
Changes will be validated across different sections of the issue tracker including:
ticket lists
ticket detail pages
wiki pages
reports and timeline
Validation will focus on:
visual consistency
text readability
accessibility (contrast and focus states)
Outcome:
A stable and readable dark mode experience across the interface. -
Integration with Trac
The dark mode stylesheet will be integrated using Trac’s template system.
Possible integration points include:
site_head.html
custom template overrides
The stylesheet will be loaded after existing styles so it can override default styling without modifying core Trac assets.
Outcome:
A clean integration that maintains compatibility with existing Trac infrastructure. -
Documentation
The implementation will include documentation describing:
the structure of the dark mode stylesheet
key selectors used for overrides
the theme toggle implementation
guidelines for extending theme support in the future
This documentation will help maintainers and contributors understand and extend the implementation.
Feedback and suggestions from the community are welcome.