Themes & Accessibility
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Themes & Accessibility system in CodeBot provides a highly customizable user interface designed to meet diverse visual preferences and accessibility requirements. The system allows users to switch between built-in themes (such as Classic, Dark, and Nebula), import VS Code themes, or create entirely custom palettes using a dedicated Theme Builder.
Accessibility is a core component of this system, featuring a High Contrast mode with absolute colors, keyboard-navigable Markdown previews, and WCAG 2.1 compliant color contrast checks during theme creation. The architecture utilizes CSS variables (Design Tokens) and a centralized API to manage theme persistence across global and device-specific scopes.
Sources: webapp/templates/base.html:105-240, webapp/templates/settings/theme_builder.html:706-724, webapp/FEATURE_SUGGESTIONS/ACCESSIBLE_MARKDOWN_DISPLAY_GUIDE.md:325-345
Theme Architecture & Persistence
The system categorizes themes into three primary types: Built-in, Shared (publicly available), and Custom (user-defined). Theme selection is persisted via a combination of server-side database preferences and client-side storage to ensure a "no-flicker" loading experience.
Theme Scopes
Themes can be applied at two different levels:
- Global: Persisted in the user's database document under
ui_prefs.theme, syncing across all logged-in sessions. - Device: Stored in HTTP cookies and
localStorage, affecting only the current browser/device.
Sources: webapp/themes_api.py:30-33, webapp/themes_api.py:440-455
Implementation Flow
The following sequence diagram illustrates how a theme is applied and synchronized between the client and server.
The system uses a circular "mask" transition during theme changes to prevent white-screen flashes before CSS variables are fully applied.
Sources: webapp/themes_api.py:734-758, webapp/templates/base.html:362-401, webapp/static/css/theme-mask.css
Theme Builder & Customization
The Theme Builder is a frontend tool that allows users to manipulate Design Tokens in real-time. It provides a live preview sandbox that reflects changes to backgrounds, accents, and glassmorphism effects.
Supported Design Tokens
| Token Category | Variables | Description |
|---|---|---|
| Backgrounds | --bg-primary, --bg-secondary, --card-bg | Core layout colors. |
| Accents | --primary, --secondary | Action colors and highlights. |
| Glass Effect | --glass, --glass-blur, --glass-opacity | Transparency and blur settings. |
| Markdown | --md-surface, --md-text | Specific colors for code and text previews. |
Sources: webapp/templates/settings/theme_builder.html:61-180, webapp/templates/settings/theme_builder.html:433-448
Contrast Validation
During the saving process, the system performs a basic contrast check based on WCAG 2.1 standards. If the ratio between the primary text color and the primary background color falls below 4.5:1, a warning is issued to the user.
Sources: webapp/templates/settings/theme_builder.html:565-585, webapp/templates/settings/theme_builder.html:706-724
Accessibility Features
High Contrast Mode
CodeBot includes a specialized high-contrast.css stylesheet that overrides theme variables with absolute values to maximize readability.
- Backgrounds: Solid black (
#000000). - Text: Pure white (
#ffffff) or vibrant yellow (#ffff00). - Interactions: Thick borders (2px-3px) on focus and high-visibility outlines.
Sources: webapp/static/css/high-contrast.css, webapp/templates/base.html:268-285
Accessible Markdown Display
The Markdown engine (markdown-it) is extended with specific accessibility enhancements for screen readers and keyboard users.
Markdown Interaction Table
| Feature | Keyboard Shortcut | Implementation |
|---|---|---|
| Copy Code | Ctrl+Shift+C | Copies the first code block in the current document. |
| Permalink | Ctrl+L | Copies the direct link to the currently visible header. |
| Announcements | N/A | Uses aria-live="polite" status regions for feedback. |
Sources: webapp/FEATURE_SUGGESTIONS/ACCESSIBLE_MARKDOWN_DISPLAY_GUIDE.md:195-215, webapp/templates/md_preview.html:2460-2480
API Reference
The themes_bp Blueprint manages theme operations.
Key API Endpoints
| Method | Endpoint | Description | Rate Limit |
|---|---|---|---|
GET | /api/themes/list | Returns a merged list of Built-in, Shared, and Custom themes. | N/A |
GET | /api/themes/<id> | Returns full details of a specific theme, including variables. | 50/hr (Reg), 200/hr (Admin) |
POST | /api/themes/publish | Publishes a custom theme to the public library (Admin only). | N/A |
POST | /api/themes/import | Imports a JSON theme (VS Code or Native format). | Max 10 themes per user |
Sources: webapp/themes_api.py:48-62, webapp/themes_api.py:165-200, webapp/themes_api.py:1005-1050
Conclusion
The Themes & Accessibility system provides a robust framework for personalization while adhering to strict usability standards. By separating design tokens from structural logic and providing centralized API management, the project ensures that visual customization does not compromise technical performance or accessibility for users with different visual needs.
Sources: webapp/FEATURE_SUGGESTIONS/ACCESSIBLE_MARKDOWN_DISPLAY_GUIDE.md:325-345, webapp/templates/base.html:105-120