protocol.md

UI/UX Standards

Theme Implementation

• Always use the custom theme variables defined in custom.css
• Prioritize using CSS variables like var(--primary-color) over hardcoded hex values
• Use the provided theme classes (e.g., bg-theme-primary, btn-theme-primary)
• Do not introduce new theme components unless absolutely necessary
• For any new UI elements, use existing Bootstrap components styled with our theme classes

CSS Organization

• Never use inline styles or style blocks in HTML templates
• Always move CSS to the custom.css file with appropriate grouping
• When adding new styles, first check if existing theme classes can be utilized
• If creating new styles, ensure they follow the existing naming conventions
• Only create new theme components if there's no suitable existing class that can be extended
• New theme components should follow our CSS naming convention and use theme variables
• custom.css should be treated as a minimal extension of Bootstrap, not a replacement

Bootstrap Usage

• Rely on Bootstrap components and utilities as the foundation for UI elements
• Use Bootstrap's grid system for layout instead of creating custom layout systems
• Enhance Bootstrap components with our theme classes rather than replacing them
• Maintain Bootstrap's responsive design principles across all screen sizes
• Use Bootstrap's utility classes whenever possible before creating custom CSS
• Remember that our theming philosophy is "extend, not replace" - keep custom CSS minimal

Project Structure

• Keep apps small and focused on specific functionality
• Store templates in a directory structure matching URL patterns
• Use static file namespacing to avoid conflicts
• Create separate apps for distinct functional areas

Documentation

• Document all functions with docstrings explaining purpose, parameters, and return values
• Include setup instructions in the README.md
• Comment complex logic or non-obvious implementations
• Keep documentation updated as code changes

Code Review Checklist

• Does the code follow the style guidelines?
• Is there adequate test coverage?
• Is the code DRY (Don't Repeat Yourself)?
• Are there any security concerns?
• Is error handling implemented appropriately?
• Is the documentation updated?
• Does UI adhere to our theme guidelines?
• Are new UI elements consistent with existing design?

Refactoring Priorities

• Remove duplicate code
• Break down large functions or methods
• Extract complex logic to helper functions
• Improve naming for clarity
• Minimize CSS overrides by leveraging Bootstrap's built-in features